Debian Codegraph @

upstream/debian-unstable/man1/perlintern.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLINTERN 1"
58 .TH PERLINTERN 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perlintern \- autogenerated documentation of purely internal
65 Perl functions
66 .SH DESCRIPTION
67 .IX Xref "internal Perl functions interpreter functions"
68 .IX Header "DESCRIPTION"
69 This file is the autogenerated documentation of functions in the
70 Perl interpreter that are documented using Perl's internal documentation
71 format but are not marked as part of the Perl API. In other words,
72 \&\fBthey are not for use in extensions\fR!
73 .PP
74 It has the same sections as perlapi, though some may be empty.
75 .SH "AV Handling"
76 .IX Header "AV Handling"
77 .ie n .IP """av_fetch_simple""" 4
78 .el .IP \f(CWav_fetch_simple\fR 4
79 .IX Xref "av_fetch_simple"
80 .IX Item "av_fetch_simple"
81 This is a cut-down version of av_fetch that assumes that the array is
82 very straightforward \- no magic, not readonly, and AvREAL \- and that
83 \&\f(CW\*(C`key\*(C'\fR is not negative. This function MUST NOT be used in situations
84 where any of those assumptions may not hold.
85 .Sp
86 Returns the SV at the specified index in the array. The \f(CW\*(C`key\*(C'\fR is the
87 index. If lval is true, you are guaranteed to get a real SV back (in case
88 it wasn't real before), which you can then modify. Check that the return
89 value is non-null before dereferencing it to a \f(CW\*(C`SV*\*(C'\fR.
90 .Sp
91 The rough perl equivalent is \f(CW$myarray[$key]\fR.
92 .RS 4
93 .Sp
94 .Vb 1
95 \& SV ** av_fetch_simple(AV *av, SSize_t key, I32 lval)
96 .Ve
97 .RE
98 .RS 4
99 .RE
100 .ie n .IP """AvFILLp""" 4
101 .el .IP \f(CWAvFILLp\fR 4
102 .IX Xref "AvFILLp"
103 .IX Item "AvFILLp"
104 If the array \f(CW\*(C`av\*(C'\fR is empty, this returns \-1; otherwise it returns the maximum
105 value of the indices of all the array elements which are currently defined in
106 \&\f(CW\*(C`av\*(C'\fR. It does not handle magic, hence the \f(CW\*(C`p\*(C'\fR private indication in its name.
107 .RS 4
108 .Sp
109 .Vb 1
110 \& SSize_t AvFILLp(AV* av)
111 .Ve
112 .RE
113 .RS 4
114 .RE
115 .ie n .IP """av_new_alloc""" 4
116 .el .IP \f(CWav_new_alloc\fR 4
117 .IX Xref "av_new_alloc"
118 .IX Item "av_new_alloc"
119 This implements "\f(CW\*(C`newAV_alloc_x\*(C'\fR" in perlapi
120 and "\f(CW\*(C`newAV_alloc_xz\*(C'\fR" in perlapi, which are the public API for this
121 functionality.
122 .Sp
123 Creates a new AV and allocates its SV* array.
124 .Sp
125 This is similar to, but more efficient than doing:
126 .Sp
127 .Vb 2
128 \& AV *av = newAV();
129 \& av_extend(av, key);
130 .Ve
131 .Sp
132 The size parameter is used to pre-allocate a SV* array large enough to
133 hold at least elements \f(CW\*(C`0..(size\-1)\*(C'\fR. \f(CW\*(C`size\*(C'\fR must be at least 1.
134 .Sp
135 The \f(CW\*(C`zeroflag\*(C'\fR parameter controls whether or not the array is NULL
136 initialized.
137 .RS 4
138 .Sp
139 .Vb 1
140 \& AV * av_new_alloc(SSize_t size, bool zeroflag)
141 .Ve
142 .RE
143 .RS 4
144 .RE
145 .ie n .IP """av_store_simple""" 4
146 .el .IP \f(CWav_store_simple\fR 4
147 .IX Xref "av_store_simple"
148 .IX Item "av_store_simple"
149 This is a cut-down version of av_store that assumes that the array is
150 very straightforward \- no magic, not readonly, and AvREAL \- and that
151 \&\f(CW\*(C`key\*(C'\fR is not negative. This function MUST NOT be used in situations
152 where any of those assumptions may not hold.
153 .Sp
154 Stores an SV in an array. The array index is specified as \f(CW\*(C`key\*(C'\fR. It
155 can be dereferenced to get the \f(CW\*(C`SV*\*(C'\fR that was stored there (= \f(CW\*(C`val\*(C'\fR)).
156 .Sp
157 Note that the caller is responsible for suitably incrementing the reference
158 count of \f(CW\*(C`val\*(C'\fR before the call.
159 .Sp
160 Approximate Perl equivalent: \f(CW\*(C`splice(@myarray, $key, 1, $val)\*(C'\fR.
161 .RS 4
162 .Sp
163 .Vb 1
164 \& SV ** av_store_simple(AV *av, SSize_t key, SV *val)
165 .Ve
166 .RE
167 .RS 4
168 .RE
169 .SH "Callback Functions"
170 .IX Header "Callback Functions"
171 .ie n .IP """dowantarray""" 4
172 .el .IP \f(CWdowantarray\fR 4
173 .IX Xref "dowantarray"
174 .IX Item "dowantarray"
175 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`dowantarray\*(C'\fR
176 from a future release of Perl. Do not use it for
177 new code; remove it from existing code.
178 .Sp
179 Implements the deprecated "\f(CW\*(C`GIMME\*(C'\fR" in perlapi.
180 .RS 4
181 .Sp
182 .Vb 1
183 \& U8 dowantarray()
184 .Ve
185 .RE
186 .RS 4
187 .RE
188 .ie n .IP """leave_scope""" 4
189 .el .IP \f(CWleave_scope\fR 4
190 .IX Xref "leave_scope"
191 .IX Item "leave_scope"
192 Implements \f(CW\*(C`LEAVE_SCOPE\*(C'\fR which you should use instead.
193 .RS 4
194 .Sp
195 .Vb 1
196 \& void leave_scope(I32 base)
197 .Ve
198 .RE
199 .RS 4
200 .RE
201 .ie n .IP """magic_freedestruct""" 4
202 .el .IP \f(CWmagic_freedestruct\fR 4
203 .IX Xref "magic_freedestruct"
204 .IX Item "magic_freedestruct"
205 This function is called via magic to implement the
206 \&\f(CWmortal_destructor_sv()\fR and \f(CWmortal_destructor_x()\fR functions. It
207 should not be called directly and has no user servicable parts.
208 .RS 4
209 .Sp
210 .Vb 1
211 \& int magic_freedestruct(SV *sv, MAGIC *mg)
212 .Ve
213 .RE
214 .RS 4
215 .RE
216 .ie n .IP """mortal_svfunc_x""" 4
217 .el .IP \f(CWmortal_svfunc_x\fR 4
218 .IX Xref "mortal_svfunc_x"
219 .IX Item "mortal_svfunc_x"
220 This function arranges for a C function reference to be called at the
221 \&\fBend of the current statement\fR with the arguments provided. It is a
222 wrapper around \f(CWmortal_destructor_sv()\fR which ensures that the latter
223 function is called appropriately.
224 .Sp
225 Be aware that there is a signficant difference in timing between the
226 \&\fIend of the current statement\fR and the \fIend of the current pseudo
227 block\fR. If you are looking for a mechanism to trigger a function at the
228 end of the \fBcurrent pseudo block\fR you should look at
229 "\f(CW\*(C`SAVEDESTRUCTOR_X\*(C'\fR" in perlapi instead of this function.
230 .RS 4
231 .Sp
232 .Vb 1
233 \& void mortal_svfunc_x(SVFUNC_t f, SV *p)
234 .Ve
235 .RE
236 .RS 4
237 .RE
238 .ie n .IP """pop_scope""" 4
239 .el .IP \f(CWpop_scope\fR 4
240 .IX Xref "pop_scope"
241 .IX Item "pop_scope"
242 Implements "\f(CW\*(C`LEAVE\*(C'\fR" in perlapi
243 .RS 4
244 .Sp
245 .Vb 1
246 \& void pop_scope()
247 .Ve
248 .RE
249 .RS 4
250 .RE
251 .ie n .IP """push_scope""" 4
252 .el .IP \f(CWpush_scope\fR 4
253 .IX Xref "push_scope"
254 .IX Item "push_scope"
255 Implements "\f(CW\*(C`ENTER\*(C'\fR" in perlapi
256 .RS 4
257 .Sp
258 .Vb 1
259 \& void push_scope()
260 .Ve
261 .RE
262 .RS 4
263 .RE
264 .ie n .IP """save_adelete""" 4
265 .el .IP \f(CWsave_adelete\fR 4
266 .IX Xref "save_adelete"
267 .IX Item "save_adelete"
268 Implements \f(CW\*(C`SAVEADELETE\*(C'\fR.
269 .RS 4
270 .Sp
271 .Vb 1
272 \& void save_adelete(AV *av, SSize_t key)
273 .Ve
274 .RE
275 .RS 4
276 .RE
277 .ie n .IP """save_freercpv""" 4
278 .el .IP \f(CWsave_freercpv\fR 4
279 .IX Xref "save_freercpv"
280 .IX Item "save_freercpv"
281 Implements \f(CW\*(C`SAVEFREERCPV\*(C'\fR.
282 .Sp
283 Saves and frees a refcounted string. Calls \fBrcpv_free()\fR
284 on the argument when the current pseudo block is finished.
285 .RS 4
286 .Sp
287 .Vb 1
288 \& void save_freercpv(char *rcpv)
289 .Ve
290 .RE
291 .RS 4
292 .RE
293 .ie n .IP """save_generic_pvref""" 4
294 .el .IP \f(CWsave_generic_pvref\fR 4
295 .IX Xref "save_generic_pvref"
296 .IX Item "save_generic_pvref"
297 Implements \f(CW\*(C`SAVEGENERICPV\*(C'\fR.
298 .Sp
299 Like \fBsave_pptr()\fR, but also \fBSafefree()\fRs the new value if it is different
300 from the old one. Can be used to restore a global char* to its prior
301 contents, freeing new value.
302 .RS 4
303 .Sp
304 .Vb 1
305 \& void save_generic_pvref(char **str)
306 .Ve
307 .RE
308 .RS 4
309 .RE
310 .ie n .IP """save_generic_svref""" 4
311 .el .IP \f(CWsave_generic_svref\fR 4
312 .IX Xref "save_generic_svref"
313 .IX Item "save_generic_svref"
314 Implements \f(CW\*(C`SAVEGENERICSV\*(C'\fR.
315 .Sp
316 Like \fBsave_sptr()\fR, but also \fBSvREFCNT_dec()\fRs the new value. Can be used to
317 restore a global SV to its prior contents, freeing new value.
318 .RS 4
319 .Sp
320 .Vb 1
321 \& void save_generic_svref(SV **sptr)
322 .Ve
323 .RE
324 .RS 4
325 .RE
326 .ie n .IP """save_hdelete""" 4
327 .el .IP \f(CWsave_hdelete\fR 4
328 .IX Xref "save_hdelete"
329 .IX Item "save_hdelete"
330 Implements \f(CW\*(C`SAVEHDELETE\*(C'\fR.
331 .RS 4
332 .Sp
333 .Vb 1
334 \& void save_hdelete(HV *hv, SV *keysv)
335 .Ve
336 .RE
337 .RS 4
338 .RE
339 .ie n .IP """save_hints""" 4
340 .el .IP \f(CWsave_hints\fR 4
341 .IX Xref "save_hints"
342 .IX Item "save_hints"
343 Implements \f(CW\*(C`SAVEHINTS\*(C'\fR.
344 .RS 4
345 .Sp
346 .Vb 1
347 \& void save_hints()
348 .Ve
349 .RE
350 .RS 4
351 .RE
352 .ie n .IP """save_op""" 4
353 .el .IP \f(CWsave_op\fR 4
354 .IX Xref "save_op"
355 .IX Item "save_op"
356 Implements \f(CW\*(C`SAVEOP\*(C'\fR.
357 .RS 4
358 .Sp
359 .Vb 1
360 \& void save_op()
361 .Ve
362 .RE
363 .RS 4
364 .RE
365 .ie n .IP """save_padsv_and_mortalize""" 4
366 .el .IP \f(CWsave_padsv_and_mortalize\fR 4
367 .IX Xref "save_padsv_and_mortalize"
368 .IX Item "save_padsv_and_mortalize"
369 Implements \f(CW\*(C`SAVEPADSVANDMORTALIZE\*(C'\fR.
370 .RS 4
371 .Sp
372 .Vb 1
373 \& void save_padsv_and_mortalize(PADOFFSET off)
374 .Ve
375 .RE
376 .RS 4
377 .RE
378 .ie n .IP """save_pushptr""" 4
379 .el .IP \f(CWsave_pushptr\fR 4
380 .IX Xref "save_pushptr"
381 .IX Item "save_pushptr"
382 The refcnt of object \f(CW\*(C`ptr\*(C'\fR will be decremented at the end of the current
383 \&\fIpseudo-block\fR. \f(CW\*(C`type\*(C'\fR gives the type of \f(CW\*(C`ptr\*(C'\fR, expressed as one of the
384 constants in \fIscope.h\fR whose name begins with \f(CW\*(C`SAVEt_\*(C'\fR.
385 .Sp
386 This is the underlying implementation of several macros, like
387 \&\f(CW\*(C`SAVEFREESV\*(C'\fR.
388 .RS 4
389 .Sp
390 .Vb 1
391 \& void save_pushptr(void * const ptr, const int type)
392 .Ve
393 .RE
394 .RS 4
395 .RE
396 .ie n .IP """save_rcpv""" 4
397 .el .IP \f(CWsave_rcpv\fR 4
398 .IX Xref "save_rcpv"
399 .IX Item "save_rcpv"
400 Implements \f(CW\*(C`SAVERCPV\*(C'\fR.
401 .Sp
402 Saves and restores a refcounted string, similar to what
403 save_generic_svref would do for a SV*. Can be used to restore
404 a refcounted string to its previous state. Performs the
405 appropriate refcount counting so that nothing should leak
406 or be prematurely freed.
407 .RS 4
408 .Sp
409 .Vb 1
410 \& void save_rcpv(char **prcpv)
411 .Ve
412 .RE
413 .RS 4
414 .RE
415 .ie n .IP """save_scalar_at""" 4
416 .el .IP \f(CWsave_scalar_at\fR 4
417 .IX Xref "save_scalar_at"
418 .IX Item "save_scalar_at"
419 A helper function for localizing the SV referenced by \f(CW*sptr\fR.
420 .Sp
421 If \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR is set in in \f(CW\*(C`flags\*(C'\fR, the function returns the input
422 scalar untouched.
423 .Sp
424 Otherwise it replaces \f(CW*sptr\fR with a new \f(CW\*(C`undef\*(C'\fR scalar, and returns that.
425 The new scalar will have the old one's magic (if any) copied to it.
426 If there is such magic, and \f(CW\*(C`SAVEf_SETMAGIC\*(C'\fR is set in in \f(CW\*(C`flags\*(C'\fR, 'set'
427 magic will be processed on the new scalar. If unset, 'set' magic will be
428 skipped. The latter typically means that assignment will soon follow (\fIe.g.\fR,
429 \&\f(CW\*(Aqlocal\ $x\ =\ $y\*(Aq\fR), and that will handle the magic.
430 .RS 4
431 .Sp
432 .Vb 1
433 \& SV * save_scalar_at(SV **sptr, const U32 flags)
434 .Ve
435 .RE
436 .RS 4
437 .RE
438 .ie n .IP """save_set_svflags""" 4
439 .el .IP \f(CWsave_set_svflags\fR 4
440 .IX Xref "save_set_svflags"
441 .IX Item "save_set_svflags"
442 Implements \f(CW\*(C`SAVESETSVFLAGS\*(C'\fR.
443 .Sp
444 Set the SvFLAGS specified by mask to the values in val
445 .RS 4
446 .Sp
447 .Vb 1
448 \& void save_set_svflags(SV *sv, U32 mask, U32 val)
449 .Ve
450 .RE
451 .RS 4
452 .RE
453 .ie n .IP """save_shared_pvref""" 4
454 .el .IP \f(CWsave_shared_pvref\fR 4
455 .IX Xref "save_shared_pvref"
456 .IX Item "save_shared_pvref"
457 Implements \f(CW\*(C`SAVESHAREDPV\*(C'\fR.
458 .Sp
459 Like \fBsave_generic_pvref()\fR, but uses \fBPerlMemShared_free()\fR rather than \fBSafefree()\fR.
460 Can be used to restore a shared global char* to its prior
461 contents, freeing new value.
462 .RS 4
463 .Sp
464 .Vb 1
465 \& void save_shared_pvref(char **str)
466 .Ve
467 .RE
468 .RS 4
469 .RE
470 .ie n .IP """save_vptr""" 4
471 .el .IP \f(CWsave_vptr\fR 4
472 .IX Xref "save_vptr"
473 .IX Item "save_vptr"
474 Implements \f(CW\*(C`SAVEVPTR\*(C'\fR.
475 .RS 4
476 .Sp
477 .Vb 1
478 \& void save_vptr(void *ptr)
479 .Ve
480 .RE
481 .RS 4
482 .RE
483 .SH Casting
484 .IX Xref "NUM2PTR"
485 .IX Header "Casting"
486 There are currently no internal API items in Casting
487 .SH "Character case changing"
488 .IX Header "Character case changing"
489 There are currently no internal API items in Character case changing
490 .SH "Character classification"
491 .IX Header "Character classification"
492 There are currently no internal API items in Character classification
493 .SH "Compiler and Preprocessor information"
494 .IX Header "Compiler and Preprocessor information"
495 There are currently no internal API items in Compiler and Preprocessor information
496 .SH "Compiler directives"
497 .IX Header "Compiler directives"
498 There are currently no internal API items in Compiler directives
499 .SH "Compile-time scope hooks"
500 .IX Header "Compile-time scope hooks"
501 .ie n .IP """BhkENTRY""" 4
502 .el .IP \f(CWBhkENTRY\fR 4
503 .IX Xref "BhkENTRY"
504 .IX Item "BhkENTRY"
505 NOTE: \f(CW\*(C`BhkENTRY\*(C'\fR is \fBexperimental\fR and may change or be
506 removed without notice.
507 .Sp
508 Return an entry from the BHK structure. \f(CW\*(C`which\*(C'\fR is a preprocessor token
509 indicating which entry to return. If the appropriate flag is not set
510 this will return \f(CW\*(C`NULL\*(C'\fR. The type of the return value depends on which
511 entry you ask for.
512 .RS 4
513 .Sp
514 .Vb 1
515 \& void * BhkENTRY(BHK *hk, token which)
516 .Ve
517 .RE
518 .RS 4
519 .RE
520 .ie n .IP """BhkFLAGS""" 4
521 .el .IP \f(CWBhkFLAGS\fR 4
522 .IX Xref "BhkFLAGS"
523 .IX Item "BhkFLAGS"
524 NOTE: \f(CW\*(C`BhkFLAGS\*(C'\fR is \fBexperimental\fR and may change or be
525 removed without notice.
526 .Sp
527 Return the BHK's flags.
528 .RS 4
529 .Sp
530 .Vb 1
531 \& U32 BhkFLAGS(BHK *hk)
532 .Ve
533 .RE
534 .RS 4
535 .RE
536 .ie n .IP """CALL_BLOCK_HOOKS""" 4
537 .el .IP \f(CWCALL_BLOCK_HOOKS\fR 4
538 .IX Xref "CALL_BLOCK_HOOKS"
539 .IX Item "CALL_BLOCK_HOOKS"
540 NOTE: \f(CW\*(C`CALL_BLOCK_HOOKS\*(C'\fR is \fBexperimental\fR and may change or be
541 removed without notice.
542 .Sp
543 Call all the registered block hooks for type \f(CW\*(C`which\*(C'\fR. \f(CW\*(C`which\*(C'\fR is a
544 preprocessing token; the type of \f(CW\*(C`arg\*(C'\fR depends on \f(CW\*(C`which\*(C'\fR.
545 .RS 4
546 .Sp
547 .Vb 1
548 \& void CALL_BLOCK_HOOKS(token which, arg)
549 .Ve
550 .RE
551 .RS 4
552 .RE
553 .SH Concurrency
554 .IX Header "Concurrency"
555 .ie n .IP """CVf_SLABBED""" 4
556 .el .IP \f(CWCVf_SLABBED\fR 4
557 .IX Item "CVf_SLABBED"
558 .PD 0
559 .ie n .IP """CvROOT""" 4
560 .el .IP \f(CWCvROOT\fR 4
561 .IX Item "CvROOT"
562 .ie n .IP """CvSTART""" 4
563 .el .IP \f(CWCvSTART\fR 4
564 .IX Item "CvSTART"
565 .PD
566 Described in perlguts.
567 .ie n .IP """CX_CUR""" 4
568 .el .IP \f(CWCX_CUR\fR 4
569 .IX Item "CX_CUR"
570 Described in perlguts.
571 .RS 4
572 .Sp
573 .Vb 1
574 \& CX_CUR()
575 .Ve
576 .RE
577 .RS 4
578 .RE
579 .ie n .IP """CXINC""" 4
580 .el .IP \f(CWCXINC\fR 4
581 .IX Item "CXINC"
582 Described in perlguts.
583 .ie n .IP """CX_LEAVE_SCOPE""" 4
584 .el .IP \f(CWCX_LEAVE_SCOPE\fR 4
585 .IX Item "CX_LEAVE_SCOPE"
586 Described in perlguts.
587 .RS 4
588 .Sp
589 .Vb 1
590 \& void CX_LEAVE_SCOPE(PERL_CONTEXT* cx)
591 .Ve
592 .RE
593 .RS 4
594 .RE
595 .ie n .IP """CX_POP""" 4
596 .el .IP \f(CWCX_POP\fR 4
597 .IX Item "CX_POP"
598 Described in perlguts.
599 .RS 4
600 .Sp
601 .Vb 1
602 \& void CX_POP(PERL_CONTEXT* cx)
603 .Ve
604 .RE
605 .RS 4
606 .RE
607 .ie n .IP """cxstack""" 4
608 .el .IP \f(CWcxstack\fR 4
609 .IX Item "cxstack"
610 Described in perlguts.
611 .ie n .IP """cxstack_ix""" 4
612 .el .IP \f(CWcxstack_ix\fR 4
613 .IX Item "cxstack_ix"
614 Described in perlguts.
615 .ie n .IP """CXt_BLOCK""" 4
616 .el .IP \f(CWCXt_BLOCK\fR 4
617 .IX Item "CXt_BLOCK"
618 .PD 0
619 .ie n .IP """CXt_EVAL""" 4
620 .el .IP \f(CWCXt_EVAL\fR 4
621 .IX Item "CXt_EVAL"
622 .ie n .IP """CXt_FORMAT""" 4
623 .el .IP \f(CWCXt_FORMAT\fR 4
624 .IX Item "CXt_FORMAT"
625 .ie n .IP """CXt_GIVEN""" 4
626 .el .IP \f(CWCXt_GIVEN\fR 4
627 .IX Item "CXt_GIVEN"
628 .ie n .IP """CXt_LOOP_ARY""" 4
629 .el .IP \f(CWCXt_LOOP_ARY\fR 4
630 .IX Item "CXt_LOOP_ARY"
631 .ie n .IP """CXt_LOOP_LAZYIV""" 4
632 .el .IP \f(CWCXt_LOOP_LAZYIV\fR 4
633 .IX Item "CXt_LOOP_LAZYIV"
634 .ie n .IP """CXt_LOOP_LAZYSV""" 4
635 .el .IP \f(CWCXt_LOOP_LAZYSV\fR 4
636 .IX Item "CXt_LOOP_LAZYSV"
637 .ie n .IP """CXt_LOOP_LIST""" 4
638 .el .IP \f(CWCXt_LOOP_LIST\fR 4
639 .IX Item "CXt_LOOP_LIST"
640 .ie n .IP """CXt_LOOP_PLAIN""" 4
641 .el .IP \f(CWCXt_LOOP_PLAIN\fR 4
642 .IX Item "CXt_LOOP_PLAIN"
643 .ie n .IP """CXt_NULL""" 4
644 .el .IP \f(CWCXt_NULL\fR 4
645 .IX Item "CXt_NULL"
646 .ie n .IP """CXt_SUB""" 4
647 .el .IP \f(CWCXt_SUB\fR 4
648 .IX Item "CXt_SUB"
649 .ie n .IP """CXt_SUBST""" 4
650 .el .IP \f(CWCXt_SUBST\fR 4
651 .IX Item "CXt_SUBST"
652 .ie n .IP """CXt_WHEN""" 4
653 .el .IP \f(CWCXt_WHEN\fR 4
654 .IX Item "CXt_WHEN"
655 .PD
656 Described in perlguts.
657 .ie n .IP """cx_type""" 4
658 .el .IP \f(CWcx_type\fR 4
659 .IX Item "cx_type"
660 Described in perlguts.
661 .ie n .IP """dounwind""" 4
662 .el .IP \f(CWdounwind\fR 4
663 .IX Item "dounwind"
664 Described in perlguts.
665 .RS 4
666 .Sp
667 .Vb 1
668 \& void dounwind(I32 cxix)
669 .Ve
670 .RE
671 .RS 4
672 .RE
673 .ie n .IP """my_fork""" 4
674 .el .IP \f(CWmy_fork\fR 4
675 .IX Xref "my_fork"
676 .IX Item "my_fork"
677 This is for the use of \f(CW\*(C`PerlProc_fork\*(C'\fR as a wrapper for the C library
678 \&\fBfork\fR\|(2) on some platforms to hide some platform quirks. It should not be
679 used except through \f(CW\*(C`PerlProc_fork\*(C'\fR.
680 .RS 4
681 .Sp
682 .Vb 1
683 \& Pid_t my_fork()
684 .Ve
685 .RE
686 .RS 4
687 .RE
688 .ie n .IP """PERL_CONTEXT""" 4
689 .el .IP \f(CWPERL_CONTEXT\fR 4
690 .IX Item "PERL_CONTEXT"
691 Described in perlguts.
692 .SH "COPs and Hint Hashes"
693 .IX Header "COPs and Hint Hashes"
694 There are currently no internal API items in COPs and Hint Hashes
695 .SH "Custom Operators"
696 .IX Header "Custom Operators"
697 .ie n .IP """core_prototype""" 4
698 .el .IP \f(CWcore_prototype\fR 4
699 .IX Xref "core_prototype"
700 .IX Item "core_prototype"
701 This function assigns the prototype of the named core function to \f(CW\*(C`sv\*(C'\fR, or
702 to a new mortal SV if \f(CW\*(C`sv\*(C'\fR is \f(CW\*(C`NULL\*(C'\fR. It returns the modified \f(CW\*(C`sv\*(C'\fR, or
703 \&\f(CW\*(C`NULL\*(C'\fR if the core function has no prototype. \f(CW\*(C`code\*(C'\fR is a code as returned
704 by \f(CWkeyword()\fR. It must not be equal to 0.
705 .RS 4
706 .Sp
707 .Vb 2
708 \& SV * core_prototype(SV *sv, const char *name, const int code,
709 \& int * const opnum)
710 .Ve
711 .RE
712 .RS 4
713 .RE
714 .SH "CV Handling"
715 .IX Header "CV Handling"
716 .ie n .IP """CvREFCOUNTED_ANYSV""" 4
717 .el .IP \f(CWCvREFCOUNTED_ANYSV\fR 4
718 .IX Xref "CvREFCOUNTED_ANYSV"
719 .IX Item "CvREFCOUNTED_ANYSV"
720 If true, indicates that the \f(CW\*(C`CvXSUBANY(cv).any_sv\*(C'\fR member contains an SV
721 pointer whose reference count should be decremented when the CV itself is
722 freed. In addition, \f(CWcv_clone()\fR will increment the reference count, and
723 \&\f(CWsv_dup()\fR will duplicate the entire pointed-to SV if this flag is set.
724 .Sp
725 Any CV that wraps an XSUB has an \f(CW\*(C`ANY\*(C'\fR union that the XSUB function is free
726 to use for its own purposes. It may be the case that the code wishes to store
727 an SV in the \f(CW\*(C`any_sv\*(C'\fR member of this union. By setting this flag, this SV
728 reference will be properly reclaimed or duplicated when the CV itself is.
729 .RS 4
730 .Sp
731 .Vb 1
732 \& bool CvREFCOUNTED_ANYSV(CV *cv)
733 .Ve
734 .RE
735 .RS 4
736 .RE
737 .ie n .IP """CvREFCOUNTED_ANYSV_off""" 4
738 .el .IP \f(CWCvREFCOUNTED_ANYSV_off\fR 4
739 .IX Xref "CvREFCOUNTED_ANYSV_off"
740 .IX Item "CvREFCOUNTED_ANYSV_off"
741 Helper macro to turn off the \f(CW\*(C`CvREFCOUNTED_ANYSV\*(C'\fR flag.
742 .RS 4
743 .Sp
744 .Vb 1
745 \& void CvREFCOUNTED_ANYSV_off(CV *cv)
746 .Ve
747 .RE
748 .RS 4
749 .RE
750 .ie n .IP """CvREFCOUNTED_ANYSV_on""" 4
751 .el .IP \f(CWCvREFCOUNTED_ANYSV_on\fR 4
752 .IX Xref "CvREFCOUNTED_ANYSV_on"
753 .IX Item "CvREFCOUNTED_ANYSV_on"
754 Helper macro to turn on the \f(CW\*(C`CvREFCOUNTED_ANYSV\*(C'\fR flag.
755 .RS 4
756 .Sp
757 .Vb 1
758 \& void CvREFCOUNTED_ANYSV_on(CV *cv)
759 .Ve
760 .RE
761 .RS 4
762 .RE
763 .ie n .IP """CvWEAKOUTSIDE""" 4
764 .el .IP \f(CWCvWEAKOUTSIDE\fR 4
765 .IX Xref "CvWEAKOUTSIDE"
766 .IX Item "CvWEAKOUTSIDE"
767 Each CV has a pointer, \f(CWCvOUTSIDE()\fR, to its lexically enclosing
768 CV (if any). Because pointers to anonymous sub prototypes are
769 stored in \f(CW\*(C`&\*(C'\fR pad slots, it is a possible to get a circular reference,
770 with the parent pointing to the child and vice-versa. To avoid the
771 ensuing memory leak, we do not increment the reference count of the CV
772 pointed to by \f(CW\*(C`CvOUTSIDE\*(C'\fR in the \fIone specific instance\fR that the parent
773 has a \f(CW\*(C`&\*(C'\fR pad slot pointing back to us. In this case, we set the
774 \&\f(CW\*(C`CvWEAKOUTSIDE\*(C'\fR flag in the child. This allows us to determine under what
775 circumstances we should decrement the refcount of the parent when freeing
776 the child.
777 .Sp
778 There is a further complication with non-closure anonymous subs (i.e. those
779 that do not refer to any lexicals outside that sub). In this case, the
780 anonymous prototype is shared rather than being cloned. This has the
781 consequence that the parent may be freed while there are still active
782 children, \fIe.g.\fR,
783 .Sp
784 .Vb 1
785 \& BEGIN { $a = sub { eval \*(Aq$x\*(Aq } }
786 .Ve
787 .Sp
788 In this case, the BEGIN is freed immediately after execution since there
789 are no active references to it: the anon sub prototype has
790 \&\f(CW\*(C`CvWEAKOUTSIDE\*(C'\fR set since it's not a closure, and \f(CW$a\fR points to the same
791 CV, so it doesn't contribute to BEGIN's refcount either. When \f(CW$a\fR is
792 executed, the \f(CW\*(C`eval \*(Aq$x\*(Aq\*(C'\fR causes the chain of \f(CW\*(C`CvOUTSIDE\*(C'\fRs to be followed,
793 and the freed BEGIN is accessed.
794 .Sp
795 To avoid this, whenever a CV and its associated pad is freed, any
796 \&\f(CW\*(C`&\*(C'\fR entries in the pad are explicitly removed from the pad, and if the
797 refcount of the pointed-to anon sub is still positive, then that
798 child's \f(CW\*(C`CvOUTSIDE\*(C'\fR is set to point to its grandparent. This will only
799 occur in the single specific case of a non-closure anon prototype
800 having one or more active references (such as \f(CW$a\fR above).
801 .Sp
802 One other thing to consider is that a CV may be merely undefined
803 rather than freed, eg \f(CW\*(C`undef &foo\*(C'\fR. In this case, its refcount may
804 not have reached zero, but we still delete its pad and its \f(CW\*(C`CvROOT\*(C'\fR etc.
805 Since various children may still have their \f(CW\*(C`CvOUTSIDE\*(C'\fR pointing at this
806 undefined CV, we keep its own \f(CW\*(C`CvOUTSIDE\*(C'\fR for the time being, so that
807 the chain of lexical scopes is unbroken. For example, the following
808 should print 123:
809 .Sp
810 .Vb 5
811 \& my $x = 123;
812 \& sub tmp { sub { eval \*(Aq$x\*(Aq } }
813 \& my $a = tmp();
814 \& undef &tmp;
815 \& print $a\->();
816 .Ve
817 .RS 4
818 .Sp
819 .Vb 1
820 \& bool CvWEAKOUTSIDE(CV *cv)
821 .Ve
822 .RE
823 .RS 4
824 .RE
825 .ie n .IP """docatch""" 4
826 .el .IP \f(CWdocatch\fR 4
827 .IX Xref "docatch"
828 .IX Item "docatch"
829 Interpose, for the current op and RUNOPS loop,
830 .Sp
831 .Vb 3
832 \& \- a new JMPENV stack catch frame, and
833 \& \- an inner RUNOPS loop to run all the remaining ops following the
834 \& current PL_op.
835 .Ve
836 .Sp
837 Then handle any exceptions raised while in that loop.
838 For a caught eval at this level, re-enter the loop with the specified
839 restart op (i.e. the op following the OP_LEAVETRY etc); otherwise re-throw
840 the exception.
841 .Sp
842 \&\fBdocatch()\fR is intended to be used like this:
843 .Sp
844 .Vb 4
845 \& PP(pp_entertry)
846 \& {
847 \& if (CATCH_GET)
848 \& return docatch(Perl_pp_entertry);
849 \&
850 \& ... rest of function ...
851 \& return PL_op\->op_next;
852 \& }
853 .Ve
854 .Sp
855 If a new catch frame isn't needed, the op behaves normally. Otherwise it
856 calls \fBdocatch()\fR, which recursively calls \fBpp_entertry()\fR, this time with
857 \&\fBCATCH_GET()\fR false, so the rest of the body of the entertry is run. Then
858 \&\fBdocatch()\fR calls \fBCALLRUNOPS()\fR which executes all the ops following the
859 entertry. When the loop finally finishes, control returns to \fBdocatch()\fR,
860 which pops the JMPENV and returns to the parent \fBpp_entertry()\fR, which
861 itself immediately returns. Note that *all* subsequent ops are run within
862 the inner RUNOPS loop, not just the body of the eval. For example, in
863 .Sp
864 .Vb 2
865 \& sub TIEARRAY { eval {1}; my $x }
866 \& tie @a, "main";
867 .Ve
868 .Sp
869 at the point the 'my' is executed, the C stack will look something like:
870 .Sp
871 .Vb 11
872 \& #10 main()
873 \& #9 perl_run() # JMPENV_PUSH level 1 here
874 \& #8 S_run_body()
875 \& #7 Perl_runops_standard() # main RUNOPS loop
876 \& #6 Perl_pp_tie()
877 \& #5 Perl_call_sv()
878 \& #4 Perl_runops_standard() # unguarded RUNOPS loop: no new JMPENV
879 \& #3 Perl_pp_entertry()
880 \& #2 S_docatch() # JMPENV_PUSH level 2 here
881 \& #1 Perl_runops_standard() # docatch()\*(Aqs RUNOPs loop
882 \& #0 Perl_pp_padsv()
883 .Ve
884 .Sp
885 Basically, any section of the perl core which starts a RUNOPS loop may
886 make a promise that it will catch any exceptions and restart the loop if
887 necessary. If it's not prepared to do that (like \fBcall_sv()\fR isn't), then
888 it sets \fBCATCH_GET()\fR to true, so that any later eval-like code knows to
889 set up a new handler and loop (via \fBdocatch()\fR).
890 .Sp
891 See "Exception handing" in perlinterp for further details.
892 .RS 4
893 .Sp
894 .Vb 1
895 \& OP * docatch(Perl_ppaddr_t firstpp)
896 .Ve
897 .RE
898 .RS 4
899 .RE
900 .SH Debugging
901 .IX Header "Debugging"
902 .ie n .IP """comma_aDEPTH""" 4
903 .el .IP \f(CWcomma_aDEPTH\fR 4
904 .IX Xref "comma_aDEPTH"
905 .IX Item "comma_aDEPTH"
906 Some functions when compiled under DEBUGGING take an extra final argument named
907 \&\f(CW\*(C`depth\*(C'\fR, indicating the C stack depth. This argument is omitted otherwise.
908 This macro expands to either \f(CW\*(C`,\ depth\*(C'\fR under DEBUGGING, or to nothing at
909 all when not under DEBUGGING, reducing the number of \f(CW\*(C`#ifdef\*(C'\fR's in the code.
910 .Sp
911 The program is responsible for maintaining the correct value for \f(CW\*(C`depth\*(C'\fR.
912 .RS 4
913 .Sp
914 .Vb 1
915 \& comma_aDEPTH
916 .Ve
917 .RE
918 .RS 4
919 .RE
920 .ie n .IP """comma_pDEPTH""" 4
921 .el .IP \f(CWcomma_pDEPTH\fR 4
922 .IX Xref "comma_pDEPTH"
923 .IX Item "comma_pDEPTH"
924 This is used in the prototype declarations for functions that take a "\f(CW\*(C`comma_aDEPTH\*(C'\fR"
925 final parameter, much like \f(CW\*(C`pTHX_\*(C'\fR
926 is used in functions that take a thread context initial parameter.
927 .ie n .IP """debop""" 4
928 .el .IP \f(CWdebop\fR 4
929 .IX Xref "debop"
930 .IX Item "debop"
931 Implements \fB\-Dt\fR perl command line option on OP \f(CW\*(C`o\*(C'\fR.
932 .RS 4
933 .Sp
934 .Vb 1
935 \& I32 debop(const OP *o)
936 .Ve
937 .RE
938 .RS 4
939 .RE
940 .ie n .IP """debprof""" 4
941 .el .IP \f(CWdebprof\fR 4
942 .IX Xref "debprof"
943 .IX Item "debprof"
944 Called to indicate that \f(CW\*(C`o\*(C'\fR was executed, for profiling purposes under the
945 \&\f(CW\*(C`\-DP\*(C'\fR command line option.
946 .RS 4
947 .Sp
948 .Vb 1
949 \& void debprof(const OP *o)
950 .Ve
951 .RE
952 .RS 4
953 .RE
954 .ie n .IP """debprofdump""" 4
955 .el .IP \f(CWdebprofdump\fR 4
956 .IX Xref "debprofdump"
957 .IX Item "debprofdump"
958 Dumps the contents of the data collected by the \f(CW\*(C`\-DP\*(C'\fR perl command line
959 option.
960 .RS 4
961 .Sp
962 .Vb 1
963 \& void debprofdump()
964 .Ve
965 .RE
966 .RS 4
967 .RE
968 .ie n .IP """debug_aDEPTH""" 4
969 .el .IP \f(CWdebug_aDEPTH\fR 4
970 .IX Xref "debug_aDEPTH"
971 .IX Item "debug_aDEPTH"
972 Same as "\f(CW\*(C`comma_aDEPTH\*(C'\fR" but with no leading argument. Intended for functions with
973 no normal arguments, and used by "\f(CW\*(C`comma_aDEPTH\*(C'\fR" itself.
974 .RS 4
975 .Sp
976 .Vb 1
977 \& debug_aDEPTH
978 .Ve
979 .RE
980 .RS 4
981 .RE
982 .ie n .IP """debug_pDEPTH""" 4
983 .el .IP \f(CWdebug_pDEPTH\fR 4
984 .IX Xref "debug_pDEPTH"
985 .IX Item "debug_pDEPTH"
986 Same as "\f(CW\*(C`comma_pDEPTH\*(C'\fR" but with no leading argument. Intended for functions with
987 no normal arguments, and used by "\f(CW\*(C`comma_pDEPTH\*(C'\fR" itself.
988 .RS 4
989 .Sp
990 .Vb 1
991 \& debug_pDEPTH
992 .Ve
993 .RE
994 .RS 4
995 .RE
996 .ie n .IP """free_c_backtrace""" 4
997 .el .IP \f(CWfree_c_backtrace\fR 4
998 .IX Xref "free_c_backtrace"
999 .IX Item "free_c_backtrace"
1000 Deallocates a backtrace received from get_c_backtrace.
1001 .RS 4
1002 .Sp
1003 .Vb 1
1004 \& void free_c_backtrace(Perl_c_backtrace *bt)
1005 .Ve
1006 .RE
1007 .RS 4
1008 .RE
1009 .ie n .IP """get_c_backtrace""" 4
1010 .el .IP \f(CWget_c_backtrace\fR 4
1011 .IX Xref "get_c_backtrace"
1012 .IX Item "get_c_backtrace"
1013 Collects the backtrace (aka "stacktrace") into a single linear
1014 malloced buffer, which the caller \fBmust\fR \f(CWPerl_free_c_backtrace()\fR.
1015 .Sp
1016 Scans the frames back by \f(CW\*(C`depth\ +\ skip\*(C'\fR, then drops the \f(CW\*(C`skip\*(C'\fR innermost,
1017 returning at most \f(CW\*(C`depth\*(C'\fR frames.
1018 .RS 4
1019 .Sp
1020 .Vb 1
1021 \& Perl_c_backtrace * get_c_backtrace(int max_depth, int skip)
1022 .Ve
1023 .RE
1024 .RS 4
1025 .RE
1026 .ie n .IP """PL_DBsingle""" 4
1027 .el .IP \f(CWPL_DBsingle\fR 4
1028 .IX Xref "PL_DBsingle"
1029 .IX Item "PL_DBsingle"
1030 When Perl is run in debugging mode, with the \fB\-d\fR switch, this SV is a
1031 boolean which indicates whether subs are being single-stepped.
1032 Single-stepping is automatically turned on after every step. This is the C
1033 variable which corresponds to Perl's \f(CW$DB::single\fR variable. See
1034 \&\f(CW"PL_DBsub"\fR.
1035 .Sp
1036 On threaded perls, each thread has an independent copy of this variable;
1037 each initialized at creation time with the current value of the creating
1038 thread's copy.
1039 .RS 4
1040 .Sp
1041 .Vb 1
1042 \& SV * PL_DBsingle
1043 .Ve
1044 .RE
1045 .RS 4
1046 .RE
1047 .ie n .IP """PL_DBsub""" 4
1048 .el .IP \f(CWPL_DBsub\fR 4
1049 .IX Xref "PL_DBsub"
1050 .IX Item "PL_DBsub"
1051 When Perl is run in debugging mode, with the \fB\-d\fR switch, this GV contains
1052 the SV which holds the name of the sub being debugged. This is the C
1053 variable which corresponds to Perl's \f(CW$DB::sub\fR variable. See
1054 \&\f(CW"PL_DBsingle"\fR.
1055 .Sp
1056 On threaded perls, each thread has an independent copy of this variable;
1057 each initialized at creation time with the current value of the creating
1058 thread's copy.
1059 .RS 4
1060 .Sp
1061 .Vb 1
1062 \& GV * PL_DBsub
1063 .Ve
1064 .RE
1065 .RS 4
1066 .RE
1067 .ie n .IP """PL_DBtrace""" 4
1068 .el .IP \f(CWPL_DBtrace\fR 4
1069 .IX Xref "PL_DBtrace"
1070 .IX Item "PL_DBtrace"
1071 Trace variable used when Perl is run in debugging mode, with the \fB\-d\fR
1072 switch. This is the C variable which corresponds to Perl's \f(CW$DB::trace\fR
1073 variable. See \f(CW"PL_DBsingle"\fR.
1074 .Sp
1075 On threaded perls, each thread has an independent copy of this variable;
1076 each initialized at creation time with the current value of the creating
1077 thread's copy.
1078 .RS 4
1079 .Sp
1080 .Vb 1
1081 \& SV * PL_DBtrace
1082 .Ve
1083 .RE
1084 .RS 4
1085 .RE
1086 .ie n .IP """runops_debug""" 4
1087 .el .IP \f(CWrunops_debug\fR 4
1088 .IX Item "runops_debug"
1089 Described in perlguts.
1090 .RS 4
1091 .Sp
1092 .Vb 1
1093 \& int runops_debug()
1094 .Ve
1095 .RE
1096 .RS 4
1097 .RE
1098 .ie n .IP """runops_standard""" 4
1099 .el .IP \f(CWrunops_standard\fR 4
1100 .IX Item "runops_standard"
1101 Described in perlguts.
1102 .RS 4
1103 .Sp
1104 .Vb 1
1105 \& int runops_standard()
1106 .Ve
1107 .RE
1108 .RS 4
1109 .RE
1110 .SH "Display functions"
1111 .IX Xref "PERL_PV_PRETTY_DUMP PERL_PV_PRETTY_NOCLEAR PERL_PV_PRETTY_REGPROP"
1112 .IX Header "Display functions"
1113 .ie n .IP """sv_peek""" 4
1114 .el .IP \f(CWsv_peek\fR 4
1115 .IX Xref "sv_peek"
1116 .IX Item "sv_peek"
1117 Implements \f(CW\*(C`SvPEEK\*(C'\fR
1118 .RS 4
1119 .Sp
1120 .Vb 1
1121 \& char * sv_peek(SV *sv)
1122 .Ve
1123 .RE
1124 .RS 4
1125 .RE
1126 .SH "Embedding, Threads, and Interpreter Cloning"
1127 .IX Header "Embedding, Threads, and Interpreter Cloning"
1128 .ie n .IP """cv_dump""" 4
1129 .el .IP \f(CWcv_dump\fR 4
1130 .IX Xref "cv_dump"
1131 .IX Item "cv_dump"
1132 dump the contents of a CV
1133 .RS 4
1134 .Sp
1135 .Vb 1
1136 \& void cv_dump(const CV *cv, const char *title)
1137 .Ve
1138 .RE
1139 .RS 4
1140 .RE
1141 .ie n .IP """cv_forget_slab""" 4
1142 .el .IP \f(CWcv_forget_slab\fR 4
1143 .IX Xref "cv_forget_slab"
1144 .IX Item "cv_forget_slab"
1145 When a CV has a reference count on its slab (\f(CW\*(C`CvSLABBED\*(C'\fR), it is responsible
1146 for making sure it is freed. (Hence, no two CVs should ever have a
1147 reference count on the same slab.) The CV only needs to reference the slab
1148 during compilation. Once it is compiled and \f(CW\*(C`CvROOT\*(C'\fR attached, it has
1149 finished its job, so it can forget the slab.
1150 .RS 4
1151 .Sp
1152 .Vb 1
1153 \& void cv_forget_slab(CV *cv)
1154 .Ve
1155 .RE
1156 .RS 4
1157 .RE
1158 .ie n .IP """do_dump_pad""" 4
1159 .el .IP \f(CWdo_dump_pad\fR 4
1160 .IX Xref "do_dump_pad"
1161 .IX Item "do_dump_pad"
1162 Dump the contents of a padlist
1163 .RS 4
1164 .Sp
1165 .Vb 2
1166 \& void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist,
1167 \& int full)
1168 .Ve
1169 .RE
1170 .RS 4
1171 .RE
1172 .ie n .IP """get_context""" 4
1173 .el .IP \f(CWget_context\fR 4
1174 .IX Xref "get_context"
1175 .IX Item "get_context"
1176 Implements "\f(CW\*(C`PERL_GET_CONTEXT\*(C'\fR" in perlapi, which you should use instead.
1177 .RS 4
1178 .Sp
1179 .Vb 1
1180 \& void * get_context()
1181 .Ve
1182 .RE
1183 .RS 4
1184 .RE
1185 .ie n .IP """pad_alloc_name""" 4
1186 .el .IP \f(CWpad_alloc_name\fR 4
1187 .IX Xref "pad_alloc_name"
1188 .IX Item "pad_alloc_name"
1189 Allocates a place in the currently-compiling
1190 pad (via "pad_alloc" in perlapi) and
1191 then stores a name for that entry. \f(CW\*(C`name\*(C'\fR is adopted and
1192 becomes the name entry; it must already contain the name
1193 string. \f(CW\*(C`typestash\*(C'\fR and \f(CW\*(C`ourstash\*(C'\fR and the \f(CW\*(C`padadd_STATE\*(C'\fR
1194 flag gets added to \f(CW\*(C`name\*(C'\fR.
1195 None of the other processing of "pad_add_name_pvn" in perlapi
1196 is done. Returns the offset of the allocated pad slot.
1197 .RS 4
1198 .Sp
1199 .Vb 2
1200 \& PADOFFSET pad_alloc_name(PADNAME *name, U32 flags, HV *typestash,
1201 \& HV *ourstash)
1202 .Ve
1203 .RE
1204 .RS 4
1205 .RE
1206 .ie n .IP """pad_block_start""" 4
1207 .el .IP \f(CWpad_block_start\fR 4
1208 .IX Xref "pad_block_start"
1209 .IX Item "pad_block_start"
1210 Update the pad compilation state variables on entry to a new block.
1211 .RS 4
1212 .Sp
1213 .Vb 1
1214 \& void pad_block_start(int full)
1215 .Ve
1216 .RE
1217 .RS 4
1218 .RE
1219 .ie n .IP """pad_check_dup""" 4
1220 .el .IP \f(CWpad_check_dup\fR 4
1221 .IX Xref "pad_check_dup"
1222 .IX Item "pad_check_dup"
1223 Check for duplicate declarations: report any of:
1224 .Sp
1225 .Vb 3
1226 \& * a \*(Aqmy\*(Aq in the current scope with the same name;
1227 \& * an \*(Aqour\*(Aq (anywhere in the pad) with the same name and the
1228 \& same stash as \*(Aqourstash\*(Aq
1229 .Ve
1230 .Sp
1231 \&\f(CW\*(C`is_our\*(C'\fR indicates that the name to check is an \f(CW"our"\fR declaration.
1232 .RS 4
1233 .Sp
1234 .Vb 1
1235 \& void pad_check_dup(PADNAME *name, U32 flags, const HV *ourstash)
1236 .Ve
1237 .RE
1238 .RS 4
1239 .RE
1240 .ie n .IP """pad_findlex""" 4
1241 .el .IP \f(CWpad_findlex\fR 4
1242 .IX Xref "pad_findlex"
1243 .IX Item "pad_findlex"
1244 Find a named lexical anywhere in a chain of nested pads. Add fake entries
1245 in the inner pads if it's found in an outer one.
1246 .Sp
1247 Returns the offset in the bottom pad of the lex or the fake lex.
1248 \&\f(CW\*(C`cv\*(C'\fR is the CV in which to start the search, and seq is the current \f(CW\*(C`cop_seq\*(C'\fR
1249 to match against. If \f(CW\*(C`warn\*(C'\fR is true, print appropriate warnings. The \f(CW\*(C`out_\*(C'\fR*
1250 vars return values, and so are pointers to where the returned values
1251 should be stored. \f(CW\*(C`out_capture\*(C'\fR, if non-null, requests that the innermost
1252 instance of the lexical is captured; \f(CW\*(C`out_name\*(C'\fR is set to the innermost
1253 matched pad name or fake pad name; \f(CW\*(C`out_flags\*(C'\fR returns the flags normally
1254 associated with the \f(CW\*(C`PARENT_FAKELEX_FLAGS\*(C'\fR field of a fake pad name.
1255 .Sp
1256 Note that \f(CWpad_findlex()\fR is recursive; it recurses up the chain of CVs,
1257 then comes back down, adding fake entries
1258 as it goes. It has to be this way
1259 because fake names in anon prototypes have to store in \f(CW\*(C`xpadn_low\*(C'\fR the
1260 index into the parent pad.
1261 .RS 4
1262 .Sp
1263 .Vb 4
1264 \& PADOFFSET pad_findlex(const char *namepv, STRLEN namelen,
1265 \& U32 flags, const CV *cv, U32 seq, int warn,
1266 \& SV **out_capture, PADNAME **out_name,
1267 \& int *out_flags)
1268 .Ve
1269 .RE
1270 .RS 4
1271 .RE
1272 .ie n .IP """pad_fixup_inner_anons""" 4
1273 .el .IP \f(CWpad_fixup_inner_anons\fR 4
1274 .IX Xref "pad_fixup_inner_anons"
1275 .IX Item "pad_fixup_inner_anons"
1276 For any anon CVs in the pad, change \f(CW\*(C`CvOUTSIDE\*(C'\fR of that CV from
1277 \&\f(CW\*(C`old_cv\*(C'\fR to \f(CW\*(C`new_cv\*(C'\fR if necessary. Needed when a newly-compiled CV has to be
1278 moved to a pre-existing CV struct.
1279 .RS 4
1280 .Sp
1281 .Vb 2
1282 \& void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv,
1283 \& CV *new_cv)
1284 .Ve
1285 .RE
1286 .RS 4
1287 .RE
1288 .ie n .IP """pad_free""" 4
1289 .el .IP \f(CWpad_free\fR 4
1290 .IX Xref "pad_free"
1291 .IX Item "pad_free"
1292 Free the SV at offset po in the current pad.
1293 .RS 4
1294 .Sp
1295 .Vb 1
1296 \& void pad_free(PADOFFSET po)
1297 .Ve
1298 .RE
1299 .RS 4
1300 .RE
1301 .ie n .IP """pad_leavemy""" 4
1302 .el .IP \f(CWpad_leavemy\fR 4
1303 .IX Xref "pad_leavemy"
1304 .IX Item "pad_leavemy"
1305 Cleanup at end of scope during compilation: set the max seq number for
1306 lexicals in this scope and warn of any lexicals that never got introduced.
1307 .RS 4
1308 .Sp
1309 .Vb 1
1310 \& OP * pad_leavemy()
1311 .Ve
1312 .RE
1313 .RS 4
1314 .RE
1315 .ie n .IP """padlist_dup""" 4
1316 .el .IP \f(CWpadlist_dup\fR 4
1317 .IX Xref "padlist_dup"
1318 .IX Item "padlist_dup"
1319 Duplicates a pad.
1320 .RS 4
1321 .Sp
1322 .Vb 1
1323 \& PADLIST * padlist_dup(PADLIST *srcpad, CLONE_PARAMS *param)
1324 .Ve
1325 .RE
1326 .RS 4
1327 .RE
1328 .ie n .IP """padname_dup""" 4
1329 .el .IP \f(CWpadname_dup\fR 4
1330 .IX Xref "padname_dup"
1331 .IX Item "padname_dup"
1332 Duplicates a pad name.
1333 .RS 4
1334 .Sp
1335 .Vb 1
1336 \& PADNAME * padname_dup(PADNAME *src, CLONE_PARAMS *param)
1337 .Ve
1338 .RE
1339 .RS 4
1340 .RE
1341 .ie n .IP """padnamelist_dup""" 4
1342 .el .IP \f(CWpadnamelist_dup\fR 4
1343 .IX Xref "padnamelist_dup"
1344 .IX Item "padnamelist_dup"
1345 Duplicates a pad name list.
1346 .RS 4
1347 .Sp
1348 .Vb 2
1349 \& PADNAMELIST * padnamelist_dup(PADNAMELIST *srcpad,
1350 \& CLONE_PARAMS *param)
1351 .Ve
1352 .RE
1353 .RS 4
1354 .RE
1355 .ie n .IP """pad_push""" 4
1356 .el .IP \f(CWpad_push\fR 4
1357 .IX Xref "pad_push"
1358 .IX Item "pad_push"
1359 Push a new pad frame onto the padlist, unless there's already a pad at
1360 this depth, in which case don't bother creating a new one. Then give
1361 the new pad an \f(CW@_\fR in slot zero.
1362 .RS 4
1363 .Sp
1364 .Vb 1
1365 \& void pad_push(PADLIST *padlist, int depth)
1366 .Ve
1367 .RE
1368 .RS 4
1369 .RE
1370 .ie n .IP """pad_reset""" 4
1371 .el .IP \f(CWpad_reset\fR 4
1372 .IX Xref "pad_reset"
1373 .IX Item "pad_reset"
1374 Mark all the current temporaries for reuse
1375 .RS 4
1376 .Sp
1377 .Vb 1
1378 \& void pad_reset()
1379 .Ve
1380 .RE
1381 .RS 4
1382 .RE
1383 .ie n .IP """pad_setsv""" 4
1384 .el .IP \f(CWpad_setsv\fR 4
1385 .IX Xref "pad_setsv"
1386 .IX Item "pad_setsv"
1387 Set the value at offset \f(CW\*(C`po\*(C'\fR in the current (compiling or executing) pad.
1388 Use the macro \f(CWPAD_SETSV()\fR rather than calling this function directly.
1389 .RS 4
1390 .Sp
1391 .Vb 1
1392 \& void pad_setsv(PADOFFSET po, SV *sv)
1393 .Ve
1394 .RE
1395 .RS 4
1396 .RE
1397 .ie n .IP """pad_sv""" 4
1398 .el .IP \f(CWpad_sv\fR 4
1399 .IX Xref "pad_sv"
1400 .IX Item "pad_sv"
1401 Get the value at offset \f(CW\*(C`po\*(C'\fR in the current (compiling or executing) pad.
1402 Use macro \f(CW\*(C`PAD_SV\*(C'\fR instead of calling this function directly.
1403 .RS 4
1404 .Sp
1405 .Vb 1
1406 \& SV * pad_sv(PADOFFSET po)
1407 .Ve
1408 .RE
1409 .RS 4
1410 .RE
1411 .ie n .IP """pad_swipe""" 4
1412 .el .IP \f(CWpad_swipe\fR 4
1413 .IX Xref "pad_swipe"
1414 .IX Item "pad_swipe"
1415 Abandon the tmp in the current pad at offset \f(CW\*(C`po\*(C'\fR and replace with a
1416 new one.
1417 .RS 4
1418 .Sp
1419 .Vb 1
1420 \& void pad_swipe(PADOFFSET po, bool refadjust)
1421 .Ve
1422 .RE
1423 .RS 4
1424 .RE
1425 .ie n .IP """set_context""" 4
1426 .el .IP \f(CWset_context\fR 4
1427 .IX Xref "set_context"
1428 .IX Item "set_context"
1429 Implements "\f(CW\*(C`PERL_SET_CONTEXT\*(C'\fR" in perlapi, which you should use instead.
1430 .RS 4
1431 .Sp
1432 .Vb 1
1433 \& void set_context(void *t)
1434 .Ve
1435 .RE
1436 .RS 4
1437 .RE
1438 .ie n .IP """si_dup""" 4
1439 .el .IP \f(CWsi_dup\fR 4
1440 .IX Xref "si_dup"
1441 .IX Item "si_dup"
1442 Duplicate a stack info structure, returning a pointer to the cloned object.
1443 .RS 4
1444 .Sp
1445 .Vb 1
1446 \& PERL_SI * si_dup(PERL_SI *si, CLONE_PARAMS *param)
1447 .Ve
1448 .RE
1449 .RS 4
1450 .RE
1451 .ie n .IP """ss_dup""" 4
1452 .el .IP \f(CWss_dup\fR 4
1453 .IX Xref "ss_dup"
1454 .IX Item "ss_dup"
1455 Duplicate the save stack, returning a pointer to the cloned object.
1456 .RS 4
1457 .Sp
1458 .Vb 1
1459 \& ANY * ss_dup(PerlInterpreter *proto_perl, CLONE_PARAMS *param)
1460 .Ve
1461 .RE
1462 .RS 4
1463 .RE
1464 .SH Errno
1465 .IX Header "Errno"
1466 .ie n .IP """dSAVEDERRNO""" 4
1467 .el .IP \f(CWdSAVEDERRNO\fR 4
1468 .IX Xref "dSAVEDERRNO"
1469 .IX Item "dSAVEDERRNO"
1470 Declare variables needed to save \f(CW\*(C`errno\*(C'\fR and any operating system
1471 specific error number.
1472 .RS 4
1473 .Sp
1474 .Vb 1
1475 \& void dSAVEDERRNO
1476 .Ve
1477 .RE
1478 .RS 4
1479 .RE
1480 .ie n .IP """dSAVE_ERRNO""" 4
1481 .el .IP \f(CWdSAVE_ERRNO\fR 4
1482 .IX Xref "dSAVE_ERRNO"
1483 .IX Item "dSAVE_ERRNO"
1484 Declare variables needed to save \f(CW\*(C`errno\*(C'\fR and any operating system
1485 specific error number, and save them for optional later restoration
1486 by \f(CW\*(C`RESTORE_ERRNO\*(C'\fR.
1487 .RS 4
1488 .Sp
1489 .Vb 1
1490 \& void dSAVE_ERRNO
1491 .Ve
1492 .RE
1493 .RS 4
1494 .RE
1495 .ie n .IP """RESTORE_ERRNO""" 4
1496 .el .IP \f(CWRESTORE_ERRNO\fR 4
1497 .IX Xref "RESTORE_ERRNO"
1498 .IX Item "RESTORE_ERRNO"
1499 Restore \f(CW\*(C`errno\*(C'\fR and any operating system specific error number that
1500 was saved by \f(CW\*(C`dSAVE_ERRNO\*(C'\fR or \f(CW\*(C`RESTORE_ERRNO\*(C'\fR.
1501 .RS 4
1502 .Sp
1503 .Vb 1
1504 \& void RESTORE_ERRNO
1505 .Ve
1506 .RE
1507 .RS 4
1508 .RE
1509 .ie n .IP """SAVE_ERRNO""" 4
1510 .el .IP \f(CWSAVE_ERRNO\fR 4
1511 .IX Xref "SAVE_ERRNO"
1512 .IX Item "SAVE_ERRNO"
1513 Save \f(CW\*(C`errno\*(C'\fR and any operating system specific error number for
1514 optional later restoration by \f(CW\*(C`RESTORE_ERRNO\*(C'\fR. Requires
1515 \&\f(CW\*(C`dSAVEDERRNO\*(C'\fR or \f(CW\*(C`dSAVE_ERRNO\*(C'\fR in scope.
1516 .RS 4
1517 .Sp
1518 .Vb 1
1519 \& void SAVE_ERRNO
1520 .Ve
1521 .RE
1522 .RS 4
1523 .RE
1524 .ie n .IP """SETERRNO""" 4
1525 .el .IP \f(CWSETERRNO\fR 4
1526 .IX Xref "SETERRNO"
1527 .IX Item "SETERRNO"
1528 Set \f(CW\*(C`errno\*(C'\fR, and on VMS set \f(CW\*(C`vaxc$errno\*(C'\fR.
1529 .RS 4
1530 .Sp
1531 .Vb 1
1532 \& void SETERRNO(int errcode, int vmserrcode)
1533 .Ve
1534 .RE
1535 .RS 4
1536 .RE
1537 .SH "Exception Handling (simple) Macros"
1538 .IX Header "Exception Handling (simple) Macros"
1539 There are currently no internal API items in Exception Handling (simple) Macros
1540 .SH "Filesystem configuration values"
1541 .IX Header "Filesystem configuration values"
1542 There are currently no internal API items in Filesystem configuration values
1543 .SH "Floating point"
1544 .IX Header "Floating point"
1545 There are currently no internal API items in Floating point
1546 .SH "General Configuration"
1547 .IX Header "General Configuration"
1548 There are currently no internal API items in General Configuration
1549 .SH "Global Variables"
1550 .IX Header "Global Variables"
1551 There are currently no internal API items in Global Variables
1552 .SH "GV Handling and Stashes"
1553 .IX Xref "GV_CACHE_ONLY"
1554 .IX Header "GV Handling and Stashes"
1555 .ie n .IP """amagic_applies""" 4
1556 .el .IP \f(CWamagic_applies\fR 4
1557 .IX Xref "amagic_applies"
1558 .IX Item "amagic_applies"
1559 Check \f(CW\*(C`sv\*(C'\fR to see if the overloaded (active magic) operation \f(CW\*(C`method\*(C'\fR
1560 applies to it. If the sv is not SvROK or it is not an object then returns
1561 false, otherwise checks if the object is blessed into a class supporting
1562 overloaded operations, and returns true if a call to \fBamagic_call()\fR with
1563 this SV and the given method would trigger an amagic operation, including
1564 via the overload fallback rules or via nomethod. Thus a call like:
1565 .Sp
1566 .Vb 1
1567 \& amagic_applies(sv, string_amg, AMG_unary)
1568 .Ve
1569 .Sp
1570 would return true for an object with overloading set up in any of the
1571 following ways:
1572 .Sp
1573 .Vb 2
1574 \& use overload q("") => sub { ... };
1575 \& use overload q(0+) => sub { ... }, fallback => 1;
1576 .Ve
1577 .Sp
1578 and could be used to tell if a given object would stringify to something
1579 other than the normal default ref stringification.
1580 .Sp
1581 Note that the fact that this function returns TRUE does not mean you
1582 can succesfully perform the operation with \fBamagic_call()\fR, for instance
1583 any overloaded method might throw a fatal exception, however if this
1584 function returns FALSE you can be confident that it will NOT perform
1585 the given overload operation.
1586 .Sp
1587 \&\f(CW\*(C`method\*(C'\fR is an integer enum, one of the values found in \fIoverload.h\fR,
1588 for instance \f(CW\*(C`string_amg\*(C'\fR.
1589 .Sp
1590 \&\f(CW\*(C`flags\*(C'\fR should be set to AMG_unary for unary operations.
1591 .RS 4
1592 .Sp
1593 .Vb 1
1594 \& bool amagic_applies(SV *sv, int method, int flags)
1595 .Ve
1596 .RE
1597 .RS 4
1598 .RE
1599 .ie n .IP """gp_dup""" 4
1600 .el .IP \f(CWgp_dup\fR 4
1601 .IX Xref "gp_dup"
1602 .IX Item "gp_dup"
1603 Duplicate a typeglob, returning a pointer to the cloned object.
1604 .RS 4
1605 .Sp
1606 .Vb 1
1607 \& GP * gp_dup(GP * const gp, CLONE_PARAMS * const param)
1608 .Ve
1609 .RE
1610 .RS 4
1611 .RE
1612 .ie n .IP """gv_handler""" 4
1613 .el .IP \f(CWgv_handler\fR 4
1614 .IX Xref "gv_handler"
1615 .IX Item "gv_handler"
1616 Implements \f(CW\*(C`StashHANDLER\*(C'\fR, which you should use instead
1617 .RS 4
1618 .Sp
1619 .Vb 1
1620 \& CV * gv_handler(HV *stash, I32 id)
1621 .Ve
1622 .RE
1623 .RS 4
1624 .RE
1625 .ie n .IP """gv_stashsvpvn_cached""" 4
1626 .el .IP \f(CWgv_stashsvpvn_cached\fR 4
1627 .IX Xref "gv_stashsvpvn_cached"
1628 .IX Item "gv_stashsvpvn_cached"
1629 Returns a pointer to the stash for a specified package, possibly
1630 cached. Implements both "\f(CW\*(C`gv_stashpvn\*(C'\fR" in perlapi and
1631 "\f(CW\*(C`gv_stashsv\*(C'\fR" in perlapi.
1632 .Sp
1633 Requires one of either \f(CW\*(C`namesv\*(C'\fR or \f(CW\*(C`namepv\*(C'\fR to be non-null.
1634 .Sp
1635 If the flag \f(CW\*(C`GV_CACHE_ONLY\*(C'\fR is set, return the stash only if found in the
1636 cache; see "\f(CW\*(C`gv_stashpvn\*(C'\fR" in perlapi for details on the other \f(CW\*(C`flags\*(C'\fR.
1637 .Sp
1638 Note it is strongly preferred for \f(CW\*(C`namesv\*(C'\fR to be non-null, for performance
1639 reasons.
1640 .RS 4
1641 .Sp
1642 .Vb 2
1643 \& HV * gv_stashsvpvn_cached(SV *namesv, const char *name,
1644 \& U32 namelen, I32 flags)
1645 .Ve
1646 .RE
1647 .RS 4
1648 .RE
1649 .ie n .IP """gv_try_downgrade""" 4
1650 .el .IP \f(CWgv_try_downgrade\fR 4
1651 .IX Xref "gv_try_downgrade"
1652 .IX Item "gv_try_downgrade"
1653 NOTE: \f(CW\*(C`gv_try_downgrade\*(C'\fR is \fBexperimental\fR and may change or be
1654 removed without notice.
1655 .Sp
1656 If the typeglob \f(CW\*(C`gv\*(C'\fR can be expressed more succinctly, by having
1657 something other than a real GV in its place in the stash, replace it
1658 with the optimised form. Basic requirements for this are that \f(CW\*(C`gv\*(C'\fR
1659 is a real typeglob, is sufficiently ordinary, and is only referenced
1660 from its package. This function is meant to be used when a GV has been
1661 looked up in part to see what was there, causing upgrading, but based
1662 on what was found it turns out that the real GV isn't required after all.
1663 .Sp
1664 If \f(CW\*(C`gv\*(C'\fR is a completely empty typeglob, it is deleted from the stash.
1665 .Sp
1666 If \f(CW\*(C`gv\*(C'\fR is a typeglob containing only a sufficiently-ordinary constant
1667 sub, the typeglob is replaced with a scalar-reference placeholder that
1668 more compactly represents the same thing.
1669 .RS 4
1670 .Sp
1671 .Vb 1
1672 \& void gv_try_downgrade(GV *gv)
1673 .Ve
1674 .RE
1675 .RS 4
1676 .RE
1677 .SH "Hook manipulation"
1678 .IX Header "Hook manipulation"
1679 There are currently no internal API items in Hook manipulation
1680 .SH "HV Handling"
1681 .IX Xref "HvNAME_get"
1682 .IX Header "HV Handling"
1683 .ie n .IP """hv_eiter_p""" 4
1684 .el .IP \f(CWhv_eiter_p\fR 4
1685 .IX Xref "hv_eiter_p"
1686 .IX Item "hv_eiter_p"
1687 Implements \f(CW\*(C`HvEITER\*(C'\fR which you should use instead.
1688 .Sp
1689 NOTE: \f(CW\*(C`hv_eiter_p\*(C'\fR must be explicitly called as
1690 \&\f(CW\*(C`Perl_hv_eiter_p\*(C'\fR
1691 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
1692 .RS 4
1693 .Sp
1694 .Vb 1
1695 \& HE ** Perl_hv_eiter_p(pTHX_ HV *hv)
1696 .Ve
1697 .RE
1698 .RS 4
1699 .RE
1700 .ie n .IP """hv_eiter_set""" 4
1701 .el .IP \f(CWhv_eiter_set\fR 4
1702 .IX Xref "hv_eiter_set"
1703 .IX Item "hv_eiter_set"
1704 Implements \f(CW\*(C`HvEITER_set\*(C'\fR which you should use instead.
1705 .Sp
1706 NOTE: \f(CW\*(C`hv_eiter_set\*(C'\fR must be explicitly called as
1707 \&\f(CW\*(C`Perl_hv_eiter_set\*(C'\fR
1708 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
1709 .RS 4
1710 .Sp
1711 .Vb 1
1712 \& void Perl_hv_eiter_set(pTHX_ HV *hv, HE *eiter)
1713 .Ve
1714 .RE
1715 .RS 4
1716 .RE
1717 .ie n .IP """hv_ename_add""" 4
1718 .el .IP \f(CWhv_ename_add\fR 4
1719 .IX Xref "hv_ename_add"
1720 .IX Item "hv_ename_add"
1721 Adds a name to a stash's internal list of effective names. See
1722 \&\f(CW"hv_ename_delete"\fR.
1723 .Sp
1724 This is called when a stash is assigned to a new location in the symbol
1725 table.
1726 .RS 4
1727 .Sp
1728 .Vb 1
1729 \& void hv_ename_add(HV *hv, const char *name, U32 len, U32 flags)
1730 .Ve
1731 .RE
1732 .RS 4
1733 .RE
1734 .ie n .IP """hv_ename_delete""" 4
1735 .el .IP \f(CWhv_ename_delete\fR 4
1736 .IX Xref "hv_ename_delete"
1737 .IX Item "hv_ename_delete"
1738 Removes a name from a stash's internal list of effective names. If this is
1739 the name returned by \f(CW\*(C`HvENAME\*(C'\fR, then another name in the list will take
1740 its place (\f(CW\*(C`HvENAME\*(C'\fR will use it).
1741 .Sp
1742 This is called when a stash is deleted from the symbol table.
1743 .RS 4
1744 .Sp
1745 .Vb 2
1746 \& void hv_ename_delete(HV *hv, const char *name, U32 len,
1747 \& U32 flags)
1748 .Ve
1749 .RE
1750 .RS 4
1751 .RE
1752 .ie n .IP """hv_fill""" 4
1753 .el .IP \f(CWhv_fill\fR 4
1754 .IX Xref "hv_fill"
1755 .IX Item "hv_fill"
1756 Returns the number of hash buckets that happen to be in use.
1757 .Sp
1758 This function implements the \f(CW\*(C`HvFILL\*(C'\fR macro which you should
1759 use instead.
1760 .Sp
1761 As of perl 5.25 this function is used only for debugging
1762 purposes, and the number of used hash buckets is not
1763 in any way cached, thus this function can be costly
1764 to execute as it must iterate over all the buckets in the
1765 hash.
1766 .Sp
1767 NOTE: \f(CW\*(C`hv_fill\*(C'\fR must be explicitly called as
1768 \&\f(CW\*(C`Perl_hv_fill\*(C'\fR
1769 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
1770 .RS 4
1771 .Sp
1772 .Vb 1
1773 \& STRLEN Perl_hv_fill(pTHX_ HV * const hv)
1774 .Ve
1775 .RE
1776 .RS 4
1777 .RE
1778 .ie n .IP """hv_placeholders_get""" 4
1779 .el .IP \f(CWhv_placeholders_get\fR 4
1780 .IX Xref "hv_placeholders_get"
1781 .IX Item "hv_placeholders_get"
1782 Implements \f(CW\*(C`HvPLACEHOLDERS_get\*(C'\fR, which you should use instead.
1783 .Sp
1784 NOTE: \f(CW\*(C`hv_placeholders_get\*(C'\fR must be explicitly called as
1785 \&\f(CW\*(C`Perl_hv_placeholders_get\*(C'\fR
1786 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
1787 .RS 4
1788 .Sp
1789 .Vb 1
1790 \& I32 Perl_hv_placeholders_get(pTHX_ const HV *hv)
1791 .Ve
1792 .RE
1793 .RS 4
1794 .RE
1795 .ie n .IP """hv_placeholders_set""" 4
1796 .el .IP \f(CWhv_placeholders_set\fR 4
1797 .IX Xref "hv_placeholders_set"
1798 .IX Item "hv_placeholders_set"
1799 Implements \f(CW\*(C`HvPLACEHOLDERS_set\*(C'\fR, which you should use instead.
1800 .Sp
1801 NOTE: \f(CW\*(C`hv_placeholders_set\*(C'\fR must be explicitly called as
1802 \&\f(CW\*(C`Perl_hv_placeholders_set\*(C'\fR
1803 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
1804 .RS 4
1805 .Sp
1806 .Vb 1
1807 \& void Perl_hv_placeholders_set(pTHX_ HV *hv, I32 ph)
1808 .Ve
1809 .RE
1810 .RS 4
1811 .RE
1812 .ie n .IP """hv_riter_p""" 4
1813 .el .IP \f(CWhv_riter_p\fR 4
1814 .IX Xref "hv_riter_p"
1815 .IX Item "hv_riter_p"
1816 Implements \f(CW\*(C`HvRITER\*(C'\fR which you should use instead.
1817 .Sp
1818 NOTE: \f(CW\*(C`hv_riter_p\*(C'\fR must be explicitly called as
1819 \&\f(CW\*(C`Perl_hv_riter_p\*(C'\fR
1820 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
1821 .RS 4
1822 .Sp
1823 .Vb 1
1824 \& I32 * Perl_hv_riter_p(pTHX_ HV *hv)
1825 .Ve
1826 .RE
1827 .RS 4
1828 .RE
1829 .ie n .IP """hv_riter_set""" 4
1830 .el .IP \f(CWhv_riter_set\fR 4
1831 .IX Xref "hv_riter_set"
1832 .IX Item "hv_riter_set"
1833 Implements \f(CW\*(C`HvRITER_set\*(C'\fR which you should use instead.
1834 .Sp
1835 NOTE: \f(CW\*(C`hv_riter_set\*(C'\fR must be explicitly called as
1836 \&\f(CW\*(C`Perl_hv_riter_set\*(C'\fR
1837 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
1838 .RS 4
1839 .Sp
1840 .Vb 1
1841 \& void Perl_hv_riter_set(pTHX_ HV *hv, I32 riter)
1842 .Ve
1843 .RE
1844 .RS 4
1845 .RE
1846 .ie n .IP """refcounted_he_chain_2hv""" 4
1847 .el .IP \f(CWrefcounted_he_chain_2hv\fR 4
1848 .IX Xref "refcounted_he_chain_2hv"
1849 .IX Item "refcounted_he_chain_2hv"
1850 Generates and returns a \f(CW\*(C`HV *\*(C'\fR representing the content of a
1851 \&\f(CW\*(C`refcounted_he\*(C'\fR chain.
1852 \&\f(CW\*(C`flags\*(C'\fR is currently unused and must be zero.
1853 .RS 4
1854 .Sp
1855 .Vb 2
1856 \& HV * refcounted_he_chain_2hv(const struct refcounted_he *c,
1857 \& U32 flags)
1858 .Ve
1859 .RE
1860 .RS 4
1861 .RE
1862 .ie n .IP """refcounted_he_fetch_pv""" 4
1863 .el .IP \f(CWrefcounted_he_fetch_pv\fR 4
1864 .IX Xref "refcounted_he_fetch_pv"
1865 .IX Item "refcounted_he_fetch_pv"
1866 Like "refcounted_he_fetch_pvn", but takes a nul-terminated string
1867 instead of a string/length pair.
1868 .RS 4
1869 .Sp
1870 .Vb 2
1871 \& SV * refcounted_he_fetch_pv(const struct refcounted_he *chain,
1872 \& const char *key, U32 hash, U32 flags)
1873 .Ve
1874 .RE
1875 .RS 4
1876 .RE
1877 .ie n .IP """refcounted_he_fetch_pvn""" 4
1878 .el .IP \f(CWrefcounted_he_fetch_pvn\fR 4
1879 .IX Xref "refcounted_he_fetch_pvn"
1880 .IX Item "refcounted_he_fetch_pvn"
1881 Search along a \f(CW\*(C`refcounted_he\*(C'\fR chain for an entry with the key specified
1882 by \f(CW\*(C`keypv\*(C'\fR and \f(CW\*(C`keylen\*(C'\fR. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`REFCOUNTED_HE_KEY_UTF8\*(C'\fR
1883 bit set, the key octets are interpreted as UTF\-8, otherwise they
1884 are interpreted as Latin\-1. \f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key
1885 string, or zero if it has not been precomputed. Returns a mortal scalar
1886 representing the value associated with the key, or \f(CW&PL_sv_placeholder\fR
1887 if there is no value associated with the key.
1888 .RS 4
1889 .Sp
1890 .Vb 3
1891 \& SV * refcounted_he_fetch_pvn(const struct refcounted_he *chain,
1892 \& const char *keypv, STRLEN keylen,
1893 \& U32 hash, U32 flags)
1894 .Ve
1895 .RE
1896 .RS 4
1897 .RE
1898 .ie n .IP """refcounted_he_fetch_pvs""" 4
1899 .el .IP \f(CWrefcounted_he_fetch_pvs\fR 4
1900 .IX Xref "refcounted_he_fetch_pvs"
1901 .IX Item "refcounted_he_fetch_pvs"
1902 Like "refcounted_he_fetch_pvn", but takes a literal string
1903 instead of a string/length pair, and no precomputed hash.
1904 .RS 4
1905 .Sp
1906 .Vb 2
1907 \& SV * refcounted_he_fetch_pvs(const struct refcounted_he *chain,
1908 \& "key", U32 flags)
1909 .Ve
1910 .RE
1911 .RS 4
1912 .RE
1913 .ie n .IP """refcounted_he_fetch_sv""" 4
1914 .el .IP \f(CWrefcounted_he_fetch_sv\fR 4
1915 .IX Xref "refcounted_he_fetch_sv"
1916 .IX Item "refcounted_he_fetch_sv"
1917 Like "refcounted_he_fetch_pvn", but takes a Perl scalar instead of a
1918 string/length pair.
1919 .RS 4
1920 .Sp
1921 .Vb 2
1922 \& SV * refcounted_he_fetch_sv(const struct refcounted_he *chain,
1923 \& SV *key, U32 hash, U32 flags)
1924 .Ve
1925 .RE
1926 .RS 4
1927 .RE
1928 .ie n .IP """refcounted_he_free""" 4
1929 .el .IP \f(CWrefcounted_he_free\fR 4
1930 .IX Xref "refcounted_he_free"
1931 .IX Item "refcounted_he_free"
1932 Decrements the reference count of a \f(CW\*(C`refcounted_he\*(C'\fR by one. If the
1933 reference count reaches zero the structure's memory is freed, which
1934 (recursively) causes a reduction of its parent \f(CW\*(C`refcounted_he\*(C'\fR's
1935 reference count. It is safe to pass a null pointer to this function:
1936 no action occurs in this case.
1937 .RS 4
1938 .Sp
1939 .Vb 1
1940 \& void refcounted_he_free(struct refcounted_he *he)
1941 .Ve
1942 .RE
1943 .RS 4
1944 .RE
1945 .ie n .IP """refcounted_he_inc""" 4
1946 .el .IP \f(CWrefcounted_he_inc\fR 4
1947 .IX Xref "refcounted_he_inc"
1948 .IX Item "refcounted_he_inc"
1949 Increment the reference count of a \f(CW\*(C`refcounted_he\*(C'\fR. The pointer to the
1950 \&\f(CW\*(C`refcounted_he\*(C'\fR is also returned. It is safe to pass a null pointer
1951 to this function: no action occurs and a null pointer is returned.
1952 .RS 4
1953 .Sp
1954 .Vb 2
1955 \& struct refcounted_he * refcounted_he_inc(
1956 \& struct refcounted_he *he)
1957 .Ve
1958 .RE
1959 .RS 4
1960 .RE
1961 .ie n .IP """refcounted_he_new_pv""" 4
1962 .el .IP \f(CWrefcounted_he_new_pv\fR 4
1963 .IX Xref "refcounted_he_new_pv"
1964 .IX Item "refcounted_he_new_pv"
1965 Like "refcounted_he_new_pvn", but takes a nul-terminated string instead
1966 of a string/length pair.
1967 .RS 4
1968 .Sp
1969 .Vb 4
1970 \& struct refcounted_he * refcounted_he_new_pv(
1971 \& struct refcounted_he *parent,
1972 \& const char *key, U32 hash,
1973 \& SV *value, U32 flags)
1974 .Ve
1975 .RE
1976 .RS 4
1977 .RE
1978 .ie n .IP """refcounted_he_new_pvn""" 4
1979 .el .IP \f(CWrefcounted_he_new_pvn\fR 4
1980 .IX Xref "refcounted_he_new_pvn"
1981 .IX Item "refcounted_he_new_pvn"
1982 Creates a new \f(CW\*(C`refcounted_he\*(C'\fR. This consists of a single key/value
1983 pair and a reference to an existing \f(CW\*(C`refcounted_he\*(C'\fR chain (which may
1984 be empty), and thus forms a longer chain. When using the longer chain,
1985 the new key/value pair takes precedence over any entry for the same key
1986 further along the chain.
1987 .Sp
1988 The new key is specified by \f(CW\*(C`keypv\*(C'\fR and \f(CW\*(C`keylen\*(C'\fR. If \f(CW\*(C`flags\*(C'\fR has
1989 the \f(CW\*(C`REFCOUNTED_HE_KEY_UTF8\*(C'\fR bit set, the key octets are interpreted
1990 as UTF\-8, otherwise they are interpreted as Latin\-1. \f(CW\*(C`hash\*(C'\fR is
1991 a precomputed hash of the key string, or zero if it has not been
1992 precomputed.
1993 .Sp
1994 \&\f(CW\*(C`value\*(C'\fR is the scalar value to store for this key. \f(CW\*(C`value\*(C'\fR is copied
1995 by this function, which thus does not take ownership of any reference
1996 to it, and later changes to the scalar will not be reflected in the
1997 value visible in the \f(CW\*(C`refcounted_he\*(C'\fR. Complex types of scalar will not
1998 be stored with referential integrity, but will be coerced to strings.
1999 \&\f(CW\*(C`value\*(C'\fR may be either null or \f(CW&PL_sv_placeholder\fR to indicate that no
2000 value is to be associated with the key; this, as with any non-null value,
2001 takes precedence over the existence of a value for the key further along
2002 the chain.
2003 .Sp
2004 \&\f(CW\*(C`parent\*(C'\fR points to the rest of the \f(CW\*(C`refcounted_he\*(C'\fR chain to be
2005 attached to the new \f(CW\*(C`refcounted_he\*(C'\fR. This function takes ownership
2006 of one reference to \f(CW\*(C`parent\*(C'\fR, and returns one reference to the new
2007 \&\f(CW\*(C`refcounted_he\*(C'\fR.
2008 .RS 4
2009 .Sp
2010 .Vb 5
2011 \& struct refcounted_he * refcounted_he_new_pvn(
2012 \& struct refcounted_he *parent,
2013 \& const char *keypv,
2014 \& STRLEN keylen, U32 hash,
2015 \& SV *value, U32 flags)
2016 .Ve
2017 .RE
2018 .RS 4
2019 .RE
2020 .ie n .IP """refcounted_he_new_pvs""" 4
2021 .el .IP \f(CWrefcounted_he_new_pvs\fR 4
2022 .IX Xref "refcounted_he_new_pvs"
2023 .IX Item "refcounted_he_new_pvs"
2024 Like "refcounted_he_new_pvn", but takes a literal string
2025 instead of a string/length pair, and no precomputed hash.
2026 .RS 4
2027 .Sp
2028 .Vb 3
2029 \& struct refcounted_he * refcounted_he_new_pvs(
2030 \& struct refcounted_he *parent,
2031 \& "key", SV *value, U32 flags)
2032 .Ve
2033 .RE
2034 .RS 4
2035 .RE
2036 .ie n .IP """refcounted_he_new_sv""" 4
2037 .el .IP \f(CWrefcounted_he_new_sv\fR 4
2038 .IX Xref "refcounted_he_new_sv"
2039 .IX Item "refcounted_he_new_sv"
2040 Like "refcounted_he_new_pvn", but takes a Perl scalar instead of a
2041 string/length pair.
2042 .RS 4
2043 .Sp
2044 .Vb 4
2045 \& struct refcounted_he * refcounted_he_new_sv(
2046 \& struct refcounted_he *parent,
2047 \& SV *key, U32 hash, SV *value,
2048 \& U32 flags)
2049 .Ve
2050 .RE
2051 .RS 4
2052 .RE
2053 .ie n .IP """unsharepvn""" 4
2054 .el .IP \f(CWunsharepvn\fR 4
2055 .IX Xref "unsharepvn"
2056 .IX Item "unsharepvn"
2057 If no one has access to shared string \f(CW\*(C`str\*(C'\fR with length \f(CW\*(C`len\*(C'\fR, free it.
2058 .Sp
2059 \&\f(CW\*(C`len\*(C'\fR and \f(CW\*(C`hash\*(C'\fR must both be valid for \f(CW\*(C`str\*(C'\fR.
2060 .RS 4
2061 .Sp
2062 .Vb 1
2063 \& void unsharepvn(const char *sv, I32 len, U32 hash)
2064 .Ve
2065 .RE
2066 .RS 4
2067 .RE
2068 .SH Input/Output
2069 .IX Header "Input/Output"
2070 .ie n .IP """dirp_dup""" 4
2071 .el .IP \f(CWdirp_dup\fR 4
2072 .IX Xref "dirp_dup"
2073 .IX Item "dirp_dup"
2074 Duplicate a directory handle, returning a pointer to the cloned object.
2075 .RS 4
2076 .Sp
2077 .Vb 1
2078 \& DIR * dirp_dup(DIR * const dp, CLONE_PARAMS * const param)
2079 .Ve
2080 .RE
2081 .RS 4
2082 .RE
2083 .ie n .IP """fp_dup""" 4
2084 .el .IP \f(CWfp_dup\fR 4
2085 .IX Xref "fp_dup"
2086 .IX Item "fp_dup"
2087 Duplicate a file handle, returning a pointer to the cloned object.
2088 .RS 4
2089 .Sp
2090 .Vb 2
2091 \& PerlIO * fp_dup(PerlIO * const fp, const char type,
2092 \& CLONE_PARAMS * const param)
2093 .Ve
2094 .RE
2095 .RS 4
2096 .RE
2097 .ie n .IP """my_fflush_all""" 4
2098 .el .IP \f(CWmy_fflush_all\fR 4
2099 .IX Xref "my_fflush_all"
2100 .IX Item "my_fflush_all"
2101 Implements \f(CW\*(C`PERL_FLUSHALL_FOR_CHILD\*(C'\fR on some platforms.
2102 .RS 4
2103 .Sp
2104 .Vb 1
2105 \& I32 my_fflush_all()
2106 .Ve
2107 .RE
2108 .RS 4
2109 .RE
2110 .ie n .IP """my_mkostemp""" 4
2111 .el .IP \f(CWmy_mkostemp\fR 4
2112 .IX Xref "my_mkostemp"
2113 .IX Item "my_mkostemp"
2114 The C library \f(CWmkostemp(3)\fR if available, or a Perl implementation of it.
2115 .Sp
2116 NOTE: \f(CW\*(C`my_mkostemp\*(C'\fR must be explicitly called as
2117 \&\f(CW\*(C`Perl_my_mkostemp\*(C'\fR
2118 \&.
2119 .RS 4
2120 .Sp
2121 .Vb 1
2122 \& int Perl_my_mkostemp(char *templte, int flags)
2123 .Ve
2124 .RE
2125 .RS 4
2126 .RE
2127 .ie n .IP """my_mkstemp""" 4
2128 .el .IP \f(CWmy_mkstemp\fR 4
2129 .IX Xref "my_mkstemp"
2130 .IX Item "my_mkstemp"
2131 The C library \f(CWmkstemp(3)\fR if available, or a Perl implementation of it.
2132 .Sp
2133 NOTE: \f(CW\*(C`my_mkstemp\*(C'\fR must be explicitly called as
2134 \&\f(CW\*(C`Perl_my_mkstemp\*(C'\fR
2135 \&.
2136 .RS 4
2137 .Sp
2138 .Vb 1
2139 \& int Perl_my_mkstemp(char *templte)
2140 .Ve
2141 .RE
2142 .RS 4
2143 .RE
2144 .ie n .IP """PL_last_in_gv""" 4
2145 .el .IP \f(CWPL_last_in_gv\fR 4
2146 .IX Xref "PL_last_in_gv"
2147 .IX Item "PL_last_in_gv"
2148 The GV which was last used for a filehandle input operation. (\f(CW\*(C`<FH>\*(C'\fR)
2149 .Sp
2150 On threaded perls, each thread has an independent copy of this variable;
2151 each initialized at creation time with the current value of the creating
2152 thread's copy.
2153 .RS 4
2154 .Sp
2155 .Vb 1
2156 \& GV* PL_last_in_gv
2157 .Ve
2158 .RE
2159 .RS 4
2160 .RE
2161 .ie n .IP """PL_ofsgv""" 4
2162 .el .IP \f(CWPL_ofsgv\fR 4
2163 .IX Xref "PL_ofsgv"
2164 .IX Item "PL_ofsgv"
2165 The glob containing the output field separator \- \f(CW\*(C`*,\*(C'\fR in Perl space.
2166 .Sp
2167 On threaded perls, each thread has an independent copy of this variable;
2168 each initialized at creation time with the current value of the creating
2169 thread's copy.
2170 .RS 4
2171 .Sp
2172 .Vb 1
2173 \& GV* PL_ofsgv
2174 .Ve
2175 .RE
2176 .RS 4
2177 .RE
2178 .ie n .IP """PL_rs""" 4
2179 .el .IP \f(CWPL_rs\fR 4
2180 .IX Xref "PL_rs"
2181 .IX Item "PL_rs"
2182 The input record separator \- \f(CW$/\fR in Perl space.
2183 .Sp
2184 On threaded perls, each thread has an independent copy of this variable;
2185 each initialized at creation time with the current value of the creating
2186 thread's copy.
2187 .RS 4
2188 .Sp
2189 .Vb 1
2190 \& SV* PL_rs
2191 .Ve
2192 .RE
2193 .RS 4
2194 .RE
2195 .ie n .IP """start_glob""" 4
2196 .el .IP \f(CWstart_glob\fR 4
2197 .IX Xref "start_glob"
2198 .IX Item "start_glob"
2199 NOTE: \f(CW\*(C`start_glob\*(C'\fR is \fBexperimental\fR and may change or be
2200 removed without notice.
2201 .Sp
2202 Function called by \f(CW\*(C`do_readline\*(C'\fR to spawn a glob (or do the glob inside
2203 perl on VMS). This code used to be inline, but now perl uses \f(CW\*(C`File::Glob\*(C'\fR
2204 this glob starter is only used by miniperl during the build process,
2205 or when PERL_EXTERNAL_GLOB is defined.
2206 Moving it away shrinks \fIpp_hot.c\fR; shrinking \fIpp_hot.c\fR helps speed perl up.
2207 .Sp
2208 NOTE: \f(CW\*(C`start_glob\*(C'\fR must be explicitly called as
2209 \&\f(CW\*(C`Perl_start_glob\*(C'\fR
2210 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
2211 .RS 4
2212 .Sp
2213 .Vb 1
2214 \& PerlIO * Perl_start_glob(pTHX_ SV *tmpglob, IO *io)
2215 .Ve
2216 .RE
2217 .RS 4
2218 .RE
2219 .SH Integer
2220 .IX Header "Integer"
2221 There are currently no internal API items in Integer
2222 .SH "I/O Formats"
2223 .IX Header "I/O Formats"
2224 There are currently no internal API items in I/O Formats
2225 .SH "Lexer interface"
2226 .IX Header "Lexer interface"
2227 .ie n .IP """resume_compcv_and_save""" 4
2228 .el .IP \f(CWresume_compcv_and_save\fR 4
2229 .IX Xref "resume_compcv_and_save"
2230 .IX Item "resume_compcv_and_save"
2231 Resumes a buffer previously suspended by the \f(CW\*(C`suspend_compcv\*(C'\fR function, in a
2232 way that will be re-suspended at the end of the scope so it can be used again
2233 later. This should be used within an \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR scoped pair.
2234 .RS 4
2235 .Sp
2236 .Vb 1
2237 \& void resume_compcv_and_save(struct suspended_compcv *buffer)
2238 .Ve
2239 .RE
2240 .RS 4
2241 .RE
2242 .ie n .IP """resume_compcv_final""" 4
2243 .el .IP \f(CWresume_compcv_final\fR 4
2244 .IX Xref "resume_compcv_final"
2245 .IX Item "resume_compcv_final"
2246 Resumes the parser state previously saved using the \f(CW\*(C`suspend_compcv\*(C'\fR function
2247 for a final time before being compiled into a full CV. This should be used
2248 within an \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR scoped pair.
2249 .RS 4
2250 .Sp
2251 .Vb 1
2252 \& void resume_compcv_final(struct suspended_compcv *buffer)
2253 .Ve
2254 .RE
2255 .RS 4
2256 .RE
2257 .ie n .IP """validate_proto""" 4
2258 .el .IP \f(CWvalidate_proto\fR 4
2259 .IX Xref "validate_proto"
2260 .IX Item "validate_proto"
2261 NOTE: \f(CW\*(C`validate_proto\*(C'\fR is \fBexperimental\fR and may change or be
2262 removed without notice.
2263 .Sp
2264 This function performs syntax checking on a prototype, \f(CW\*(C`proto\*(C'\fR.
2265 If \f(CW\*(C`warn\*(C'\fR is true, any illegal characters or mismatched brackets
2266 will trigger illegalproto warnings, declaring that they were
2267 detected in the prototype for \f(CW\*(C`name\*(C'\fR.
2268 .Sp
2269 The return value is \f(CW\*(C`true\*(C'\fR if this is a valid prototype, and
2270 \&\f(CW\*(C`false\*(C'\fR if it is not, regardless of whether \f(CW\*(C`warn\*(C'\fR was \f(CW\*(C`true\*(C'\fR or
2271 \&\f(CW\*(C`false\*(C'\fR.
2272 .Sp
2273 Note that \f(CW\*(C`NULL\*(C'\fR is a valid \f(CW\*(C`proto\*(C'\fR and will always return \f(CW\*(C`true\*(C'\fR.
2274 .RS 4
2275 .Sp
2276 .Vb 2
2277 \& bool validate_proto(SV *name, SV *proto, bool warn,
2278 \& bool curstash)
2279 .Ve
2280 .RE
2281 .RS 4
2282 .RE
2283 .SH Locales
2284 .IX Header "Locales"
2285 There are currently no internal API items in Locales
2286 .SH Magic
2287 .IX Header "Magic"
2288 .ie n .IP """magic_clearhint""" 4
2289 .el .IP \f(CWmagic_clearhint\fR 4
2290 .IX Xref "magic_clearhint"
2291 .IX Item "magic_clearhint"
2292 Triggered by a delete from \f(CW\*(C`%^H\*(C'\fR, records the key to
2293 \&\f(CW\*(C`PL_compiling.cop_hints_hash\*(C'\fR.
2294 .RS 4
2295 .Sp
2296 .Vb 1
2297 \& int magic_clearhint(SV *sv, MAGIC *mg)
2298 .Ve
2299 .RE
2300 .RS 4
2301 .RE
2302 .ie n .IP """magic_clearhints""" 4
2303 .el .IP \f(CWmagic_clearhints\fR 4
2304 .IX Xref "magic_clearhints"
2305 .IX Item "magic_clearhints"
2306 Triggered by clearing \f(CW\*(C`%^H\*(C'\fR, resets \f(CW\*(C`PL_compiling.cop_hints_hash\*(C'\fR.
2307 .RS 4
2308 .Sp
2309 .Vb 1
2310 \& int magic_clearhints(SV *sv, MAGIC *mg)
2311 .Ve
2312 .RE
2313 .RS 4
2314 .RE
2315 .ie n .IP """magic_methcall""" 4
2316 .el .IP \f(CWmagic_methcall\fR 4
2317 .IX Xref "magic_methcall"
2318 .IX Item "magic_methcall"
2319 Invoke a magic method (like FETCH).
2320 .Sp
2321 \&\f(CW\*(C`sv\*(C'\fR and \f(CW\*(C`mg\*(C'\fR are the tied thingy and the tie magic.
2322 .Sp
2323 \&\f(CW\*(C`meth\*(C'\fR is the name of the method to call.
2324 .Sp
2325 \&\f(CW\*(C`argc\*(C'\fR is the number of args (in addition to \f(CW$self\fR) to pass to the method.
2326 .Sp
2327 The \f(CW\*(C`flags\*(C'\fR can be:
2328 .Sp
2329 .Vb 4
2330 \& G_DISCARD invoke method with G_DISCARD flag and don\*(Aqt
2331 \& return a value
2332 \& G_UNDEF_FILL fill the stack with argc pointers to
2333 \& PL_sv_undef
2334 .Ve
2335 .Sp
2336 The arguments themselves are any values following the \f(CW\*(C`flags\*(C'\fR argument.
2337 .Sp
2338 Returns the SV (if any) returned by the method, or \f(CW\*(C`NULL\*(C'\fR on failure.
2339 .Sp
2340 NOTE: \f(CW\*(C`magic_methcall\*(C'\fR must be explicitly called as
2341 \&\f(CW\*(C`Perl_magic_methcall\*(C'\fR
2342 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
2343 .RS 4
2344 .Sp
2345 .Vb 2
2346 \& SV * Perl_magic_methcall(pTHX_ SV *sv, const MAGIC *mg,
2347 \& SV *meth, U32 flags, U32 argc, ...)
2348 .Ve
2349 .RE
2350 .RS 4
2351 .RE
2352 .ie n .IP """magic_sethint""" 4
2353 .el .IP \f(CWmagic_sethint\fR 4
2354 .IX Xref "magic_sethint"
2355 .IX Item "magic_sethint"
2356 Triggered by a store to \f(CW\*(C`%^H\*(C'\fR, records the key/value pair to
2357 \&\f(CW\*(C`PL_compiling.cop_hints_hash\*(C'\fR. It is assumed that hints aren't storing
2358 anything that would need a deep copy. Maybe we should warn if we find a
2359 reference.
2360 .RS 4
2361 .Sp
2362 .Vb 1
2363 \& int magic_sethint(SV *sv, MAGIC *mg)
2364 .Ve
2365 .RE
2366 .RS 4
2367 .RE
2368 .ie n .IP """mg_dup""" 4
2369 .el .IP \f(CWmg_dup\fR 4
2370 .IX Xref "mg_dup"
2371 .IX Item "mg_dup"
2372 Duplicate a chain of magic, returning a pointer to the cloned object.
2373 .RS 4
2374 .Sp
2375 .Vb 1
2376 \& MAGIC * mg_dup(MAGIC *mg, CLONE_PARAMS * const param)
2377 .Ve
2378 .RE
2379 .RS 4
2380 .RE
2381 .ie n .IP """mg_localize""" 4
2382 .el .IP \f(CWmg_localize\fR 4
2383 .IX Xref "mg_localize"
2384 .IX Item "mg_localize"
2385 Copy some of the magic from an existing SV to new localized version of that
2386 SV. Container magic (\fIe.g.\fR, \f(CW%ENV\fR, \f(CW$1\fR, \f(CW\*(C`tie\*(C'\fR)
2387 gets copied, value magic doesn't (\fIe.g.\fR,
2388 \&\f(CW\*(C`taint\*(C'\fR, \f(CW\*(C`pos\*(C'\fR).
2389 .Sp
2390 If \f(CW\*(C`setmagic\*(C'\fR is false then no set magic will be called on the new (empty) SV.
2391 This typically means that assignment will soon follow (e.g. \f(CW\*(Aqlocal\ $x\ =\ $y\*(Aq\fR),
2392 and that will handle the magic.
2393 .RS 4
2394 .Sp
2395 .Vb 1
2396 \& void mg_localize(SV *sv, SV *nsv, bool setmagic)
2397 .Ve
2398 .RE
2399 .RS 4
2400 .RE
2401 .SH "Memory Management"
2402 .IX Header "Memory Management"
2403 .ie n .IP """calloc""" 4
2404 .el .IP \f(CWcalloc\fR 4
2405 .IX Xref "calloc"
2406 .IX Item "calloc"
2407 Implements "\f(CW\*(C`Newxz\*(C'\fR" in perlapi which you should use instead.
2408 .Sp
2409 NOTE: \f(CW\*(C`calloc\*(C'\fR must be explicitly called as
2410 \&\f(CW\*(C`Perl_calloc\*(C'\fR
2411 \&.
2412 .RS 4
2413 .Sp
2414 .Vb 1
2415 \& Malloc_t Perl_calloc(MEM_SIZE elements, MEM_SIZE size)
2416 .Ve
2417 .RE
2418 .RS 4
2419 .RE
2420 .ie n .IP """malloc""" 4
2421 .el .IP \f(CWmalloc\fR 4
2422 .IX Xref "malloc"
2423 .IX Item "malloc"
2424 Implements "\f(CW\*(C`Newx\*(C'\fR" in perlapi which you should use instead.
2425 .Sp
2426 NOTE: \f(CW\*(C`malloc\*(C'\fR must be explicitly called as
2427 \&\f(CW\*(C`Perl_malloc\*(C'\fR
2428 \&.
2429 .RS 4
2430 .Sp
2431 .Vb 1
2432 \& Malloc_t Perl_malloc(MEM_SIZE nbytes)
2433 .Ve
2434 .RE
2435 .RS 4
2436 .RE
2437 .ie n .IP """mfree""" 4
2438 .el .IP \f(CWmfree\fR 4
2439 .IX Xref "mfree"
2440 .IX Item "mfree"
2441 Implements "\f(CW\*(C`Safefree\*(C'\fR" in perlapi which you should use instead.
2442 .Sp
2443 NOTE: \f(CW\*(C`mfree\*(C'\fR must be explicitly called as
2444 \&\f(CW\*(C`Perl_mfree\*(C'\fR
2445 \&.
2446 .RS 4
2447 .Sp
2448 .Vb 1
2449 \& Free_t Perl_mfree(Malloc_t where)
2450 .Ve
2451 .RE
2452 .RS 4
2453 .RE
2454 .ie n .IP """realloc""" 4
2455 .el .IP \f(CWrealloc\fR 4
2456 .IX Xref "realloc"
2457 .IX Item "realloc"
2458 Implements "\f(CW\*(C`Renew\*(C'\fR" in perlapi which you should use instead.
2459 .Sp
2460 NOTE: \f(CW\*(C`realloc\*(C'\fR must be explicitly called as
2461 \&\f(CW\*(C`Perl_realloc\*(C'\fR
2462 \&.
2463 .RS 4
2464 .Sp
2465 .Vb 1
2466 \& Malloc_t Perl_realloc(Malloc_t where, MEM_SIZE nbytes)
2467 .Ve
2468 .RE
2469 .RS 4
2470 .RE
2471 .SH MRO
2472 .IX Header "MRO"
2473 .ie n .IP """mro_get_linear_isa_dfs""" 4
2474 .el .IP \f(CWmro_get_linear_isa_dfs\fR 4
2475 .IX Xref "mro_get_linear_isa_dfs"
2476 .IX Item "mro_get_linear_isa_dfs"
2477 Returns the Depth-First Search linearization of \f(CW@ISA\fR
2478 the given stash. The return value is a read-only AV*
2479 whose elements are string SVs giving class names.
2480 \&\f(CW\*(C`level\*(C'\fR should be 0 (it is used internally in this
2481 function's recursion).
2482 .Sp
2483 You are responsible for \f(CWSvREFCNT_inc()\fR on the
2484 return value if you plan to store it anywhere
2485 semi-permanently (otherwise it might be deleted
2486 out from under you the next time the cache is
2487 invalidated).
2488 .RS 4
2489 .Sp
2490 .Vb 1
2491 \& AV * mro_get_linear_isa_dfs(HV *stash, U32 level)
2492 .Ve
2493 .RE
2494 .RS 4
2495 .RE
2496 .ie n .IP """mro_isa_changed_in""" 4
2497 .el .IP \f(CWmro_isa_changed_in\fR 4
2498 .IX Xref "mro_isa_changed_in"
2499 .IX Item "mro_isa_changed_in"
2500 Takes the necessary steps (cache invalidations, mostly)
2501 when the \f(CW@ISA\fR of the given package has changed. Invoked
2502 by the \f(CW\*(C`setisa\*(C'\fR magic, should not need to invoke directly.
2503 .RS 4
2504 .Sp
2505 .Vb 1
2506 \& void mro_isa_changed_in(HV *stash)
2507 .Ve
2508 .RE
2509 .RS 4
2510 .RE
2511 .ie n .IP """mro_package_moved""" 4
2512 .el .IP \f(CWmro_package_moved\fR 4
2513 .IX Xref "mro_package_moved"
2514 .IX Item "mro_package_moved"
2515 Call this function to signal to a stash that it has been assigned to
2516 another spot in the stash hierarchy. \f(CW\*(C`stash\*(C'\fR is the stash that has been
2517 assigned. \f(CW\*(C`oldstash\*(C'\fR is the stash it replaces, if any. \f(CW\*(C`gv\*(C'\fR is the glob
2518 that is actually being assigned to.
2519 .Sp
2520 This can also be called with a null first argument to
2521 indicate that \f(CW\*(C`oldstash\*(C'\fR has been deleted.
2522 .Sp
2523 This function invalidates isa caches on the old stash, on all subpackages
2524 nested inside it, and on the subclasses of all those, including
2525 non-existent packages that have corresponding entries in \f(CW\*(C`stash\*(C'\fR.
2526 .Sp
2527 It also sets the effective names (\f(CW\*(C`HvENAME\*(C'\fR) on all the stashes as
2528 appropriate.
2529 .Sp
2530 If the \f(CW\*(C`gv\*(C'\fR is present and is not in the symbol table, then this function
2531 simply returns. This checked will be skipped if \f(CW\*(C`flags & 1\*(C'\fR.
2532 .RS 4
2533 .Sp
2534 .Vb 2
2535 \& void mro_package_moved(HV * const stash, HV * const oldstash,
2536 \& const GV * const gv, U32 flags)
2537 .Ve
2538 .RE
2539 .RS 4
2540 .RE
2541 .SH "Multicall Functions"
2542 .IX Header "Multicall Functions"
2543 There are currently no internal API items in Multicall Functions
2544 .SH "Numeric Functions"
2545 .IX Header "Numeric Functions"
2546 .ie n .IP """isinfnansv""" 4
2547 .el .IP \f(CWisinfnansv\fR 4
2548 .IX Xref "isinfnansv"
2549 .IX Item "isinfnansv"
2550 Checks whether the argument would be either an infinity or \f(CW\*(C`NaN\*(C'\fR when used
2551 as a number, but is careful not to trigger non-numeric or uninitialized
2552 warnings. it assumes the caller has done \f(CWSvGETMAGIC(sv)\fR already.
2553 .Sp
2554 Note that this always accepts trailing garbage (similar to \f(CW\*(C`grok_number_flags\*(C'\fR
2555 with \f(CW\*(C`PERL_SCAN_TRAILING\*(C'\fR), so \f(CW"inferior"\fR and \f(CW"NAND gates"\fR will
2556 return true.
2557 .RS 4
2558 .Sp
2559 .Vb 1
2560 \& bool isinfnansv(SV *sv)
2561 .Ve
2562 .RE
2563 .RS 4
2564 .RE
2565 .SH Optrees
2566 .IX Header "Optrees"
2567 .ie n .IP """newATTRSUB_x""" 4
2568 .el .IP \f(CWnewATTRSUB_x\fR 4
2569 .IX Xref "newATTRSUB_x"
2570 .IX Item "newATTRSUB_x"
2571 Construct a Perl subroutine, also performing some surrounding jobs.
2572 .Sp
2573 This function is expected to be called in a Perl compilation context,
2574 and some aspects of the subroutine are taken from global variables
2575 associated with compilation. In particular, \f(CW\*(C`PL_compcv\*(C'\fR represents
2576 the subroutine that is currently being compiled. It must be non-null
2577 when this function is called, and some aspects of the subroutine being
2578 constructed are taken from it. The constructed subroutine may actually
2579 be a reuse of the \f(CW\*(C`PL_compcv\*(C'\fR object, but will not necessarily be so.
2580 .Sp
2581 If \f(CW\*(C`block\*(C'\fR is null then the subroutine will have no body, and for the
2582 time being it will be an error to call it. This represents a forward
2583 subroutine declaration such as \f(CW\*(C`sub\ foo\ ($$);\*(C'\fR. If \f(CW\*(C`block\*(C'\fR is
2584 non-null then it provides the Perl code of the subroutine body, which
2585 will be executed when the subroutine is called. This body includes
2586 any argument unwrapping code resulting from a subroutine signature or
2587 similar. The pad use of the code must correspond to the pad attached
2588 to \f(CW\*(C`PL_compcv\*(C'\fR. The code is not expected to include a \f(CW\*(C`leavesub\*(C'\fR or
2589 \&\f(CW\*(C`leavesublv\*(C'\fR op; this function will add such an op. \f(CW\*(C`block\*(C'\fR is consumed
2590 by this function and will become part of the constructed subroutine.
2591 .Sp
2592 \&\f(CW\*(C`proto\*(C'\fR specifies the subroutine's prototype, unless one is supplied
2593 as an attribute (see below). If \f(CW\*(C`proto\*(C'\fR is null, then the subroutine
2594 will not have a prototype. If \f(CW\*(C`proto\*(C'\fR is non-null, it must point to a
2595 \&\f(CW\*(C`const\*(C'\fR op whose value is a string, and the subroutine will have that
2596 string as its prototype. If a prototype is supplied as an attribute, the
2597 attribute takes precedence over \f(CW\*(C`proto\*(C'\fR, but in that case \f(CW\*(C`proto\*(C'\fR should
2598 preferably be null. In any case, \f(CW\*(C`proto\*(C'\fR is consumed by this function.
2599 .Sp
2600 \&\f(CW\*(C`attrs\*(C'\fR supplies attributes to be applied the subroutine. A handful of
2601 attributes take effect by built-in means, being applied to \f(CW\*(C`PL_compcv\*(C'\fR
2602 immediately when seen. Other attributes are collected up and attached
2603 to the subroutine by this route. \f(CW\*(C`attrs\*(C'\fR may be null to supply no
2604 attributes, or point to a \f(CW\*(C`const\*(C'\fR op for a single attribute, or point
2605 to a \f(CW\*(C`list\*(C'\fR op whose children apart from the \f(CW\*(C`pushmark\*(C'\fR are \f(CW\*(C`const\*(C'\fR
2606 ops for one or more attributes. Each \f(CW\*(C`const\*(C'\fR op must be a string,
2607 giving the attribute name optionally followed by parenthesised arguments,
2608 in the manner in which attributes appear in Perl source. The attributes
2609 will be applied to the sub by this function. \f(CW\*(C`attrs\*(C'\fR is consumed by
2610 this function.
2611 .Sp
2612 If \f(CW\*(C`o_is_gv\*(C'\fR is false and \f(CW\*(C`o\*(C'\fR is null, then the subroutine will
2613 be anonymous. If \f(CW\*(C`o_is_gv\*(C'\fR is false and \f(CW\*(C`o\*(C'\fR is non-null, then \f(CW\*(C`o\*(C'\fR
2614 must point to a \f(CW\*(C`const\*(C'\fR OP, which will be consumed by this function,
2615 and its string value supplies a name for the subroutine. The name may
2616 be qualified or unqualified, and if it is unqualified then a default
2617 stash will be selected in some manner. If \f(CW\*(C`o_is_gv\*(C'\fR is true, then \f(CW\*(C`o\*(C'\fR
2618 doesn't point to an \f(CW\*(C`OP\*(C'\fR at all, but is instead a cast pointer to a \f(CW\*(C`GV\*(C'\fR
2619 by which the subroutine will be named.
2620 .Sp
2621 If there is already a subroutine of the specified name, then the new
2622 sub will either replace the existing one in the glob or be merged with
2623 the existing one. A warning may be generated about redefinition.
2624 .Sp
2625 If the subroutine has one of a few special names, such as \f(CW\*(C`BEGIN\*(C'\fR or
2626 \&\f(CW\*(C`END\*(C'\fR, then it will be claimed by the appropriate queue for automatic
2627 running of phase-related subroutines. In this case the relevant glob will
2628 be left not containing any subroutine, even if it did contain one before.
2629 In the case of \f(CW\*(C`BEGIN\*(C'\fR, the subroutine will be executed and the reference
2630 to it disposed of before this function returns.
2631 .Sp
2632 The function returns a pointer to the constructed subroutine. If the sub
2633 is anonymous then ownership of one counted reference to the subroutine
2634 is transferred to the caller. If the sub is named then the caller does
2635 not get ownership of a reference. In most such cases, where the sub
2636 has a non-phase name, the sub will be alive at the point it is returned
2637 by virtue of being contained in the glob that names it. A phase-named
2638 subroutine will usually be alive by virtue of the reference owned by the
2639 phase's automatic run queue. But a \f(CW\*(C`BEGIN\*(C'\fR subroutine, having already
2640 been executed, will quite likely have been destroyed already by the
2641 time this function returns, making it erroneous for the caller to make
2642 any use of the returned pointer. It is the caller's responsibility to
2643 ensure that it knows which of these situations applies.
2644 .RS 4
2645 .Sp
2646 .Vb 2
2647 \& CV * newATTRSUB_x(I32 floor, OP *o, OP *proto, OP *attrs,
2648 \& OP *block, bool o_is_gv)
2649 .Ve
2650 .RE
2651 .RS 4
2652 .RE
2653 .ie n .IP """newMYSUB""" 4
2654 .el .IP \f(CWnewMYSUB\fR 4
2655 .IX Xref "newMYSUB"
2656 .IX Item "newMYSUB"
2657 Construct a Perl lexical subroutine, also performing some surrounding jobs, and
2658 returning a pointer to the constructed subroutine.
2659 .Sp
2660 Similar in action to "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern.
2661 .RS 4
2662 .Sp
2663 .Vb 1
2664 \& CV * newMYSUB(I32 floor, OP *o, OP *proto, OP *attrs, OP *block)
2665 .Ve
2666 .RE
2667 .RS 4
2668 .RE
2669 .ie n .IP """newXS_len_flags""" 4
2670 .el .IP \f(CWnewXS_len_flags\fR 4
2671 .IX Xref "newXS_len_flags"
2672 .IX Item "newXS_len_flags"
2673 Construct an XS subroutine, also performing some surrounding jobs.
2674 .Sp
2675 The subroutine will have the entry point \f(CW\*(C`subaddr\*(C'\fR. It will have
2676 the prototype specified by the nul-terminated string \f(CW\*(C`proto\*(C'\fR, or
2677 no prototype if \f(CW\*(C`proto\*(C'\fR is null. The prototype string is copied;
2678 the caller can mutate the supplied string afterwards. If \f(CW\*(C`filename\*(C'\fR
2679 is non-null, it must be a nul-terminated filename, and the subroutine
2680 will have its \f(CW\*(C`CvFILE\*(C'\fR set accordingly. By default \f(CW\*(C`CvFILE\*(C'\fR is set to
2681 point directly to the supplied string, which must be static. If \f(CW\*(C`flags\*(C'\fR
2682 has the \f(CW\*(C`XS_DYNAMIC_FILENAME\*(C'\fR bit set, then a copy of the string will
2683 be taken instead.
2684 .Sp
2685 Other aspects of the subroutine will be left in their default state.
2686 If anything else needs to be done to the subroutine for it to function
2687 correctly, it is the caller's responsibility to do that after this
2688 function has constructed it. However, beware of the subroutine
2689 potentially being destroyed before this function returns, as described
2690 below.
2691 .Sp
2692 If \f(CW\*(C`name\*(C'\fR is null then the subroutine will be anonymous, with its
2693 \&\f(CW\*(C`CvGV\*(C'\fR referring to an \f(CW\*(C`_\|_ANON_\|_\*(C'\fR glob. If \f(CW\*(C`name\*(C'\fR is non-null then the
2694 subroutine will be named accordingly, referenced by the appropriate glob.
2695 \&\f(CW\*(C`name\*(C'\fR is a string of length \f(CW\*(C`len\*(C'\fR bytes giving a sigilless symbol name,
2696 in UTF\-8 if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SVf_UTF8\*(C'\fR bit set and in Latin\-1 otherwise.
2697 The name may be either qualified or unqualified, with the stash defaulting
2698 in the same manner as for \f(CW\*(C`gv_fetchpvn_flags\*(C'\fR. \f(CW\*(C`flags\*(C'\fR may contain
2699 flag bits understood by \f(CW\*(C`gv_fetchpvn_flags\*(C'\fR with the same meaning as
2700 they have there, such as \f(CW\*(C`GV_ADDWARN\*(C'\fR. The symbol is always added to
2701 the stash if necessary, with \f(CW\*(C`GV_ADDMULTI\*(C'\fR semantics.
2702 .Sp
2703 If there is already a subroutine of the specified name, then the new sub
2704 will replace the existing one in the glob. A warning may be generated
2705 about the redefinition. If the old subroutine was \f(CW\*(C`CvCONST\*(C'\fR then the
2706 decision about whether to warn is influenced by an expectation about
2707 whether the new subroutine will become a constant of similar value.
2708 That expectation is determined by \f(CW\*(C`const_svp\*(C'\fR. (Note that the call to
2709 this function doesn't make the new subroutine \f(CW\*(C`CvCONST\*(C'\fR in any case;
2710 that is left to the caller.) If \f(CW\*(C`const_svp\*(C'\fR is null then it indicates
2711 that the new subroutine will not become a constant. If \f(CW\*(C`const_svp\*(C'\fR
2712 is non-null then it indicates that the new subroutine will become a
2713 constant, and it points to an \f(CW\*(C`SV*\*(C'\fR that provides the constant value
2714 that the subroutine will have.
2715 .Sp
2716 If the subroutine has one of a few special names, such as \f(CW\*(C`BEGIN\*(C'\fR or
2717 \&\f(CW\*(C`END\*(C'\fR, then it will be claimed by the appropriate queue for automatic
2718 running of phase-related subroutines. In this case the relevant glob will
2719 be left not containing any subroutine, even if it did contain one before.
2720 In the case of \f(CW\*(C`BEGIN\*(C'\fR, the subroutine will be executed and the reference
2721 to it disposed of before this function returns, and also before its
2722 prototype is set. If a \f(CW\*(C`BEGIN\*(C'\fR subroutine would not be sufficiently
2723 constructed by this function to be ready for execution then the caller
2724 must prevent this happening by giving the subroutine a different name.
2725 .Sp
2726 The function returns a pointer to the constructed subroutine. If the sub
2727 is anonymous then ownership of one counted reference to the subroutine
2728 is transferred to the caller. If the sub is named then the caller does
2729 not get ownership of a reference. In most such cases, where the sub
2730 has a non-phase name, the sub will be alive at the point it is returned
2731 by virtue of being contained in the glob that names it. A phase-named
2732 subroutine will usually be alive by virtue of the reference owned by the
2733 phase's automatic run queue. But a \f(CW\*(C`BEGIN\*(C'\fR subroutine, having already
2734 been executed, will quite likely have been destroyed already by the
2735 time this function returns, making it erroneous for the caller to make
2736 any use of the returned pointer. It is the caller's responsibility to
2737 ensure that it knows which of these situations applies.
2738 .RS 4
2739 .Sp
2740 .Vb 5
2741 \& CV * newXS_len_flags(const char *name, STRLEN len,
2742 \& XSUBADDR_t subaddr,
2743 \& const char * const filename,
2744 \& const char * const proto, SV ** const_svp,
2745 \& U32 flags)
2746 .Ve
2747 .RE
2748 .RS 4
2749 .RE
2750 .ie n .IP """op_refcnt_lock""" 4
2751 .el .IP \f(CWop_refcnt_lock\fR 4
2752 .IX Xref "op_refcnt_lock"
2753 .IX Item "op_refcnt_lock"
2754 Implements the \f(CW\*(C`OP_REFCNT_LOCK\*(C'\fR macro which you should use instead.
2755 .RS 4
2756 .Sp
2757 .Vb 1
2758 \& void op_refcnt_lock()
2759 .Ve
2760 .RE
2761 .RS 4
2762 .RE
2763 .ie n .IP """op_refcnt_unlock""" 4
2764 .el .IP \f(CWop_refcnt_unlock\fR 4
2765 .IX Xref "op_refcnt_unlock"
2766 .IX Item "op_refcnt_unlock"
2767 Implements the \f(CW\*(C`OP_REFCNT_UNLOCK\*(C'\fR macro which you should use instead.
2768 .RS 4
2769 .Sp
2770 .Vb 1
2771 \& void op_refcnt_unlock()
2772 .Ve
2773 .RE
2774 .RS 4
2775 .RE
2776 .ie n .IP """traverse_op_tree""" 4
2777 .el .IP \f(CWtraverse_op_tree\fR 4
2778 .IX Xref "traverse_op_tree"
2779 .IX Item "traverse_op_tree"
2780 Return the next op in a depth-first traversal of the op tree,
2781 returning NULL when the traversal is complete.
2782 .Sp
2783 The initial call must supply the root of the tree as both top and o.
2784 .Sp
2785 For now it's static, but it may be exposed to the API in the future.
2786 .RS 4
2787 .Sp
2788 .Vb 1
2789 \& OP * traverse_op_tree(OP *top, OP *o)
2790 .Ve
2791 .RE
2792 .RS 4
2793 .RE
2794 .SH "Pack and Unpack"
2795 .IX Header "Pack and Unpack"
2796 There are currently no internal API items in Pack and Unpack
2797 .SH "Pad Data Structures"
2798 .IX Header "Pad Data Structures"
2799 .ie n .IP """CX_CURPAD_SAVE""" 4
2800 .el .IP \f(CWCX_CURPAD_SAVE\fR 4
2801 .IX Xref "CX_CURPAD_SAVE"
2802 .IX Item "CX_CURPAD_SAVE"
2803 Save the current pad in the given context block structure.
2804 .RS 4
2805 .Sp
2806 .Vb 1
2807 \& void CX_CURPAD_SAVE(struct context)
2808 .Ve
2809 .RE
2810 .RS 4
2811 .RE
2812 .ie n .IP """CX_CURPAD_SV""" 4
2813 .el .IP \f(CWCX_CURPAD_SV\fR 4
2814 .IX Xref "CX_CURPAD_SV"
2815 .IX Item "CX_CURPAD_SV"
2816 Access the SV at offset \f(CW\*(C`po\*(C'\fR in the saved current pad in the given
2817 context block structure (can be used as an lvalue).
2818 .RS 4
2819 .Sp
2820 .Vb 1
2821 \& SV * CX_CURPAD_SV(struct context, PADOFFSET po)
2822 .Ve
2823 .RE
2824 .RS 4
2825 .RE
2826 .ie n .IP """PAD_BASE_SV""" 4
2827 .el .IP \f(CWPAD_BASE_SV\fR 4
2828 .IX Xref "PAD_BASE_SV"
2829 .IX Item "PAD_BASE_SV"
2830 Get the value from slot \f(CW\*(C`po\*(C'\fR in the base (DEPTH=1) pad of a padlist
2831 .RS 4
2832 .Sp
2833 .Vb 1
2834 \& SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
2835 .Ve
2836 .RE
2837 .RS 4
2838 .RE
2839 .ie n .IP """PAD_CLONE_VARS""" 4
2840 .el .IP \f(CWPAD_CLONE_VARS\fR 4
2841 .IX Xref "PAD_CLONE_VARS"
2842 .IX Item "PAD_CLONE_VARS"
2843 Clone the state variables associated with running and compiling pads.
2844 .RS 4
2845 .Sp
2846 .Vb 2
2847 \& void PAD_CLONE_VARS(PerlInterpreter *proto_perl,
2848 \& CLONE_PARAMS* param)
2849 .Ve
2850 .RE
2851 .RS 4
2852 .RE
2853 .ie n .IP """PAD_COMPNAME_FLAGS""" 4
2854 .el .IP \f(CWPAD_COMPNAME_FLAGS\fR 4
2855 .IX Xref "PAD_COMPNAME_FLAGS"
2856 .IX Item "PAD_COMPNAME_FLAGS"
2857 Return the flags for the current compiling pad name
2858 at offset \f(CW\*(C`po\*(C'\fR. Assumes a valid slot entry.
2859 .RS 4
2860 .Sp
2861 .Vb 1
2862 \& U32 PAD_COMPNAME_FLAGS(PADOFFSET po)
2863 .Ve
2864 .RE
2865 .RS 4
2866 .RE
2867 .ie n .IP """PAD_COMPNAME_GEN""" 4
2868 .el .IP \f(CWPAD_COMPNAME_GEN\fR 4
2869 .IX Xref "PAD_COMPNAME_GEN"
2870 .IX Item "PAD_COMPNAME_GEN"
2871 The generation number of the name at offset \f(CW\*(C`po\*(C'\fR in the current
2872 compiling pad (lvalue).
2873 .RS 4
2874 .Sp
2875 .Vb 1
2876 \& STRLEN PAD_COMPNAME_GEN(PADOFFSET po)
2877 .Ve
2878 .RE
2879 .RS 4
2880 .RE
2881 .ie n .IP """PAD_COMPNAME_GEN_set""" 4
2882 .el .IP \f(CWPAD_COMPNAME_GEN_set\fR 4
2883 .IX Xref "PAD_COMPNAME_GEN_set"
2884 .IX Item "PAD_COMPNAME_GEN_set"
2885 Sets the generation number of the name at offset \f(CW\*(C`po\*(C'\fR in the current
2886 ling pad (lvalue) to \f(CW\*(C`gen\*(C'\fR.
2887 .RS 4
2888 .Sp
2889 .Vb 1
2890 \& STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
2891 .Ve
2892 .RE
2893 .RS 4
2894 .RE
2895 .ie n .IP """PAD_COMPNAME_OURSTASH""" 4
2896 .el .IP \f(CWPAD_COMPNAME_OURSTASH\fR 4
2897 .IX Xref "PAD_COMPNAME_OURSTASH"
2898 .IX Item "PAD_COMPNAME_OURSTASH"
2899 Return the stash associated with an \f(CW\*(C`our\*(C'\fR variable.
2900 Assumes the slot entry is a valid \f(CW\*(C`our\*(C'\fR lexical.
2901 .RS 4
2902 .Sp
2903 .Vb 1
2904 \& HV * PAD_COMPNAME_OURSTASH(PADOFFSET po)
2905 .Ve
2906 .RE
2907 .RS 4
2908 .RE
2909 .ie n .IP """PAD_COMPNAME_PV""" 4
2910 .el .IP \f(CWPAD_COMPNAME_PV\fR 4
2911 .IX Xref "PAD_COMPNAME_PV"
2912 .IX Item "PAD_COMPNAME_PV"
2913 Return the name of the current compiling pad name
2914 at offset \f(CW\*(C`po\*(C'\fR. Assumes a valid slot entry.
2915 .RS 4
2916 .Sp
2917 .Vb 1
2918 \& char * PAD_COMPNAME_PV(PADOFFSET po)
2919 .Ve
2920 .RE
2921 .RS 4
2922 .RE
2923 .ie n .IP """PAD_COMPNAME_TYPE""" 4
2924 .el .IP \f(CWPAD_COMPNAME_TYPE\fR 4
2925 .IX Xref "PAD_COMPNAME_TYPE"
2926 .IX Item "PAD_COMPNAME_TYPE"
2927 Return the type (stash) of the current compiling pad name at offset
2928 \&\f(CW\*(C`po\*(C'\fR. Must be a valid name. Returns null if not typed.
2929 .RS 4
2930 .Sp
2931 .Vb 1
2932 \& HV * PAD_COMPNAME_TYPE(PADOFFSET po)
2933 .Ve
2934 .RE
2935 .RS 4
2936 .RE
2937 .ie n .IP """PadnameIsFIELD""" 4
2938 .el .IP \f(CWPadnameIsFIELD\fR 4
2939 .IX Xref "PadnameIsFIELD"
2940 .IX Item "PadnameIsFIELD"
2941 Whether this is a "field" variable. PADNAMEs where this is true will
2942 have additional information available via \f(CW\*(C`PadnameFIELDINFO\*(C'\fR.
2943 .RS 4
2944 .Sp
2945 .Vb 1
2946 \& bool PadnameIsFIELD(PADNAME * pn)
2947 .Ve
2948 .RE
2949 .RS 4
2950 .RE
2951 .ie n .IP """PadnameIsOUR""" 4
2952 .el .IP \f(CWPadnameIsOUR\fR 4
2953 .IX Xref "PadnameIsOUR"
2954 .IX Item "PadnameIsOUR"
2955 Whether this is an "our" variable.
2956 .RS 4
2957 .Sp
2958 .Vb 1
2959 \& bool PadnameIsOUR(PADNAME * pn)
2960 .Ve
2961 .RE
2962 .RS 4
2963 .RE
2964 .ie n .IP """PadnameIsSTATE""" 4
2965 .el .IP \f(CWPadnameIsSTATE\fR 4
2966 .IX Xref "PadnameIsSTATE"
2967 .IX Item "PadnameIsSTATE"
2968 Whether this is a "state" variable.
2969 .RS 4
2970 .Sp
2971 .Vb 1
2972 \& bool PadnameIsSTATE(PADNAME * pn)
2973 .Ve
2974 .RE
2975 .RS 4
2976 .RE
2977 .ie n .IP """PadnameOURSTASH""" 4
2978 .el .IP \f(CWPadnameOURSTASH\fR 4
2979 .IX Xref "PadnameOURSTASH"
2980 .IX Item "PadnameOURSTASH"
2981 The stash in which this "our" variable was declared.
2982 .RS 4
2983 .Sp
2984 .Vb 1
2985 \& HV * PadnameOURSTASH(PADNAME * pn)
2986 .Ve
2987 .RE
2988 .RS 4
2989 .RE
2990 .ie n .IP """PadnameOUTER""" 4
2991 .el .IP \f(CWPadnameOUTER\fR 4
2992 .IX Xref "PadnameOUTER"
2993 .IX Item "PadnameOUTER"
2994 Whether this entry belongs to an outer pad. Entries for which this is true
2995 are often referred to as 'fake'.
2996 .RS 4
2997 .Sp
2998 .Vb 1
2999 \& bool PadnameOUTER(PADNAME * pn)
3000 .Ve
3001 .RE
3002 .RS 4
3003 .RE
3004 .ie n .IP """PadnameTYPE""" 4
3005 .el .IP \f(CWPadnameTYPE\fR 4
3006 .IX Xref "PadnameTYPE"
3007 .IX Item "PadnameTYPE"
3008 The stash associated with a typed lexical. This returns the \f(CW%Foo::\fR hash
3009 for \f(CW\*(C`my Foo $bar\*(C'\fR.
3010 .RS 4
3011 .Sp
3012 .Vb 1
3013 \& HV * PadnameTYPE(PADNAME * pn)
3014 .Ve
3015 .RE
3016 .RS 4
3017 .RE
3018 .ie n .IP """PAD_RESTORE_LOCAL""" 4
3019 .el .IP \f(CWPAD_RESTORE_LOCAL\fR 4
3020 .IX Xref "PAD_RESTORE_LOCAL"
3021 .IX Item "PAD_RESTORE_LOCAL"
3022 Restore the old pad saved into the local variable \f(CW\*(C`opad\*(C'\fR by \f(CWPAD_SAVE_LOCAL()\fR
3023 .RS 4
3024 .Sp
3025 .Vb 1
3026 \& void PAD_RESTORE_LOCAL(PAD *opad)
3027 .Ve
3028 .RE
3029 .RS 4
3030 .RE
3031 .ie n .IP """PAD_SAVE_LOCAL""" 4
3032 .el .IP \f(CWPAD_SAVE_LOCAL\fR 4
3033 .IX Xref "PAD_SAVE_LOCAL"
3034 .IX Item "PAD_SAVE_LOCAL"
3035 Save the current pad to the local variable \f(CW\*(C`opad\*(C'\fR, then make the
3036 current pad equal to \f(CW\*(C`npad\*(C'\fR
3037 .RS 4
3038 .Sp
3039 .Vb 1
3040 \& void PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
3041 .Ve
3042 .RE
3043 .RS 4
3044 .RE
3045 .ie n .IP """PAD_SAVE_SETNULLPAD""" 4
3046 .el .IP \f(CWPAD_SAVE_SETNULLPAD\fR 4
3047 .IX Xref "PAD_SAVE_SETNULLPAD"
3048 .IX Item "PAD_SAVE_SETNULLPAD"
3049 Save the current pad then set it to null.
3050 .RS 4
3051 .Sp
3052 .Vb 1
3053 \& void PAD_SAVE_SETNULLPAD()
3054 .Ve
3055 .RE
3056 .RS 4
3057 .RE
3058 .ie n .IP """PAD_SET_CUR""" 4
3059 .el .IP \f(CWPAD_SET_CUR\fR 4
3060 .IX Xref "PAD_SET_CUR"
3061 .IX Item "PAD_SET_CUR"
3062 Set the current pad to be pad \f(CW\*(C`n\*(C'\fR in the padlist, saving
3063 the previous current pad. NB currently this macro expands to a string too
3064 long for some compilers, so it's best to replace it with
3065 .Sp
3066 .Vb 2
3067 \& SAVECOMPPAD();
3068 \& PAD_SET_CUR_NOSAVE(padlist,n);
3069 .Ve
3070 .RS 4
3071 .Sp
3072 .Vb 1
3073 \& void PAD_SET_CUR(PADLIST padlist, I32 n)
3074 .Ve
3075 .RE
3076 .RS 4
3077 .RE
3078 .ie n .IP """PAD_SET_CUR_NOSAVE""" 4
3079 .el .IP \f(CWPAD_SET_CUR_NOSAVE\fR 4
3080 .IX Xref "PAD_SET_CUR_NOSAVE"
3081 .IX Item "PAD_SET_CUR_NOSAVE"
3082 like PAD_SET_CUR, but without the save
3083 .RS 4
3084 .Sp
3085 .Vb 1
3086 \& void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
3087 .Ve
3088 .RE
3089 .RS 4
3090 .RE
3091 .ie n .IP """PAD_SETSV""" 4
3092 .el .IP \f(CWPAD_SETSV\fR 4
3093 .IX Xref "PAD_SETSV"
3094 .IX Item "PAD_SETSV"
3095 Set the slot at offset \f(CW\*(C`po\*(C'\fR in the current pad to \f(CW\*(C`sv\*(C'\fR
3096 .RS 4
3097 .Sp
3098 .Vb 1
3099 \& SV * PAD_SETSV(PADOFFSET po, SV* sv)
3100 .Ve
3101 .RE
3102 .RS 4
3103 .RE
3104 .ie n .IP """PAD_SV""" 4
3105 .el .IP \f(CWPAD_SV\fR 4
3106 .IX Xref "PAD_SV"
3107 .IX Item "PAD_SV"
3108 Get the value at offset \f(CW\*(C`po\*(C'\fR in the current pad
3109 .RS 4
3110 .Sp
3111 .Vb 1
3112 \& SV * PAD_SV(PADOFFSET po)
3113 .Ve
3114 .RE
3115 .RS 4
3116 .RE
3117 .ie n .IP """PAD_SVl""" 4
3118 .el .IP \f(CWPAD_SVl\fR 4
3119 .IX Xref "PAD_SVl"
3120 .IX Item "PAD_SVl"
3121 Lightweight and lvalue version of \f(CW\*(C`PAD_SV\*(C'\fR.
3122 Get or set the value at offset \f(CW\*(C`po\*(C'\fR in the current pad.
3123 Unlike \f(CW\*(C`PAD_SV\*(C'\fR, does not print diagnostics with \-DX.
3124 For internal use only.
3125 .RS 4
3126 .Sp
3127 .Vb 1
3128 \& SV * PAD_SVl(PADOFFSET po)
3129 .Ve
3130 .RE
3131 .RS 4
3132 .RE
3133 .ie n .IP """SAVECLEARSV""" 4
3134 .el .IP \f(CWSAVECLEARSV\fR 4
3135 .IX Xref "SAVECLEARSV"
3136 .IX Item "SAVECLEARSV"
3137 Clear the pointed to pad value on scope exit. (i.e. the runtime action of
3138 \&\f(CW\*(C`my\*(C'\fR)
3139 .RS 4
3140 .Sp
3141 .Vb 1
3142 \& void SAVECLEARSV(SV **svp)
3143 .Ve
3144 .RE
3145 .RS 4
3146 .RE
3147 .ie n .IP """SAVECOMPPAD""" 4
3148 .el .IP \f(CWSAVECOMPPAD\fR 4
3149 .IX Xref "SAVECOMPPAD"
3150 .IX Item "SAVECOMPPAD"
3151 save \f(CW\*(C`PL_comppad\*(C'\fR and \f(CW\*(C`PL_curpad\*(C'\fR
3152 .RS 4
3153 .Sp
3154 .Vb 1
3155 \& void SAVECOMPPAD()
3156 .Ve
3157 .RE
3158 .RS 4
3159 .RE
3160 .ie n .IP """SAVEPADSV""" 4
3161 .el .IP \f(CWSAVEPADSV\fR 4
3162 .IX Xref "SAVEPADSV"
3163 .IX Item "SAVEPADSV"
3164 Save a pad slot (used to restore after an iteration)
3165 .RS 4
3166 .Sp
3167 .Vb 1
3168 \& void SAVEPADSV(PADOFFSET po)
3169 .Ve
3170 .RE
3171 .RS 4
3172 .RE
3173 .SH "Password and Group access"
3174 .IX Header "Password and Group access"
3175 There are currently no internal API items in Password and Group access
3176 .SH "Paths to system commands"
3177 .IX Header "Paths to system commands"
3178 There are currently no internal API items in Paths to system commands
3179 .SH "Prototype information"
3180 .IX Header "Prototype information"
3181 There are currently no internal API items in Prototype information
3182 .SH "Reference-counted stack manipulation"
3183 .IX Header "Reference-counted stack manipulation"
3184 There are currently no internal API items in Reference-counted stack manipulation
3185 .SH "REGEXP Functions"
3186 .IX Xref "RX_OFFSp"
3187 .IX Header "REGEXP Functions"
3188 .ie n .IP """regnode""" 4
3189 .el .IP \f(CWregnode\fR 4
3190 .IX Item "regnode"
3191 Described in perlreguts.
3192 .SH "Reports and Formats"
3193 .IX Header "Reports and Formats"
3194 There are currently no internal API items in Reports and Formats
3195 .SH Signals
3196 .IX Header "Signals"
3197 There are currently no internal API items in Signals
3198 .SH "Site configuration"
3199 .IX Header "Site configuration"
3200 There are currently no internal API items in Site configuration
3201 .SH "Sockets configuration values"
3202 .IX Header "Sockets configuration values"
3203 There are currently no internal API items in Sockets configuration values
3204 .SH "Source Filters"
3205 .IX Header "Source Filters"
3206 There are currently no internal API items in Source Filters
3207 .SH "Stack Manipulation Macros"
3208 .IX Header "Stack Manipulation Macros"
3209 .ie n .IP """djSP""" 4
3210 .el .IP \f(CWdjSP\fR 4
3211 .IX Xref "djSP"
3212 .IX Item "djSP"
3213 Declare Just \f(CW\*(C`SP\*(C'\fR. This is actually identical to \f(CW\*(C`dSP\*(C'\fR, and declares
3214 a local copy of perl's stack pointer, available via the \f(CW\*(C`SP\*(C'\fR macro.
3215 See \f(CW\*(C`"SP" in perlapi\*(C'\fR. (Available for backward source code compatibility with
3216 the old (Perl 5.005) thread model.)
3217 .RS 4
3218 .Sp
3219 .Vb 1
3220 \& djSP();
3221 .Ve
3222 .RE
3223 .RS 4
3224 .RE
3225 .ie n .IP """LVRET""" 4
3226 .el .IP \f(CWLVRET\fR 4
3227 .IX Xref "LVRET"
3228 .IX Item "LVRET"
3229 True if this op will be the return value of an lvalue subroutine
3230 .ie n .IP """save_alloc""" 4
3231 .el .IP \f(CWsave_alloc\fR 4
3232 .IX Xref "save_alloc"
3233 .IX Item "save_alloc"
3234 Implements "\f(CW\*(C`SSNEW\*(C'\fR" in perlapi and kin, which should be used instead of this
3235 function.
3236 .RS 4
3237 .Sp
3238 .Vb 1
3239 \& SSize_t save_alloc(SSize_t size, I32 pad)
3240 .Ve
3241 .RE
3242 .RS 4
3243 .RE
3244 .SH "String Handling"
3245 .IX Header "String Handling"
3246 .ie n .IP """delimcpy_no_escape""" 4
3247 .el .IP \f(CWdelimcpy_no_escape\fR 4
3248 .IX Xref "delimcpy_no_escape"
3249 .IX Item "delimcpy_no_escape"
3250 Copy a source buffer to a destination buffer, stopping at (but not including)
3251 the first occurrence in the source of the delimiter byte, \f(CW\*(C`delim\*(C'\fR. The source
3252 is the bytes between \f(CW\*(C`from\*(C'\fR\ and\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1. Similarly, the dest is
3253 \&\f(CW\*(C`to\*(C'\fR up to \f(CW\*(C`to_end\*(C'\fR.
3254 .Sp
3255 The number of bytes copied is written to \f(CW*retlen\fR.
3256 .Sp
3257 Returns the position of \f(CW\*(C`delim\*(C'\fR in the \f(CW\*(C`from\*(C'\fR buffer, but if there is no
3258 such occurrence before \f(CW\*(C`from_end\*(C'\fR, then \f(CW\*(C`from_end\*(C'\fR is returned, and the entire
3259 buffer \f(CW\*(C`from\*(C'\fR\ ..\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1 is copied.
3260 .Sp
3261 If there is room in the destination available after the copy, an extra
3262 terminating safety \f(CW\*(C`NUL\*(C'\fR byte is appended (not included in the returned
3263 length).
3264 .Sp
3265 The error case is if the destination buffer is not large enough to accommodate
3266 everything that should be copied. In this situation, a value larger than
3267 \&\f(CW\*(C`to_end\*(C'\fR\ \-\ \f(CW\*(C`to\*(C'\fR is written to \f(CW*retlen\fR, and as much of the source as
3268 fits will be written to the destination. Not having room for the safety \f(CW\*(C`NUL\*(C'\fR
3269 is not considered an error.
3270 .RS 4
3271 .Sp
3272 .Vb 3
3273 \& char * delimcpy_no_escape(char *to, const char *to_end,
3274 \& const char *from, const char *from_end,
3275 \& const int delim, I32 *retlen)
3276 .Ve
3277 .RE
3278 .RS 4
3279 .RE
3280 .ie n .IP """my_cxt_init""" 4
3281 .el .IP \f(CWmy_cxt_init\fR 4
3282 .IX Xref "my_cxt_init"
3283 .IX Item "my_cxt_init"
3284 Implements the "\f(CW\*(C`MY_CXT_INIT\*(C'\fR" in perlxs macro, which you should use instead.
3285 .Sp
3286 The first time a module is loaded, the global \f(CW\*(C`PL_my_cxt_index\*(C'\fR is incremented,
3287 and that value is assigned to that module's static \f(CW\*(C`my_cxt_index\*(C'\fR (whose
3288 address is passed as an arg). Then, for each interpreter this function is
3289 called for, it makes sure a \f(CW\*(C`void*\*(C'\fR slot is available to hang the static data
3290 off, by allocating or extending the interpreter's \f(CW\*(C`PL_my_cxt_list\*(C'\fR array
3291 .Sp
3292 NOTE: \f(CW\*(C`my_cxt_init\*(C'\fR must be explicitly called as
3293 \&\f(CW\*(C`Perl_my_cxt_init\*(C'\fR
3294 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
3295 .RS 4
3296 .Sp
3297 .Vb 1
3298 \& void * Perl_my_cxt_init(pTHX_ int *indexp, size_t size)
3299 .Ve
3300 .RE
3301 .RS 4
3302 .RE
3303 .ie n .IP """quadmath_format_needed""" 4
3304 .el .IP \f(CWquadmath_format_needed\fR 4
3305 .IX Xref "quadmath_format_needed"
3306 .IX Item "quadmath_format_needed"
3307 \&\f(CWquadmath_format_needed()\fR returns true if the \f(CW\*(C`format\*(C'\fR string seems to
3308 contain at least one non-Q-prefixed \f(CW\*(C`%[efgaEFGA]\*(C'\fR format specifier,
3309 or returns false otherwise.
3310 .Sp
3311 The format specifier detection is not complete printf-syntax detection,
3312 but it should catch most common cases.
3313 .Sp
3314 If true is returned, those arguments \fBshould\fR in theory be processed
3315 with \f(CWquadmath_snprintf()\fR, but in case there is more than one such
3316 format specifier (see "quadmath_format_valid"), and if there is
3317 anything else beyond that one (even just a single byte), they
3318 \&\fBcannot\fR be processed because \f(CWquadmath_snprintf()\fR is very strict,
3319 accepting only one format spec, and nothing else.
3320 In this case, the code should probably fail.
3321 .RS 4
3322 .Sp
3323 .Vb 1
3324 \& bool quadmath_format_needed(const char *format)
3325 .Ve
3326 .RE
3327 .RS 4
3328 .RE
3329 .ie n .IP """quadmath_format_valid""" 4
3330 .el .IP \f(CWquadmath_format_valid\fR 4
3331 .IX Xref "quadmath_format_valid"
3332 .IX Item "quadmath_format_valid"
3333 \&\f(CWquadmath_snprintf()\fR is very strict about its \f(CW\*(C`format\*(C'\fR string and will
3334 fail, returning \-1, if the format is invalid. It accepts exactly
3335 one format spec.
3336 .Sp
3337 \&\f(CWquadmath_format_valid()\fR checks that the intended single spec looks
3338 sane: begins with \f(CW\*(C`%\*(C'\fR, has only one \f(CW\*(C`%\*(C'\fR, ends with \f(CW\*(C`[efgaEFGA]\*(C'\fR,
3339 and has \f(CW\*(C`Q\*(C'\fR before it. This is not a full "printf syntax check",
3340 just the basics.
3341 .Sp
3342 Returns true if it is valid, false if not.
3343 .Sp
3344 See also "quadmath_format_needed".
3345 .RS 4
3346 .Sp
3347 .Vb 1
3348 \& bool quadmath_format_valid(const char *format)
3349 .Ve
3350 .RE
3351 .RS 4
3352 .RE
3353 .SH "SV Flags"
3354 .IX Header "SV Flags"
3355 .ie n .IP """SVt_INVLIST""" 4
3356 .el .IP \f(CWSVt_INVLIST\fR 4
3357 .IX Xref "SVt_INVLIST"
3358 .IX Item "SVt_INVLIST"
3359 Type flag for scalars. See "svtype" in perlapi.
3360 .SH "SV Handling"
3361 .IX Header "SV Handling"
3362 .ie n .IP """PL_Sv""" 4
3363 .el .IP \f(CWPL_Sv\fR 4
3364 .IX Xref "PL_Sv"
3365 .IX Item "PL_Sv"
3366 A scratch pad SV for whatever temporary use you need. Chiefly used as a
3367 fallback by macros on platforms where "PERL_USE_GCC_BRACE_GROUPS" in perlapi> is
3368 unavailable, and which would otherwise evaluate their SV parameter more than
3369 once.
3370 .Sp
3371 \&\fBBUT BEWARE\fR, if this is used in a situation where something that is using it
3372 is in a call stack with something else that is using it, this variable would
3373 get zapped, leading to hard-to-diagnose errors.
3374 .RS 4
3375 .Sp
3376 .Vb 1
3377 \& PL_Sv
3378 .Ve
3379 .RE
3380 .RS 4
3381 .RE
3382 .ie n .IP """sv_add_arena""" 4
3383 .el .IP \f(CWsv_add_arena\fR 4
3384 .IX Xref "sv_add_arena"
3385 .IX Item "sv_add_arena"
3386 Given a chunk of memory, link it to the head of the list of arenas,
3387 and split it into a list of free SVs.
3388 .RS 4
3389 .Sp
3390 .Vb 2
3391 \& void sv_add_arena(char * const ptr, const U32 size,
3392 \& const U32 flags)
3393 .Ve
3394 .RE
3395 .RS 4
3396 .RE
3397 .ie n .IP """sv_2bool""" 4
3398 .el .IP \f(CWsv_2bool\fR 4
3399 .IX Xref "sv_2bool"
3400 .IX Item "sv_2bool"
3401 This macro is only used by \f(CWsv_true()\fR or its macro equivalent, and only if
3402 the latter's argument is neither \f(CW\*(C`SvPOK\*(C'\fR, \f(CW\*(C`SvIOK\*(C'\fR nor \f(CW\*(C`SvNOK\*(C'\fR.
3403 It calls \f(CW\*(C`sv_2bool_flags\*(C'\fR with the \f(CW\*(C`SV_GMAGIC\*(C'\fR flag.
3404 .RS 4
3405 .Sp
3406 .Vb 1
3407 \& bool sv_2bool(SV * const sv)
3408 .Ve
3409 .RE
3410 .RS 4
3411 .RE
3412 .ie n .IP """sv_2bool_flags""" 4
3413 .el .IP \f(CWsv_2bool_flags\fR 4
3414 .IX Xref "sv_2bool_flags"
3415 .IX Item "sv_2bool_flags"
3416 This function is only used by \f(CWsv_true()\fR and friends, and only if
3417 the latter's argument is neither \f(CW\*(C`SvPOK\*(C'\fR, \f(CW\*(C`SvIOK\*(C'\fR nor \f(CW\*(C`SvNOK\*(C'\fR. If the flags
3418 contain \f(CW\*(C`SV_GMAGIC\*(C'\fR, then it does an \f(CWmg_get()\fR first.
3419 .RS 4
3420 .Sp
3421 .Vb 1
3422 \& bool sv_2bool_flags(SV *sv, I32 flags)
3423 .Ve
3424 .RE
3425 .RS 4
3426 .RE
3427 .ie n .IP """sv_clean_all""" 4
3428 .el .IP \f(CWsv_clean_all\fR 4
3429 .IX Xref "sv_clean_all"
3430 .IX Item "sv_clean_all"
3431 Decrement the refcnt of each remaining SV, possibly triggering a
3432 cleanup. This function may have to be called multiple times to free
3433 SVs which are in complex self-referential hierarchies.
3434 .RS 4
3435 .Sp
3436 .Vb 1
3437 \& SSize_t sv_clean_all()
3438 .Ve
3439 .RE
3440 .RS 4
3441 .RE
3442 .ie n .IP """sv_clean_objs""" 4
3443 .el .IP \f(CWsv_clean_objs\fR 4
3444 .IX Xref "sv_clean_objs"
3445 .IX Item "sv_clean_objs"
3446 Attempt to destroy all objects not yet freed.
3447 .RS 4
3448 .Sp
3449 .Vb 1
3450 \& void sv_clean_objs()
3451 .Ve
3452 .RE
3453 .RS 4
3454 .RE
3455 .ie n .IP """sv_free_arenas""" 4
3456 .el .IP \f(CWsv_free_arenas\fR 4
3457 .IX Xref "sv_free_arenas"
3458 .IX Item "sv_free_arenas"
3459 Deallocate the memory used by all arenas. Note that all the individual SV
3460 heads and bodies within the arenas must already have been freed.
3461 .RS 4
3462 .Sp
3463 .Vb 1
3464 \& void sv_free_arenas()
3465 .Ve
3466 .RE
3467 .RS 4
3468 .RE
3469 .ie n .IP """sv_grow""" 4
3470 .el .IP \f(CWsv_grow\fR 4
3471 .IX Xref "sv_grow"
3472 .IX Item "sv_grow"
3473 Expands the character buffer in the SV. If necessary, uses \f(CW\*(C`sv_unref\*(C'\fR and
3474 upgrades the SV to \f(CW\*(C`SVt_PV\*(C'\fR. Returns a pointer to the character buffer.
3475 Use the \f(CW\*(C`SvGROW\*(C'\fR wrapper instead.
3476 .RS 4
3477 .Sp
3478 .Vb 1
3479 \& char * sv_grow(SV * const sv, STRLEN newlen)
3480 .Ve
3481 .RE
3482 .RS 4
3483 .RE
3484 .ie n .IP """sv_grow_fresh""" 4
3485 .el .IP \f(CWsv_grow_fresh\fR 4
3486 .IX Xref "sv_grow_fresh"
3487 .IX Item "sv_grow_fresh"
3488 A cut-down version of sv_grow intended only for when sv is a freshly-minted
3489 SVt_PV, SVt_PVIV, SVt_PVNV, or SVt_PVMG. i.e. sv has the default flags, has
3490 never been any other type, and does not have an existing string. Basically,
3491 just assigns a char buffer and returns a pointer to it.
3492 .RS 4
3493 .Sp
3494 .Vb 1
3495 \& char * sv_grow_fresh(SV * const sv, STRLEN newlen)
3496 .Ve
3497 .RE
3498 .RS 4
3499 .RE
3500 .ie n .IP """sv_newref""" 4
3501 .el .IP \f(CWsv_newref\fR 4
3502 .IX Xref "sv_newref"
3503 .IX Item "sv_newref"
3504 Increment an SV's reference count. Use the \f(CWSvREFCNT_inc()\fR wrapper
3505 instead.
3506 .RS 4
3507 .Sp
3508 .Vb 1
3509 \& SV * sv_newref(SV * const sv)
3510 .Ve
3511 .RE
3512 .RS 4
3513 .RE
3514 .ie n .IP """sv_2num""" 4
3515 .el .IP \f(CWsv_2num\fR 4
3516 .IX Xref "sv_2num"
3517 .IX Item "sv_2num"
3518 NOTE: \f(CW\*(C`sv_2num\*(C'\fR is \fBexperimental\fR and may change or be
3519 removed without notice.
3520 .Sp
3521 Return an SV with the numeric value of the source SV, doing any necessary
3522 reference or overload conversion. The caller is expected to have handled
3523 get-magic already.
3524 .RS 4
3525 .Sp
3526 .Vb 1
3527 \& SV * sv_2num(SV * const sv)
3528 .Ve
3529 .RE
3530 .RS 4
3531 .RE
3532 .ie n .IP """sv_pv""" 4
3533 .el .IP \f(CWsv_pv\fR 4
3534 .IX Xref "sv_pv"
3535 .IX Item "sv_pv"
3536 Use the \f(CW\*(C`SvPV_nolen\*(C'\fR macro instead
3537 .RS 4
3538 .Sp
3539 .Vb 1
3540 \& char * sv_pv(SV *sv)
3541 .Ve
3542 .RE
3543 .RS 4
3544 .RE
3545 .ie n .IP """sv_pvbyte""" 4
3546 .el .IP \f(CWsv_pvbyte\fR 4
3547 .IX Xref "sv_pvbyte"
3548 .IX Item "sv_pvbyte"
3549 Use \f(CW\*(C`SvPVbyte_nolen\*(C'\fR instead.
3550 .RS 4
3551 .Sp
3552 .Vb 1
3553 \& char * sv_pvbyte(SV *sv)
3554 .Ve
3555 .RE
3556 .RS 4
3557 .RE
3558 .ie n .IP """sv_pvbyten_force""" 4
3559 .el .IP \f(CWsv_pvbyten_force\fR 4
3560 .IX Xref "sv_pvbyten_force"
3561 .IX Item "sv_pvbyten_force"
3562 The backend for the \f(CW\*(C`SvPVbytex_force\*(C'\fR macro. Always use the macro
3563 instead. If the SV cannot be downgraded from UTF\-8, this croaks.
3564 .RS 4
3565 .Sp
3566 .Vb 1
3567 \& char * sv_pvbyten_force(SV * const sv, STRLEN * const lp)
3568 .Ve
3569 .RE
3570 .RS 4
3571 .RE
3572 .ie n .IP """sv_2pvbyte_nolen""" 4
3573 .el .IP \f(CWsv_2pvbyte_nolen\fR 4
3574 .IX Xref "sv_2pvbyte_nolen"
3575 .IX Item "sv_2pvbyte_nolen"
3576 Return a pointer to the byte-encoded representation of the SV.
3577 May cause the SV to be downgraded from UTF\-8 as a side-effect.
3578 .Sp
3579 Usually accessed via the \f(CW\*(C`SvPVbyte_nolen\*(C'\fR macro.
3580 .RS 4
3581 .Sp
3582 .Vb 1
3583 \& char * sv_2pvbyte_nolen(SV *sv)
3584 .Ve
3585 .RE
3586 .RS 4
3587 .RE
3588 .ie n .IP """sv_pvn_force""" 4
3589 .el .IP \f(CWsv_pvn_force\fR 4
3590 .IX Xref "sv_pvn_force"
3591 .IX Item "sv_pvn_force"
3592 Get a sensible string out of the SV somehow.
3593 A private implementation of the \f(CW\*(C`SvPV_force\*(C'\fR macro for compilers which
3594 can't cope with complex macro expressions. Always use the macro instead.
3595 .RS 4
3596 .Sp
3597 .Vb 1
3598 \& char * sv_pvn_force(SV *sv, STRLEN *lp)
3599 .Ve
3600 .RE
3601 .RS 4
3602 .RE
3603 .ie n .IP """sv_2pv_nolen""" 4
3604 .el .IP \f(CWsv_2pv_nolen\fR 4
3605 .IX Xref "sv_2pv_nolen"
3606 .IX Item "sv_2pv_nolen"
3607 Like \f(CWsv_2pv()\fR, but doesn't return the length too. You should usually
3608 use the macro wrapper \f(CWSvPV_nolen(sv)\fR instead.
3609 .RS 4
3610 .Sp
3611 .Vb 1
3612 \& char * sv_2pv_nolen(SV *sv)
3613 .Ve
3614 .RE
3615 .RS 4
3616 .RE
3617 .ie n .IP """sv_pvutf8n_force""" 4
3618 .el .IP \f(CWsv_pvutf8n_force\fR 4
3619 .IX Xref "sv_pvutf8n_force"
3620 .IX Item "sv_pvutf8n_force"
3621 The backend for the \f(CW\*(C`SvPVutf8x_force\*(C'\fR macro. Always use the macro
3622 instead.
3623 .RS 4
3624 .Sp
3625 .Vb 1
3626 \& char * sv_pvutf8n_force(SV * const sv, STRLEN * const lp)
3627 .Ve
3628 .RE
3629 .RS 4
3630 .RE
3631 .ie n .IP """sv_2pvutf8_nolen""" 4
3632 .el .IP \f(CWsv_2pvutf8_nolen\fR 4
3633 .IX Xref "sv_2pvutf8_nolen"
3634 .IX Item "sv_2pvutf8_nolen"
3635 Return a pointer to the UTF\-8\-encoded representation of the SV.
3636 May cause the SV to be upgraded to UTF\-8 as a side-effect.
3637 .Sp
3638 Usually accessed via the \f(CW\*(C`SvPVutf8_nolen\*(C'\fR macro.
3639 .RS 4
3640 .Sp
3641 .Vb 1
3642 \& char * sv_2pvutf8_nolen(SV *sv)
3643 .Ve
3644 .RE
3645 .RS 4
3646 .RE
3647 .ie n .IP """sv_pvutf8""" 4
3648 .el .IP \f(CWsv_pvutf8\fR 4
3649 .IX Xref "sv_pvutf8"
3650 .IX Item "sv_pvutf8"
3651 Use the \f(CW\*(C`SvPVutf8_nolen\*(C'\fR macro instead
3652 .RS 4
3653 .Sp
3654 .Vb 1
3655 \& char * sv_pvutf8(SV *sv)
3656 .Ve
3657 .RE
3658 .RS 4
3659 .RE
3660 .ie n .IP """sv_tainted""" 4
3661 .el .IP \f(CWsv_tainted\fR 4
3662 .IX Xref "sv_tainted"
3663 .IX Item "sv_tainted"
3664 Test an SV for taintedness. Use \f(CW\*(C`SvTAINTED\*(C'\fR instead.
3665 .RS 4
3666 .Sp
3667 .Vb 1
3668 \& bool sv_tainted(SV * const sv)
3669 .Ve
3670 .RE
3671 .RS 4
3672 .RE
3673 .ie n .IP """SvTHINKFIRST""" 4
3674 .el .IP \f(CWSvTHINKFIRST\fR 4
3675 .IX Xref "SvTHINKFIRST"
3676 .IX Item "SvTHINKFIRST"
3677 A quick flag check to see whether an \f(CW\*(C`sv\*(C'\fR should be passed to \f(CW\*(C`sv_force_normal\*(C'\fR
3678 to be "downgraded" before \f(CW\*(C`SvIVX\*(C'\fR or \f(CW\*(C`SvPVX\*(C'\fR can be modified directly.
3679 .Sp
3680 For example, if your scalar is a reference and you want to modify the \f(CW\*(C`SvIVX\*(C'\fR
3681 slot, you can't just do \f(CW\*(C`SvROK_off\*(C'\fR, as that will leak the referent.
3682 .Sp
3683 This is used internally by various sv-modifying functions, such as
3684 \&\f(CW\*(C`sv_setsv\*(C'\fR, \f(CW\*(C`sv_setiv\*(C'\fR and \f(CW\*(C`sv_pvn_force\*(C'\fR.
3685 .Sp
3686 One case that this does not handle is a gv without SvFAKE set. After
3687 .Sp
3688 .Vb 1
3689 \& if (SvTHINKFIRST(gv)) sv_force_normal(gv);
3690 .Ve
3691 .Sp
3692 it will still be a gv.
3693 .Sp
3694 \&\f(CW\*(C`SvTHINKFIRST\*(C'\fR sometimes produces false positives. In those cases
3695 \&\f(CW\*(C`sv_force_normal\*(C'\fR does nothing.
3696 .RS 4
3697 .Sp
3698 .Vb 1
3699 \& U32 SvTHINKFIRST(SV *sv)
3700 .Ve
3701 .RE
3702 .RS 4
3703 .RE
3704 .ie n .IP """sv_true""" 4
3705 .el .IP \f(CWsv_true\fR 4
3706 .IX Xref "sv_true"
3707 .IX Item "sv_true"
3708 Returns true if the SV has a true value by Perl's rules.
3709 Use the \f(CW\*(C`SvTRUE\*(C'\fR macro instead, which may call \f(CWsv_true()\fR or may
3710 instead use an in-line version.
3711 .RS 4
3712 .Sp
3713 .Vb 1
3714 \& I32 sv_true(SV * const sv)
3715 .Ve
3716 .RE
3717 .RS 4
3718 .RE
3719 .ie n .IP """sv_untaint""" 4
3720 .el .IP \f(CWsv_untaint\fR 4
3721 .IX Xref "sv_untaint"
3722 .IX Item "sv_untaint"
3723 Untaint an SV. Use \f(CW\*(C`SvTAINTED_off\*(C'\fR instead.
3724 .RS 4
3725 .Sp
3726 .Vb 1
3727 \& void sv_untaint(SV * const sv)
3728 .Ve
3729 .RE
3730 .RS 4
3731 .RE
3732 .SH Tainting
3733 .IX Header "Tainting"
3734 .ie n .IP """sv_taint""" 4
3735 .el .IP \f(CWsv_taint\fR 4
3736 .IX Xref "sv_taint"
3737 .IX Item "sv_taint"
3738 Taint an SV. Use \f(CW\*(C`SvTAINTED_on\*(C'\fR instead.
3739 .RS 4
3740 .Sp
3741 .Vb 1
3742 \& void sv_taint(SV *sv)
3743 .Ve
3744 .RE
3745 .RS 4
3746 .RE
3747 .ie n .IP """TAINT""" 4
3748 .el .IP \f(CWTAINT\fR 4
3749 .IX Xref "TAINT"
3750 .IX Item "TAINT"
3751 If we aren't in taint checking mode, do nothing;
3752 otherwise indicate to "\f(CW\*(C`TAINT_set\*(C'\fR" and "\f(CW\*(C`TAINT_PROPER\*(C'\fR" that some
3753 unspecified element is tainted.
3754 .RS 4
3755 .Sp
3756 .Vb 1
3757 \& void TAINT()
3758 .Ve
3759 .RE
3760 .RS 4
3761 .RE
3762 .ie n .IP """TAINT_ENV""" 4
3763 .el .IP \f(CWTAINT_ENV\fR 4
3764 .IX Xref "TAINT_ENV"
3765 .IX Item "TAINT_ENV"
3766 Looks at several components of \f(CW%ENV\fR for taintedness, and
3767 calls "\f(CW\*(C`taint_proper\*(C'\fR" if any are tainted. The components it searches are
3768 things like \f(CW$PATH\fR.
3769 .RS 4
3770 .Sp
3771 .Vb 1
3772 \& void TAINT_ENV
3773 .Ve
3774 .RE
3775 .RS 4
3776 .RE
3777 .ie n .IP """taint_env""" 4
3778 .el .IP \f(CWtaint_env\fR 4
3779 .IX Xref "taint_env"
3780 .IX Item "taint_env"
3781 Implements the "TAINT_ENV" macro, which you should generally use instead.
3782 .RS 4
3783 .Sp
3784 .Vb 1
3785 \& void taint_env()
3786 .Ve
3787 .RE
3788 .RS 4
3789 .RE
3790 .ie n .IP """TAINT_get""" 4
3791 .el .IP \f(CWTAINT_get\fR 4
3792 .IX Xref "TAINT_get"
3793 .IX Item "TAINT_get"
3794 Returns a boolean as to whether some element is tainted or not.
3795 .RS 4
3796 .Sp
3797 .Vb 1
3798 \& bool TAINT_get()
3799 .Ve
3800 .RE
3801 .RS 4
3802 .RE
3803 .ie n .IP """TAINT_IF""" 4
3804 .el .IP \f(CWTAINT_IF\fR 4
3805 .IX Xref "TAINT_IF"
3806 .IX Item "TAINT_IF"
3807 If \f(CW\*(C`c\*(C'\fR evaluates to true, call "\f(CW\*(C`TAINT\*(C'\fR" to indicate that something is
3808 tainted; otherwise do nothing.
3809 .RS 4
3810 .Sp
3811 .Vb 1
3812 \& void TAINT_IF(bool c)
3813 .Ve
3814 .RE
3815 .RS 4
3816 .RE
3817 .ie n .IP """TAINTING_get""" 4
3818 .el .IP \f(CWTAINTING_get\fR 4
3819 .IX Xref "TAINTING_get"
3820 .IX Item "TAINTING_get"
3821 Returns a boolean as to whether taint checking is enabled or not.
3822 .RS 4
3823 .Sp
3824 .Vb 1
3825 \& bool TAINTING_get()
3826 .Ve
3827 .RE
3828 .RS 4
3829 .RE
3830 .ie n .IP """TAINTING_set""" 4
3831 .el .IP \f(CWTAINTING_set\fR 4
3832 .IX Xref "TAINTING_set"
3833 .IX Item "TAINTING_set"
3834 Turn taint checking mode off/on
3835 .RS 4
3836 .Sp
3837 .Vb 1
3838 \& void TAINTING_set(bool s)
3839 .Ve
3840 .RE
3841 .RS 4
3842 .RE
3843 .ie n .IP """TAINT_NOT""" 4
3844 .el .IP \f(CWTAINT_NOT\fR 4
3845 .IX Xref "TAINT_NOT"
3846 .IX Item "TAINT_NOT"
3847 Remove any taintedness previously set by, \fIe.g.\fR, \f(CW\*(C`TAINT\*(C'\fR.
3848 .RS 4
3849 .Sp
3850 .Vb 1
3851 \& void TAINT_NOT()
3852 .Ve
3853 .RE
3854 .RS 4
3855 .RE
3856 .ie n .IP """TAINT_PROPER""" 4
3857 .el .IP \f(CWTAINT_PROPER\fR 4
3858 .IX Xref "TAINT_PROPER"
3859 .IX Item "TAINT_PROPER"
3860 If no element is tainted, do nothing;
3861 otherwise output a message (containing \f(CW\*(C`s\*(C'\fR) that indicates there is a
3862 tainting violation. If such violations are fatal, it croaks.
3863 .RS 4
3864 .Sp
3865 .Vb 1
3866 \& void TAINT_PROPER(const char * s)
3867 .Ve
3868 .RE
3869 .RS 4
3870 .RE
3871 .ie n .IP """taint_proper""" 4
3872 .el .IP \f(CWtaint_proper\fR 4
3873 .IX Xref "taint_proper"
3874 .IX Item "taint_proper"
3875 Implements the "TAINT_PROPER" macro, which you should generally use instead.
3876 .RS 4
3877 .Sp
3878 .Vb 1
3879 \& void taint_proper(const char *f, const char * const s)
3880 .Ve
3881 .RE
3882 .RS 4
3883 .RE
3884 .ie n .IP """TAINT_set""" 4
3885 .el .IP \f(CWTAINT_set\fR 4
3886 .IX Xref "TAINT_set"
3887 .IX Item "TAINT_set"
3888 If \f(CW\*(C`s\*(C'\fR is true, "\f(CW\*(C`TAINT_get\*(C'\fR" returns true;
3889 If \f(CW\*(C`s\*(C'\fR is false, "\f(CW\*(C`TAINT_get\*(C'\fR" returns false;
3890 .RS 4
3891 .Sp
3892 .Vb 1
3893 \& void TAINT_set(bool s)
3894 .Ve
3895 .RE
3896 .RS 4
3897 .RE
3898 .ie n .IP """TAINT_WARN_get""" 4
3899 .el .IP \f(CWTAINT_WARN_get\fR 4
3900 .IX Xref "TAINT_WARN_get"
3901 .IX Item "TAINT_WARN_get"
3902 Returns false if tainting violations are fatal;
3903 Returns true if they're just warnings
3904 .RS 4
3905 .Sp
3906 .Vb 1
3907 \& bool TAINT_WARN_get()
3908 .Ve
3909 .RE
3910 .RS 4
3911 .RE
3912 .ie n .IP """TAINT_WARN_set""" 4
3913 .el .IP \f(CWTAINT_WARN_set\fR 4
3914 .IX Xref "TAINT_WARN_set"
3915 .IX Item "TAINT_WARN_set"
3916 \&\f(CW\*(C`s\*(C'\fR being true indicates "\f(CW\*(C`TAINT_WARN_get\*(C'\fR" should return that tainting
3917 violations are just warnings
3918 .Sp
3919 \&\f(CW\*(C`s\*(C'\fR being false indicates "\f(CW\*(C`TAINT_WARN_get\*(C'\fR" should return that tainting
3920 violations are fatal.
3921 .RS 4
3922 .Sp
3923 .Vb 1
3924 \& void TAINT_WARN_set(bool s)
3925 .Ve
3926 .RE
3927 .RS 4
3928 .RE
3929 .SH Time
3930 .IX Header "Time"
3931 There are currently no internal API items in Time
3932 .SH "Typedef names"
3933 .IX Header "Typedef names"
3934 There are currently no internal API items in Typedef names
3935 .SH "Unicode Support"
3936 .IX Xref "FOLDEQ_LOCALE FOLDEQ_S1_ALREADY_FOLDED FOLDEQ_S1_FOLDS_SANE FOLDEQ_S2_ALREADY_FOLDED FOLDEQ_S2_FOLDS_SANE FOLDEQ_UTF8_NOMIX_ASCII"
3937 .IX Header "Unicode Support"
3938 .ie n .IP """bytes_from_utf8_loc""" 4
3939 .el .IP \f(CWbytes_from_utf8_loc\fR 4
3940 .IX Xref "bytes_from_utf8_loc"
3941 .IX Item "bytes_from_utf8_loc"
3942 NOTE: \f(CW\*(C`bytes_from_utf8_loc\*(C'\fR is \fBexperimental\fR and may change or be
3943 removed without notice.
3944 .Sp
3945 Like \f(CW\*(C`"bytes_from_utf8" in perlapi()\*(C'\fR, but takes an extra parameter, a pointer
3946 to where to store the location of the first character in \f(CW"s"\fR that cannot be
3947 converted to non\-UTF8.
3948 .Sp
3949 If that parameter is \f(CW\*(C`NULL\*(C'\fR, this function behaves identically to
3950 \&\f(CW\*(C`bytes_from_utf8\*(C'\fR.
3951 .Sp
3952 Otherwise if \f(CW*is_utf8p\fR is 0 on input, the function behaves identically to
3953 \&\f(CW\*(C`bytes_from_utf8\*(C'\fR, except it also sets \f(CW*first_non_downgradable\fR to \f(CW\*(C`NULL\*(C'\fR.
3954 .Sp
3955 Otherwise, the function returns a newly created \f(CW\*(C`NUL\*(C'\fR\-terminated string
3956 containing the non\-UTF8 equivalent of the convertible first portion of
3957 \&\f(CW"s"\fR. \f(CW*lenp\fR is set to its length, not including the terminating \f(CW\*(C`NUL\*(C'\fR.
3958 If the entire input string was converted, \f(CW*is_utf8p\fR is set to a FALSE value,
3959 and \f(CW*first_non_downgradable\fR is set to \f(CW\*(C`NULL\*(C'\fR.
3960 .Sp
3961 Otherwise, \f(CW*first_non_downgradable\fR is set to point to the first byte of the
3962 first character in the original string that wasn't converted. \f(CW*is_utf8p\fR is
3963 unchanged. Note that the new string may have length 0.
3964 .Sp
3965 Another way to look at it is, if \f(CW*first_non_downgradable\fR is non\-\f(CW\*(C`NULL\*(C'\fR and
3966 \&\f(CW*is_utf8p\fR is TRUE, this function starts at the beginning of \f(CW"s"\fR and
3967 converts as many characters in it as possible stopping at the first one it
3968 finds that can't be converted to non\-UTF\-8. \f(CW*first_non_downgradable\fR is
3969 set to point to that. The function returns the portion that could be converted
3970 in a newly created \f(CW\*(C`NUL\*(C'\fR\-terminated string, and \f(CW*lenp\fR is set to its length,
3971 not including the terminating \f(CW\*(C`NUL\*(C'\fR. If the very first character in the
3972 original could not be converted, \f(CW*lenp\fR will be 0, and the new string will
3973 contain just a single \f(CW\*(C`NUL\*(C'\fR. If the entire input string was converted,
3974 \&\f(CW*is_utf8p\fR is set to FALSE and \f(CW*first_non_downgradable\fR is set to \f(CW\*(C`NULL\*(C'\fR.
3975 .Sp
3976 Upon successful return, the number of variants in the converted portion of the
3977 string can be computed by having saved the value of \f(CW*lenp\fR before the call,
3978 and subtracting the after-call value of \f(CW*lenp\fR from it.
3979 .RS 4
3980 .Sp
3981 .Vb 3
3982 \& U8 * bytes_from_utf8_loc(const U8 *s, STRLEN *lenp,
3983 \& bool *is_utf8p,
3984 \& const U8 **first_unconverted)
3985 .Ve
3986 .RE
3987 .RS 4
3988 .RE
3989 .ie n .IP """find_uninit_var""" 4
3990 .el .IP \f(CWfind_uninit_var\fR 4
3991 .IX Xref "find_uninit_var"
3992 .IX Item "find_uninit_var"
3993 NOTE: \f(CW\*(C`find_uninit_var\*(C'\fR is \fBexperimental\fR and may change or be
3994 removed without notice.
3995 .Sp
3996 Find the name of the undefined variable (if any) that caused the operator
3997 to issue a "Use of uninitialized value" warning.
3998 If match is true, only return a name if its value matches \f(CW\*(C`uninit_sv\*(C'\fR.
3999 So roughly speaking, if a unary operator (such as \f(CW\*(C`OP_COS\*(C'\fR) generates a
4000 warning, then following the direct child of the op may yield an
4001 \&\f(CW\*(C`OP_PADSV\*(C'\fR or \f(CW\*(C`OP_GV\*(C'\fR that gives the name of the undefined variable. On the
4002 other hand, with \f(CW\*(C`OP_ADD\*(C'\fR there are two branches to follow, so we only print
4003 the variable name if we get an exact match.
4004 \&\f(CW\*(C`desc_p\*(C'\fR points to a string pointer holding the description of the op.
4005 This may be updated if needed.
4006 .Sp
4007 The name is returned as a mortal SV.
4008 .Sp
4009 Assumes that \f(CW\*(C`PL_op\*(C'\fR is the OP that originally triggered the error, and that
4010 \&\f(CW\*(C`PL_comppad\*(C'\fR/\f(CW\*(C`PL_curpad\*(C'\fR points to the currently executing pad.
4011 .RS 4
4012 .Sp
4013 .Vb 3
4014 \& SV * find_uninit_var(const OP * const obase,
4015 \& const SV * const uninit_sv, bool match,
4016 \& const char **desc_p)
4017 .Ve
4018 .RE
4019 .RS 4
4020 .RE
4021 .ie n .IP """isSCRIPT_RUN""" 4
4022 .el .IP \f(CWisSCRIPT_RUN\fR 4
4023 .IX Xref "isSCRIPT_RUN"
4024 .IX Item "isSCRIPT_RUN"
4025 Returns a bool as to whether or not the sequence of bytes from \f(CW\*(C`s\*(C'\fR up to but
4026 not including \f(CW\*(C`send\*(C'\fR form a "script run". \f(CW\*(C`utf8_target\*(C'\fR is TRUE iff the
4027 sequence starting at \f(CW\*(C`s\*(C'\fR is to be treated as UTF\-8. To be precise, except for
4028 two degenerate cases given below, this function returns TRUE iff all code
4029 points in it come from any combination of three "scripts" given by the Unicode
4030 "Script Extensions" property: Common, Inherited, and possibly one other.
4031 Additionally all decimal digits must come from the same consecutive sequence of
4032 10.
4033 .Sp
4034 For example, if all the characters in the sequence are Greek, or Common, or
4035 Inherited, this function will return TRUE, provided any decimal digits in it
4036 are from the same block of digits in Common. (These are the ASCII digits
4037 "0".."9" and additionally a block for full width forms of these, and several
4038 others used in mathematical notation.) For scripts (unlike Greek) that have
4039 their own digits defined this will accept either digits from that set or from
4040 one of the Common digit sets, but not a combination of the two. Some scripts,
4041 such as Arabic, have more than one set of digits. All digits must come from
4042 the same set for this function to return TRUE.
4043 .Sp
4044 \&\f(CW*ret_script\fR, if \f(CW\*(C`ret_script\*(C'\fR is not NULL, will on return of TRUE
4045 contain the script found, using the \f(CW\*(C`SCX_enum\*(C'\fR typedef. Its value will be
4046 \&\f(CW\*(C`SCX_INVALID\*(C'\fR if the function returns FALSE.
4047 .Sp
4048 If the sequence is empty, TRUE is returned, but \f(CW*ret_script\fR (if asked for)
4049 will be \f(CW\*(C`SCX_INVALID\*(C'\fR.
4050 .Sp
4051 If the sequence contains a single code point which is unassigned to a character
4052 in the version of Unicode being used, the function will return TRUE, and the
4053 script will be \f(CW\*(C`SCX_Unknown\*(C'\fR. Any other combination of unassigned code points
4054 in the input sequence will result in the function treating the input as not
4055 being a script run.
4056 .Sp
4057 The returned script will be \f(CW\*(C`SCX_Inherited\*(C'\fR iff all the code points in it are
4058 from the Inherited script.
4059 .Sp
4060 Otherwise, the returned script will be \f(CW\*(C`SCX_Common\*(C'\fR iff all the code points in
4061 it are from the Inherited or Common scripts.
4062 .RS 4
4063 .Sp
4064 .Vb 2
4065 \& bool isSCRIPT_RUN(const U8 *s, const U8 *send,
4066 \& const bool utf8_target)
4067 .Ve
4068 .RE
4069 .RS 4
4070 .RE
4071 .ie n .IP """is_utf8_non_invariant_string""" 4
4072 .el .IP \f(CWis_utf8_non_invariant_string\fR 4
4073 .IX Xref "is_utf8_non_invariant_string"
4074 .IX Item "is_utf8_non_invariant_string"
4075 Returns TRUE if "is_utf8_invariant_string" in perlapi returns FALSE for the first
4076 \&\f(CW\*(C`len\*(C'\fR bytes of the string \f(CW\*(C`s\*(C'\fR, but they are, nonetheless, legal Perl-extended
4077 UTF\-8; otherwise returns FALSE.
4078 .Sp
4079 A TRUE return means that at least one code point represented by the sequence
4080 either is a wide character not representable as a single byte, or the
4081 representation differs depending on whether the sequence is encoded in UTF\-8 or
4082 not.
4083 .Sp
4084 See also
4085 \&\f(CW\*(C`"is_utf8_invariant_string" in perlapi\*(C'\fR,
4086 \&\f(CW\*(C`"is_utf8_string" in perlapi\*(C'\fR
4087 .RS 4
4088 .Sp
4089 .Vb 1
4090 \& bool is_utf8_non_invariant_string(const U8 * const s, STRLEN len)
4091 .Ve
4092 .RE
4093 .RS 4
4094 .RE
4095 .ie n .IP """utf8n_to_uvuni""" 4
4096 .el .IP \f(CWutf8n_to_uvuni\fR 4
4097 .IX Xref "utf8n_to_uvuni"
4098 .IX Item "utf8n_to_uvuni"
4099 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`utf8n_to_uvuni\*(C'\fR
4100 from a future release of Perl. Do not use it for
4101 new code; remove it from existing code.
4102 .Sp
4103 Instead use "utf8_to_uvchr_buf" in perlapi, or rarely, "utf8n_to_uvchr" in perlapi.
4104 .Sp
4105 This function was useful for code that wanted to handle both EBCDIC and
4106 ASCII platforms with Unicode properties, but starting in Perl v5.20, the
4107 distinctions between the platforms have mostly been made invisible to most
4108 code, so this function is quite unlikely to be what you want. If you do need
4109 this precise functionality, use instead
4110 \&\f(CW\*(C`NATIVE_TO_UNI(utf8_to_uvchr_buf(...))\*(C'\fR
4111 or \f(CW\*(C`NATIVE_TO_UNI(utf8n_to_uvchr(...))\*(C'\fR.
4112 .RS 4
4113 .Sp
4114 .Vb 2
4115 \& UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen,
4116 \& U32 flags)
4117 .Ve
4118 .RE
4119 .RS 4
4120 .RE
4121 .ie n .IP """utf8_to_uvuni""" 4
4122 .el .IP \f(CWutf8_to_uvuni\fR 4
4123 .IX Xref "utf8_to_uvuni"
4124 .IX Item "utf8_to_uvuni"
4125 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`utf8_to_uvuni\*(C'\fR
4126 from a future release of Perl. Do not use it for
4127 new code; remove it from existing code.
4128 .Sp
4129 Returns the Unicode code point of the first character in the string \f(CW\*(C`s\*(C'\fR
4130 which is assumed to be in UTF\-8 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the
4131 length, in bytes, of that character.
4132 .Sp
4133 Some, but not all, UTF\-8 malformations are detected, and in fact, some
4134 malformed input could cause reading beyond the end of the input buffer, which
4135 is one reason why this function is deprecated. The other is that only in
4136 extremely limited circumstances should the Unicode versus native code point be
4137 of any interest to you.
4138 .Sp
4139 If \f(CW\*(C`s\*(C'\fR points to one of the detected malformations, and UTF8 warnings are
4140 enabled, zero is returned and \f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR doesn't point to
4141 NULL) to \-1. If those warnings are off, the computed value if well-defined (or
4142 the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and \f(CW*retlen\fR
4143 is set (if \f(CW\*(C`retlen\*(C'\fR isn't NULL) so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR) is the
4144 next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed character.
4145 See "utf8n_to_uvchr" in perlapi for details on when the REPLACEMENT CHARACTER is returned.
4146 .RS 4
4147 .Sp
4148 .Vb 1
4149 \& UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
4150 .Ve
4151 .RE
4152 .RS 4
4153 .RE
4154 .ie n .IP """uvoffuni_to_utf8_flags""" 4
4155 .el .IP \f(CWuvoffuni_to_utf8_flags\fR 4
4156 .IX Xref "uvoffuni_to_utf8_flags"
4157 .IX Item "uvoffuni_to_utf8_flags"
4158 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.
4159 Instead, \fBAlmost all code should use "uvchr_to_utf8" in perlapi or
4160 "uvchr_to_utf8_flags" in perlapi\fR.
4161 .Sp
4162 This function is like them, but the input is a strict Unicode
4163 (as opposed to native) code point. Only in very rare circumstances should code
4164 not be using the native code point.
4165 .Sp
4166 For details, see the description for "uvchr_to_utf8_flags" in perlapi.
4167 .RS 4
4168 .Sp
4169 .Vb 1
4170 \& U8 * uvoffuni_to_utf8_flags(U8 *d, UV uv, UV flags)
4171 .Ve
4172 .RE
4173 .RS 4
4174 .RE
4175 .ie n .IP """valid_utf8_to_uvchr""" 4
4176 .el .IP \f(CWvalid_utf8_to_uvchr\fR 4
4177 .IX Xref "valid_utf8_to_uvchr"
4178 .IX Item "valid_utf8_to_uvchr"
4179 Like \f(CW\*(C`"utf8_to_uvchr_buf" in perlapi\*(C'\fR, but should only be called when it is
4180 known that the next character in the input UTF\-8 string \f(CW\*(C`s\*(C'\fR is well-formed
4181 (\fIe.g.\fR, it passes \f(CW\*(C`"isUTF8_CHAR" in perlapi\*(C'\fR. Surrogates, non-character code
4182 points, and non-Unicode code points are allowed.
4183 .RS 4
4184 .Sp
4185 .Vb 1
4186 \& UV valid_utf8_to_uvchr(const U8 *s, STRLEN *retlen)
4187 .Ve
4188 .RE
4189 .RS 4
4190 .RE
4191 .ie n .IP """variant_under_utf8_count""" 4
4192 .el .IP \f(CWvariant_under_utf8_count\fR 4
4193 .IX Xref "variant_under_utf8_count"
4194 .IX Item "variant_under_utf8_count"
4195 This function looks at the sequence of bytes between \f(CW\*(C`s\*(C'\fR and \f(CW\*(C`e\*(C'\fR, which are
4196 assumed to be encoded in ASCII/Latin1, and returns how many of them would
4197 change should the string be translated into UTF\-8. Due to the nature of UTF\-8,
4198 each of these would occupy two bytes instead of the single one in the input
4199 string. Thus, this function returns the precise number of bytes the string
4200 would expand by when translated to UTF\-8.
4201 .Sp
4202 Unlike most of the other functions that have \f(CW\*(C`utf8\*(C'\fR in their name, the input
4203 to this function is NOT a UTF\-8\-encoded string. The function name is slightly
4204 \&\fIodd\fR to emphasize this.
4205 .Sp
4206 This function is internal to Perl because khw thinks that any XS code that
4207 would want this is probably operating too close to the internals. Presenting a
4208 valid use case could change that.
4209 .Sp
4210 See also
4211 \&\f(CW\*(C`"is_utf8_invariant_string" in perlapi\*(C'\fR
4212 and
4213 \&\f(CW\*(C`"is_utf8_invariant_string_loc" in perlapi\*(C'\fR,
4214 .RS 4
4215 .Sp
4216 .Vb 2
4217 \& Size_t variant_under_utf8_count(const U8 * const s,
4218 \& const U8 * const e)
4219 .Ve
4220 .RE
4221 .RS 4
4222 .RE
4223 .SH "Utility Functions"
4224 .IX Header "Utility Functions"
4225 .ie n .IP """my_popen_list""" 4
4226 .el .IP \f(CWmy_popen_list\fR 4
4227 .IX Xref "my_popen_list"
4228 .IX Item "my_popen_list"
4229 Implementing function on some systems for \fBPerlProc_popen_list()\fR
4230 .RS 4
4231 .Sp
4232 .Vb 1
4233 \& PerlIO * my_popen_list(const char *mode, int n, SV **args)
4234 .Ve
4235 .RE
4236 .RS 4
4237 .RE
4238 .ie n .IP """my_socketpair""" 4
4239 .el .IP \f(CWmy_socketpair\fR 4
4240 .IX Xref "my_socketpair"
4241 .IX Item "my_socketpair"
4242 Emulates \fBsocketpair\fR\|(2) on systems that don't have it, but which do have
4243 enough functionality for the emulation.
4244 .RS 4
4245 .Sp
4246 .Vb 1
4247 \& int my_socketpair(int family, int type, int protocol, int fd[2])
4248 .Ve
4249 .RE
4250 .RS 4
4251 .RE
4252 .SH Versioning
4253 .IX Header "Versioning"
4254 There are currently no internal API items in Versioning
4255 .SH "Warning and Dieing"
4256 .IX Header "Warning and Dieing"
4257 .ie n .IP """deprecate""" 4
4258 .el .IP \f(CWdeprecate\fR 4
4259 .IX Xref "deprecate"
4260 .IX Item "deprecate"
4261 Wrapper around \fBPerl_ck_warner_d()\fR to produce a deprecated warning in the
4262 given category with an appropriate message. The \f(CW\*(C`message\*(C'\fR argument must
4263 be a C string. The string " is deprecated" will automatically be added
4264 to the end of the \f(CW\*(C`message\*(C'\fR.
4265 .RS 4
4266 .Sp
4267 .Vb 1
4268 \& deprecate(U32 category, "message")
4269 .Ve
4270 .RE
4271 .RS 4
4272 .RE
4273 .ie n .IP """deprecate_disappears_in""" 4
4274 .el .IP \f(CWdeprecate_disappears_in\fR 4
4275 .IX Xref "deprecate_disappears_in"
4276 .IX Item "deprecate_disappears_in"
4277 Wrapper around \fBPerl_ck_warner_d()\fR to produce a deprecated warning in the
4278 given category with an appropriate message that the construct referred
4279 to by the message will disappear in a specific release. The \f(CW\*(C`when\*(C'\fR and
4280 \&\f(CW\*(C`message\*(C'\fR arguments must be a C string. The \f(CW\*(C`when\*(C'\fR string is expected
4281 to be of the form "5.40", with no minor element in the version. The actual
4282 message output will be the result of the following expression \f(CW\*(C`message
4283 " is deprecated, and will disappear in Perl " when\*(C'\fR which is why \f(CW\*(C`message\*(C'\fR
4284 and \f(CW\*(C`when\*(C'\fR must be literal C strings.
4285 .RS 4
4286 .Sp
4287 .Vb 1
4288 \& deprecate_disappears_in(U32 category, "when", "message")
4289 .Ve
4290 .RE
4291 .RS 4
4292 .RE
4293 .ie n .IP """deprecate_fatal_in""" 4
4294 .el .IP \f(CWdeprecate_fatal_in\fR 4
4295 .IX Xref "deprecate_fatal_in"
4296 .IX Item "deprecate_fatal_in"
4297 Wrapper around \fBPerl_ck_warner_d()\fR to produce a deprecated warning in the
4298 given category with an appropriate message that the construct referred
4299 to by the message will become fatal in a specific release. The \f(CW\*(C`when\*(C'\fR
4300 and \f(CW\*(C`message\*(C'\fR arguments must be a C string. The \f(CW\*(C`when\*(C'\fR string is expected
4301 to be of the form "5.40", with no minor element in the version. The actual
4302 message output will be the result of the following expression \f(CW\*(C`message " is
4303 deprecated, and will become fatal in Perl " when\*(C'\fR which is why \f(CW\*(C`message\*(C'\fR
4304 and \f(CW\*(C`when\*(C'\fR must be literal C strings.
4305 .RS 4
4306 .Sp
4307 .Vb 1
4308 \& deprecate_fatal_in(U32 category, "when", "message")
4309 .Ve
4310 .RE
4311 .RS 4
4312 .RE
4313 .ie n .IP """PL_dowarn""" 4
4314 .el .IP \f(CWPL_dowarn\fR 4
4315 .IX Xref "PL_dowarn"
4316 .IX Item "PL_dowarn"
4317 The C variable that roughly corresponds to Perl's \f(CW$^W\fR warning variable.
4318 However, \f(CW$^W\fR is treated as a boolean, whereas \f(CW\*(C`PL_dowarn\*(C'\fR is a
4319 collection of flag bits.
4320 .Sp
4321 On threaded perls, each thread has an independent copy of this variable;
4322 each initialized at creation time with the current value of the creating
4323 thread's copy.
4324 .RS 4
4325 .Sp
4326 .Vb 1
4327 \& U8 PL_dowarn
4328 .Ve
4329 .RE
4330 .RS 4
4331 .RE
4332 .ie n .IP """report_uninit""" 4
4333 .el .IP \f(CWreport_uninit\fR 4
4334 .IX Xref "report_uninit"
4335 .IX Item "report_uninit"
4336 Print appropriate "Use of uninitialized variable" warning.
4337 .RS 4
4338 .Sp
4339 .Vb 1
4340 \& void report_uninit(const SV *uninit_sv)
4341 .Ve
4342 .RE
4343 .RS 4
4344 .RE
4345 .SH XS
4346 .IX Header "XS"
4347 There are currently no internal API items in XS
4348 .SH "Undocumented elements"
4349 .IX Header "Undocumented elements"
4350 This section lists the elements that are otherwise undocumented. If you use
4351 any of them, please consider creating and submitting documentation for it.
4352 .PP
4353 Experimental and deprecated undocumented elements are listed separately at the
4354 end.
4355 .PP
4356
4357 .IX Xref "abort_execution add_above_Latin1_folds add_cp_to_invlist _add_range_to_invlist allocmy amagic_cmp amagic_cmp_desc amagic_cmp_locale amagic_cmp_locale_desc amagic_i_ncmp amagic_i_ncmp_desc amagic_is_enabled amagic_ncmp amagic_ncmp_desc any_dup append_utf8_from_native_byte apply atfork_lock atfork_unlock av_arylen_p av_extend_guts av_iter_p av_nonelem av_reify bind_match block_gimme boot_core_builtin boot_core_mro boot_core_PerlIO boot_core_UNIVERSAL build_infix_plugin _byte_dump_string call_list cando capture_clear cast_iv cast_i32 cast_ulong cast_uv check_hash_fields_and_hekify check_regnode_after check_utf8_print ck_anoncode ck_backtick ck_bitop ck_classname ck_cmp ck_concat ck_defined ck_delete ck_each ck_entersub_args_core ck_eof ck_eval ck_exec ck_exists ck_ftst ck_fun ck_glob ck_grep ck_helemexistsor ck_index ck_isa ck_join ck_length ck_lfun ck_listiob ck_match ck_method ck_null ck_open ck_prototype ck_readline ck_refassign ck_repeat ck_require ck_return ck_rfun ck_rvconst ck_sassign ck_select ck_shift ck_smartmatch ck_sort ck_spair ck_split ck_stringify ck_subr ck_substr ck_svconst ck_tell ck_trunc ck_trycatch ckwarn ckwarn_d class_add_ADJUST class_add_field class_apply_attributes class_apply_field_attributes class_prepare_initfield_parse class_prepare_method_parse class_seal_stash class_set_field_defop class_setup_stash class_wrap_method_body clear_defarray closest_cop cmpchain_extend cmpchain_finish cmpchain_start cmp_desc cmp_locale_desc cntrl_to_mnemonic construct_ahocorasick_from_trie cop_file_avn coresub_op croak_caller croak_kw_unless_class croak_memory_wrap croak_no_mem croak_no_mem_ext croak_popstack csighandler csighandler1 csighandler3 current_re_engine custom_op_get_field cv_clone_into cv_const_sv_or_av cvgv_from_hek cvgv_set cvstash_set cv_undef_flags cx_dump cx_dup cxinc deb_stack_all debstackptrs debug_hash_seed debug_peep debug_show_study_flags debug_studydata defelem_target despatch_signals die_unwind do_aexec do_aexec5 do_aspawn do_eof does_utf8_overflow do_exec do_exec3 dofile do_gv_dump do_gvgv_dump do_hv_dump doing_taint do_ipcctl do_ipcget do_magic_dump do_msgrcv do_msgsnd do_ncmp do_op_dump do_pmop_dump do_print do_readline doref do_seek do_semop do_shmio do_spawn do_spawn_nowait do_sv_dump do_sysseek do_tell do_trans do_uniprop_match do_vecget do_vecset do_vop drand48_init_r drand48_r dtrace_probe_call dtrace_probe_load dtrace_probe_op dtrace_probe_phase dump_all_perl dump_indent dump_packsubs_perl dump_sub_perl dump_sv_child dumpuntil dump_vindent dup_warnings find_first_differing_byte_pos find_lexical_cv find_runcv_where find_script finish_export_lexical foldEQ_latin1_s2_folded foldEQ_latin1 foldEQ_utf8_flags force_locale_unlock _force_out_malformed_utf8_message form_alien_digit_msg form_cp_too_large_msg free_tied_hv_pool free_tmps get_and_check_backslash_N_name get_ANYOFHbbm_contents get_ANYOFM_contents get_db_sub get_debug_opts get_deprecated_property_msg getenv_len get_extended_os_errno get_hash_seed get_invlist_iter_addr get_invlist_offset_addr get_invlist_previous_index_addr get_mstats get_prop_definition get_prop_values get_regclass_aux_data get_re_gclass_aux_data get_regex_charset_name get_win32_message_utf8ness gp_free gp_ref grok_bin_oct_hex grok_bslash_c grok_bslash_o grok_bslash_x gv_check gv_fetchmeth_internal gv_override gv_setref gv_stashpvn_internal he_dup hek_dup hfree_next_entry hv_auxalloc hv_common hv_common_key_len hv_delayfree_ent hv_free_ent hv_placeholders_p hv_pushkv hv_rand_set hv_undef_flags import_builtin_bundle infix_plugin_standard init_argv_symbols init_constants init_dbargs init_debugger init_i18nl10n init_named_cv init_stacks init_tm init_uniprops _inverse_folds invert invlist_array _invlist_array_init invlist_clear invlist_clone _invlist_contains_cp invlist_contents _invlist_dump _invlistEQ invlist_extend invlist_highest _invlist_intersection _invlist_intersection_maybe_complement_2nd _invlist_invert invlist_is_iterating invlist_iterfinish invlist_iterinit invlist_iternext _invlist_len invlist_max invlist_previous_index _invlist_search invlist_set_len invlist_set_previous_index _invlist_subtract invlist_trim _invlist_union _invlist_union_maybe_complement_2nd invmap_dump invoke_exception_hook io_close isFF_overlong is_grapheme _is_in_locale_category is_invlist is_standard_filehandle_name _is_uni_FOO _is_uni_perl_idcont _is_uni_perl_idstart is_utf8_char_helper_ is_utf8_common is_utf8_FF_helper_ _is_utf8_FOO is_utf8_overlong _is_utf8_perl_idcont _is_utf8_perl_idstart jmaybe join_exact keyword keyword_plugin_standard list load_charnames locale_panic localize lossless_NV_to_IV lsbit_pos32 lsbit_pos64 magic_clear_all_env magic_cleararylen_p magic_clearenv magic_clearhook magic_clearhookall magic_clearisa magic_clearpack magic_clearsig magic_copycallchecker magic_existspack magic_freearylen_p magic_freecollxfrm magic_freemglob magic_freeovrld magic_freeutf8 magic_get magic_getarylen magic_getdebugvar magic_getdefelem magic_getnkeys magic_getpack magic_getpos magic_getsig magic_getsubstr magic_gettaint magic_getuvar magic_getvec magic_killbackrefs magic_nextpack magic_regdata_cnt magic_regdatum_get magic_regdatum_set magic_scalarpack magic_set magic_set_all_env magic_setarylen magic_setcollxfrm magic_setdbline magic_setdebugvar magic_setdefelem magic_setenv magic_sethook magic_sethookall magic_setisa magic_setlvref magic_setmglob magic_setnkeys magic_setnonelem magic_setpack magic_setpos magic_setregexp magic_setsig magic_setsigall magic_setsubstr magic_settaint magic_setutf8 magic_setuvar magic_setvec magic_sizepack magic_wipepack make_trie malloced_size malloc_good_size markstack_grow mbtowc_ mem_collxfrm_ mem_log_alloc mem_log_del_sv mem_log_free mem_log_new_sv mem_log_realloc mg_find_mglob mg_size mode_from_discipline more_bodies more_sv moreswitches mortal_getenv mortalized_pv_copy mro_get_private_data mro_meta_dup mro_meta_init msbit_pos32 msbit_pos64 multiconcat_stringify multideref_stringify my_atof2 my_atof3 my_attrs my_clearenv my_lstat my_lstat_flags my_memrchr my_mkostemp_cloexec my_mkstemp_cloexec my_stat my_stat_flags my_strerror my_unexec newFORM _new_invlist _new_invlist_C_array newMETHOP_internal newPROG new_stackinfo new_stackinfo_flags newSTUB newSVavdefelem newXS_deffile nextargv no_bareword_allowed no_bareword_filehandle noperl_die notify_parser_that_changed_to_utf8 oopsAV oopsHV op_clear op_integerize op_lvalue_flags opmethod_stash op_prune_chain_head op_relocate_sv opslab_force_free opslab_free opslab_free_nopad op_std_init op_varname package package_version pad_add_weakref padlist_store padname_free PadnameIN_SCOPE padnamelist_free parser_dup parser_free parser_free_nexttoke_ops parse_unicode_opts path_is_searchable peep perl_alloc_using perl_clone_using PerlEnv_putenv PerlIO_context_layers PerlIO_restore_errno PerlIO_save_errno PerlLIO_dup_cloexec PerlLIO_dup2_cloexec PerlLIO_open_cloexec PerlLIO_open3_cloexec PerlProc_pipe_cloexec PerlSock_accept_cloexec PerlSock_socket_cloexec PerlSock_socketpair_cloexec perly_sighandler pmruntime POPMARK populate_anyof_bitmap_from_invlist populate_bitmap_from_invlist populate_invlist_from_bitmap populate_isa pregfree pregfree2 prepare_export_lexical ptr_hash qerror ReANY reentrant_free reentrant_init reentrant_retry reentrant_size re_exec_indentf ref reg_add_data regcurly regdump regdupe_internal regexec_flags regfree_internal reginitcolors reg_named_buff reg_named_buff_all reg_named_buff_exists reg_named_buff_fetch reg_named_buff_firstkey reg_named_buff_iter reg_named_buff_nextkey reg_named_buff_scalar regnext regnode_after reg_numbered_buff_fetch reg_numbered_buff_fetch_flags reg_numbered_buff_length reg_numbered_buff_store regprop reg_qr_package reg_skipcomment reg_temp_copy re_indentf re_intuit_start re_intuit_string re_op_compile report_evil_fh report_redefined_cv report_wrongway_fh re_printf rpeep rsignal_restore rsignal_save rvpv_dup rxres_save same_dirent save_bool save_clearsv save_delete save_destructor save_destructor_x save_freeop save_freepv save_freesv save_int save_iv save_I8 save_I16 save_I32 save_mortalizesv save_pptr save_pushi32ptr save_pushptrptr save_re_context save_sptr savestack_grow savestack_grow_cnt save_strlen sawparens scalar scalarvoid scan_commit scan_num seed set_ANYOF_arg set_caret_X setfd_cloexec setfd_cloexec_for_nonsysfd setfd_cloexec_or_inhexec_by_sysfdness setfd_inhexec setfd_inhexec_for_sysfd set_numeric_standard set_numeric_underlying set_padlist _setup_canned_invlist share_hek should_warn_nl should_we_output_Debug_r sighandler sighandler1 sighandler3 single_1bit_pos32 single_1bit_pos64 Slab_Alloc Slab_Free Slab_to_ro Slab_to_rw softref2xv sortsv_flags_impl ssc_init stack_grow str_to_version strxfrm study_chunk sub_crush_depth sv_add_backref sv_buf_to_ro sv_del_backref sv_i_ncmp sv_i_ncmp_desc sv_2iv sv_magicext_mglob sv_mark_arenas sv_ncmp sv_ncmp_desc sv_only_taint_gmagic sv_or_pv_pos_u2b sv_pvbyten_force_wrapper sv_pvutf8n_force_wrapper sv_resetpvn sv_sethek sv_sweep_arenas SvTRUE_common sv_unglob sv_2uv switch_locale_context sys_init sys_init3 sys_intern_clear sys_intern_dup sys_intern_init sys_term tied_method tmps_grow_p _to_fold_latin1 TOPMARK to_uni_fold _to_uni_fold_flags to_uni_lower to_uni_title to_uni_upper _to_upper_title_latin1 _to_utf8_fold_flags _to_utf8_lower_flags _to_utf8_title_flags _to_utf8_upper_flags translate_substr_offsets try_amagic_bin try_amagic_un uiv_2buf unlnk unshare_hek unwind_paren _utf8n_to_uvchr_msgs_helper utf16_to_utf8_base utf16_to_utf8_reversed utf16_to_utf8 utf8_to_uvchr_buf_helper utilize uvoffuni_to_utf8_flags_msgs variant_byte_number varname vivify_defelem vivify_ref wait4pid warn_elem_scalar_context warn_problematic_locale was_lvalue_sub watch win32_croak_not_implemented write_to_stderr xs_boot_epilog xs_handshake yyerror yyerror_pv yyerror_pvn yylex yyparse yyquit yyunlex"
4358 .PP
4359 .Vb 10
4360 \& abort_execution
4361 \& add_above_Latin1_folds
4362 \& add_cp_to_invlist
4363 \& _add_range_to_invlist
4364 \& allocmy
4365 \& amagic_cmp
4366 \& amagic_cmp_desc
4367 \& amagic_cmp_locale
4368 \& amagic_cmp_locale_desc
4369 \& amagic_i_ncmp
4370 \& amagic_i_ncmp_desc
4371 \& amagic_is_enabled
4372 \& amagic_ncmp
4373 \& amagic_ncmp_desc
4374 \& any_dup
4375 \& append_utf8_from_native_byte
4376 \& apply
4377 \& atfork_lock
4378 \& atfork_unlock
4379 \& av_arylen_p
4380 \& av_extend_guts
4381 \& av_iter_p
4382 \& av_nonelem
4383 \& av_reify
4384 \& bind_match
4385 \& block_gimme
4386 \& boot_core_builtin
4387 \& boot_core_mro
4388 \& boot_core_PerlIO
4389 \& boot_core_UNIVERSAL
4390 \& build_infix_plugin
4391 \& _byte_dump_string
4392 \& call_list
4393 \& cando
4394 \& capture_clear
4395 \& cast_iv
4396 \& cast_i32
4397 \& cast_ulong
4398 \& cast_uv
4399 \& check_hash_fields_and_hekify
4400 \& check_regnode_after
4401 \& check_utf8_print
4402 \& ck_anoncode
4403 \& ck_backtick
4404 \& ck_bitop
4405 \& ck_classname
4406 \& ck_cmp
4407 \& ck_concat
4408 \& ck_defined
4409 \& ck_delete
4410 \& ck_each
4411 \& ck_entersub_args_core
4412 \& ck_eof
4413 \& ck_eval
4414 \& ck_exec
4415 \& ck_exists
4416 \& ck_ftst
4417 \& ck_fun
4418 \& ck_glob
4419 \& ck_grep
4420 \& ck_helemexistsor
4421 \& ck_index
4422 \& ck_isa
4423 \& ck_join
4424 \& ck_length
4425 \& ck_lfun
4426 \& ck_listiob
4427 \& ck_match
4428 \& ck_method
4429 \& ck_null
4430 \& ck_open
4431 \& ck_prototype
4432 \& ck_readline
4433 \& ck_refassign
4434 \& ck_repeat
4435 \& ck_require
4436 \& ck_return
4437 \& ck_rfun
4438 \& ck_rvconst
4439 \& ck_sassign
4440 \& ck_select
4441 \& ck_shift
4442 \& ck_smartmatch
4443 \& ck_sort
4444 \& ck_spair
4445 \& ck_split
4446 \& ck_stringify
4447 \& ck_subr
4448 \& ck_substr
4449 \& ck_svconst
4450 \& ck_tell
4451 \& ck_trunc
4452 \& ck_trycatch
4453 \& ckwarn
4454 \& ckwarn_d
4455 \& class_add_ADJUST
4456 \& class_add_field
4457 \& class_apply_attributes
4458 \& class_apply_field_attributes
4459 \& class_prepare_initfield_parse
4460 \& class_prepare_method_parse
4461 \& class_seal_stash
4462 \& class_set_field_defop
4463 \& class_setup_stash
4464 \& class_wrap_method_body
4465 \& clear_defarray
4466 \& closest_cop
4467 \& cmpchain_extend
4468 \& cmpchain_finish
4469 \& cmpchain_start
4470 \& cmp_desc
4471 \& cmp_locale_desc
4472 \& cntrl_to_mnemonic
4473 \& construct_ahocorasick_from_trie
4474 \& cop_file_avn
4475 \& coresub_op
4476 \& croak_caller
4477 \& croak_kw_unless_class
4478 \& croak_memory_wrap
4479 \& croak_no_mem
4480 \& croak_no_mem_ext
4481 \& croak_popstack
4482 \& csighandler
4483 \& csighandler1
4484 \& csighandler3
4485 \& current_re_engine
4486 \& custom_op_get_field
4487 \& cv_clone_into
4488 \& cv_const_sv_or_av
4489 \& cvgv_from_hek
4490 \& cvgv_set
4491 \& cvstash_set
4492 \& cv_undef_flags
4493 \& cx_dump
4494 \& cx_dup
4495 \& cxinc
4496 \& deb_stack_all
4497 \& debstackptrs
4498 \& debug_hash_seed
4499 \& debug_peep
4500 \& debug_show_study_flags
4501 \& debug_studydata
4502 \& defelem_target
4503 \& despatch_signals
4504 \& die_unwind
4505 \& do_aexec
4506 \& do_aexec5
4507 \& do_aspawn
4508 \& do_eof
4509 \& does_utf8_overflow
4510 \& do_exec
4511 \& do_exec3
4512 \& dofile
4513 \& do_gv_dump
4514 \& do_gvgv_dump
4515 \& do_hv_dump
4516 \& doing_taint
4517 \& do_ipcctl
4518 \& do_ipcget
4519 \& do_magic_dump
4520 \& do_msgrcv
4521 \& do_msgsnd
4522 \& do_ncmp
4523 \& do_op_dump
4524 \& do_pmop_dump
4525 \& do_print
4526 \& do_readline
4527 \& doref
4528 \& do_seek
4529 \& do_semop
4530 \& do_shmio
4531 \& do_spawn
4532 \& do_spawn_nowait
4533 \& do_sv_dump
4534 \& do_sysseek
4535 \& do_tell
4536 \& do_trans
4537 \& do_uniprop_match
4538 \& do_vecget
4539 \& do_vecset
4540 \& do_vop
4541 \& drand48_init_r
4542 \& drand48_r
4543 \& dtrace_probe_call
4544 \& dtrace_probe_load
4545 \& dtrace_probe_op
4546 \& dtrace_probe_phase
4547 \& dump_all_perl
4548 \& dump_indent
4549 \& dump_packsubs_perl
4550 \& dump_sub_perl
4551 \& dump_sv_child
4552 \& dumpuntil
4553 \& dump_vindent
4554 \& dup_warnings
4555 \& find_first_differing_byte_pos
4556 \& find_lexical_cv
4557 \& find_runcv_where
4558 \& find_script
4559 \& finish_export_lexical
4560 \& foldEQ_latin1_s2_folded
4561 \& foldEQ_latin1
4562 \& foldEQ_utf8_flags
4563 \& force_locale_unlock
4564 \& _force_out_malformed_utf8_message
4565 \& form_alien_digit_msg
4566 \& form_cp_too_large_msg
4567 \& free_tied_hv_pool
4568 \& free_tmps
4569 \& get_and_check_backslash_N_name
4570 \& get_ANYOFHbbm_contents
4571 \& get_ANYOFM_contents
4572 \& get_db_sub
4573 \& get_debug_opts
4574 \& get_deprecated_property_msg
4575 \& getenv_len
4576 \& get_extended_os_errno
4577 \& get_hash_seed
4578 \& get_invlist_iter_addr
4579 \& get_invlist_offset_addr
4580 \& get_invlist_previous_index_addr
4581 \& get_mstats
4582 \& get_prop_definition
4583 \& get_prop_values
4584 \& get_regclass_aux_data
4585 \& get_re_gclass_aux_data
4586 \& get_regex_charset_name
4587 \& get_win32_message_utf8ness
4588 \& gp_free
4589 \& gp_ref
4590 \& grok_bin_oct_hex
4591 \& grok_bslash_c
4592 \& grok_bslash_o
4593 \& grok_bslash_x
4594 \& gv_check
4595 \& gv_fetchmeth_internal
4596 \& gv_override
4597 \& gv_setref
4598 \& gv_stashpvn_internal
4599 \& he_dup
4600 \& hek_dup
4601 \& hfree_next_entry
4602 \& hv_auxalloc
4603 \& hv_common
4604 \& hv_common_key_len
4605 \& hv_delayfree_ent
4606 \& hv_free_ent
4607 \& hv_placeholders_p
4608 \& hv_pushkv
4609 \& hv_rand_set
4610 \& hv_undef_flags
4611 \& import_builtin_bundle
4612 \& infix_plugin_standard
4613 \& init_argv_symbols
4614 \& init_constants
4615 \& init_dbargs
4616 \& init_debugger
4617 \& init_i18nl10n
4618 \& init_named_cv
4619 \& init_stacks
4620 \& init_tm
4621 \& init_uniprops
4622 \& _inverse_folds
4623 \& invert
4624 \& invlist_array
4625 \& _invlist_array_init
4626 \& invlist_clear
4627 \& invlist_clone
4628 \& _invlist_contains_cp
4629 \& invlist_contents
4630 \& _invlist_dump
4631 \& _invlistEQ
4632 \& invlist_extend
4633 \& invlist_highest
4634 \& _invlist_intersection
4635 \& _invlist_intersection_maybe_complement_2nd
4636 \& _invlist_invert
4637 \& invlist_is_iterating
4638 \& invlist_iterfinish
4639 \& invlist_iterinit
4640 \& invlist_iternext
4641 \& _invlist_len
4642 \& invlist_max
4643 \& invlist_previous_index
4644 \& _invlist_search
4645 \& invlist_set_len
4646 \& invlist_set_previous_index
4647 \& _invlist_subtract
4648 \& invlist_trim
4649 \& _invlist_union
4650 \& _invlist_union_maybe_complement_2nd
4651 \& invmap_dump
4652 \& invoke_exception_hook
4653 \& io_close
4654 \& isFF_overlong
4655 \& is_grapheme
4656 \& _is_in_locale_category
4657 \& is_invlist
4658 \& is_standard_filehandle_name
4659 \& _is_uni_FOO
4660 \& _is_uni_perl_idcont
4661 \& _is_uni_perl_idstart
4662 \& is_utf8_char_helper_
4663 \& is_utf8_common
4664 \& is_utf8_FF_helper_
4665 \& _is_utf8_FOO
4666 \& is_utf8_overlong
4667 \& _is_utf8_perl_idcont
4668 \& _is_utf8_perl_idstart
4669 \& jmaybe
4670 \& join_exact
4671 \& keyword
4672 \& keyword_plugin_standard
4673 \& list
4674 \& load_charnames
4675 \& locale_panic
4676 \& localize
4677 \& lossless_NV_to_IV
4678 \& lsbit_pos32
4679 \& lsbit_pos64
4680 \& magic_clear_all_env
4681 \& magic_cleararylen_p
4682 \& magic_clearenv
4683 \& magic_clearhook
4684 \& magic_clearhookall
4685 \& magic_clearisa
4686 \& magic_clearpack
4687 \& magic_clearsig
4688 \& magic_copycallchecker
4689 \& magic_existspack
4690 \& magic_freearylen_p
4691 \& magic_freecollxfrm
4692 \& magic_freemglob
4693 \& magic_freeovrld
4694 \& magic_freeutf8
4695 \& magic_get
4696 \& magic_getarylen
4697 \& magic_getdebugvar
4698 \& magic_getdefelem
4699 \& magic_getnkeys
4700 \& magic_getpack
4701 \& magic_getpos
4702 \& magic_getsig
4703 \& magic_getsubstr
4704 \& magic_gettaint
4705 \& magic_getuvar
4706 \& magic_getvec
4707 \& magic_killbackrefs
4708 \& magic_nextpack
4709 \& magic_regdata_cnt
4710 \& magic_regdatum_get
4711 \& magic_regdatum_set
4712 \& magic_scalarpack
4713 \& magic_set
4714 \& magic_set_all_env
4715 \& magic_setarylen
4716 \& magic_setcollxfrm
4717 \& magic_setdbline
4718 \& magic_setdebugvar
4719 \& magic_setdefelem
4720 \& magic_setenv
4721 \& magic_sethook
4722 \& magic_sethookall
4723 \& magic_setisa
4724 \& magic_setlvref
4725 \& magic_setmglob
4726 \& magic_setnkeys
4727 \& magic_setnonelem
4728 \& magic_setpack
4729 \& magic_setpos
4730 \& magic_setregexp
4731 \& magic_setsig
4732 \& magic_setsigall
4733 \& magic_setsubstr
4734 \& magic_settaint
4735 \& magic_setutf8
4736 \& magic_setuvar
4737 \& magic_setvec
4738 \& magic_sizepack
4739 \& magic_wipepack
4740 \& make_trie
4741 \& malloced_size
4742 \& malloc_good_size
4743 \& markstack_grow
4744 \& mbtowc_
4745 \& mem_collxfrm_
4746 \& mem_log_alloc
4747 \& mem_log_del_sv
4748 \& mem_log_free
4749 \& mem_log_new_sv
4750 \& mem_log_realloc
4751 \& mg_find_mglob
4752 \& mg_size
4753 \& mode_from_discipline
4754 \& more_bodies
4755 \& more_sv
4756 \& moreswitches
4757 \& mortal_getenv
4758 \& mortalized_pv_copy
4759 \& mro_get_private_data
4760 \& mro_meta_dup
4761 \& mro_meta_init
4762 \& msbit_pos32
4763 \& msbit_pos64
4764 \& multiconcat_stringify
4765 \& multideref_stringify
4766 \& my_atof2
4767 \& my_atof3
4768 \& my_attrs
4769 \& my_clearenv
4770 \& my_lstat
4771 \& my_lstat_flags
4772 \& my_memrchr
4773 \& my_mkostemp_cloexec
4774 \& my_mkstemp_cloexec
4775 \& my_stat
4776 \& my_stat_flags
4777 \& my_strerror
4778 \& my_unexec
4779 \& newFORM
4780 \& _new_invlist
4781 \& _new_invlist_C_array
4782 \& newMETHOP_internal
4783 \& newPROG
4784 \& new_stackinfo
4785 \& new_stackinfo_flags
4786 \& newSTUB
4787 \& newSVavdefelem
4788 \& newXS_deffile
4789 \& nextargv
4790 \& no_bareword_allowed
4791 \& no_bareword_filehandle
4792 \& noperl_die
4793 \& notify_parser_that_changed_to_utf8
4794 \& oopsAV
4795 \& oopsHV
4796 \& op_clear
4797 \& op_integerize
4798 \& op_lvalue_flags
4799 \& opmethod_stash
4800 \& op_prune_chain_head
4801 \& op_relocate_sv
4802 \& opslab_force_free
4803 \& opslab_free
4804 \& opslab_free_nopad
4805 \& op_std_init
4806 \& op_varname
4807 \& package
4808 \& package_version
4809 \& pad_add_weakref
4810 \& padlist_store
4811 \& padname_free
4812 \& PadnameIN_SCOPE
4813 \& padnamelist_free
4814 \& parser_dup
4815 \& parser_free
4816 \& parser_free_nexttoke_ops
4817 \& parse_unicode_opts
4818 \& path_is_searchable
4819 \& peep
4820 \& perl_alloc_using
4821 \& perl_clone_using
4822 \& PerlEnv_putenv
4823 \& PerlIO_context_layers
4824 \& PerlIO_restore_errno
4825 \& PerlIO_save_errno
4826 \& PerlLIO_dup_cloexec
4827 \& PerlLIO_dup2_cloexec
4828 \& PerlLIO_open_cloexec
4829 \& PerlLIO_open3_cloexec
4830 \& PerlProc_pipe_cloexec
4831 \& PerlSock_accept_cloexec
4832 \& PerlSock_socket_cloexec
4833 \& PerlSock_socketpair_cloexec
4834 \& perly_sighandler
4835 \& pmruntime
4836 \& POPMARK
4837 \& populate_anyof_bitmap_from_invlist
4838 \& populate_bitmap_from_invlist
4839 \& populate_invlist_from_bitmap
4840 \& populate_isa
4841 \& pregfree
4842 \& pregfree2
4843 \& prepare_export_lexical
4844 \& ptr_hash
4845 \& qerror
4846 \& ReANY
4847 \& reentrant_free
4848 \& reentrant_init
4849 \& reentrant_retry
4850 \& reentrant_size
4851 \& re_exec_indentf
4852 \& ref
4853 \& reg_add_data
4854 \& regcurly
4855 \& regdump
4856 \& regdupe_internal
4857 \& regexec_flags
4858 \& regfree_internal
4859 \& reginitcolors
4860 \& reg_named_buff
4861 \& reg_named_buff_all
4862 \& reg_named_buff_exists
4863 \& reg_named_buff_fetch
4864 \& reg_named_buff_firstkey
4865 \& reg_named_buff_iter
4866 \& reg_named_buff_nextkey
4867 \& reg_named_buff_scalar
4868 \& regnext
4869 \& regnode_after
4870 \& reg_numbered_buff_fetch
4871 \& reg_numbered_buff_fetch_flags
4872 \& reg_numbered_buff_length
4873 \& reg_numbered_buff_store
4874 \& regprop
4875 \& reg_qr_package
4876 \& reg_skipcomment
4877 \& reg_temp_copy
4878 \& re_indentf
4879 \& re_intuit_start
4880 \& re_intuit_string
4881 \& re_op_compile
4882 \& report_evil_fh
4883 \& report_redefined_cv
4884 \& report_wrongway_fh
4885 \& re_printf
4886 \& rpeep
4887 \& rsignal_restore
4888 \& rsignal_save
4889 \& rvpv_dup
4890 \& rxres_save
4891 \& same_dirent
4892 \& save_bool
4893 \& save_clearsv
4894 \& save_delete
4895 \& save_destructor
4896 \& save_destructor_x
4897 \& save_freeop
4898 \& save_freepv
4899 \& save_freesv
4900 \& save_int
4901 \& save_iv
4902 \& save_I8
4903 \& save_I16
4904 \& save_I32
4905 \& save_mortalizesv
4906 \& save_pptr
4907 \& save_pushi32ptr
4908 \& save_pushptrptr
4909 \& save_re_context
4910 \& save_sptr
4911 \& savestack_grow
4912 \& savestack_grow_cnt
4913 \& save_strlen
4914 \& sawparens
4915 \& scalar
4916 \& scalarvoid
4917 \& scan_commit
4918 \& scan_num
4919 \& seed
4920 \& set_ANYOF_arg
4921 \& set_caret_X
4922 \& setfd_cloexec
4923 \& setfd_cloexec_for_nonsysfd
4924 \& setfd_cloexec_or_inhexec_by_sysfdness
4925 \& setfd_inhexec
4926 \& setfd_inhexec_for_sysfd
4927 \& set_numeric_standard
4928 \& set_numeric_underlying
4929 \& set_padlist
4930 \& _setup_canned_invlist
4931 \& share_hek
4932 \& should_warn_nl
4933 \& should_we_output_Debug_r
4934 \& sighandler
4935 \& sighandler1
4936 \& sighandler3
4937 \& single_1bit_pos32
4938 \& single_1bit_pos64
4939 \& Slab_Alloc
4940 \& Slab_Free
4941 \& Slab_to_ro
4942 \& Slab_to_rw
4943 \& softref2xv
4944 \& sortsv_flags_impl
4945 \& ssc_init
4946 \& stack_grow
4947 \& str_to_version
4948 \& strxfrm
4949 \& study_chunk
4950 \& sub_crush_depth
4951 \& sv_add_backref
4952 \& sv_buf_to_ro
4953 \& sv_del_backref
4954 \& sv_i_ncmp
4955 \& sv_i_ncmp_desc
4956 \& sv_2iv
4957 \& sv_magicext_mglob
4958 \& sv_mark_arenas
4959 \& sv_ncmp
4960 \& sv_ncmp_desc
4961 \& sv_only_taint_gmagic
4962 \& sv_or_pv_pos_u2b
4963 \& sv_pvbyten_force_wrapper
4964 \& sv_pvutf8n_force_wrapper
4965 \& sv_resetpvn
4966 \& sv_sethek
4967 \& sv_sweep_arenas
4968 \& SvTRUE_common
4969 \& sv_unglob
4970 \& sv_2uv
4971 \& switch_locale_context
4972 \& sys_init
4973 \& sys_init3
4974 \& sys_intern_clear
4975 \& sys_intern_dup
4976 \& sys_intern_init
4977 \& sys_term
4978 \& tied_method
4979 \& tmps_grow_p
4980 \& _to_fold_latin1
4981 \& TOPMARK
4982 \& to_uni_fold
4983 \& _to_uni_fold_flags
4984 \& to_uni_lower
4985 \& to_uni_title
4986 \& to_uni_upper
4987 \& _to_upper_title_latin1
4988 \& _to_utf8_fold_flags
4989 \& _to_utf8_lower_flags
4990 \& _to_utf8_title_flags
4991 \& _to_utf8_upper_flags
4992 \& translate_substr_offsets
4993 \& try_amagic_bin
4994 \& try_amagic_un
4995 \& uiv_2buf
4996 \& unlnk
4997 \& unshare_hek
4998 \& unwind_paren
4999 \& _utf8n_to_uvchr_msgs_helper
5000 \& utf16_to_utf8_base
5001 \& utf16_to_utf8_reversed
5002 \& utf16_to_utf8
5003 \& utf8_to_uvchr_buf_helper
5004 \& utilize
5005 \& uvoffuni_to_utf8_flags_msgs
5006 \& variant_byte_number
5007 \& varname
5008 \& vivify_defelem
5009 \& vivify_ref
5010 \& wait4pid
5011 \& warn_elem_scalar_context
5012 \& warn_problematic_locale
5013 \& was_lvalue_sub
5014 \& watch
5015 \& win32_croak_not_implemented
5016 \& write_to_stderr
5017 \& xs_boot_epilog
5018 \& xs_handshake
5019 \& yyerror
5020 \& yyerror_pv
5021 \& yyerror_pvn
5022 \& yylex
5023 \& yyparse
5024 \& yyquit
5025 \& yyunlex
5026 .Ve
5027 .PP
5028 Next are the experimental undocumented elements
5029 .PP
5030
5031 .IX Xref "alloc_LOGOP av_remove_offset clear_defarray_simple create_eval_scope cv_ckproto_len_flags cx_popblock cx_popeval cx_popformat cx_popgiven cx_poploop cx_popsub cx_popsub_args cx_popsub_common cx_popwhen cx_pushblock cx_pusheval cx_pushformat cx_pushgiven cx_pushloop_for cx_pushloop_plain cx_pushsub cx_pushtry cx_pushwhen cx_topblock delete_eval_scope do_open_raw do_open6 emulate_cop_io get_re_arg get_vtbl gimme_V hv_backreferences_p hv_kill_backrefs invlist_highest_range_start invlist_lowest newGP new_warnings_bitfield op_refcnt_dec op_refcnt_inc op_unscope pop_stackinfo pp_wrap push_stackinfo rpp_free_2_ rpp_obliterate_stack_to rpp_replace_2_1_COMMON runops_wrap scan_str scan_word scan_word6 skipspace_flags sv_free2 sv_kill_backrefs sv_setpv_freshbuf sv_setsv_cow sv_strftime_ints switch_argstack utf8_to_utf16_base xs_wrap"
5032 .PP
5033 .Vb 10
5034 \& alloc_LOGOP gimme_V
5035 \& av_remove_offset hv_backreferences_p
5036 \& clear_defarray_simple hv_kill_backrefs
5037 \& create_eval_scope invlist_highest_range_start
5038 \& cv_ckproto_len_flags invlist_lowest
5039 \& cx_popblock newGP
5040 \& cx_popeval new_warnings_bitfield
5041 \& cx_popformat op_refcnt_dec
5042 \& cx_popgiven op_refcnt_inc
5043 \& cx_poploop op_unscope
5044 \& cx_popsub pop_stackinfo
5045 \& cx_popsub_args pp_wrap
5046 \& cx_popsub_common push_stackinfo
5047 \& cx_popwhen rpp_free_2_
5048 \& cx_pushblock rpp_obliterate_stack_to
5049 \& cx_pusheval rpp_replace_2_1_COMMON
5050 \& cx_pushformat runops_wrap
5051 \& cx_pushgiven scan_str
5052 \& cx_pushloop_for scan_word
5053 \& cx_pushloop_plain scan_word6
5054 \& cx_pushsub skipspace_flags
5055 \& cx_pushtry sv_free2
5056 \& cx_pushwhen sv_kill_backrefs
5057 \& cx_topblock sv_setpv_freshbuf
5058 \& delete_eval_scope sv_setsv_cow
5059 \& do_open_raw sv_strftime_ints
5060 \& do_open6 switch_argstack
5061 \& emulate_cop_io utf8_to_utf16_base
5062 \& get_re_arg xs_wrap
5063 \& get_vtbl
5064 .Ve
5065 .PP
5066 Finally are the deprecated undocumented elements.
5067 Do not use any for new code; remove all occurrences of all of these from
5068 existing code.
5069 .PP
5070
5071 .IX Xref "get_no_modify get_opargs get_ppaddr uvuni_to_utf8"
5072 .PP
5073 .Vb 1
5074 \& get_no_modify get_opargs get_ppaddr uvuni_to_utf8
5075 .Ve
5076 .SH AUTHORS
5077 .IX Header "AUTHORS"
5078 The autodocumentation system was originally added to the Perl core by
5079 Benjamin Stuhl. Documentation is by whoever was kind enough to
5080 document their functions.
5081 .SH "SEE ALSO"
5082 .IX Header "SEE ALSO"
5083 \&\fIconfig.h\fR, perlapi, perlapio, perlcall, perlclib, perlembed, perlfilter, perlguts, perlhacktips, perlinterp, perliol, perlmroapi, perlreapi, perlreguts, perlxs