1PERLAPI(1)             Perl Programmers Reference Guide             PERLAPI(1)
2
3
4

NAME

6       perlapi - autogenerated documentation for the perl public API
7

DESCRIPTION

9       This file contains most of the documentation of the perl public API, as
10       generated by embed.pl.  Specifically, it is a listing of functions,
11       macros, flags, and variables that may be used by extension writers.
12       Besides perlintern and config.h, some items are listed here as being
13       actually documented in another pod.
14
15       At the end is a list of functions which have yet to be documented.
16       Patches welcome!  The interfaces of these are subject to change without
17       notice.
18
19       Some of the functions documented here are consolidated so that a single
20       entry serves for multiple functions which all do basically the same
21       thing, but have some slight differences.  For example, one form might
22       process magic, while another doesn't.  The name of each variation is
23       listed at the top of the single entry.  But if all have the same
24       signature (arguments and return type) except for their names, only the
25       usage for the base form is shown.  If any one of the forms has a
26       different signature (such as returning "const" or not) every function's
27       signature is explicitly displayed.
28
29       Anything not listed here or in the other mentioned pods is not part of
30       the public API, and should not be used by extension writers at all.
31       For these reasons, blindly using functions listed in proto.h is to be
32       avoided when writing extensions.
33
34       In Perl, unlike C, a string of characters may generally contain
35       embedded "NUL" characters.  Sometimes in the documentation a Perl
36       string is referred to as a "buffer" to distinguish it from a C string,
37       but sometimes they are both just referred to as strings.
38
39       Note that all Perl API global variables must be referenced with the
40       "PL_" prefix.  Again, those not listed here are not to be used by
41       extension writers, and may be changed or removed without notice; same
42       with macros.  Some macros are provided for compatibility with the
43       older, unadorned names, but this support may be disabled in a future
44       release.
45
46       Perl was originally written to handle US-ASCII only (that is characters
47       whose ordinal numbers are in the range 0 - 127).  And documentation and
48       comments may still use the term ASCII, when sometimes in fact the
49       entire range from 0 - 255 is meant.
50
51       The non-ASCII characters below 256 can have various meanings, depending
52       on various things.  (See, most notably, perllocale.)  But usually the
53       whole range can be referred to as ISO-8859-1.  Often, the term
54       "Latin-1" (or "Latin1") is used as an equivalent for ISO-8859-1.  But
55       some people treat "Latin1" as referring just to the characters in the
56       range 128 through 255, or sometimes from 160 through 255.  This
57       documentation uses "Latin1" and "Latin-1" to refer to all 256
58       characters.
59
60       Note that Perl can be compiled and run under either ASCII or EBCDIC
61       (See perlebcdic).  Most of the documentation (and even comments in the
62       code) ignore the EBCDIC possibility.  For almost all purposes the
63       differences are transparent.  As an example, under EBCDIC, instead of
64       UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so whenever
65       this documentation refers to "utf8" (and variants of that name,
66       including in function names), it also (essentially transparently) means
67       "UTF-EBCDIC".  But the ordinals of characters differ between ASCII,
68       EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may
69       occupy a different number of bytes than in UTF-8.
70
71       The organization of this document is tentative and subject to change.
72       Suggestions and patches welcome perl5-porters@perl.org
73       <mailto:perl5-porters@perl.org>.
74
75       The sections in this document currently are
76
77       "AV Handling"
78       "Callback Functions"
79       "Casting"
80       "Character case changing"
81       "Character classification"
82       "Compiler and Preprocessor information"
83       "Compiler directives"
84       "Compile-time scope hooks"
85       "Concurrency"
86       "COPs and Hint Hashes"
87       "Custom Operators"
88       "CV Handling"
89       "Debugging"
90       "Display functions"
91       "Embedding, Threads, and Interpreter Cloning"
92       "Errno"
93       "Exception Handling (simple) Macros"
94       "Filesystem configuration values"
95       "Floating point"
96       "General Configuration"
97       "Global Variables"
98       "GV Handling and Stashes"
99       "Hook manipulation"
100       "HV Handling"
101       "Input/Output"
102       "Integer"
103       "I/O Formats"
104       "Lexer interface"
105       "Locales"
106       "Magic"
107       "Memory Management"
108       "MRO"
109       "Multicall Functions"
110       "Numeric Functions"
111       "Optrees"
112       "Pack and Unpack"
113       "Pad Data Structures"
114       "Password and Group access"
115       "Paths to system commands"
116       "Prototype information"
117       "REGEXP Functions"
118       "Reports and Formats"
119       "Signals"
120       "Site configuration"
121       "Sockets configuration values"
122       "Source Filters"
123       "Stack Manipulation Macros"
124       "String Handling"
125       "SV Flags"
126       "SV Handling"
127       "Tainting"
128       "Time"
129       "Typedef names"
130       "Unicode Support"
131       "Utility Functions"
132       "Versioning"
133       "Warning and Dieing"
134       "XS"
135       "Undocumented elements"
136
137       The listing below is alphabetical, case insensitive.
138

AV Handling

140       "AV"
141           Described in perlguts.
142
143       "AvALLOC"
144           Described in perlguts.
145
146              AvALLOC(AV* av)
147
148       "AvARRAY"
149           Returns a pointer to the AV's internal SV* array.
150
151           This is useful for doing pointer arithmetic on the array.  If all
152           you need is to look up an array element, then prefer "av_fetch".
153
154            SV**  AvARRAY(AV* av)
155
156       "av_clear"
157           Frees all the elements of an array, leaving it empty.  The XS
158           equivalent of "@array = ()".  See also "av_undef".
159
160           Note that it is possible that the actions of a destructor called
161           directly or indirectly by freeing an element of the array could
162           cause the reference count of the array itself to be reduced (e.g.
163           by deleting an entry in the symbol table). So it is a possibility
164           that the AV could have been freed (or even reallocated) on return
165           from the call unless you hold a reference to it.
166
167            void  av_clear(AV *av)
168
169       "av_count"
170           Returns the number of elements in the array "av".  This is the true
171           length of the array, including any undefined elements.  It is
172           always the same as "av_top_index(av) + 1".
173
174            Size_t  av_count(AV *av)
175
176       "av_create_and_push"
177           Push an SV onto the end of the array, creating the array if
178           necessary.  A small internal helper function to remove a commonly
179           duplicated idiom.
180
181           NOTE: "av_create_and_push" must be explicitly called as
182           "Perl_av_create_and_push" with an "aTHX_" parameter.
183
184            void  Perl_av_create_and_push(pTHX_ AV ** const avp,
185                                          SV * const val)
186
187       "av_create_and_unshift_one"
188           Unshifts an SV onto the beginning of the array, creating the array
189           if necessary.  A small internal helper function to remove a
190           commonly duplicated idiom.
191
192           NOTE: "av_create_and_unshift_one" must be explicitly called as
193           "Perl_av_create_and_unshift_one" with an "aTHX_" parameter.
194
195            SV **  Perl_av_create_and_unshift_one(pTHX_ AV ** const avp,
196                                                  SV * const val)
197
198       "av_delete"
199           Deletes the element indexed by "key" from the array, makes the
200           element mortal, and returns it.  If "flags" equals "G_DISCARD", the
201           element is freed and NULL is returned. NULL is also returned if
202           "key" is out of range.
203
204           Perl equivalent: "splice(@myarray, $key, 1, undef)" (with the
205           "splice" in void context if "G_DISCARD" is present).
206
207            SV *  av_delete(AV *av, SSize_t key, I32 flags)
208
209       "av_exists"
210           Returns true if the element indexed by "key" has been initialized.
211
212           This relies on the fact that uninitialized array elements are set
213           to "NULL".
214
215           Perl equivalent: exists($myarray[$key]).
216
217            bool  av_exists(AV *av, SSize_t key)
218
219       "av_extend"
220           Pre-extend an array so that it is capable of storing values at
221           indexes "0..key". Thus "av_extend(av,99)" guarantees that the array
222           can store 100 elements, i.e. that "av_store(av, 0, sv)" through
223           "av_store(av, 99, sv)" on a plain array will work without any
224           further memory allocation.
225
226           If the av argument is a tied array then will call the "EXTEND" tied
227           array method with an argument of "(key+1)".
228
229            void  av_extend(AV *av, SSize_t key)
230
231       "av_fetch"
232           Returns the SV at the specified index in the array.  The "key" is
233           the index.  If "lval" is true, you are guaranteed to get a real SV
234           back (in case it wasn't real before), which you can then modify.
235           Check that the return value is non-NULL before dereferencing it to
236           a "SV*".
237
238           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
239           for more information on how to use this function on tied arrays.
240
241           The rough perl equivalent is $myarray[$key].
242
243            SV **  av_fetch(AV *av, SSize_t key, I32 lval)
244
245       "AvFILL"
246           Same as "av_top_index" or "av_tindex".
247
248            SSize_t  AvFILL(AV* av)
249
250       "av_fill"
251           Set the highest index in the array to the given number, equivalent
252           to Perl's "$#array = $fill;".
253
254           The number of elements in the array will be "fill + 1" after
255           av_fill() returns.  If the array was previously shorter, then the
256           additional elements appended are set to NULL.  If the array was
257           longer, then the excess elements are freed.  "av_fill(av, -1)" is
258           the same as av_clear(av).
259
260            void  av_fill(AV *av, SSize_t fill)
261
262       "av_len"
263           Same as "av_top_index".  Note that, unlike what the name implies,
264           it returns the maximum index in the array.  This is unlike
265           "sv_len", which returns what you would expect.
266
267           To get the true number of elements in the array, instead use
268           "av_count".
269
270            SSize_t  av_len(AV *av)
271
272       "av_make"
273           Creates a new AV and populates it with a list (**strp, length
274           "size") of SVs.  A copy is made of each SV, so their refcounts are
275           not changed.  The new AV will have a reference count of 1.
276
277           Perl equivalent: "my @new_array = ($scalar1, $scalar2,
278           $scalar3...);"
279
280            AV *  av_make(SSize_t size, SV **strp)
281
282       "av_pop"
283           Removes one SV from the end of the array, reducing its size by one
284           and returning the SV (transferring control of one reference count)
285           to the caller.  Returns &PL_sv_undef if the array is empty.
286
287           Perl equivalent: "pop(@myarray);"
288
289            SV *  av_pop(AV *av)
290
291       "av_push"
292           Pushes an SV (transferring control of one reference count) onto the
293           end of the array.  The array will grow automatically to accommodate
294           the addition.
295
296           Perl equivalent: "push @myarray, $val;".
297
298            void  av_push(AV *av, SV *val)
299
300       "av_push_simple"
301           This is a cut-down version of av_push that assumes that the array
302           is very straightforward - no magic, not readonly, and AvREAL - and
303           that "key" is not less than -1. This function MUST NOT be used in
304           situations where any of those assumptions may not hold.
305
306           Pushes an SV (transferring control of one reference count) onto the
307           end of the array.  The array will grow automatically to accommodate
308           the addition.
309
310           Perl equivalent: "push @myarray, $val;".
311
312            void  av_push_simple(AV *av, SV *val)
313
314       "av_shift"
315           Removes one SV from the start of the array, reducing its size by
316           one and returning the SV (transferring control of one reference
317           count) to the caller.  Returns &PL_sv_undef if the array is empty.
318
319           Perl equivalent: "shift(@myarray);"
320
321            SV *  av_shift(AV *av)
322
323       "av_store"
324           Stores an SV in an array.  The array index is specified as "key".
325           The return value will be "NULL" if the operation failed or if the
326           value did not need to be actually stored within the array (as in
327           the case of tied arrays).  Otherwise, it can be dereferenced to get
328           the "SV*" that was stored there (= "val")).
329
330           Note that the caller is responsible for suitably incrementing the
331           reference count of "val" before the call, and decrementing it if
332           the function returned "NULL".
333
334           Approximate Perl equivalent: "splice(@myarray, $key, 1, $val)".
335
336           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
337           for more information on how to use this function on tied arrays.
338
339            SV **  av_store(AV *av, SSize_t key, SV *val)
340
341       "av_tindex"
342       "av_top_index"
343           These behave identically.  If the array "av" is empty, these return
344           -1; otherwise they return the maximum value of the indices of all
345           the array elements which are currently defined in "av".
346
347           They process 'get' magic.
348
349           The Perl equivalent for these is $#av.
350
351           Use "av_count" to get the number of elements in an array.
352
353            SSize_t  av_tindex(AV *av)
354
355       "av_undef"
356           Undefines the array. The XS equivalent of undef(@array).
357
358           As well as freeing all the elements of the array (like av_clear()),
359           this also frees the memory used by the av to store its list of
360           scalars.
361
362           See "av_clear" for a note about the array possibly being invalid on
363           return.
364
365            void  av_undef(AV *av)
366
367       "av_unshift"
368           Unshift the given number of "undef" values onto the beginning of
369           the array.  The array will grow automatically to accommodate the
370           addition.
371
372           Perl equivalent: "unshift @myarray, ((undef) x $num);"
373
374            void  av_unshift(AV *av, SSize_t num)
375
376       "get_av"
377           Returns the AV of the specified Perl global or package array with
378           the given name (so it won't work on lexical variables).  "flags"
379           are passed to "gv_fetchpv".  If "GV_ADD" is set and the Perl
380           variable does not exist then it will be created.  If "flags" is
381           zero (ignoring "SVf_UTF8") and the variable does not exist then
382           "NULL" is returned.
383
384           Perl equivalent: "@{"$name"}".
385
386           NOTE: the perl_get_av() form is deprecated.
387
388            AV *  get_av(const char *name, I32 flags)
389
390       "newAV"
391       "newAV_alloc_x"
392       "newAV_alloc_xz"
393           These all create a new AV, setting the reference count to 1.  If
394           you also know the initial elements of the array with, see
395           ""av_make"".
396
397           As background, an array consists of three things:
398
399           1.  A data structure containing information about the array as a
400               whole, such as its size and reference count.
401
402           2.  A C language array of pointers to the individual elements.
403               These are treated as pointers to SVs, so all must be castable
404               to SV*.
405
406           3.  The individual elements themselves.  These could be, for
407               instance, SVs and/or AVs and/or HVs, etc.
408
409           An empty array need only have the first data structure, and all
410           these functions create that.  They differ in what else they do, as
411           follows:
412
413           "newAV" form
414               This does nothing beyond creating the whole-array data
415               structure.  The Perl equivalent is approximately "my @array;"
416
417               This is useful when the minimum size of the array could be zero
418               (perhaps there are likely code paths that will entirely skip
419               using it).
420
421               If the array does get used, the pointers data structure will
422               need to be allocated at that time.  This will end up being done
423               by "av_extend">, either explicitly:
424
425                   av_extend(av, len);
426
427               or implicitly when the first element is stored:
428
429                   (void)av_store(av, 0, sv);
430
431               Unused array elements are typically initialized by "av_extend".
432
433           "newAV_alloc_x" form
434               This effectively does a "newAV" followed by also allocating
435               (uninitialized) space for the pointers array.  This is used
436               when you know ahead of time the likely minimum size of the
437               array.  It is more efficient to do this than doing a plain
438               "newAV" followed by an "av_extend".
439
440               Of course the array can be extended later should it become
441               necessary.
442
443               "size" must be at least 1.
444
445           "newAV_alloc_xz" form
446               This is "newAV_alloc_x", but initializes each pointer in it to
447               NULL.  This gives added safety to guard against them being read
448               before being set.
449
450               "size" must be at least 1.
451
452           The following examples all result in an array that can fit four
453           elements (indexes 0 .. 3):
454
455               AV *av = newAV();
456               av_extend(av, 3);
457
458               AV *av = newAV_alloc_x(4);
459
460               AV *av = newAV_alloc_xz(4);
461
462           In contrast, the following examples allocate an array that is only
463           guaranteed to fit one element without extending:
464
465               AV *av = newAV_alloc_x(1);
466               AV *av = newAV_alloc_xz(1);
467
468            AV *  newAV         ()
469            AV *  newAV_alloc_x (SSize_t size)
470            AV *  newAV_alloc_xz(SSize_t size)
471
472       "newAVav"
473           Creates a new AV and populates it with values copied from an
474           existing AV.  The new AV will have a reference count of 1, and will
475           contain newly created SVs copied from the original SV.  The
476           original source will remain unchanged.
477
478           Perl equivalent: "my @new_array = @existing_array;"
479
480            AV *  newAVav(AV *oav)
481
482       "newAVhv"
483           Creates a new AV and populates it with keys and values copied from
484           an existing HV.  The new AV will have a reference count of 1, and
485           will contain newly created SVs copied from the original HV.  The
486           original source will remain unchanged.
487
488           Perl equivalent: "my @new_array = %existing_hash;"
489
490            AV *  newAVhv(HV *ohv)
491
492       "Nullav"
493           "DEPRECATED!"  It is planned to remove "Nullav" from a future
494           release of Perl.  Do not use it for new code; remove it from
495           existing code.
496
497           Null AV pointer.
498
499           (deprecated - use "(AV *)NULL" instead)
500

Callback Functions

502       "call_argv"
503           Performs a callback to the specified named and package-scoped Perl
504           subroutine with "argv" (a "NULL"-terminated array of strings) as
505           arguments.  See perlcall.
506
507           Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
508
509           NOTE: the perl_call_argv() form is deprecated.
510
511            I32  call_argv(const char *sub_name, I32 flags, char **argv)
512
513       "call_method"
514           Performs a callback to the specified Perl method.  The blessed
515           object must be on the stack.  See perlcall.
516
517           NOTE: the perl_call_method() form is deprecated.
518
519            I32  call_method(const char *methname, I32 flags)
520
521       "call_pv"
522           Performs a callback to the specified Perl sub.  See perlcall.
523
524           NOTE: the perl_call_pv() form is deprecated.
525
526            I32  call_pv(const char *sub_name, I32 flags)
527
528       "call_sv"
529           Performs a callback to the Perl sub specified by the SV.
530
531           If neither the "G_METHOD" nor "G_METHOD_NAMED" flag is supplied,
532           the SV may be any of a CV, a GV, a reference to a CV, a reference
533           to a GV or SvPV(sv) will be used as the name of the sub to call.
534
535           If the "G_METHOD" flag is supplied, the SV may be a reference to a
536           CV or SvPV(sv) will be used as the name of the method to call.
537
538           If the "G_METHOD_NAMED" flag is supplied, SvPV(sv) will be used as
539           the name of the method to call.
540
541           Some other values are treated specially for internal use and should
542           not be depended on.
543
544           See perlcall.
545
546           NOTE: the perl_call_sv() form is deprecated.
547
548            I32  call_sv(SV *sv, volatile I32 flags)
549
550       "DESTRUCTORFUNC_NOCONTEXT_t"
551           Described in perlguts.
552
553       "DESTRUCTORFUNC_t"
554           Described in perlguts.
555
556       "ENTER"
557           Opening bracket on a callback.  See "LEAVE" and perlcall.
558
559              ENTER;
560
561       "ENTER_with_name"
562           Same as "ENTER", but when debugging is enabled it also associates
563           the given literal string with the new scope.
564
565              ENTER_with_name("name");
566
567       "eval_pv"
568           Tells Perl to "eval" the given string in scalar context and return
569           an SV* result.
570
571           NOTE: the perl_eval_pv() form is deprecated.
572
573            SV *  eval_pv(const char *p, I32 croak_on_error)
574
575       "eval_sv"
576           Tells Perl to "eval" the string in the SV.  It supports the same
577           flags as "call_sv", with the obvious exception of "G_EVAL".  See
578           perlcall.
579
580           The "G_RETHROW" flag can be used if you only need eval_sv() to
581           execute code specified by a string, but not catch any errors.
582
583           NOTE: the perl_eval_sv() form is deprecated.
584
585            I32  eval_sv(SV *sv, I32 flags)
586
587       "FREETMPS"
588           Closing bracket for temporaries on a callback.  See "SAVETMPS" and
589           perlcall.
590
591              FREETMPS;
592
593       "G_DISCARD"
594           Described in perlcall.
595
596       "G_EVAL"
597           Described in perlcall.
598
599       "GIMME"
600           "DEPRECATED!"  It is planned to remove "GIMME" from a future
601           release of Perl.  Do not use it for new code; remove it from
602           existing code.
603
604           A backward-compatible version of "GIMME_V" which can only return
605           "G_SCALAR" or "G_LIST"; in a void context, it returns "G_SCALAR".
606           Deprecated.  Use "GIMME_V" instead.
607
608            U32  GIMME
609
610       "GIMME_V"
611           The XSUB-writer's equivalent to Perl's "wantarray".  Returns
612           "G_VOID", "G_SCALAR" or "G_LIST" for void, scalar or list context,
613           respectively.  See perlcall for a usage example.
614
615            U32  GIMME_V
616
617       "G_KEEPERR"
618           Described in perlcall.
619
620       "G_LIST"
621           Described in perlcall.
622
623       "G_NOARGS"
624           Described in perlcall.
625
626       "G_SCALAR"
627           Described in perlcall.
628
629       "G_VOID"
630           Described in perlcall.
631
632       "is_lvalue_sub"
633           Returns non-zero if the sub calling this function is being called
634           in an lvalue context.  Returns 0 otherwise.
635
636            I32  is_lvalue_sub()
637
638       "LEAVE"
639           Closing bracket on a callback.  See "ENTER" and perlcall.
640
641              LEAVE;
642
643       "LEAVE_with_name"
644           Same as "LEAVE", but when debugging is enabled it first checks that
645           the scope has the given name. "name" must be a literal string.
646
647              LEAVE_with_name("name");
648
649       "MORTALDESTRUCTOR_SV"
650           Described in perlguts.
651
652              MORTALDESTRUCTOR_SV(SV *coderef, SV *args)
653
654       "mortal_destructor_sv"
655           This function arranges for either a Perl code reference, or a C
656           function reference to be called at the end of the current
657           statement.
658
659           The "coderef" argument determines the type of function that will be
660           called. If it is SvROK() it is assumed to be a reference to a CV
661           and will arrange for the coderef to be called. If it is not SvROK()
662           then it is assumed to be a SvIV() which is SvIOK() whose value is a
663           pointer to a C function of type "DESTRUCTORFUNC_t" created using
664           PTR2INT().  Either way the "args" parameter will be provided to the
665           callback as a parameter, although the rules for doing so differ
666           between the Perl and C mode. Normally this function is only used
667           directly for the Perl case and the wrapper mortal_destructor_x() is
668           used for the C function case.
669
670           When operating in Perl callback mode the "args" parameter may be
671           NULL in which case the code reference is called with no arguments,
672           otherwise if it is an AV (SvTYPE(args) == SVt_PVAV) then the
673           contents of the AV will be used as the arguments to the code
674           reference, and if it is any other type then the "args" SV will be
675           provided as a single argument to the code reference.
676
677           When operating in a C callback mode the "args" parameter will be
678           passed directly to the C function as a "void *" pointer. No
679           additional processing of the argument will be peformed, and it is
680           the callers responsibility to free the "args" parameter if
681           necessary.
682
683           Be aware that there is a signficant difference in timing between
684           the end of the current statement and the end of the current pseudo
685           block. If you are looking for a mechanism to trigger a function at
686           the end of the current pseudo block you should look at
687           SAVEDESTRUCTORX() instead of this function.
688
689            void  mortal_destructor_sv(SV *coderef, SV *args)
690
691       "MORTALDESTRUCTOR_X"
692           Described in perlguts.
693
694              MORTALDESTRUCTOR_X(DESTRUCTORFUNC_t f, SV *sv)
695
696       "PL_errgv"
697           Described in perlcall.
698
699       "save_aelem"
700       "save_aelem_flags"
701           These each arrange for the value of the array element "av[idx]" to
702           be restored at the end of the enclosing pseudo-block.
703
704           In "save_aelem", the SV at C**sptr> will be replaced by a new
705           "undef" scalar.  That scalar will inherit any magic from the
706           original **sptr, and any 'set' magic will be processed.
707
708           In "save_aelem_flags", "SAVEf_KEEPOLDELEM" being set in "flags"
709           causes the function to forgo all that:  the scalar at **sptr is
710           untouched.  If "SAVEf_KEEPOLDELEM" is not set, the SV at C**sptr>
711           will be replaced by a new "undef" scalar.  That scalar will inherit
712           any magic from the original **sptr.  Any 'set' magic will be
713           processed if and only if "SAVEf_SETMAGIC" is set in in "flags".
714
715            void  save_aelem      (AV *av, SSize_t idx, SV **sptr)
716            void  save_aelem_flags(AV *av, SSize_t idx, SV **sptr,
717                                   const U32 flags)
718
719       "save_aptr"
720           Described in perlguts.
721
722            void  save_aptr(AV **aptr)
723
724       "save_ary"
725           Described in perlguts.
726
727            AV *  save_ary(GV *gv)
728
729       "SAVEBOOL"
730           Described in perlguts.
731
732              SAVEBOOL(bool i)
733
734       "SAVEDELETE"
735           Described in perlguts.
736
737              SAVEDELETE(HV * hv, char * key, I32 length)
738
739       "SAVEDESTRUCTOR"
740           Described in perlguts.
741
742              SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)
743
744       "SAVEDESTRUCTOR_X"
745           Described in perlguts.
746
747              SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)
748
749       "SAVEFREEOP"
750           Described in perlguts.
751
752              SAVEFREEOP(OP *op)
753
754       "SAVEFREEPV"
755           Described in perlguts.
756
757              SAVEFREEPV(char *pv)
758
759       "SAVEFREERCPV"
760           Described in perlguts.
761
762              SAVEFREERCPV(char *pv)
763
764       "SAVEFREESV"
765           Described in perlguts.
766
767              SAVEFREESV(SV* sv)
768
769       "SAVEGENERICSV"
770           Described in perlguts.
771
772              SAVEGENERICSV(char **psv)
773
774       "save_hash"
775           Described in perlguts.
776
777            HV *  save_hash(GV *gv)
778
779       "save_helem"
780       "save_helem_flags"
781           These each arrange for the value of the hash element (in Perlish
782           terms) "$hv{key}]" to be restored at the end of the enclosing
783           pseudo-block.
784
785           In "save_helem", the SV at C**sptr> will be replaced by a new
786           "undef" scalar.  That scalar will inherit any magic from the
787           original **sptr, and any 'set' magic will be processed.
788
789           In "save_helem_flags", "SAVEf_KEEPOLDELEM" being set in "flags"
790           causes the function to forgo all that:  the scalar at **sptr is
791           untouched.  If "SAVEf_KEEPOLDELEM" is not set, the SV at C**sptr>
792           will be replaced by a new "undef" scalar.  That scalar will inherit
793           any magic from the original **sptr.  Any 'set' magic will be
794           processed if and only if "SAVEf_SETMAGIC" is set in in "flags".
795
796            void  save_helem      (HV *hv, SV *key, SV **sptr)
797            void  save_helem_flags(HV *hv, SV *key, SV **sptr,
798                                   const U32 flags)
799
800       "save_hptr"
801           Described in perlguts.
802
803            void  save_hptr(HV **hptr)
804
805       "SAVEINT"
806           Described in perlguts.
807
808              SAVEINT(int i)
809
810       "save_item"
811           Described in perlguts.
812
813            void  save_item(SV *item)
814
815       "SAVEIV"
816           Described in perlguts.
817
818              SAVEIV(IV i)
819
820       "SAVEI8"
821           Described in perlguts.
822
823              SAVEI8(I8 i)
824
825       "SAVEI16"
826           Described in perlguts.
827
828              SAVEI16(I16 i)
829
830       "SAVEI32"
831           Described in perlguts.
832
833              SAVEI32(I32 i)
834
835       "SAVELONG"
836           Described in perlguts.
837
838              SAVELONG(long i)
839
840       "SAVEMORTALIZESV"
841           Described in perlguts.
842
843              SAVEMORTALIZESV(SV* sv)
844
845       "SAVEPPTR"
846           Described in perlguts.
847
848              SAVEPPTR(char * p)
849
850       "SAVERCPV"
851           Described in perlguts.
852
853              SAVERCPV(char *pv)
854
855       "save_scalar"
856           Described in perlguts.
857
858            SV *  save_scalar(GV *gv)
859
860       "SAVESPTR"
861           Described in perlguts.
862
863              SAVESPTR(SV * s)
864
865       "SAVESTACK_POS"
866           Described in perlguts.
867
868              SAVESTACK_POS()
869
870       "SAVESTRLEN"
871           Described in perlguts.
872
873              SAVESTRLEN(STRLEN i)
874
875       "save_svref"
876           Described in perlguts.
877
878            SV *  save_svref(SV **sptr)
879
880       "SAVETMPS"
881           Opening bracket for temporaries on a callback.  See "FREETMPS" and
882           perlcall.
883
884              SAVETMPS;
885

Casting

887       "Atof"
888           This is a synonym for ""my_atof"".
889
890            NV  Atof(NN const char * const s)
891
892       "cBOOL"
893           Cast-to-bool.  When Perl was able to be compiled on pre-C99
894           compilers, a "(bool)" cast didn't necessarily do the right thing,
895           so this macro was created (and made somewhat complicated to work
896           around bugs in old compilers).  Now, many years later, and C99 is
897           used, this is no longer required, but is kept for backwards
898           compatibility.
899
900            bool  cBOOL(bool expr)
901
902       "INT2PTR"
903           Described in perlguts.
904
905            type  INT2PTR(type, int value)
906
907       "I_V"
908           Cast an NV to IV while avoiding undefined C behavior
909
910            IV  I_V(NV what)
911
912       "I_32"
913           Cast an NV to I32 while avoiding undefined C behavior
914
915            I32  I_32(NV what)
916
917       "PTR2IV"
918           Described in perlguts.
919
920            IV  PTR2IV(void * ptr)
921
922       "PTR2nat"
923           Described in perlguts.
924
925            IV  PTR2nat(void *)
926
927       "PTR2NV"
928           Described in perlguts.
929
930            NV  PTR2NV(void * ptr)
931
932       "PTR2ul"
933           Described in perlguts.
934
935            unsigned long  PTR2ul(void *)
936
937       "PTR2UV"
938           Described in perlguts.
939
940            UV  PTR2UV(void * ptr)
941
942       "PTRV"
943           Described in perlguts.
944
945       "U_V"
946           Cast an NV to UV while avoiding undefined C behavior
947
948            UV  U_V(NV what)
949
950       "U_32"
951           Cast an NV to U32 while avoiding undefined C behavior
952
953            U32  U_32(NV what)
954

Character case changing

956       Perl uses "full" Unicode case mappings.  This means that converting a
957       single character to another case may result in a sequence of more than
958       one character.  For example, the uppercase of "ß" (LATIN SMALL LETTER
959       SHARP S) is the two character sequence "SS".  This presents some
960       complications   The lowercase of all characters in the range 0..255 is
961       a single character, and thus "toLOWER_L1" is furnished.  But,
962       "toUPPER_L1" can't exist, as it couldn't return a valid result for all
963       legal inputs.  Instead "toUPPER_uvchr" has an API that does allow every
964       possible legal result to be returned.)  Likewise no other function that
965       is crippled by not being able to give the correct results for the full
966       range of possible inputs has been implemented here.
967
968       "toFOLD"
969       "toFOLD_A"
970       "toFOLD_utf8"
971       "toFOLD_utf8_safe"
972       "toFOLD_uvchr"
973           These all return the foldcase of a character.  "foldcase" is an
974           internal case for "/i" pattern matching. If the foldcase of
975           character A and the foldcase of character B are the same, they
976           match caselessly; otherwise they don't.
977
978           The differences in the forms are what domain they operate on, and
979           whether the input is specified as a code point (those forms with a
980           "cp" parameter) or as a UTF-8 string (the others).  In the latter
981           case, the code point to use is the first one in the buffer of UTF-8
982           encoded code points, delineated by the arguments "p .. e - 1".
983
984           "toFOLD" and "toFOLD_A" are synonyms of each other.  They return
985           the foldcase of any ASCII-range code point.  In this range, the
986           foldcase is identical to the lowercase.  All other inputs are
987           returned unchanged.  Since these are macros, the input type may be
988           any integral one, and the output will occupy the same number of
989           bits as the input.
990
991           There is no "toFOLD_L1" nor "toFOLD_LATIN1" as the foldcase of some
992           code points in the 0..255 range is above that range or consists of
993           multiple characters.  Instead use "toFOLD_uvchr".
994
995           "toFOLD_uvchr" returns the foldcase of any Unicode code point.  The
996           return value is identical to that of "toFOLD_A" for input code
997           points in the ASCII range.  The foldcase of the vast majority of
998           Unicode code points is the same as the code point itself.  For
999           these, and for code points above the legal Unicode maximum, this
1000           returns the input code point unchanged.  It additionally stores the
1001           UTF-8 of the result into the buffer beginning at "s", and its
1002           length in bytes into *lenp.  The caller must have made "s" large
1003           enough to contain at least "UTF8_MAXBYTES_CASE+1" bytes to avoid
1004           possible overflow.
1005
1006           NOTE: the foldcase of a code point may be more than one code point.
1007           The return value of this function is only the first of these.  The
1008           entire foldcase is returned in "s".  To determine if the result is
1009           more than a single code point, you can do something like this:
1010
1011            uc = toFOLD_uvchr(cp, s, &len);
1012            if (len > UTF8SKIP(s)) { is multiple code points }
1013            else { is a single code point }
1014
1015           "toFOLD_utf8" and "toFOLD_utf8_safe" are synonyms of each other.
1016           The only difference between these and "toFOLD_uvchr" is that the
1017           source for these is encoded in UTF-8, instead of being a code
1018           point.  It is passed as a buffer starting at "p", with "e" pointing
1019           to one byte beyond its end.  The "p" buffer may certainly contain
1020           more than one code point; but only the first one (up through
1021           "e - 1") is examined.  If the UTF-8 for the input character is
1022           malformed in some way, the program may croak, or the function may
1023           return the REPLACEMENT CHARACTER, at the discretion of the
1024           implementation, and subject to change in future releases.
1025
1026            UV  toFOLD          (UV cp)
1027            UV  toFOLD_A        (UV cp)
1028            UV  toFOLD_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
1029            UV  toFOLD_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1030            UV  toFOLD_uvchr    (UV cp, U8* s, STRLEN* lenp)
1031
1032       "toLOWER"
1033       "toLOWER_A"
1034       "toLOWER_LATIN1"
1035       "toLOWER_LC"
1036       "toLOWER_L1"
1037       "toLOWER_utf8"
1038       "toLOWER_utf8_safe"
1039       "toLOWER_uvchr"
1040           These all return the lowercase of a character.  The differences are
1041           what domain they operate on, and whether the input is specified as
1042           a code point (those forms with a "cp" parameter) or as a UTF-8
1043           string (the others).  In the latter case, the code point to use is
1044           the first one in the buffer of UTF-8 encoded code points,
1045           delineated by the arguments "p .. e - 1".
1046
1047           "toLOWER" and "toLOWER_A" are synonyms of each other.  They return
1048           the lowercase of any uppercase ASCII-range code point.  All other
1049           inputs are returned unchanged.  Since these are macros, the input
1050           type may be any integral one, and the output will occupy the same
1051           number of bits as the input.
1052
1053           "toLOWER_L1" and "toLOWER_LATIN1" are synonyms of each other.  They
1054           behave identically as "toLOWER" for ASCII-range input.  But
1055           additionally will return the lowercase of any uppercase code point
1056           in the entire 0..255 range, assuming a Latin-1 encoding (or the
1057           EBCDIC equivalent on such platforms).
1058
1059           "toLOWER_LC" returns the lowercase of the input code point
1060           according to the rules of the current POSIX locale.  Input code
1061           points outside the range 0..255 are returned unchanged.
1062
1063           "toLOWER_uvchr" returns the lowercase of any Unicode code point.
1064           The return value is identical to that of "toLOWER_L1" for input
1065           code points in the 0..255 range.  The lowercase of the vast
1066           majority of Unicode code points is the same as the code point
1067           itself.  For these, and for code points above the legal Unicode
1068           maximum, this returns the input code point unchanged.  It
1069           additionally stores the UTF-8 of the result into the buffer
1070           beginning at "s", and its length in bytes into *lenp.  The caller
1071           must have made "s" large enough to contain at least
1072           "UTF8_MAXBYTES_CASE+1" bytes to avoid possible overflow.
1073
1074           NOTE: the lowercase of a code point may be more than one code
1075           point.  The return value of this function is only the first of
1076           these.  The entire lowercase is returned in "s".  To determine if
1077           the result is more than a single code point, you can do something
1078           like this:
1079
1080            uc = toLOWER_uvchr(cp, s, &len);
1081            if (len > UTF8SKIP(s)) { is multiple code points }
1082            else { is a single code point }
1083
1084           "toLOWER_utf8" and "toLOWER_utf8_safe" are synonyms of each other.
1085           The only difference between these and "toLOWER_uvchr" is that the
1086           source for these is encoded in UTF-8, instead of being a code
1087           point.  It is passed as a buffer starting at "p", with "e" pointing
1088           to one byte beyond its end.  The "p" buffer may certainly contain
1089           more than one code point; but only the first one (up through
1090           "e - 1") is examined.  If the UTF-8 for the input character is
1091           malformed in some way, the program may croak, or the function may
1092           return the REPLACEMENT CHARACTER, at the discretion of the
1093           implementation, and subject to change in future releases.
1094
1095            UV  toLOWER          (UV cp)
1096            UV  toLOWER_A        (UV cp)
1097            UV  toLOWER_LATIN1   (UV cp)
1098            UV  toLOWER_LC       (UV cp)
1099            UV  toLOWER_L1       (UV cp)
1100            UV  toLOWER_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
1101            UV  toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1102            UV  toLOWER_uvchr    (UV cp, U8* s, STRLEN* lenp)
1103
1104       "toTITLE"
1105       "toTITLE_A"
1106       "toTITLE_utf8"
1107       "toTITLE_utf8_safe"
1108       "toTITLE_uvchr"
1109           These all return the titlecase of a character.  The differences are
1110           what domain they operate on, and whether the input is specified as
1111           a code point (those forms with a "cp" parameter) or as a UTF-8
1112           string (the others).  In the latter case, the code point to use is
1113           the first one in the buffer of UTF-8 encoded code points,
1114           delineated by the arguments "p .. e - 1".
1115
1116           "toTITLE" and "toTITLE_A" are synonyms of each other.  They return
1117           the titlecase of any lowercase ASCII-range code point.  In this
1118           range, the titlecase is identical to the uppercase.  All other
1119           inputs are returned unchanged.  Since these are macros, the input
1120           type may be any integral one, and the output will occupy the same
1121           number of bits as the input.
1122
1123           There is no "toTITLE_L1" nor "toTITLE_LATIN1" as the titlecase of
1124           some code points in the 0..255 range is above that range or
1125           consists of multiple characters.  Instead use "toTITLE_uvchr".
1126
1127           "toTITLE_uvchr" returns the titlecase of any Unicode code point.
1128           The return value is identical to that of "toTITLE_A" for input code
1129           points in the ASCII range.  The titlecase of the vast majority of
1130           Unicode code points is the same as the code point itself.  For
1131           these, and for code points above the legal Unicode maximum, this
1132           returns the input code point unchanged.  It additionally stores the
1133           UTF-8 of the result into the buffer beginning at "s", and its
1134           length in bytes into *lenp.  The caller must have made "s" large
1135           enough to contain at least "UTF8_MAXBYTES_CASE+1" bytes to avoid
1136           possible overflow.
1137
1138           NOTE: the titlecase of a code point may be more than one code
1139           point.  The return value of this function is only the first of
1140           these.  The entire titlecase is returned in "s".  To determine if
1141           the result is more than a single code point, you can do something
1142           like this:
1143
1144            uc = toTITLE_uvchr(cp, s, &len);
1145            if (len > UTF8SKIP(s)) { is multiple code points }
1146            else { is a single code point }
1147
1148           "toTITLE_utf8" and "toTITLE_utf8_safe" are synonyms of each other.
1149           The only difference between these and "toTITLE_uvchr" is that the
1150           source for these is encoded in UTF-8, instead of being a code
1151           point.  It is passed as a buffer starting at "p", with "e" pointing
1152           to one byte beyond its end.  The "p" buffer may certainly contain
1153           more than one code point; but only the first one (up through
1154           "e - 1") is examined.  If the UTF-8 for the input character is
1155           malformed in some way, the program may croak, or the function may
1156           return the REPLACEMENT CHARACTER, at the discretion of the
1157           implementation, and subject to change in future releases.
1158
1159            UV  toTITLE          (UV cp)
1160            UV  toTITLE_A        (UV cp)
1161            UV  toTITLE_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
1162            UV  toTITLE_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1163            UV  toTITLE_uvchr    (UV cp, U8* s, STRLEN* lenp)
1164
1165       "toUPPER"
1166       "toUPPER_A"
1167       "toUPPER_utf8"
1168       "toUPPER_utf8_safe"
1169       "toUPPER_uvchr"
1170           These all return the uppercase of a character.  The differences are
1171           what domain they operate on, and whether the input is specified as
1172           a code point (those forms with a "cp" parameter) or as a UTF-8
1173           string (the others).  In the latter case, the code point to use is
1174           the first one in the buffer of UTF-8 encoded code points,
1175           delineated by the arguments "p .. e - 1".
1176
1177           "toUPPER" and "toUPPER_A" are synonyms of each other.  They return
1178           the uppercase of any lowercase ASCII-range code point.  All other
1179           inputs are returned unchanged.  Since these are macros, the input
1180           type may be any integral one, and the output will occupy the same
1181           number of bits as the input.
1182
1183           There is no "toUPPER_L1" nor "toUPPER_LATIN1" as the uppercase of
1184           some code points in the 0..255 range is above that range or
1185           consists of multiple characters.  Instead use "toUPPER_uvchr".
1186
1187           "toUPPER_uvchr" returns the uppercase of any Unicode code point.
1188           The return value is identical to that of "toUPPER_A" for input code
1189           points in the ASCII range.  The uppercase of the vast majority of
1190           Unicode code points is the same as the code point itself.  For
1191           these, and for code points above the legal Unicode maximum, this
1192           returns the input code point unchanged.  It additionally stores the
1193           UTF-8 of the result into the buffer beginning at "s", and its
1194           length in bytes into *lenp.  The caller must have made "s" large
1195           enough to contain at least "UTF8_MAXBYTES_CASE+1" bytes to avoid
1196           possible overflow.
1197
1198           NOTE: the uppercase of a code point may be more than one code
1199           point.  The return value of this function is only the first of
1200           these.  The entire uppercase is returned in "s".  To determine if
1201           the result is more than a single code point, you can do something
1202           like this:
1203
1204            uc = toUPPER_uvchr(cp, s, &len);
1205            if (len > UTF8SKIP(s)) { is multiple code points }
1206            else { is a single code point }
1207
1208           "toUPPER_utf8" and "toUPPER_utf8_safe" are synonyms of each other.
1209           The only difference between these and "toUPPER_uvchr" is that the
1210           source for these is encoded in UTF-8, instead of being a code
1211           point.  It is passed as a buffer starting at "p", with "e" pointing
1212           to one byte beyond its end.  The "p" buffer may certainly contain
1213           more than one code point; but only the first one (up through
1214           "e - 1") is examined.  If the UTF-8 for the input character is
1215           malformed in some way, the program may croak, or the function may
1216           return the REPLACEMENT CHARACTER, at the discretion of the
1217           implementation, and subject to change in future releases.
1218
1219            UV  toUPPER          (UV cp)
1220            UV  toUPPER_A        (UV cp)
1221            UV  toUPPER_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
1222            UV  toUPPER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1223            UV  toUPPER_uvchr    (UV cp, U8* s, STRLEN* lenp)
1224

Character classification

1226       This section is about functions (really macros) that classify
1227       characters into types, such as punctuation versus alphabetic, etc.
1228       Most of these are analogous to regular expression character classes.
1229       (See "POSIX Character Classes" in perlrecharclass.)  There are several
1230       variants for each class.  (Not all macros have all variants; each item
1231       below lists the ones valid for it.)  None are affected by "use bytes",
1232       and only the ones with "LC" in the name are affected by the current
1233       locale.
1234
1235       The base function, e.g., isALPHA(), takes any signed or unsigned value,
1236       treating it as a code point, and returns a boolean as to whether or not
1237       the character represented by it is (or on non-ASCII platforms,
1238       corresponds to) an ASCII character in the named class based on
1239       platform, Unicode, and Perl rules.  If the input is a number that
1240       doesn't fit in an octet, FALSE is returned.
1241
1242       Variant "isFOO_A" (e.g., isALPHA_A()) is identical to the base function
1243       with no suffix "_A".  This variant is used to emphasize by its name
1244       that only ASCII-range characters can return TRUE.
1245
1246       Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivalent) character
1247       set onto the platform.  That is, the code points that are ASCII are
1248       unaffected, since ASCII is a subset of Latin-1.  But the non-ASCII code
1249       points are treated as if they are Latin-1 characters.  For example,
1250       isWORDCHAR_L1() will return true when called with the code point 0xDF,
1251       which is a word character in both ASCII and EBCDIC (though it
1252       represents different characters in each).  If the input is a number
1253       that doesn't fit in an octet, FALSE is returned.  (Perl's documentation
1254       uses a colloquial definition of Latin-1, to include all code points
1255       below 256.)
1256
1257       Variant "isFOO_uvchr" is exactly like the "isFOO_L1" variant, for
1258       inputs below 256, but if the code point is larger than 255, Unicode
1259       rules are used to determine if it is in the character class.  For
1260       example, isWORDCHAR_uvchr(0x100) returns TRUE, since 0x100 is LATIN
1261       CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.
1262
1263       Variants "isFOO_utf8" and "isFOO_utf8_safe" are like "isFOO_uvchr", but
1264       are used for UTF-8 encoded strings.  The two forms are different names
1265       for the same thing.  Each call to one of these classifies the first
1266       character of the string starting at "p".  The second parameter, "e",
1267       points to anywhere in the string beyond the first character, up to one
1268       byte past the end of the entire string.  Although both variants are
1269       identical, the suffix "_safe" in one name emphasizes that it will not
1270       attempt to read beyond "e - 1", provided that the constraint "s < e" is
1271       true (this is asserted for in "-DDEBUGGING" builds).  If the UTF-8 for
1272       the input character is malformed in some way, the program may croak, or
1273       the function may return FALSE, at the discretion of the implementation,
1274       and subject to change in future releases.
1275
1276       Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but
1277       the result is based on the current locale, which is what "LC" in the
1278       name stands for.  If Perl can determine that the current locale is a
1279       UTF-8 locale, it uses the published Unicode rules; otherwise, it uses
1280       the C library function that gives the named classification.  For
1281       example, isDIGIT_LC() when not in a UTF-8 locale returns the result of
1282       calling isdigit().  FALSE is always returned if the input won't fit
1283       into an octet.  On some platforms where the C library function is known
1284       to be defective, Perl changes its result to follow the POSIX standard's
1285       rules.
1286
1287       Variant "isFOO_LC_uvchr" acts exactly like "isFOO_LC" for inputs less
1288       than 256, but for larger ones it returns the Unicode classification of
1289       the code point.
1290
1291       Variants "isFOO_LC_utf8" and "isFOO_LC_utf8_safe" are like
1292       "isFOO_LC_uvchr", but are used for UTF-8 encoded strings.  The two
1293       forms are different names for the same thing.  Each call to one of
1294       these classifies the first character of the string starting at "p".
1295       The second parameter, "e", points to anywhere in the string beyond the
1296       first character, up to one byte past the end of the entire string.
1297       Although both variants are identical, the suffix "_safe" in one name
1298       emphasizes that it will not attempt to read beyond "e - 1", provided
1299       that the constraint "s < e" is true (this is asserted for in
1300       "-DDEBUGGING" builds).  If the UTF-8 for the input character is
1301       malformed in some way, the program may croak, or the function may
1302       return FALSE, at the discretion of the implementation, and subject to
1303       change in future releases.
1304
1305       "isALNUM"
1306       "isALNUM_A"
1307       "isALNUM_LC"
1308       "isALNUM_LC_uvchr"
1309           These are each a synonym for their respectively named
1310           ""isWORDCHAR"" variant.
1311
1312           They are provided for backward compatibility, even though a word
1313           character includes more than the standard C language meaning of
1314           alphanumeric.  To get the C language definition, use the
1315           corresponding ""isALPHANUMERIC"" variant.
1316
1317            bool  isALNUM(UV ch)
1318
1319       "isALNUMC"
1320       "isALNUMC_A"
1321       "isALNUMC_LC"
1322       "isALNUMC_LC_uvchr"
1323       "isALNUMC_L1"
1324           These are discouraged, backward compatibility macros for
1325           ""isALPHANUMERIC"".  That is, each returns a boolean indicating
1326           whether the specified character is one of "[A-Za-z0-9]", analogous
1327           to "m/[[:alnum:]]/".
1328
1329           The "C" suffix in the names was meant to indicate that they
1330           correspond to the C language isalnum(3).
1331
1332            bool  isALNUMC(UV ch)
1333
1334       "isALPHA"
1335       "isALPHA_A"
1336       "isALPHA_LC"
1337       "isALPHA_LC_utf8_safe"
1338       "isALPHA_LC_uvchr"
1339       "isALPHA_L1"
1340       "isALPHA_utf8"
1341       "isALPHA_utf8_safe"
1342       "isALPHA_uvchr"
1343           Returns a boolean indicating whether the specified input is one of
1344           "[A-Za-z]", analogous to "m/[[:alpha:]]/".  See the top of this
1345           section for an explanation of the variants.
1346
1347            bool  isALPHA             (UV ch)
1348            bool  isALPHA_A           (UV ch)
1349            bool  isALPHA_LC          (UV ch)
1350            bool  isALPHA_LC_utf8_safe(U8 * s, U8 *end)
1351            bool  isALPHA_LC_uvchr    (UV ch)
1352            bool  isALPHA_L1          (UV ch)
1353            bool  isALPHA_utf8        (U8 * s, U8 * end)
1354            bool  isALPHA_utf8_safe   (U8 * s, U8 * end)
1355            bool  isALPHA_uvchr       (UV ch)
1356
1357       "isALPHANUMERIC"
1358       "isALPHANUMERIC_A"
1359       "isALPHANUMERIC_LC"
1360       "isALPHANUMERIC_LC_utf8_safe"
1361       "isALPHANUMERIC_LC_uvchr"
1362       "isALPHANUMERIC_L1"
1363       "isALPHANUMERIC_utf8"
1364       "isALPHANUMERIC_utf8_safe"
1365       "isALPHANUMERIC_uvchr"
1366           Returns a boolean indicating whether the specified character is one
1367           of "[A-Za-z0-9]", analogous to "m/[[:alnum:]]/".  See the top of
1368           this section for an explanation of the variants.
1369
1370            bool  isALPHANUMERIC             (UV ch)
1371            bool  isALPHANUMERIC_A           (UV ch)
1372            bool  isALPHANUMERIC_LC          (UV ch)
1373            bool  isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end)
1374            bool  isALPHANUMERIC_LC_uvchr    (UV ch)
1375            bool  isALPHANUMERIC_L1          (UV ch)
1376            bool  isALPHANUMERIC_utf8        (U8 * s, U8 * end)
1377            bool  isALPHANUMERIC_utf8_safe   (U8 * s, U8 * end)
1378            bool  isALPHANUMERIC_uvchr       (UV ch)
1379
1380       "isASCII"
1381       "isASCII_A"
1382       "isASCII_LC"
1383       "isASCII_LC_utf8_safe"
1384       "isASCII_LC_uvchr"
1385       "isASCII_L1"
1386       "isASCII_utf8"
1387       "isASCII_utf8_safe"
1388       "isASCII_uvchr"
1389           Returns a boolean indicating whether the specified character is one
1390           of the 128 characters in the ASCII character set, analogous to
1391           "m/[[:ascii:]]/".  On non-ASCII platforms, it returns TRUE iff this
1392           character corresponds to an ASCII character.  Variants isASCII_A()
1393           and isASCII_L1() are identical to isASCII().  See the top of this
1394           section for an explanation of the variants.  Note, however, that
1395           some platforms do not have the C library routine isascii().  In
1396           these cases, the variants whose names contain "LC" are the same as
1397           the corresponding ones without.
1398
1399           Also note, that because all ASCII characters are UTF-8 invariant
1400           (meaning they have the exact same representation (always a single
1401           byte) whether encoded in UTF-8 or not), "isASCII" will give the
1402           correct results when called with any byte in any string encoded or
1403           not in UTF-8.  And similarly "isASCII_utf8" and "isASCII_utf8_safe"
1404           will work properly on any string encoded or not in UTF-8.
1405
1406            bool  isASCII             (UV ch)
1407            bool  isASCII_A           (UV ch)
1408            bool  isASCII_LC          (UV ch)
1409            bool  isASCII_LC_utf8_safe(U8 * s, U8 *end)
1410            bool  isASCII_LC_uvchr    (UV ch)
1411            bool  isASCII_L1          (UV ch)
1412            bool  isASCII_utf8        (U8 * s, U8 * end)
1413            bool  isASCII_utf8_safe   (U8 * s, U8 * end)
1414            bool  isASCII_uvchr       (UV ch)
1415
1416       "isBLANK"
1417       "isBLANK_A"
1418       "isBLANK_LC"
1419       "isBLANK_LC_utf8_safe"
1420       "isBLANK_LC_uvchr"
1421       "isBLANK_L1"
1422       "isBLANK_utf8"
1423       "isBLANK_utf8_safe"
1424       "isBLANK_uvchr"
1425           Returns a boolean indicating whether the specified character is a
1426           character considered to be a blank, analogous to "m/[[:blank:]]/".
1427           See the top of this section for an explanation of the variants.
1428           Note, however, that some platforms do not have the C library
1429           routine isblank().  In these cases, the variants whose names
1430           contain "LC" are the same as the corresponding ones without.
1431
1432            bool  isBLANK             (UV ch)
1433            bool  isBLANK_A           (UV ch)
1434            bool  isBLANK_LC          (UV ch)
1435            bool  isBLANK_LC_utf8_safe(U8 * s, U8 *end)
1436            bool  isBLANK_LC_uvchr    (UV ch)
1437            bool  isBLANK_L1          (UV ch)
1438            bool  isBLANK_utf8        (U8 * s, U8 * end)
1439            bool  isBLANK_utf8_safe   (U8 * s, U8 * end)
1440            bool  isBLANK_uvchr       (UV ch)
1441
1442       "isCNTRL"
1443       "isCNTRL_A"
1444       "isCNTRL_LC"
1445       "isCNTRL_LC_utf8_safe"
1446       "isCNTRL_LC_uvchr"
1447       "isCNTRL_L1"
1448       "isCNTRL_utf8"
1449       "isCNTRL_utf8_safe"
1450       "isCNTRL_uvchr"
1451           Returns a boolean indicating whether the specified character is a
1452           control character, analogous to "m/[[:cntrl:]]/".  See the top of
1453           this section for an explanation of the variants.  On EBCDIC
1454           platforms, you almost always want to use the "isCNTRL_L1" variant.
1455
1456            bool  isCNTRL             (UV ch)
1457            bool  isCNTRL_A           (UV ch)
1458            bool  isCNTRL_LC          (UV ch)
1459            bool  isCNTRL_LC_utf8_safe(U8 * s, U8 *end)
1460            bool  isCNTRL_LC_uvchr    (UV ch)
1461            bool  isCNTRL_L1          (UV ch)
1462            bool  isCNTRL_utf8        (U8 * s, U8 * end)
1463            bool  isCNTRL_utf8_safe   (U8 * s, U8 * end)
1464            bool  isCNTRL_uvchr       (UV ch)
1465
1466       "isDIGIT"
1467       "isDIGIT_A"
1468       "isDIGIT_LC"
1469       "isDIGIT_LC_utf8_safe"
1470       "isDIGIT_LC_uvchr"
1471       "isDIGIT_L1"
1472       "isDIGIT_utf8"
1473       "isDIGIT_utf8_safe"
1474       "isDIGIT_uvchr"
1475           Returns a boolean indicating whether the specified character is a
1476           digit, analogous to "m/[[:digit:]]/".  Variants "isDIGIT_A" and
1477           "isDIGIT_L1" are identical to "isDIGIT".  See the top of this
1478           section for an explanation of the variants.
1479
1480            bool  isDIGIT             (UV ch)
1481            bool  isDIGIT_A           (UV ch)
1482            bool  isDIGIT_LC          (UV ch)
1483            bool  isDIGIT_LC_utf8_safe(U8 * s, U8 *end)
1484            bool  isDIGIT_LC_uvchr    (UV ch)
1485            bool  isDIGIT_L1          (UV ch)
1486            bool  isDIGIT_utf8        (U8 * s, U8 * end)
1487            bool  isDIGIT_utf8_safe   (U8 * s, U8 * end)
1488            bool  isDIGIT_uvchr       (UV ch)
1489
1490       "isGRAPH"
1491       "isGRAPH_A"
1492       "isGRAPH_LC"
1493       "isGRAPH_LC_utf8_safe"
1494       "isGRAPH_LC_uvchr"
1495       "isGRAPH_L1"
1496       "isGRAPH_utf8"
1497       "isGRAPH_utf8_safe"
1498       "isGRAPH_uvchr"
1499           Returns a boolean indicating whether the specified character is a
1500           graphic character, analogous to "m/[[:graph:]]/".  See the top of
1501           this section for an explanation of the variants.
1502
1503            bool  isGRAPH             (UV ch)
1504            bool  isGRAPH_A           (UV ch)
1505            bool  isGRAPH_LC          (UV ch)
1506            bool  isGRAPH_LC_utf8_safe(U8 * s, U8 *end)
1507            bool  isGRAPH_LC_uvchr    (UV ch)
1508            bool  isGRAPH_L1          (UV ch)
1509            bool  isGRAPH_utf8        (U8 * s, U8 * end)
1510            bool  isGRAPH_utf8_safe   (U8 * s, U8 * end)
1511            bool  isGRAPH_uvchr       (UV ch)
1512
1513       "isIDCONT"
1514       "isIDCONT_A"
1515       "isIDCONT_LC"
1516       "isIDCONT_LC_utf8_safe"
1517       "isIDCONT_LC_uvchr"
1518       "isIDCONT_L1"
1519       "isIDCONT_utf8"
1520       "isIDCONT_utf8_safe"
1521       "isIDCONT_uvchr"
1522           Returns a boolean indicating whether the specified character can be
1523           the second or succeeding character of an identifier.  This is very
1524           close to, but not quite the same as the official Unicode property
1525           "XID_Continue".  The difference is that this returns true only if
1526           the input character also matches "isWORDCHAR".  See the top of this
1527           section for an explanation of the variants.
1528
1529            bool  isIDCONT             (UV ch)
1530            bool  isIDCONT_A           (UV ch)
1531            bool  isIDCONT_LC          (UV ch)
1532            bool  isIDCONT_LC_utf8_safe(U8 * s, U8 *end)
1533            bool  isIDCONT_LC_uvchr    (UV ch)
1534            bool  isIDCONT_L1          (UV ch)
1535            bool  isIDCONT_utf8        (U8 * s, U8 * end)
1536            bool  isIDCONT_utf8_safe   (U8 * s, U8 * end)
1537            bool  isIDCONT_uvchr       (UV ch)
1538
1539       "isIDFIRST"
1540       "isIDFIRST_A"
1541       "isIDFIRST_LC"
1542       "isIDFIRST_LC_utf8_safe"
1543       "isIDFIRST_LC_uvchr"
1544       "isIDFIRST_L1"
1545       "isIDFIRST_utf8"
1546       "isIDFIRST_utf8_safe"
1547       "isIDFIRST_uvchr"
1548           Returns a boolean indicating whether the specified character can be
1549           the first character of an identifier.  This is very close to, but
1550           not quite the same as the official Unicode property "XID_Start".
1551           The difference is that this returns true only if the input
1552           character also matches "isWORDCHAR".  See the top of this section
1553           for an explanation of the variants.
1554
1555            bool  isIDFIRST             (UV ch)
1556            bool  isIDFIRST_A           (UV ch)
1557            bool  isIDFIRST_LC          (UV ch)
1558            bool  isIDFIRST_LC_utf8_safe(U8 * s, U8 *end)
1559            bool  isIDFIRST_LC_uvchr    (UV ch)
1560            bool  isIDFIRST_L1          (UV ch)
1561            bool  isIDFIRST_utf8        (U8 * s, U8 * end)
1562            bool  isIDFIRST_utf8_safe   (U8 * s, U8 * end)
1563            bool  isIDFIRST_uvchr       (UV ch)
1564
1565       "isLOWER"
1566       "isLOWER_A"
1567       "isLOWER_LC"
1568       "isLOWER_LC_utf8_safe"
1569       "isLOWER_LC_uvchr"
1570       "isLOWER_L1"
1571       "isLOWER_utf8"
1572       "isLOWER_utf8_safe"
1573       "isLOWER_uvchr"
1574           Returns a boolean indicating whether the specified character is a
1575           lowercase character, analogous to "m/[[:lower:]]/".  See the top of
1576           this section for an explanation of the variants
1577
1578            bool  isLOWER             (UV ch)
1579            bool  isLOWER_A           (UV ch)
1580            bool  isLOWER_LC          (UV ch)
1581            bool  isLOWER_LC_utf8_safe(U8 * s, U8 *end)
1582            bool  isLOWER_LC_uvchr    (UV ch)
1583            bool  isLOWER_L1          (UV ch)
1584            bool  isLOWER_utf8        (U8 * s, U8 * end)
1585            bool  isLOWER_utf8_safe   (U8 * s, U8 * end)
1586            bool  isLOWER_uvchr       (UV ch)
1587
1588       "isOCTAL"
1589       "isOCTAL_A"
1590       "isOCTAL_L1"
1591           Returns a boolean indicating whether the specified character is an
1592           octal digit, [0-7].  The only two variants are "isOCTAL_A" and
1593           "isOCTAL_L1"; each is identical to "isOCTAL".
1594
1595            bool  isOCTAL(UV ch)
1596
1597       "isPRINT"
1598       "isPRINT_A"
1599       "isPRINT_LC"
1600       "isPRINT_LC_utf8_safe"
1601       "isPRINT_LC_uvchr"
1602       "isPRINT_L1"
1603       "isPRINT_utf8"
1604       "isPRINT_utf8_safe"
1605       "isPRINT_uvchr"
1606           Returns a boolean indicating whether the specified character is a
1607           printable character, analogous to "m/[[:print:]]/".  See the top of
1608           this section for an explanation of the variants.
1609
1610            bool  isPRINT             (UV ch)
1611            bool  isPRINT_A           (UV ch)
1612            bool  isPRINT_LC          (UV ch)
1613            bool  isPRINT_LC_utf8_safe(U8 * s, U8 *end)
1614            bool  isPRINT_LC_uvchr    (UV ch)
1615            bool  isPRINT_L1          (UV ch)
1616            bool  isPRINT_utf8        (U8 * s, U8 * end)
1617            bool  isPRINT_utf8_safe   (U8 * s, U8 * end)
1618            bool  isPRINT_uvchr       (UV ch)
1619
1620       "isPSXSPC"
1621       "isPSXSPC_A"
1622       "isPSXSPC_LC"
1623       "isPSXSPC_LC_utf8_safe"
1624       "isPSXSPC_LC_uvchr"
1625       "isPSXSPC_L1"
1626       "isPSXSPC_utf8"
1627       "isPSXSPC_utf8_safe"
1628       "isPSXSPC_uvchr"
1629           (short for Posix Space) Starting in 5.18, this is identical in all
1630           its forms to the corresponding isSPACE() macros.  The locale forms
1631           of this macro are identical to their corresponding isSPACE() forms
1632           in all Perl releases.  In releases prior to 5.18, the non-locale
1633           forms differ from their isSPACE() forms only in that the isSPACE()
1634           forms don't match a Vertical Tab, and the isPSXSPC() forms do.
1635           Otherwise they are identical.  Thus this macro is analogous to what
1636           "m/[[:space:]]/" matches in a regular expression.  See the top of
1637           this section for an explanation of the variants.
1638
1639            bool  isPSXSPC             (UV ch)
1640            bool  isPSXSPC_A           (UV ch)
1641            bool  isPSXSPC_LC          (UV ch)
1642            bool  isPSXSPC_LC_utf8_safe(U8 * s, U8 *end)
1643            bool  isPSXSPC_LC_uvchr    (UV ch)
1644            bool  isPSXSPC_L1          (UV ch)
1645            bool  isPSXSPC_utf8        (U8 * s, U8 * end)
1646            bool  isPSXSPC_utf8_safe   (U8 * s, U8 * end)
1647            bool  isPSXSPC_uvchr       (UV ch)
1648
1649       "isPUNCT"
1650       "isPUNCT_A"
1651       "isPUNCT_LC"
1652       "isPUNCT_LC_utf8_safe"
1653       "isPUNCT_LC_uvchr"
1654       "isPUNCT_L1"
1655       "isPUNCT_utf8"
1656       "isPUNCT_utf8_safe"
1657       "isPUNCT_uvchr"
1658           Returns a boolean indicating whether the specified character is a
1659           punctuation character, analogous to "m/[[:punct:]]/".  Note that
1660           the definition of what is punctuation isn't as straightforward as
1661           one might desire.  See "POSIX Character Classes" in perlrecharclass
1662           for details.  See the top of this section for an explanation of the
1663           variants.
1664
1665            bool  isPUNCT             (UV ch)
1666            bool  isPUNCT_A           (UV ch)
1667            bool  isPUNCT_LC          (UV ch)
1668            bool  isPUNCT_LC_utf8_safe(U8 * s, U8 *end)
1669            bool  isPUNCT_LC_uvchr    (UV ch)
1670            bool  isPUNCT_L1          (UV ch)
1671            bool  isPUNCT_utf8        (U8 * s, U8 * end)
1672            bool  isPUNCT_utf8_safe   (U8 * s, U8 * end)
1673            bool  isPUNCT_uvchr       (UV ch)
1674
1675       "isSPACE"
1676       "isSPACE_A"
1677       "isSPACE_LC"
1678       "isSPACE_LC_utf8_safe"
1679       "isSPACE_LC_uvchr"
1680       "isSPACE_L1"
1681       "isSPACE_utf8"
1682       "isSPACE_utf8_safe"
1683       "isSPACE_uvchr"
1684           Returns a boolean indicating whether the specified character is a
1685           whitespace character.  This is analogous to what "m/\s/" matches in
1686           a regular expression.  Starting in Perl 5.18 this also matches what
1687           "m/[[:space:]]/" does.  Prior to 5.18, only the locale forms of
1688           this macro (the ones with "LC" in their names) matched precisely
1689           what "m/[[:space:]]/" does.  In those releases, the only
1690           difference, in the non-locale variants, was that isSPACE() did not
1691           match a vertical tab.  (See "isPSXSPC" for a macro that matches a
1692           vertical tab in all releases.)  See the top of this section for an
1693           explanation of the variants.
1694
1695            bool  isSPACE             (UV ch)
1696            bool  isSPACE_A           (UV ch)
1697            bool  isSPACE_LC          (UV ch)
1698            bool  isSPACE_LC_utf8_safe(U8 * s, U8 *end)
1699            bool  isSPACE_LC_uvchr    (UV ch)
1700            bool  isSPACE_L1          (UV ch)
1701            bool  isSPACE_utf8        (U8 * s, U8 * end)
1702            bool  isSPACE_utf8_safe   (U8 * s, U8 * end)
1703            bool  isSPACE_uvchr       (UV ch)
1704
1705       "isUPPER"
1706       "isUPPER_A"
1707       "isUPPER_LC"
1708       "isUPPER_LC_utf8_safe"
1709       "isUPPER_LC_uvchr"
1710       "isUPPER_L1"
1711       "isUPPER_utf8"
1712       "isUPPER_utf8_safe"
1713       "isUPPER_uvchr"
1714           Returns a boolean indicating whether the specified character is an
1715           uppercase character, analogous to "m/[[:upper:]]/".  See the top of
1716           this section for an explanation of the variants.
1717
1718            bool  isUPPER             (UV ch)
1719            bool  isUPPER_A           (UV ch)
1720            bool  isUPPER_LC          (UV ch)
1721            bool  isUPPER_LC_utf8_safe(U8 * s, U8 *end)
1722            bool  isUPPER_LC_uvchr    (UV ch)
1723            bool  isUPPER_L1          (UV ch)
1724            bool  isUPPER_utf8        (U8 * s, U8 * end)
1725            bool  isUPPER_utf8_safe   (U8 * s, U8 * end)
1726            bool  isUPPER_uvchr       (UV ch)
1727
1728       "isWORDCHAR"
1729       "isWORDCHAR_A"
1730       "isWORDCHAR_LC"
1731       "isWORDCHAR_LC_utf8_safe"
1732       "isWORDCHAR_LC_uvchr"
1733       "isWORDCHAR_L1"
1734       "isWORDCHAR_utf8"
1735       "isWORDCHAR_utf8_safe"
1736       "isWORDCHAR_uvchr"
1737           Returns a boolean indicating whether the specified character is a
1738           character that is a word character, analogous to what "m/\w/" and
1739           "m/[[:word:]]/" match in a regular expression.  A word character is
1740           an alphabetic character, a decimal digit, a connecting punctuation
1741           character (such as an underscore), or a "mark" character that
1742           attaches to one of those (like some sort of accent).
1743
1744           See the top of this section for an explanation of the variants.
1745
1746           "isWORDCHAR_A", "isWORDCHAR_L1", "isWORDCHAR_uvchr",
1747           "isWORDCHAR_LC", "isWORDCHAR_LC_uvchr", "isWORDCHAR_LC_utf8", and
1748           "isWORDCHAR_LC_utf8_safe" are also as described there, but
1749           additionally include the platform's native underscore.
1750
1751            bool  isWORDCHAR             (UV ch)
1752            bool  isWORDCHAR_A           (UV ch)
1753            bool  isWORDCHAR_LC          (UV ch)
1754            bool  isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end)
1755            bool  isWORDCHAR_LC_uvchr    (UV ch)
1756            bool  isWORDCHAR_L1          (UV ch)
1757            bool  isWORDCHAR_utf8        (U8 * s, U8 * end)
1758            bool  isWORDCHAR_utf8_safe   (U8 * s, U8 * end)
1759            bool  isWORDCHAR_uvchr       (UV ch)
1760
1761       "isXDIGIT"
1762       "isXDIGIT_A"
1763       "isXDIGIT_LC"
1764       "isXDIGIT_LC_utf8_safe"
1765       "isXDIGIT_LC_uvchr"
1766       "isXDIGIT_L1"
1767       "isXDIGIT_utf8"
1768       "isXDIGIT_utf8_safe"
1769       "isXDIGIT_uvchr"
1770           Returns a boolean indicating whether the specified character is a
1771           hexadecimal digit.  In the ASCII range these are "[0-9A-Fa-f]".
1772           Variants isXDIGIT_A() and isXDIGIT_L1() are identical to
1773           isXDIGIT().  See the top of this section for an explanation of the
1774           variants.
1775
1776            bool  isXDIGIT             (UV ch)
1777            bool  isXDIGIT_A           (UV ch)
1778            bool  isXDIGIT_LC          (UV ch)
1779            bool  isXDIGIT_LC_utf8_safe(U8 * s, U8 *end)
1780            bool  isXDIGIT_LC_uvchr    (UV ch)
1781            bool  isXDIGIT_L1          (UV ch)
1782            bool  isXDIGIT_utf8        (U8 * s, U8 * end)
1783            bool  isXDIGIT_utf8_safe   (U8 * s, U8 * end)
1784            bool  isXDIGIT_uvchr       (UV ch)
1785

Compiler and Preprocessor information

1787       "CPPLAST"
1788           This symbol is intended to be used along with "CPPRUN" in the same
1789           manner symbol "CPPMINUS" is used with "CPPSTDIN". It contains
1790           either "-" or "".
1791
1792       "CPPMINUS"
1793           This symbol contains the second part of the string which will
1794           invoke the C preprocessor on the standard input and produce to
1795           standard output.  This symbol will have the value "-" if "CPPSTDIN"
1796           needs a minus to specify standard input, otherwise the value is "".
1797
1798       "CPPRUN"
1799           This symbol contains the string which will invoke a C preprocessor
1800           on the standard input and produce to standard output. It needs to
1801           end with "CPPLAST", after all other preprocessor flags have been
1802           specified.  The main difference with "CPPSTDIN" is that this
1803           program will never be a pointer to a shell wrapper, i.e. it will be
1804           empty if no preprocessor is available directly to the user. Note
1805           that it may well be different from the preprocessor used to compile
1806           the C program.
1807
1808       "CPPSTDIN"
1809           This symbol contains the first part of the string which will invoke
1810           the C preprocessor on the standard input and produce to standard
1811           output.  Typical value of "cc -E" or "/lib/cpp", but it can also
1812           call a wrapper. See "CPPRUN".
1813
1814       "HASATTRIBUTE_ALWAYS_INLINE"
1815           Can we handle "GCC" attribute for functions that should always be
1816           inlined.
1817
1818       "HASATTRIBUTE_DEPRECATED"
1819           Can we handle "GCC" attribute for marking deprecated "APIs"
1820
1821       "HASATTRIBUTE_FORMAT"
1822           Can we handle "GCC" attribute for checking printf-style formats
1823
1824       "HASATTRIBUTE_NONNULL"
1825           Can we handle "GCC" attribute for nonnull function parms.
1826
1827       "HASATTRIBUTE_NORETURN"
1828           Can we handle "GCC" attribute for functions that do not return
1829
1830       "HASATTRIBUTE_PURE"
1831           Can we handle "GCC" attribute for pure functions
1832
1833       "HASATTRIBUTE_UNUSED"
1834           Can we handle "GCC" attribute for unused variables and arguments
1835
1836       "HASATTRIBUTE_VISIBILITY"
1837           Can we handle "GCC" attribute for functions that should have a
1838           different visibility.
1839
1840       "HASATTRIBUTE_WARN_UNUSED_RESULT"
1841           Can we handle "GCC" attribute for warning on unused results
1842
1843       "HAS_BUILTIN_ADD_OVERFLOW"
1844           This symbol, if defined, indicates that the compiler supports
1845           "__builtin_add_overflow" for adding integers with overflow checks.
1846
1847       "HAS_BUILTIN_CHOOSE_EXPR"
1848           Can we handle "GCC" builtin for compile-time ternary-like
1849           expressions
1850
1851       "HAS_BUILTIN_EXPECT"
1852           Can we handle "GCC" builtin for telling that certain values are
1853           more likely
1854
1855       "HAS_BUILTIN_MUL_OVERFLOW"
1856           This symbol, if defined, indicates that the compiler supports
1857           "__builtin_mul_overflow" for multiplying integers with overflow
1858           checks.
1859
1860       "HAS_BUILTIN_SUB_OVERFLOW"
1861           This symbol, if defined, indicates that the compiler supports
1862           "__builtin_sub_overflow" for subtracting integers with overflow
1863           checks.
1864
1865       "HAS_C99_VARIADIC_MACROS"
1866           If defined, the compiler supports C99 variadic macros.
1867
1868       "HAS_STATIC_INLINE"
1869           This symbol, if defined, indicates that the C compiler supports
1870           C99-style static inline.  That is, the function can't be called
1871           from another translation unit.
1872
1873       "MEM_ALIGNBYTES"
1874           This symbol contains the number of bytes required to align a
1875           double, or a long double when applicable. Usual values are 2, 4 and
1876           8. The default is eight, for safety.  For cross-compiling or
1877           multiarch support, Configure will set a minimum of 8.
1878
1879       "PERL_STATIC_INLINE"
1880           This symbol gives the best-guess incantation to use for static
1881           inline functions.  If "HAS_STATIC_INLINE" is defined, this will
1882           give C99-style inline.  If "HAS_STATIC_INLINE" is not defined, this
1883           will give a plain 'static'.  It will always be defined to something
1884           that gives static linkage.  Possibilities include
1885
1886            static inline       (c99)
1887            static __inline__   (gcc -ansi)
1888            static __inline     (MSVC)
1889            static _inline      (older MSVC)
1890            static              (c89 compilers)
1891
1892       "PERL_THREAD_LOCAL"
1893           This symbol, if defined, gives a linkage specification for thread-
1894           local storage. For example, for a C11 compiler this will be
1895           "_Thread_local".  Beware, some compilers are sensitive to the C
1896           language standard they are told to parse. For example, suncc
1897           defaults to C11, so our probe will report that "_Thread_local" can
1898           be used. However, if the -std=c99 is later added to the compiler
1899           flags, then "_Thread_local" will become a syntax error. Hence it is
1900           important for these flags to be consistent between probing and use.
1901
1902       "U32_ALIGNMENT_REQUIRED"
1903           This symbol, if defined, indicates that you must access character
1904           data through U32-aligned pointers.
1905

Compiler directives

1907       "__ASSERT_"
1908           This is a helper macro to avoid preprocessor issues, replaced by
1909           nothing unless under DEBUGGING, where it expands to an assert of
1910           its argument, followed by a comma (hence the comma operator).  If
1911           we just used a straight assert(), we would get a comma with nothing
1912           before it when not DEBUGGING.
1913
1914              __ASSERT_(bool expr)
1915
1916       "ASSUME"
1917           "ASSUME" is like assert(), but it has a benefit in a release build.
1918           It is a hint to a compiler about a statement of fact in a function
1919           call free expression, which allows the compiler to generate better
1920           machine code.  In a debug build, ASSUME(x) is a synonym for
1921           assert(x). ASSUME(0) means the control path is unreachable. In a
1922           for loop, "ASSUME" can be used to hint that a loop will run at
1923           least X times. "ASSUME" is based off MSVC's "__assume" intrinsic
1924           function, see its documents for more details.
1925
1926              ASSUME(bool expr)
1927
1928       "dNOOP"
1929           Declare nothing; typically used as a placeholder to replace
1930           something that used to declare something.  Works on compilers that
1931           require declarations before any code.
1932
1933              dNOOP;
1934
1935       "END_EXTERN_C"
1936           When not compiling using C++, expands to nothing.  Otherwise ends a
1937           section of code already begun by a "START_EXTERN_C".
1938
1939              END_EXTERN_C
1940
1941       "EXTERN_C"
1942           When not compiling using C++, expands to nothing.  Otherwise is
1943           used in a declaration of a function to indicate the function should
1944           have external C linkage.  This is required for things to work for
1945           just about all functions with external linkage compiled into perl.
1946           Often, you can use "START_EXTERN_C" ... "END_EXTERN_C" blocks
1947           surrounding all your code that you need to have this linkage.
1948
1949           Example usage:
1950
1951            EXTERN_C int flock(int fd, int op);
1952
1953       "LIKELY"
1954           Returns the input unchanged, but at the same time it gives a branch
1955           prediction hint to the compiler that this condition is likely to be
1956           true.
1957
1958              LIKELY(bool expr)
1959
1960       "NOOP"
1961           Do nothing; typically used as a placeholder to replace something
1962           that used to do something.
1963
1964              NOOP;
1965
1966       "PERL_UNUSED_ARG"
1967           This is used to suppress compiler warnings that a parameter to a
1968           function is not used.  This situation can arise, for example, when
1969           a parameter is needed under some configuration conditions, but not
1970           others, so that C preprocessor conditional compilation causes it be
1971           used just sometimes.
1972
1973              PERL_UNUSED_ARG(void x);
1974
1975       "PERL_UNUSED_CONTEXT"
1976           This is used to suppress compiler warnings that the thread context
1977           parameter to a function is not used.  This situation can arise, for
1978           example, when a C preprocessor conditional compilation causes it be
1979           used just some times.
1980
1981              PERL_UNUSED_CONTEXT;
1982
1983       "PERL_UNUSED_DECL"
1984           Tells the compiler that the parameter in the function prototype
1985           just before it is not necessarily expected to be used in the
1986           function.  Not that many compilers understand this, so this should
1987           only be used in cases where "PERL_UNUSED_ARG" can't conveniently be
1988           used.
1989
1990           Example usage:
1991
1992            Signal_t
1993            Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
1994                                  void *uap PERL_UNUSED_DECL, bool safe)
1995
1996       "PERL_UNUSED_RESULT"
1997           This macro indicates to discard the return value of the function
1998           call inside it, e.g.,
1999
2000            PERL_UNUSED_RESULT(foo(a, b))
2001
2002           The main reason for this is that the combination of "gcc
2003           -Wunused-result" (part of "-Wall") and the
2004           "__attribute__((warn_unused_result))" cannot be silenced with
2005           casting to "void".  This causes trouble when the system header
2006           files use the attribute.
2007
2008           Use "PERL_UNUSED_RESULT" sparingly, though, since usually the
2009           warning is there for a good reason: you might lose success/failure
2010           information, or leak resources, or changes in resources.
2011
2012           But sometimes you just want to ignore the return value, e.g., on
2013           codepaths soon ending up in abort, or in "best effort" attempts, or
2014           in situations where there is no good way to handle failures.
2015
2016           Sometimes "PERL_UNUSED_RESULT" might not be the most natural way:
2017           another possibility is that you can capture the return value and
2018           use "PERL_UNUSED_VAR" on that.
2019
2020              PERL_UNUSED_RESULT(void x)
2021
2022       "PERL_UNUSED_VAR"
2023           This is used to suppress compiler warnings that the variable x is
2024           not used.  This situation can arise, for example, when a C
2025           preprocessor conditional compilation causes it be used just some
2026           times.
2027
2028              PERL_UNUSED_VAR(void x);
2029
2030       "START_EXTERN_C"
2031           When not compiling using C++, expands to nothing.  Otherwise begins
2032           a section of code in which every function will effectively have
2033           "EXTERN_C" applied to it, that is to have external C linkage.  The
2034           section is ended by a "END_EXTERN_C".
2035
2036              START_EXTERN_C
2037
2038       "STATIC"
2039           Described in perlguts.
2040
2041       "STMT_END"
2042       "STMT_START"
2043           These allow a series of statements in a macro to be used as a
2044           single statement, as in
2045
2046            if (x) STMT_START { ... } STMT_END else ...
2047
2048           Note that you can't return a value out of this construct and cannot
2049           use it as an operand to the comma operator.  These limit its
2050           utility.
2051
2052           But, a value could be returned by constructing the API so that a
2053           pointer is passed and the macro dereferences this to set the
2054           return.  If the value can be any of various types, depending on
2055           context, you can handle that situation in some situations by adding
2056           the type of the return as an extra accompanying parameter:
2057
2058            #define foo(param, type)  STMT_START {
2059                                         type * param; *param = do_calc; ...
2060                                      } STMT_END
2061
2062           This could be awkward, so consider instead using a C language
2063           "static inline" function.
2064
2065           If you do use this construct, it is easy to forget that it is a
2066           macro and not a function, and hence fall into traps that might not
2067           show up until someone someday writes code which contains names that
2068           clash with the ones you chose here, or calls it with a parameter
2069           which is an expression with side effects, the consequences of which
2070           you didn't think about.  See "Writing safer macros" in perlhacktips
2071           for how to avoid these.
2072
2073       "UNLIKELY"
2074           Returns the input unchanged, but at the same time it gives a branch
2075           prediction hint to the compiler that this condition is likely to be
2076           false.
2077
2078              UNLIKELY(bool expr)
2079

Compile-time scope hooks

2081       "BhkDISABLE"
2082           NOTE: "BhkDISABLE" is experimental and may change or be removed
2083           without notice.
2084
2085           Temporarily disable an entry in this BHK structure, by clearing the
2086           appropriate flag.  "which" is a preprocessor token indicating which
2087           entry to disable.
2088
2089            void  BhkDISABLE(BHK *hk, token which)
2090
2091       "BhkENABLE"
2092           NOTE: "BhkENABLE" is experimental and may change or be removed
2093           without notice.
2094
2095           Re-enable an entry in this BHK structure, by setting the
2096           appropriate flag.  "which" is a preprocessor token indicating which
2097           entry to enable.  This will assert (under -DDEBUGGING) if the entry
2098           doesn't contain a valid pointer.
2099
2100            void  BhkENABLE(BHK *hk, token which)
2101
2102       "BhkENTRY_set"
2103           NOTE: "BhkENTRY_set" is experimental and may change or be removed
2104           without notice.
2105
2106           Set an entry in the BHK structure, and set the flags to indicate it
2107           is valid.  "which" is a preprocessing token indicating which entry
2108           to set.  The type of "ptr" depends on the entry.
2109
2110            void  BhkENTRY_set(BHK *hk, token which, void *ptr)
2111
2112       "blockhook_register"
2113           NOTE: "blockhook_register" is experimental and may change or be
2114           removed without notice.
2115
2116           Register a set of hooks to be called when the Perl lexical scope
2117           changes at compile time.  See "Compile-time scope hooks" in
2118           perlguts.
2119
2120           NOTE: "blockhook_register" must be explicitly called as
2121           "Perl_blockhook_register" with an "aTHX_" parameter.
2122
2123            void  Perl_blockhook_register(pTHX_ BHK *hk)
2124

Concurrency

2126       "aTHX"
2127           Described in perlguts.
2128
2129       "aTHX_"
2130           Described in perlguts.
2131
2132       "CPERLscope"
2133           "DEPRECATED!"  It is planned to remove "CPERLscope" from a future
2134           release of Perl.  Do not use it for new code; remove it from
2135           existing code.
2136
2137           Now a no-op.
2138
2139            void  CPERLscope(void x)
2140
2141       "dTHR"
2142           Described in perlguts.
2143
2144       "dTHX"
2145           Described in perlguts.
2146
2147       "dTHXa"
2148           On threaded perls, set "pTHX" to "a"; on unthreaded perls, do
2149           nothing
2150
2151       "dTHXoa"
2152           Now a synonym for "dTHXa".
2153
2154       "dVAR"
2155           This is now a synonym for dNOOP: declare nothing
2156
2157       "GETENV_PRESERVES_OTHER_THREAD"
2158           This symbol, if defined, indicates that the getenv system call
2159           doesn't zap the static buffer of getenv() in a different thread.
2160           The typical getenv() implementation will return a pointer to the
2161           proper position in **environ.  But some may instead copy them to a
2162           static buffer in getenv().  If there is a per-thread instance of
2163           that buffer, or the return points to **environ, then a
2164           many-reader/1-writer mutex will work; otherwise an exclusive
2165           locking mutex is required to prevent races.
2166
2167       "HAS_PTHREAD_ATFORK"
2168           This symbol, if defined, indicates that the "pthread_atfork"
2169           routine is available to setup fork handlers.
2170
2171       "HAS_PTHREAD_ATTR_SETSCOPE"
2172           This symbol, if defined, indicates that the "pthread_attr_setscope"
2173           system call is available to set the contention scope attribute of a
2174           thread attribute object.
2175
2176       "HAS_PTHREAD_YIELD"
2177           This symbol, if defined, indicates that the "pthread_yield" routine
2178           is available to yield the execution of the current thread.
2179           "sched_yield" is preferable to "pthread_yield".
2180
2181       "HAS_SCHED_YIELD"
2182           This symbol, if defined, indicates that the "sched_yield" routine
2183           is available to yield the execution of the current thread.
2184           "sched_yield" is preferable to "pthread_yield".
2185
2186       "I_MACH_CTHREADS"
2187           This symbol, if defined, indicates to the C program that it should
2188           include mach/cthreads.h.
2189
2190            #ifdef I_MACH_CTHREADS
2191                #include <mach_cthreads.h>
2192            #endif
2193
2194       "I_PTHREAD"
2195           This symbol, if defined, indicates to the C program that it should
2196           include pthread.h.
2197
2198            #ifdef I_PTHREAD
2199                #include <pthread.h>
2200            #endif
2201
2202       "MULTIPLICITY"
2203           This symbol, if defined, indicates that Perl should be built to use
2204           multiplicity.
2205
2206       "OLD_PTHREAD_CREATE_JOINABLE"
2207           This symbol, if defined, indicates how to create pthread in
2208           joinable (aka undetached) state.  "NOTE": not defined if pthread.h
2209           already has defined "PTHREAD_CREATE_JOINABLE" (the new version of
2210           the constant).  If defined, known values are
2211           "PTHREAD_CREATE_UNDETACHED" and "__UNDETACHED".
2212
2213       "OLD_PTHREADS_API"
2214           This symbol, if defined, indicates that Perl should be built to use
2215           the old draft "POSIX" threads "API".
2216
2217       "PERL_IMPLICIT_CONTEXT"
2218           Described in perlguts.
2219
2220       "PERL_NO_GET_CONTEXT"
2221           Described in perlguts.
2222
2223       "pTHX"
2224           Described in perlguts.
2225
2226       "pTHX_"
2227           Described in perlguts.
2228
2229       "SCHED_YIELD"
2230           This symbol defines the way to yield the execution of the current
2231           thread.  Known ways are "sched_yield", "pthread_yield", and
2232           "pthread_yield" with "NULL".
2233

COPs and Hint Hashes

2235       "cop_fetch_label"
2236           NOTE: "cop_fetch_label" is experimental and may change or be
2237           removed without notice.
2238
2239           Returns the label attached to a cop, and stores its length in bytes
2240           into *len.  Upon return, *flags will be set to either "SVf_UTF8" or
2241           0.
2242
2243           Alternatively, use the macro "CopLABEL_len_flags"; or if you don't
2244           need to know if the label is UTF-8 or not, the macro
2245           "CopLABEL_len"; or if you additionally don't need to know the
2246           length, "CopLABEL".
2247
2248            const char *  cop_fetch_label(COP * const cop, STRLEN *len,
2249                                          U32 *flags)
2250
2251       "CopFILE"
2252           Returns the name of the file associated with the "COP" "c"
2253
2254            const char *  CopFILE(const COP * c)
2255
2256       "CopFILEAV"
2257           Returns the AV associated with the "COP" "c", creating it if
2258           necessary.
2259
2260            AV *  CopFILEAV(const COP * c)
2261
2262       "CopFILEAVn"
2263           Returns the AV associated with the "COP" "c", returning NULL if it
2264           doesn't already exist.
2265
2266            AV *  CopFILEAVn(const COP * c)
2267
2268       "CopFILE_copy"
2269           Efficiently copies the cop file name from one COP to another. Wraps
2270           the required logic to do a refcounted copy under threads or not.
2271
2272            void  CopFILE_copy(COP * dst, COP * src)
2273
2274       "CopFILE_free"
2275           Frees the file data in a cop. Under the hood this is a refcounting
2276           operation.
2277
2278            void  CopFILE_free(COP * c)
2279
2280       "CopFILEGV"
2281           Returns the GV associated with the "COP" "c"
2282
2283            GV *  CopFILEGV(const COP * c)
2284
2285       "CopFILEGV_set"
2286           Available only on unthreaded perls.  Makes "pv" the name of the
2287           file associated with the "COP" "c"
2288
2289            void  CopFILEGV_set(COP *c, GV *gv)
2290
2291       "CopFILE_LEN"
2292           Returns the length of the file associated with the "COP" "c"
2293
2294            const char *  CopFILE_LEN(const COP * c)
2295
2296       "CopFILE_set"
2297           Makes "pv" the name of the file associated with the "COP" "c"
2298
2299            void  CopFILE_set(COP * c, const char * pv)
2300
2301       "CopFILE_setn"
2302           Makes "pv" the name of the file associated with the "COP" "c"
2303
2304            void  CopFILE_setn(COP * c, const char * pv, STRLEN len)
2305
2306       "CopFILESV"
2307           Returns the SV associated with the "COP" "c"
2308
2309            SV *  CopFILESV(const COP * c)
2310
2311       "cophh_copy"
2312           NOTE: "cophh_copy" is experimental and may change or be removed
2313           without notice.
2314
2315           Make and return a complete copy of the cop hints hash "cophh".
2316
2317            COPHH *  cophh_copy(COPHH *cophh)
2318
2319       "cophh_delete_pv"
2320       "cophh_delete_pvn"
2321       "cophh_delete_pvs"
2322       "cophh_delete_sv"
2323           NOTE: all these forms are experimental and may change or be removed
2324           without notice.
2325
2326           These delete a key and its associated value from the cop hints hash
2327           "cophh", and return the modified hash.  The returned hash pointer
2328           is in general not the same as the hash pointer that was passed in.
2329           The input hash is consumed by the function, and the pointer to it
2330           must not be subsequently used.  Use "cophh_copy" if you need both
2331           hashes.
2332
2333           The forms differ in how the key is specified.  In all forms, the
2334           key is pointed to by "key".  In the plain "pv" form, the key is a C
2335           language NUL-terminated string.  In the "pvs" form, the key is a C
2336           language string literal.  In the "pvn" form, an additional
2337           parameter, "keylen", specifies the length of the string, which
2338           hence, may contain embedded-NUL characters.  In the "sv" form, *key
2339           is an SV, and the key is the PV extracted from that.  using
2340           "SvPV_const".
2341
2342           "hash" is a precomputed hash of the key string, or zero if it has
2343           not been precomputed.  This parameter is omitted from the "pvs"
2344           form, as it is computed automatically at compile time.
2345
2346           The only flag currently used from the "flags" parameter is
2347           "COPHH_KEY_UTF8".  It is illegal to set this in the "sv" form.  In
2348           the "pv*" forms, it specifies whether the key octets are
2349           interpreted as UTF-8 (if set) or as Latin-1 (if cleared).  The "sv"
2350           form uses the underlying SV to determine the UTF-8ness of the
2351           octets.
2352
2353            COPHH *  cophh_delete_pv (COPHH *cophh, const char *key, U32 hash,
2354                                      U32 flags)
2355            COPHH *  cophh_delete_pvn(COPHH *cophh, const char *key,
2356                                      STRLEN keylen, U32 hash, U32 flags)
2357            COPHH *  cophh_delete_pvs(COPHH *cophh, "key", U32 flags)
2358            COPHH *  cophh_delete_sv (COPHH *cophh, SV *key, U32 hash,
2359                                      U32 flags)
2360
2361       "cophh_exists_pvn"
2362           NOTE: "cophh_exists_pvn" is experimental and may change or be
2363           removed without notice.
2364
2365           These look up the hint entry in the cop "cop" with the key
2366           specified by "key" (and "keylen" in the "pvn" form), returning true
2367           if a value exists, and false otherwise.
2368
2369           The forms differ in how the key is specified.  In the plain "pv"
2370           form, the key is a C language NUL-terminated string.  In the "pvs"
2371           form, the key is a C language string literal.  In the "pvn" form,
2372           an additional parameter, "keylen", specifies the length of the
2373           string, which hence, may contain embedded-NUL characters.  In the
2374           "sv" form, *key is an SV, and the key is the PV extracted from
2375           that.  using "SvPV_const".
2376
2377           "hash" is a precomputed hash of the key string, or zero if it has
2378           not been precomputed.  This parameter is omitted from the "pvs"
2379           form, as it is computed automatically at compile time.
2380
2381           The only flag currently used from the "flags" parameter is
2382           "COPHH_KEY_UTF8".  It is illegal to set this in the "sv" form.  In
2383           the "pv*" forms, it specifies whether the key octets are
2384           interpreted as UTF-8 (if set) or as Latin-1 (if cleared).  The "sv"
2385           form uses the underlying SV to determine the UTF-8ness of the
2386           octets.
2387
2388            bool  cophh_exists_pvn(const COPHH *cophh, const char *key,
2389                                   STRLEN keylen, U32 hash, U32 flags)
2390
2391       "cophh_fetch_pv"
2392       "cophh_fetch_pvn"
2393       "cophh_fetch_pvs"
2394       "cophh_fetch_sv"
2395           NOTE: all these forms are experimental and may change or be removed
2396           without notice.
2397
2398           These look up the entry in the cop hints hash "cophh" with the key
2399           specified by "key" (and "keylen" in the "pvn" form), returning that
2400           value as a mortal scalar copy, or &PL_sv_placeholder if there is no
2401           value associated with the key.
2402
2403           The forms differ in how the key is specified.  In the plain "pv"
2404           form, the key is a C language NUL-terminated string.  In the "pvs"
2405           form, the key is a C language string literal.  In the "pvn" form,
2406           an additional parameter, "keylen", specifies the length of the
2407           string, which hence, may contain embedded-NUL characters.  In the
2408           "sv" form, *key is an SV, and the key is the PV extracted from
2409           that.  using "SvPV_const".
2410
2411           "hash" is a precomputed hash of the key string, or zero if it has
2412           not been precomputed.  This parameter is omitted from the "pvs"
2413           form, as it is computed automatically at compile time.
2414
2415           The only flag currently used from the "flags" parameter is
2416           "COPHH_KEY_UTF8".  It is illegal to set this in the "sv" form.  In
2417           the "pv*" forms, it specifies whether the key octets are
2418           interpreted as UTF-8 (if set) or as Latin-1 (if cleared).  The "sv"
2419           form uses the underlying SV to determine the UTF-8ness of the
2420           octets.
2421
2422            SV *  cophh_fetch_pv (const COPHH *cophh, const char *key,
2423                                  U32 hash, U32 flags)
2424            SV *  cophh_fetch_pvn(const COPHH *cophh, const char *key,
2425                                  STRLEN keylen, U32 hash, U32 flags)
2426            SV *  cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags)
2427            SV *  cophh_fetch_sv (const COPHH *cophh, SV *key, U32 hash,
2428                                  U32 flags)
2429
2430       "cophh_free"
2431           NOTE: "cophh_free" is experimental and may change or be removed
2432           without notice.
2433
2434           Discard the cop hints hash "cophh", freeing all resources
2435           associated with it.
2436
2437            void  cophh_free(COPHH *cophh)
2438
2439       "cophh_2hv"
2440           NOTE: "cophh_2hv" is experimental and may change or be removed
2441           without notice.
2442
2443           Generates and returns a standard Perl hash representing the full
2444           set of key/value pairs in the cop hints hash "cophh".  "flags" is
2445           currently unused and must be zero.
2446
2447            HV *  cophh_2hv(const COPHH *cophh, U32 flags)
2448
2449       "cophh_new_empty"
2450           NOTE: "cophh_new_empty" is experimental and may change or be
2451           removed without notice.
2452
2453           Generate and return a fresh cop hints hash containing no entries.
2454
2455            COPHH *  cophh_new_empty()
2456
2457       "cophh_store_pv"
2458       "cophh_store_pvn"
2459       "cophh_store_pvs"
2460       "cophh_store_sv"
2461           NOTE: all these forms are experimental and may change or be removed
2462           without notice.
2463
2464           These store a value, associated with a key, in the cop hints hash
2465           "cophh", and return the modified hash.  The returned hash pointer
2466           is in general not the same as the hash pointer that was passed in.
2467           The input hash is consumed by the function, and the pointer to it
2468           must not be subsequently used.  Use "cophh_copy" if you need both
2469           hashes.
2470
2471           "value" is the scalar value to store for this key.  "value" is
2472           copied by these functions, which thus do not take ownership of any
2473           reference to it, and hence later changes to the scalar will not be
2474           reflected in the value visible in the cop hints hash.  Complex
2475           types of scalar will not be stored with referential integrity, but
2476           will be coerced to strings.
2477
2478           The forms differ in how the key is specified.  In all forms, the
2479           key is pointed to by "key".  In the plain "pv" form, the key is a C
2480           language NUL-terminated string.  In the "pvs" form, the key is a C
2481           language string literal.  In the "pvn" form, an additional
2482           parameter, "keylen", specifies the length of the string, which
2483           hence, may contain embedded-NUL characters.  In the "sv" form, *key
2484           is an SV, and the key is the PV extracted from that.  using
2485           "SvPV_const".
2486
2487           "hash" is a precomputed hash of the key string, or zero if it has
2488           not been precomputed.  This parameter is omitted from the "pvs"
2489           form, as it is computed automatically at compile time.
2490
2491           The only flag currently used from the "flags" parameter is
2492           "COPHH_KEY_UTF8".  It is illegal to set this in the "sv" form.  In
2493           the "pv*" forms, it specifies whether the key octets are
2494           interpreted as UTF-8 (if set) or as Latin-1 (if cleared).  The "sv"
2495           form uses the underlying SV to determine the UTF-8ness of the
2496           octets.
2497
2498            COPHH *  cophh_store_pv (COPHH *cophh, const char *key, U32 hash,
2499                                     SV *value, U32 flags)
2500            COPHH *  cophh_store_pvn(COPHH *cophh, const char *key,
2501                                     STRLEN keylen, U32 hash, SV *value,
2502                                     U32 flags)
2503            COPHH *  cophh_store_pvs(COPHH *cophh, "key", SV *value,
2504                                     U32 flags)
2505            COPHH *  cophh_store_sv (COPHH *cophh, SV *key, U32 hash,
2506                                     SV *value, U32 flags)
2507
2508       "cop_hints_exists_pv"
2509       "cop_hints_exists_pvn"
2510       "cop_hints_exists_pvs"
2511       "cop_hints_exists_sv"
2512           These look up the hint entry in the cop "cop" with the key
2513           specified by "key" (and "keylen" in the "pvn" form), returning true
2514           if a value exists, and false otherwise.
2515
2516           The forms differ in how the key is specified.  In all forms, the
2517           key is pointed to by "key".  In the plain "pv" form, the key is a C
2518           language NUL-terminated string.  In the "pvs" form, the key is a C
2519           language string literal.  In the "pvn" form, an additional
2520           parameter, "keylen", specifies the length of the string, which
2521           hence, may contain embedded-NUL characters.  In the "sv" form, *key
2522           is an SV, and the key is the PV extracted from that.  using
2523           "SvPV_const".
2524
2525           "hash" is a precomputed hash of the key string, or zero if it has
2526           not been precomputed.  This parameter is omitted from the "pvs"
2527           form, as it is computed automatically at compile time.
2528
2529           The only flag currently used from the "flags" parameter is
2530           "COPHH_KEY_UTF8".  It is illegal to set this in the "sv" form.  In
2531           the "pv*" forms, it specifies whether the key octets are
2532           interpreted as UTF-8 (if set) or as Latin-1 (if cleared).  The "sv"
2533           form uses the underlying SV to determine the UTF-8ness of the
2534           octets.
2535
2536            bool  cop_hints_exists_pv (const COP *cop, const char *key,
2537                                       U32 hash, U32 flags)
2538            bool  cop_hints_exists_pvn(const COP *cop, const char *key,
2539                                       STRLEN keylen, U32 hash, U32 flags)
2540            bool  cop_hints_exists_pvs(const COP *cop, "key", U32 flags)
2541            bool  cop_hints_exists_sv (const COP *cop, SV *key, U32 hash,
2542                                       U32 flags)
2543
2544       "cop_hints_fetch_pv"
2545       "cop_hints_fetch_pvn"
2546       "cop_hints_fetch_pvs"
2547       "cop_hints_fetch_sv"
2548           These look up the hint entry in the cop "cop" with the key
2549           specified by "key" (and "keylen" in the "pvn" form), returning that
2550           value as a mortal scalar copy, or &PL_sv_placeholder if there is no
2551           value associated with the key.
2552
2553           The forms differ in how the key is specified.  In the plain "pv"
2554           form, the key is a C language NUL-terminated string.  In the "pvs"
2555           form, the key is a C language string literal.  In the "pvn" form,
2556           an additional parameter, "keylen", specifies the length of the
2557           string, which hence, may contain embedded-NUL characters.  In the
2558           "sv" form, *key is an SV, and the key is the PV extracted from
2559           that.  using "SvPV_const".
2560
2561           "hash" is a precomputed hash of the key string, or zero if it has
2562           not been precomputed.  This parameter is omitted from the "pvs"
2563           form, as it is computed automatically at compile time.
2564
2565           The only flag currently used from the "flags" parameter is
2566           "COPHH_KEY_UTF8".  It is illegal to set this in the "sv" form.  In
2567           the "pv*" forms, it specifies whether the key octets are
2568           interpreted as UTF-8 (if set) or as Latin-1 (if cleared).  The "sv"
2569           form uses the underlying SV to determine the UTF-8ness of the
2570           octets.
2571
2572            SV *  cop_hints_fetch_pv (const COP *cop, const char *key,
2573                                      U32 hash, U32 flags)
2574            SV *  cop_hints_fetch_pvn(const COP *cop, const char *key,
2575                                      STRLEN keylen, U32 hash, U32 flags)
2576            SV *  cop_hints_fetch_pvs(const COP *cop, "key", U32 flags)
2577            SV *  cop_hints_fetch_sv (const COP *cop, SV *key, U32 hash,
2578                                      U32 flags)
2579
2580       "cop_hints_2hv"
2581           Generates and returns a standard Perl hash representing the full
2582           set of hint entries in the cop "cop".  "flags" is currently unused
2583           and must be zero.
2584
2585            HV *  cop_hints_2hv(const COP *cop, U32 flags)
2586
2587       "CopLABEL"
2588       "CopLABEL_len"
2589       "CopLABEL_len_flags"
2590           These return the label attached to a cop.
2591
2592           "CopLABEL_len" and "CopLABEL_len_flags" additionally store the
2593           number of bytes comprising the returned label into *len.
2594
2595           "CopLABEL_len_flags" additionally returns the UTF-8ness of the
2596           returned label, by setting *flags to 0 or "SVf_UTF8".
2597
2598            const char *  CopLABEL          (COP *const cop)
2599            const char *  CopLABEL_len      (COP *const cop, STRLEN *len)
2600            const char *  CopLABEL_len_flags(COP *const cop, STRLEN *len,
2601                                             U32 *flags)
2602
2603       "CopLINE"
2604           Returns the line number in the source code associated with the
2605           "COP" "c"
2606
2607            line_t  CopLINE(const COP * c)
2608
2609       "CopSTASH"
2610           Returns the stash associated with "c".
2611
2612            HV *  CopSTASH(const COP * c)
2613
2614       "CopSTASH_eq"
2615           Returns a boolean as to whether or not "hv" is the stash associated
2616           with "c".
2617
2618            bool  CopSTASH_eq(const COP * c, const HV * hv)
2619
2620       "CopSTASHPV"
2621           Returns the package name of the stash associated with "c", or
2622           "NULL" if no associated stash
2623
2624            char *  CopSTASHPV(const COP * c)
2625
2626       "CopSTASHPV_set"
2627           Set the package name of the stash associated with "c", to the NUL-
2628           terminated C string "p", creating the package if necessary.
2629
2630            void  CopSTASHPV_set(COP * c, const char * pv)
2631
2632       "CopSTASH_set"
2633           Set the stash associated with "c" to "hv".
2634
2635            bool  CopSTASH_set(COP * c, HV * hv)
2636
2637       "cop_store_label"
2638           NOTE: "cop_store_label" is experimental and may change or be
2639           removed without notice.
2640
2641           Save a label into a "cop_hints_hash".  You need to set flags to
2642           "SVf_UTF8" for a UTF-8 label.  Any other flag is ignored.
2643
2644            void  cop_store_label(COP * const cop, const char *label,
2645                                  STRLEN len, U32 flags)
2646
2647       "PERL_SI"
2648           Use this typedef to declare variables that are to hold "struct
2649           stackinfo".
2650
2651       "PL_curcop"
2652           The currently active COP (control op) roughly representing the
2653           current statement in the source.
2654
2655           On threaded perls, each thread has an independent copy of this
2656           variable; each initialized at creation time with the current value
2657           of the creating thread's copy.
2658
2659            COP*  PL_curcop
2660
2661       "RCPV_LEN"
2662           Returns the length of a pv created with rcpv_new().  Note that this
2663           reflects the length of the string from the callers point of view,
2664           it does not include the mandatory null which is always injected at
2665           the end of the string by rcpv_new().  No checks are performed to
2666           ensure that "pv" was actually allocated with rcpv_new(), it is the
2667           callers responsibility to ensure that this is the case.
2668
2669            RCPV *  RCPV_LEN(char *pv)
2670
2671       "RCPV_REFCNT_dec"
2672           Decrements the refcount for a "char *" pointer which was created
2673           with a call to rcpv_new(). Same as calling rcpv_free().  No checks
2674           are performed to ensure that "pv" was actually allocated with
2675           rcpv_new(), it is the callers responsibility to ensure that this is
2676           the case.
2677
2678            RCPV *  RCPV_REFCNT_dec(char *pv)
2679
2680       "RCPV_REFCNT_inc"
2681           Increments the refcount for a "char *" pointer which was created
2682           with a call to rcpv_new(). Same as calling rcpv_copy().  No checks
2683           are performed to ensure that "pv" was actually allocated with
2684           rcpv_new(), it is the callers responsibility to ensure that this is
2685           the case.
2686
2687            RCPV *  RCPV_REFCNT_inc(char *pv)
2688
2689       "RCPV_REFCOUNT"
2690           Returns the refcount for a pv created with rcpv_new().  No checks
2691           are performed to ensure that "pv" was actually allocated with
2692           rcpv_new(), it is the callers responsibility to ensure that this is
2693           the case.
2694
2695            RCPV *  RCPV_REFCOUNT(char *pv)
2696
2697       "RCPVx"
2698           Returns the RCPV structure (struct rcpv) for a refcounted string pv
2699           created with rcpv_new().  No checks are performed to ensure that
2700           "pv" was actually allocated with rcpv_new(), it is the callers
2701           responsibility to ensure that this is the case.
2702
2703            RCPV *  RCPVx(char *pv)
2704

Custom Operators

2706       "custom_op_register"
2707           Register a custom op.  See "Custom Operators" in perlguts.
2708
2709           NOTE: "custom_op_register" must be explicitly called as
2710           "Perl_custom_op_register" with an "aTHX_" parameter.
2711
2712            void  Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr,
2713                                          const XOP *xop)
2714
2715       "Perl_custom_op_xop"
2716           Return the XOP structure for a given custom op.  This macro should
2717           be considered internal to "OP_NAME" and the other access macros:
2718           use them instead.  This macro does call a function.  Prior to
2719           5.19.6, this was implemented as a function.
2720
2721            const XOP *  Perl_custom_op_xop(pTHX_ const OP *o)
2722
2723       "XopDISABLE"
2724           Temporarily disable a member of the XOP, by clearing the
2725           appropriate flag.
2726
2727            void  XopDISABLE(XOP *xop, token which)
2728
2729       "XopENABLE"
2730           Reenable a member of the XOP which has been disabled.
2731
2732            void  XopENABLE(XOP *xop, token which)
2733
2734       "XopENTRY"
2735           Return a member of the XOP structure.  "which" is a cpp token
2736           indicating which entry to return.  If the member is not set this
2737           will return a default value.  The return type depends on "which".
2738           This macro evaluates its arguments more than once.  If you are
2739           using "Perl_custom_op_xop" to retrieve a "XOP *" from a "OP *", use
2740           the more efficient "XopENTRYCUSTOM" instead.
2741
2742              XopENTRY(XOP *xop, token which)
2743
2744       "XopENTRYCUSTOM"
2745           Exactly like "XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o),
2746           which)" but more efficient.  The "which" parameter is identical to
2747           "XopENTRY".
2748
2749              XopENTRYCUSTOM(const OP *o, token which)
2750
2751       "XopENTRY_set"
2752           Set a member of the XOP structure.  "which" is a cpp token
2753           indicating which entry to set.  See "Custom Operators" in perlguts
2754           for details about the available members and how they are used.
2755           This macro evaluates its argument more than once.
2756
2757            void  XopENTRY_set(XOP *xop, token which, value)
2758
2759       "XopFLAGS"
2760           Return the XOP's flags.
2761
2762            U32  XopFLAGS(XOP *xop)
2763

CV Handling

2765       This section documents functions to manipulate CVs which are code-
2766       values, meaning subroutines.  For more information, see perlguts.
2767
2768       "caller_cx"
2769           The XSUB-writer's equivalent of caller().  The returned
2770           "PERL_CONTEXT" structure can be interrogated to find all the
2771           information returned to Perl by "caller".  Note that XSUBs don't
2772           get a stack frame, so "caller_cx(0, NULL)" will return information
2773           for the immediately-surrounding Perl code.
2774
2775           This function skips over the automatic calls to &DB::sub made on
2776           the behalf of the debugger.  If the stack frame requested was a sub
2777           called by "DB::sub", the return value will be the frame for the
2778           call to "DB::sub", since that has the correct line number/etc. for
2779           the call site.  If dbcxp is non-"NULL", it will be set to a pointer
2780           to the frame for the sub call itself.
2781
2782            const PERL_CONTEXT *  caller_cx(I32 level,
2783                                            const PERL_CONTEXT **dbcxp)
2784
2785       "CvDEPTH"
2786           Returns the recursion level of the CV "sv".  Hence >= 2 indicates
2787           we are in a recursive call.
2788
2789            I32 *  CvDEPTH(const CV * const sv)
2790
2791       "CvGV"
2792           Returns the GV associated with the CV "sv", reifying it if
2793           necessary.
2794
2795            GV *  CvGV(CV *sv)
2796
2797       "CvSTASH"
2798           Returns the stash of the CV.  A stash is the symbol table hash,
2799           containing the package-scoped variables in the package where the
2800           subroutine was defined.  For more information, see perlguts.
2801
2802           This also has a special use with XS AUTOLOAD subs.  See
2803           "Autoloading with XSUBs" in perlguts.
2804
2805            HV*  CvSTASH(CV* cv)
2806
2807       "find_runcv"
2808           Locate the CV corresponding to the currently executing sub or eval.
2809           If "db_seqp" is non_null, skip CVs that are in the DB package and
2810           populate *db_seqp with the cop sequence number at the point that
2811           the DB:: code was entered.  (This allows debuggers to eval in the
2812           scope of the breakpoint rather than in the scope of the debugger
2813           itself.)
2814
2815            CV *  find_runcv(U32 *db_seqp)
2816
2817       "get_cv"
2818       "get_cvn_flags"
2819       "get_cvs"
2820           These return the CV of the specified Perl subroutine.  "flags" are
2821           passed to "gv_fetchpvn_flags".  If "GV_ADD" is set and the Perl
2822           subroutine does not exist then it will be declared (which has the
2823           same effect as saying "sub name;").  If "GV_ADD" is not set and the
2824           subroutine does not exist, then NULL is returned.
2825
2826           The forms differ only in how the subroutine is specified..  With
2827           "get_cvs", the name is a literal C string, enclosed in double
2828           quotes.  With "get_cv", the name is given by the "name" parameter,
2829           which must be a NUL-terminated C string.  With "get_cvn_flags", the
2830           name is also given by the "name" parameter, but it is a Perl string
2831           (possibly containing embedded NUL bytes), and its length in bytes
2832           is contained in the "len" parameter.
2833
2834           NOTE: the perl_get_cv() form is deprecated.
2835
2836           NOTE: the perl_get_cvn_flags() form is deprecated.
2837
2838           NOTE: the perl_get_cvs() form is deprecated.
2839
2840            CV *  get_cv       (const char *name, I32 flags)
2841            CV *  get_cvn_flags(const char *name, STRLEN len, I32 flags)
2842            CV *  get_cvs      ("string", I32 flags)
2843
2844       "Nullcv"
2845           "DEPRECATED!"  It is planned to remove "Nullcv" from a future
2846           release of Perl.  Do not use it for new code; remove it from
2847           existing code.
2848
2849           Null CV pointer.
2850
2851           (deprecated - use "(CV *)NULL" instead)
2852

Debugging

2854       "av_dump"
2855           Dumps the contents of an AV to the "STDERR" filehandle, Similar to
2856           using Devel::Peek on an arrayref but does not expect an RV wrapper.
2857           Dumps contents to a depth of 3 levels deep.
2858
2859            void  av_dump(AV *av)
2860
2861       "deb"
2862       "deb_nocontext"
2863           When perl is compiled with "-DDEBUGGING", this prints to STDERR the
2864           information given by the arguments, prefaced by the name of the
2865           file containing the script causing the call, and the line number
2866           within that file.
2867
2868           If the "v" (verbose) debugging option is in effect, the process id
2869           is also printed.
2870
2871           The two forms differ only in that "deb_nocontext" does not take a
2872           thread context ("aTHX") parameter, so is used in situations where
2873           the caller doesn't already have the thread context.
2874
2875           NOTE: "deb" must be explicitly called as "Perl_deb" with an "aTHX_"
2876           parameter.
2877
2878            void  Perl_deb     (pTHX_ const char *pat, ...)
2879            void  deb_nocontext(const char *pat, ...)
2880
2881       "debstack"
2882           Dump the current stack
2883
2884            I32  debstack()
2885
2886       "dump_all"
2887           Dumps the entire optree of the current program starting at
2888           "PL_main_root" to "STDERR".  Also dumps the optrees for all visible
2889           subroutines in "PL_defstash".
2890
2891            void  dump_all()
2892
2893       "dump_c_backtrace"
2894           Dumps the C backtrace to the given "fp".
2895
2896           Returns true if a backtrace could be retrieved, false if not.
2897
2898            bool  dump_c_backtrace(PerlIO *fp, int max_depth, int skip)
2899
2900       "dump_eval"
2901           Described in perlguts.
2902
2903            void  dump_eval()
2904
2905       "dump_form"
2906           Dumps the contents of the format contained in the GV "gv" to
2907           "STDERR", or a message that one doesn't exist.
2908
2909            void  dump_form(const GV *gv)
2910
2911       "dump_packsubs"
2912           Dumps the optrees for all visible subroutines in "stash".
2913
2914            void  dump_packsubs(const HV *stash)
2915
2916       "dump_sub"
2917           Described in perlguts.
2918
2919            void  dump_sub(const GV *gv)
2920
2921       "get_c_backtrace_dump"
2922           Returns a SV containing a dump of "depth" frames of the call stack,
2923           skipping the "skip" innermost ones.  "depth" of 20 is usually
2924           enough.
2925
2926           The appended output looks like:
2927
2928            ...
2929            1   10e004812:0082   Perl_croak   util.c:1716    /usr/bin/perl
2930            2   10df8d6d2:1d72   perl_parse   perl.c:3975    /usr/bin/perl
2931            ...
2932
2933           The fields are tab-separated.  The first column is the depth (zero
2934           being the innermost non-skipped frame).  In the hex:offset, the hex
2935           is where the program counter was in "S_parse_body", and the :offset
2936           (might be missing) tells how much inside the "S_parse_body" the
2937           program counter was.
2938
2939           The "util.c:1716" is the source code file and line number.
2940
2941           The /usr/bin/perl is obvious (hopefully).
2942
2943           Unknowns are "-".  Unknowns can happen unfortunately quite easily:
2944           if the platform doesn't support retrieving the information; if the
2945           binary is missing the debug information; if the optimizer has
2946           transformed the code by for example inlining.
2947
2948            SV *  get_c_backtrace_dump(int max_depth, int skip)
2949
2950       "gv_dump"
2951           Dump the name and, if they differ, the effective name of the GV
2952           "gv" to "STDERR".
2953
2954            void  gv_dump(GV *gv)
2955
2956       "HAS_BACKTRACE"
2957           This symbol, if defined, indicates that the backtrace() routine is
2958           available to get a stack trace.  The execinfo.h header must be
2959           included to use this routine.
2960
2961       "hv_dump"
2962           Dumps the contents of an HV to the "STDERR" filehandle.  Similar to
2963           using Devel::Peek on an hashref but does not expect an RV wrapper.
2964           Dumps contents to a depth of 3 levels deep.
2965
2966            void  hv_dump(HV *hv)
2967
2968       "magic_dump"
2969           Dumps the contents of the MAGIC "mg" to "STDERR".
2970
2971            void  magic_dump(const MAGIC *mg)
2972
2973       "op_class"
2974           Given an op, determine what type of struct it has been allocated
2975           as.  Returns one of the OPclass enums, such as OPclass_LISTOP.
2976
2977            OPclass  op_class(const OP *o)
2978
2979       "op_dump"
2980           Dumps the optree starting at OP "o" to "STDERR".
2981
2982            void  op_dump(const OP *o)
2983
2984       "PL_op"
2985           Described in perlhacktips.
2986
2987       "PL_runops"
2988           Described in perlguts.
2989
2990       "PL_sv_serial"
2991           Described in perlhacktips.
2992
2993       "pmop_dump"
2994           Dump an OP that is related to Pattern Matching, such as
2995           "s/foo/bar/"; these require special handling.
2996
2997            void  pmop_dump(PMOP *pm)
2998
2999       "sv_dump"
3000           Dumps the contents of an SV to the "STDERR" filehandle.
3001
3002           For an example of its output, see Devel::Peek. If the item is an
3003           SvROK it will dump items to a depth of 4, otherwise it will dump
3004           only the top level item, which means that it will not dump the
3005           contents of an AV * or HV *. For that use av_dump() or hv_dump().
3006
3007            void  sv_dump(SV *sv)
3008
3009       "sv_dump_depth"
3010           Dumps the contents of an SV to the "STDERR" filehandle to the depth
3011           requested. This function can be used on any SV derived type (GV,
3012           HV, AV) with an appropriate cast.  This is a more flexible variant
3013           of sv_dump(). For example
3014
3015               HV *hv = ...;
3016               sv_dump_depth((SV*)hv, 2);
3017
3018           would dump the hv, its keys and values, but would not recurse into
3019           any RV values.
3020
3021            void  sv_dump_depth(SV *sv, I32 depth)
3022
3023       "vdeb"
3024           This is like "deb", but "args" are an encapsulated argument list.
3025
3026            void  vdeb(const char *pat, va_list *args)
3027

Display functions

3029       "form"
3030       "form_nocontext"
3031           These take a sprintf-style format pattern and conventional (non-SV)
3032           arguments and return the formatted string.
3033
3034               (char *) Perl_form(pTHX_ const char* pat, ...)
3035
3036           can be used any place a string (char *) is required:
3037
3038               char * s = Perl_form("%d.%d",major,minor);
3039
3040           They use a single (per-thread) private buffer so if you want to
3041           format several strings you must explicitly copy the earlier strings
3042           away (and free the copies when you are done).
3043
3044           The two forms differ only in that "form_nocontext" does not take a
3045           thread context ("aTHX") parameter, so is used in situations where
3046           the caller doesn't already have the thread context.
3047
3048           NOTE: "form" must be explicitly called as "Perl_form" with an
3049           "aTHX_" parameter.
3050
3051            char *  Perl_form     (pTHX_ const char *pat, ...)
3052            char *  form_nocontext(const char *pat, ...)
3053
3054       "mess"
3055       "mess_nocontext"
3056           These take a sprintf-style format pattern and argument list, which
3057           are used to generate a string message.  If the message does not end
3058           with a newline, then it will be extended with some indication of
3059           the current location in the code, as described for "mess_sv".
3060
3061           Normally, the resulting message is returned in a new mortal SV.
3062           But during global destruction a single SV may be shared between
3063           uses of this function.
3064
3065           The two forms differ only in that "mess_nocontext" does not take a
3066           thread context ("aTHX") parameter, so is used in situations where
3067           the caller doesn't already have the thread context.
3068
3069           NOTE: "mess" must be explicitly called as "Perl_mess" with an
3070           "aTHX_" parameter.
3071
3072            SV *  Perl_mess     (pTHX_ const char *pat, ...)
3073            SV *  mess_nocontext(const char *pat, ...)
3074
3075       "mess_sv"
3076           Expands a message, intended for the user, to include an indication
3077           of the current location in the code, if the message does not
3078           already appear to be complete.
3079
3080           "basemsg" is the initial message or object.  If it is a reference,
3081           it will be used as-is and will be the result of this function.
3082           Otherwise it is used as a string, and if it already ends with a
3083           newline, it is taken to be complete, and the result of this
3084           function will be the same string.  If the message does not end with
3085           a newline, then a segment such as "at foo.pl line 37" will be
3086           appended, and possibly other clauses indicating the current state
3087           of execution.  The resulting message will end with a dot and a
3088           newline.
3089
3090           Normally, the resulting message is returned in a new mortal SV.
3091           During global destruction a single SV may be shared between uses of
3092           this function.  If "consume" is true, then the function is
3093           permitted (but not required) to modify and return "basemsg" instead
3094           of allocating a new SV.
3095
3096            SV *  mess_sv(SV *basemsg, bool consume)
3097
3098       "pv_display"
3099           Similar to
3100
3101             pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
3102
3103           except that an additional "\0" will be appended to the string when
3104           len > cur and pv[cur] is "\0".
3105
3106           Note that the final string may be up to 7 chars longer than pvlim.
3107
3108            char *  pv_display(SV *dsv, const char *pv, STRLEN cur,
3109                               STRLEN len, STRLEN pvlim)
3110
3111       "pv_escape"
3112           Escapes at most the first "count" chars of "pv" and puts the
3113           results into "dsv" such that the size of the escaped string will
3114           not exceed "max" chars and will not contain any incomplete escape
3115           sequences.  The number of bytes escaped will be returned in the
3116           "STRLEN *escaped" parameter if it is not null.  When the "dsv"
3117           parameter is null no escaping actually occurs, but the number of
3118           bytes that would be escaped were it not null will be calculated.
3119
3120           If flags contains "PERL_PV_ESCAPE_QUOTE" then any double quotes in
3121           the string will also be escaped.
3122
3123           Normally the SV will be cleared before the escaped string is
3124           prepared, but when "PERL_PV_ESCAPE_NOCLEAR" is set this will not
3125           occur.
3126
3127           If "PERL_PV_ESCAPE_UNI" is set then the input string is treated as
3128           UTF-8.  If "PERL_PV_ESCAPE_UNI_DETECT" is set then the input string
3129           is scanned using is_utf8_string() to determine if it is UTF-8.
3130
3131           If "PERL_PV_ESCAPE_ALL" is set then all input chars will be output
3132           using "\x01F1" style escapes, otherwise if
3133           "PERL_PV_ESCAPE_NONASCII" is set, only non-ASCII chars will be
3134           escaped using this style; otherwise, only chars above 255 will be
3135           so escaped; other non printable chars will use octal or common
3136           escaped patterns like "\n". Otherwise, if
3137           "PERL_PV_ESCAPE_NOBACKSLASH" then all chars below 255 will be
3138           treated as printable and will be output as literals. The
3139           "PERL_PV_ESCAPE_NON_WC" modifies the previous rules to cause word
3140           chars, unicode or otherwise, to be output as literals, note this
3141           uses the *unicode* rules for deciding on word characters.
3142
3143           If "PERL_PV_ESCAPE_FIRSTCHAR" is set then only the first char of
3144           the string will be escaped, regardless of max. If the output is to
3145           be in hex, then it will be returned as a plain hex sequence. Thus
3146           the output will either be a single char, an octal escape sequence,
3147           a special escape like "\n" or a hex value.
3148
3149           If "PERL_PV_ESCAPE_RE" is set then the escape char used will be a
3150           "%" and not a "\\". This is because regexes very often contain
3151           backslashed sequences, whereas "%" is not a particularly common
3152           character in patterns.
3153
3154           Returns a pointer to the escaped text as held by "dsv".
3155
3156            char *  pv_escape(SV *dsv, char const * const str,
3157                              const STRLEN count, STRLEN max,
3158                              STRLEN * const escaped, U32 flags)
3159
3160       "pv_pretty"
3161           Converts a string into something presentable, handling escaping via
3162           pv_escape() and supporting quoting and ellipses.
3163
3164           If the "PERL_PV_PRETTY_QUOTE" flag is set then the result will be
3165           double quoted with any double quotes in the string escaped.
3166           Otherwise if the "PERL_PV_PRETTY_LTGT" flag is set then the result
3167           be wrapped in angle brackets.
3168
3169           If the "PERL_PV_PRETTY_ELLIPSES" flag is set and not all characters
3170           in string were output then an ellipsis "..." will be appended to
3171           the string.  Note that this happens AFTER it has been quoted.
3172
3173           If "start_color" is non-null then it will be inserted after the
3174           opening quote (if there is one) but before the escaped text.  If
3175           "end_color" is non-null then it will be inserted after the escaped
3176           text but before any quotes or ellipses.
3177
3178           Returns a pointer to the prettified text as held by "dsv".
3179
3180            char *  pv_pretty(SV *dsv, char const * const str,
3181                              const STRLEN count, const STRLEN max,
3182                              char const * const start_color,
3183                              char const * const end_color, const U32 flags)
3184
3185       "vform"
3186           Like "form" but but the arguments are an encapsulated argument
3187           list.
3188
3189            char *  vform(const char *pat, va_list *args)
3190
3191       "vmess"
3192           "pat" and "args" are a sprintf-style format pattern and
3193           encapsulated argument list, respectively.  These are used to
3194           generate a string message.  If the message does not end with a
3195           newline, then it will be extended with some indication of the
3196           current location in the code, as described for "mess_sv".
3197
3198           Normally, the resulting message is returned in a new mortal SV.
3199           During global destruction a single SV may be shared between uses of
3200           this function.
3201
3202            SV *  vmess(const char *pat, va_list *args)
3203

Embedding, Threads, and Interpreter Cloning

3205       "call_atexit"
3206           Add a function "fn" to the list of functions to be called at global
3207           destruction.  "ptr" will be passed as an argument to "fn"; it can
3208           point to a "struct" so that you can pass anything you want.
3209
3210           Note that under threads, "fn" may run multiple times.  This is
3211           because the list is executed each time the current or any
3212           descendent thread terminates.
3213
3214            void  call_atexit(ATEXIT_t fn, void *ptr)
3215
3216       "cv_clone"
3217           Clone a CV, making a lexical closure.  "proto" supplies the
3218           prototype of the function: its code, pad structure, and other
3219           attributes.  The prototype is combined with a capture of outer
3220           lexicals to which the code refers, which are taken from the
3221           currently-executing instance of the immediately surrounding code.
3222
3223            CV *  cv_clone(CV *proto)
3224
3225       "cv_name"
3226           Returns an SV containing the name of the CV, mainly for use in
3227           error reporting.  The CV may actually be a GV instead, in which
3228           case the returned SV holds the GV's name.  Anything other than a GV
3229           or CV is treated as a string already holding the sub name, but this
3230           could change in the future.
3231
3232           An SV may be passed as a second argument.  If so, the name will be
3233           assigned to it and it will be returned.  Otherwise the returned SV
3234           will be a new mortal.
3235
3236           If "flags" has the "CV_NAME_NOTQUAL" bit set, then the package name
3237           will not be included.  If the first argument is neither a CV nor a
3238           GV, this flag is ignored (subject to change).
3239
3240            SV *  cv_name(CV *cv, SV *sv, U32 flags)
3241
3242       "cv_undef"
3243           Clear out all the active components of a CV.  This can happen
3244           either by an explicit "undef &foo", or by the reference count going
3245           to zero.  In the former case, we keep the "CvOUTSIDE" pointer, so
3246           that any anonymous children can still follow the full lexical scope
3247           chain.
3248
3249            void  cv_undef(CV *cv)
3250
3251       "find_rundefsv"
3252           Returns the global variable $_.
3253
3254            SV *  find_rundefsv()
3255
3256       "get_op_descs"
3257           "DEPRECATED!"  It is planned to remove "get_op_descs" from a future
3258           release of Perl.  Do not use it for new code; remove it from
3259           existing code.
3260
3261           Return a pointer to the array of all the descriptions of the
3262           various OPs Given an opcode from the enum in opcodes.h,
3263           "PL_op_desc[opcode]" returns a pointer to a C language string
3264           giving its description.
3265
3266            char **  get_op_descs()
3267
3268       "get_op_names"
3269           "DEPRECATED!"  It is planned to remove "get_op_names" from a future
3270           release of Perl.  Do not use it for new code; remove it from
3271           existing code.
3272
3273           Return a pointer to the array of all the names of the various OPs
3274           Given an opcode from the enum in opcodes.h, "PL_op_name[opcode]"
3275           returns a pointer to a C language string giving its name.
3276
3277            char **  get_op_names()
3278
3279       "HAS_SKIP_LOCALE_INIT"
3280           Described in perlembed.
3281
3282       "intro_my"
3283           "Introduce" "my" variables to visible status.  This is called
3284           during parsing at the end of each statement to make lexical
3285           variables visible to subsequent statements.
3286
3287            U32  intro_my()
3288
3289       "load_module"
3290       "load_module_nocontext"
3291           These load the module whose name is pointed to by the string part
3292           of "name".  Note that the actual module name, not its filename,
3293           should be given.  Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver, if
3294           specified and not NULL, provides version semantics similar to "use
3295           Foo::Bar VERSION". The optional trailing arguments can be used to
3296           specify arguments to the module's import() method, similar to "use
3297           Foo::Bar VERSION LIST"; their precise handling depends on the
3298           flags. The flags argument is a bitwise-ORed collection of any of
3299           "PERL_LOADMOD_DENY", "PERL_LOADMOD_NOIMPORT", or
3300           "PERL_LOADMOD_IMPORT_OPS" (or 0 for no flags).
3301
3302           If "PERL_LOADMOD_NOIMPORT" is set, the module is loaded as if with
3303           an empty import list, as in "use Foo::Bar ()"; this is the only
3304           circumstance in which the trailing optional arguments may be
3305           omitted entirely. Otherwise, if "PERL_LOADMOD_IMPORT_OPS" is set,
3306           the trailing arguments must consist of exactly one "OP*",
3307           containing the op tree that produces the relevant import arguments.
3308           Otherwise, the trailing arguments must all be "SV*" values that
3309           will be used as import arguments; and the list must be terminated
3310           with "(SV*) NULL". If neither "PERL_LOADMOD_NOIMPORT" nor
3311           "PERL_LOADMOD_IMPORT_OPS" is set, the trailing "NULL" pointer is
3312           needed even if no import arguments are desired. The reference count
3313           for each specified "SV*" argument is decremented. In addition, the
3314           "name" argument is modified.
3315
3316           If "PERL_LOADMOD_DENY" is set, the module is loaded as if with "no"
3317           rather than "use".
3318
3319           "load_module" and "load_module_nocontext" have the same apparent
3320           signature, but the former hides the fact that it is accessing a
3321           thread context parameter.  So use the latter when you get a
3322           compilation error about "pTHX".
3323
3324            void  load_module          (U32 flags, SV *name, SV *ver, ...)
3325            void  load_module_nocontext(U32 flags, SV *name, SV *ver, ...)
3326
3327       "my_exit"
3328           A wrapper for the C library exit(3), honoring what "PL_exit_flags"
3329           in perlapi say to do.
3330
3331            void  my_exit(U32 status)
3332
3333       "my_failure_exit"
3334           Exit the running Perl process with an error.
3335
3336           On non-VMS platforms, this is essentially equivalent to
3337           ""my_exit"", using "errno", but forces an en error code of 255 if
3338           "errno" is 0.
3339
3340           On VMS, it takes care to set the appropriate severity bits in the
3341           exit status.
3342
3343            void  my_failure_exit()
3344
3345       "my_strlcat"
3346           The C library "strlcat" if available, or a Perl implementation of
3347           it.  This operates on C "NUL"-terminated strings.
3348
3349           my_strlcat() appends string "src" to the end of "dst".  It will
3350           append at most "size - strlen(dst) - 1" characters.  It will then
3351           "NUL"-terminate, unless "size" is 0 or the original "dst" string
3352           was longer than "size" (in practice this should not happen as it
3353           means that either "size" is incorrect or that "dst" is not a proper
3354           "NUL"-terminated string).
3355
3356           Note that "size" is the full size of the destination buffer and the
3357           result is guaranteed to be "NUL"-terminated if there is room.  Note
3358           that room for the "NUL" should be included in "size".
3359
3360           The return value is the total length that "dst" would have if
3361           "size" is sufficiently large.  Thus it is the initial length of
3362           "dst" plus the length of "src".  If "size" is smaller than the
3363           return, the excess was not appended.
3364
3365            Size_t  my_strlcat(char *dst, const char *src, Size_t size)
3366
3367       "my_strlcpy"
3368           The C library "strlcpy" if available, or a Perl implementation of
3369           it.  This operates on C "NUL"-terminated strings.
3370
3371           my_strlcpy() copies up to "size - 1" characters from the string
3372           "src" to "dst", "NUL"-terminating the result if "size" is not 0.
3373
3374           The return value is the total length "src" would be if the copy
3375           completely succeeded.  If it is larger than "size", the excess was
3376           not copied.
3377
3378            Size_t  my_strlcpy(char *dst, const char *src, Size_t size)
3379
3380       "newPADNAMELIST"
3381           NOTE: "newPADNAMELIST" is experimental and may change or be removed
3382           without notice.
3383
3384           Creates a new pad name list.  "max" is the highest index for which
3385           space is allocated.
3386
3387            PADNAMELIST *  newPADNAMELIST(size_t max)
3388
3389       "newPADNAMEouter"
3390           NOTE: "newPADNAMEouter" is experimental and may change or be
3391           removed without notice.
3392
3393           Constructs and returns a new pad name.  Only use this function for
3394           names that refer to outer lexicals.  (See also "newPADNAMEpvn".)
3395           "outer" is the outer pad name that this one mirrors.  The returned
3396           pad name has the "PADNAMEf_OUTER" flag already set.
3397
3398            PADNAME *  newPADNAMEouter(PADNAME *outer)
3399
3400       "newPADNAMEpvn"
3401           NOTE: "newPADNAMEpvn" is experimental and may change or be removed
3402           without notice.
3403
3404           Constructs and returns a new pad name.  "s" must be a UTF-8 string.
3405           Do not use this for pad names that point to outer lexicals.  See
3406           "newPADNAMEouter".
3407
3408            PADNAME *  newPADNAMEpvn(const char *s, STRLEN len)
3409
3410       "nothreadhook"
3411           Stub that provides thread hook for perl_destruct when there are no
3412           threads.
3413
3414            int  nothreadhook()
3415
3416       "pad_add_anon"
3417           Allocates a place in the currently-compiling pad (via "pad_alloc")
3418           for an anonymous function that is lexically scoped inside the
3419           currently-compiling function.  The function "func" is linked into
3420           the pad, and its "CvOUTSIDE" link to the outer scope is weakened to
3421           avoid a reference loop.
3422
3423           One reference count is stolen, so you may need to do
3424           SvREFCNT_inc(func).
3425
3426           "optype" should be an opcode indicating the type of operation that
3427           the pad entry is to support.  This doesn't affect operational
3428           semantics, but is used for debugging.
3429
3430            PADOFFSET  pad_add_anon(CV *func, I32 optype)
3431
3432       "pad_add_name_pv"
3433           Exactly like "pad_add_name_pvn", but takes a nul-terminated string
3434           instead of a string/length pair.
3435
3436            PADOFFSET  pad_add_name_pv(const char *name, const U32 flags,
3437                                       HV *typestash, HV *ourstash)
3438
3439       "pad_add_name_pvn"
3440           Allocates a place in the currently-compiling pad for a named
3441           lexical variable.  Stores the name and other metadata in the name
3442           part of the pad, and makes preparations to manage the variable's
3443           lexical scoping.  Returns the offset of the allocated pad slot.
3444
3445           "namepv"/"namelen" specify the variable's name, including leading
3446           sigil.  If "typestash" is non-null, the name is for a typed
3447           lexical, and this identifies the type.  If "ourstash" is non-null,
3448           it's a lexical reference to a package variable, and this identifies
3449           the package.  The following flags can be OR'ed together:
3450
3451            padadd_OUR          redundantly specifies if it's a package var
3452            padadd_STATE        variable will retain value persistently
3453            padadd_NO_DUP_CHECK skip check for lexical shadowing
3454            padadd_FIELD        specifies that the lexical is a field for a class
3455
3456            PADOFFSET  pad_add_name_pvn(const char *namepv, STRLEN namelen,
3457                                        U32 flags, HV *typestash,
3458                                        HV *ourstash)
3459
3460       "pad_add_name_sv"
3461           Exactly like "pad_add_name_pvn", but takes the name string in the
3462           form of an SV instead of a string/length pair.
3463
3464            PADOFFSET  pad_add_name_sv(SV *name, U32 flags, HV *typestash,
3465                                       HV *ourstash)
3466
3467       "pad_alloc"
3468           NOTE: "pad_alloc" is experimental and may change or be removed
3469           without notice.
3470
3471           Allocates a place in the currently-compiling pad, returning the
3472           offset of the allocated pad slot.  No name is initially attached to
3473           the pad slot.  "tmptype" is a set of flags indicating the kind of
3474           pad entry required, which will be set in the value SV for the
3475           allocated pad entry:
3476
3477               SVs_PADMY    named lexical variable ("my", "our", "state")
3478               SVs_PADTMP   unnamed temporary store
3479               SVf_READONLY constant shared between recursion levels
3480
3481           "SVf_READONLY" has been supported here only since perl 5.20.  To
3482           work with earlier versions as well, use "SVf_READONLY|SVs_PADTMP".
3483           "SVf_READONLY" does not cause the SV in the pad slot to be marked
3484           read-only, but simply tells "pad_alloc" that it will be made read-
3485           only (by the caller), or at least should be treated as such.
3486
3487           "optype" should be an opcode indicating the type of operation that
3488           the pad entry is to support.  This doesn't affect operational
3489           semantics, but is used for debugging.
3490
3491            PADOFFSET  pad_alloc(I32 optype, U32 tmptype)
3492
3493       "pad_findmy_pv"
3494           Exactly like "pad_findmy_pvn", but takes a nul-terminated string
3495           instead of a string/length pair.
3496
3497            PADOFFSET  pad_findmy_pv(const char *name, U32 flags)
3498
3499       "pad_findmy_pvn"
3500           Given the name of a lexical variable, find its position in the
3501           currently-compiling pad.  "namepv"/"namelen" specify the variable's
3502           name, including leading sigil.  "flags" is reserved and must be
3503           zero.  If it is not in the current pad but appears in the pad of
3504           any lexically enclosing scope, then a pseudo-entry for it is added
3505           in the current pad.  Returns the offset in the current pad, or
3506           "NOT_IN_PAD" if no such lexical is in scope.
3507
3508            PADOFFSET  pad_findmy_pvn(const char *namepv, STRLEN namelen,
3509                                      U32 flags)
3510
3511       "pad_findmy_sv"
3512           Exactly like "pad_findmy_pvn", but takes the name string in the
3513           form of an SV instead of a string/length pair.
3514
3515            PADOFFSET  pad_findmy_sv(SV *name, U32 flags)
3516
3517       "padnamelist_fetch"
3518           NOTE: "padnamelist_fetch" is experimental and may change or be
3519           removed without notice.
3520
3521           Fetches the pad name from the given index.
3522
3523            PADNAME *  padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
3524
3525       "padnamelist_store"
3526           NOTE: "padnamelist_store" is experimental and may change or be
3527           removed without notice.
3528
3529           Stores the pad name (which may be null) at the given index, freeing
3530           any existing pad name in that slot.
3531
3532            PADNAME **  padnamelist_store(PADNAMELIST *pnl, SSize_t key,
3533                                          PADNAME *val)
3534
3535       "pad_tidy"
3536           NOTE: "pad_tidy" is experimental and may change or be removed
3537           without notice.
3538
3539           Tidy up a pad at the end of compilation of the code to which it
3540           belongs.  Jobs performed here are: remove most stuff from the pads
3541           of anonsub prototypes; give it a @_; mark temporaries as such.
3542           "type" indicates the kind of subroutine:
3543
3544               padtidy_SUB        ordinary subroutine
3545               padtidy_SUBCLONE   prototype for lexical closure
3546               padtidy_FORMAT     format
3547
3548            void  pad_tidy(padtidy_type type)
3549
3550       "perl_alloc"
3551           Allocates a new Perl interpreter.  See perlembed.
3552
3553            PerlInterpreter *  perl_alloc()
3554
3555       "PERL_ASYNC_CHECK"
3556           Described in perlinterp.
3557
3558            void  PERL_ASYNC_CHECK()
3559
3560       "perl_clone"
3561           Create and return a new interpreter by cloning the current one.
3562
3563           "perl_clone" takes these flags as parameters:
3564
3565           "CLONEf_COPY_STACKS" - is used to, well, copy the stacks also,
3566           without it we only clone the data and zero the stacks, with it we
3567           copy the stacks and the new perl interpreter is ready to run at the
3568           exact same point as the previous one.  The pseudo-fork code uses
3569           "COPY_STACKS" while the threads->create doesn't.
3570
3571           "CLONEf_KEEP_PTR_TABLE" - "perl_clone" keeps a ptr_table with the
3572           pointer of the old variable as a key and the new variable as a
3573           value, this allows it to check if something has been cloned and not
3574           clone it again, but rather just use the value and increase the
3575           refcount.  If "KEEP_PTR_TABLE" is not set then "perl_clone" will
3576           kill the ptr_table using the function
3577           "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;".  A reason to
3578           keep it around is if you want to dup some of your own variables
3579           which are outside the graph that perl scans.
3580
3581           "CLONEf_CLONE_HOST" - This is a win32 thing, it is ignored on unix,
3582           it tells perl's win32host code (which is c++) to clone itself, this
3583           is needed on win32 if you want to run two threads at the same time,
3584           if you just want to do some stuff in a separate perl interpreter
3585           and then throw it away and return to the original one, you don't
3586           need to do anything.
3587
3588            PerlInterpreter *  perl_clone(PerlInterpreter *proto_perl,
3589                                          UV flags)
3590
3591       "perl_construct"
3592           Initializes a new Perl interpreter.  See perlembed.
3593
3594            void  perl_construct(PerlInterpreter *my_perl)
3595
3596       "perl_destruct"
3597           Shuts down a Perl interpreter.  See perlembed for a tutorial.
3598
3599           "my_perl" points to the Perl interpreter.  It must have been
3600           previously created through the use of "perl_alloc" and
3601           "perl_construct".  It may have been initialised through
3602           "perl_parse", and may have been used through "perl_run" and other
3603           means.  This function should be called for any Perl interpreter
3604           that has been constructed with "perl_construct", even if subsequent
3605           operations on it failed, for example if "perl_parse" returned a
3606           non-zero value.
3607
3608           If the interpreter's "PL_exit_flags" word has the
3609           "PERL_EXIT_DESTRUCT_END" flag set, then this function will execute
3610           code in "END" blocks before performing the rest of destruction.  If
3611           it is desired to make any use of the interpreter between
3612           "perl_parse" and "perl_destruct" other than just calling
3613           "perl_run", then this flag should be set early on.  This matters if
3614           "perl_run" will not be called, or if anything else will be done in
3615           addition to calling "perl_run".
3616
3617           Returns a value be a suitable value to pass to the C library
3618           function "exit" (or to return from "main"), to serve as an exit
3619           code indicating the nature of the way the interpreter terminated.
3620           This takes into account any failure of "perl_parse" and any early
3621           exit from "perl_run".  The exit code is of the type required by the
3622           host operating system, so because of differing exit code
3623           conventions it is not portable to interpret specific numeric values
3624           as having specific meanings.
3625
3626            int  perl_destruct(PerlInterpreter *my_perl)
3627
3628       "perl_free"
3629           Releases a Perl interpreter.  See perlembed.
3630
3631            void  perl_free(PerlInterpreter *my_perl)
3632
3633       "PERL_GET_CONTEXT"
3634           Described in perlguts.
3635
3636       "PerlInterpreter"
3637           Described in perlembed.
3638
3639       "perl_parse"
3640           Tells a Perl interpreter to parse a Perl script.  This performs
3641           most of the initialisation of a Perl interpreter.  See perlembed
3642           for a tutorial.
3643
3644           "my_perl" points to the Perl interpreter that is to parse the
3645           script.  It must have been previously created through the use of
3646           "perl_alloc" and "perl_construct".  "xsinit" points to a callback
3647           function that will be called to set up the ability for this Perl
3648           interpreter to load XS extensions, or may be null to perform no
3649           such setup.
3650
3651           "argc" and "argv" supply a set of command-line arguments to the
3652           Perl interpreter, as would normally be passed to the "main"
3653           function of a C program.  "argv[argc]" must be null.  These
3654           arguments are where the script to parse is specified, either by
3655           naming a script file or by providing a script in a "-e" option.  If
3656           $0 will be written to in the Perl interpreter, then the argument
3657           strings must be in writable memory, and so mustn't just be string
3658           constants.
3659
3660           "env" specifies a set of environment variables that will be used by
3661           this Perl interpreter.  If non-null, it must point to a null-
3662           terminated array of environment strings.  If null, the Perl
3663           interpreter will use the environment supplied by the "environ"
3664           global variable.
3665
3666           This function initialises the interpreter, and parses and compiles
3667           the script specified by the command-line arguments.  This includes
3668           executing code in "BEGIN", "UNITCHECK", and "CHECK" blocks.  It
3669           does not execute "INIT" blocks or the main program.
3670
3671           Returns an integer of slightly tricky interpretation.  The correct
3672           use of the return value is as a truth value indicating whether
3673           there was a failure in initialisation.  If zero is returned, this
3674           indicates that initialisation was successful, and it is safe to
3675           proceed to call "perl_run" and make other use of it.  If a non-zero
3676           value is returned, this indicates some problem that means the
3677           interpreter wants to terminate.  The interpreter should not be just
3678           abandoned upon such failure; the caller should proceed to shut the
3679           interpreter down cleanly with "perl_destruct" and free it with
3680           "perl_free".
3681
3682           For historical reasons, the non-zero return value also attempts to
3683           be a suitable value to pass to the C library function "exit" (or to
3684           return from "main"), to serve as an exit code indicating the nature
3685           of the way initialisation terminated.  However, this isn't
3686           portable, due to differing exit code conventions.  An attempt is
3687           made to return an exit code of the type required by the host
3688           operating system, but because it is constrained to be non-zero, it
3689           is not necessarily possible to indicate every type of exit.  It is
3690           only reliable on Unix, where a zero exit code can be augmented with
3691           a set bit that will be ignored.  In any case, this function is not
3692           the correct place to acquire an exit code: one should get that from
3693           "perl_destruct".
3694
3695            int  perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit,
3696                            int argc, char **argv, char **env)
3697
3698       "perl_run"
3699           Tells a Perl interpreter to run its main program.  See perlembed
3700           for a tutorial.
3701
3702           "my_perl" points to the Perl interpreter.  It must have been
3703           previously created through the use of "perl_alloc" and
3704           "perl_construct", and initialised through "perl_parse".  This
3705           function should not be called if "perl_parse" returned a non-zero
3706           value, indicating a failure in initialisation or compilation.
3707
3708           This function executes code in "INIT" blocks, and then executes the
3709           main program.  The code to be executed is that established by the
3710           prior call to "perl_parse".  If the interpreter's "PL_exit_flags"
3711           word does not have the "PERL_EXIT_DESTRUCT_END" flag set, then this
3712           function will also execute code in "END" blocks.  If it is desired
3713           to make any further use of the interpreter after calling this
3714           function, then "END" blocks should be postponed to "perl_destruct"
3715           time by setting that flag.
3716
3717           Returns an integer of slightly tricky interpretation.  The correct
3718           use of the return value is as a truth value indicating whether the
3719           program terminated non-locally.  If zero is returned, this
3720           indicates that the program ran to completion, and it is safe to
3721           make other use of the interpreter (provided that the
3722           "PERL_EXIT_DESTRUCT_END" flag was set as described above).  If a
3723           non-zero value is returned, this indicates that the interpreter
3724           wants to terminate early.  The interpreter should not be just
3725           abandoned because of this desire to terminate; the caller should
3726           proceed to shut the interpreter down cleanly with "perl_destruct"
3727           and free it with "perl_free".
3728
3729           For historical reasons, the non-zero return value also attempts to
3730           be a suitable value to pass to the C library function "exit" (or to
3731           return from "main"), to serve as an exit code indicating the nature
3732           of the way the program terminated.  However, this isn't portable,
3733           due to differing exit code conventions.  An attempt is made to
3734           return an exit code of the type required by the host operating
3735           system, but because it is constrained to be non-zero, it is not
3736           necessarily possible to indicate every type of exit.  It is only
3737           reliable on Unix, where a zero exit code can be augmented with a
3738           set bit that will be ignored.  In any case, this function is not
3739           the correct place to acquire an exit code: one should get that from
3740           "perl_destruct".
3741
3742            int  perl_run(PerlInterpreter *my_perl)
3743
3744       "PERL_SET_CONTEXT"
3745           Described in perlguts.
3746
3747            void  PERL_SET_CONTEXT(PerlInterpreter* i)
3748
3749       "PERL_SYS_INIT"
3750       "PERL_SYS_INIT3"
3751           These provide system-specific tune up of the C runtime environment
3752           necessary to run Perl interpreters.  Only one should be used, and
3753           it should be called only once, before creating any Perl
3754           interpreters.
3755
3756           They differ in that "PERL_SYS_INIT3" also initializes "env".
3757
3758            void  PERL_SYS_INIT (int *argc, char*** argv)
3759            void  PERL_SYS_INIT3(int *argc, char*** argv, char*** env)
3760
3761       "PERL_SYS_TERM"
3762           Provides system-specific clean up of the C runtime environment
3763           after running Perl interpreters.  This should be called only once,
3764           after freeing any remaining Perl interpreters.
3765
3766            void  PERL_SYS_TERM()
3767
3768       "PL_exit_flags"
3769           Contains flags controlling perl's behaviour on exit():
3770
3771           •   "PERL_EXIT_DESTRUCT_END"
3772
3773               If set, END blocks are executed when the interpreter is
3774               destroyed.  This is normally set by perl itself after the
3775               interpreter is constructed.
3776
3777           •   "PERL_EXIT_ABORT"
3778
3779               Call abort() on exit.  This is used internally by perl itself
3780               to abort if exit is called while processing exit.
3781
3782           •   "PERL_EXIT_WARN"
3783
3784               Warn on exit.
3785
3786           •   "PERL_EXIT_EXPECTED"
3787
3788               Set by the "exit" in perlfunc operator.
3789
3790            U8  PL_exit_flags
3791
3792       "PL_origalen"
3793           Described in perlembed.
3794
3795       "PL_perl_destruct_level"
3796           This value may be set when embedding for full cleanup.
3797
3798           Possible values:
3799
3800           •   0 - none
3801
3802           •   1 - full
3803
3804           •   2 or greater - full with checks.
3805
3806           If $ENV{PERL_DESTRUCT_LEVEL} is set to an integer greater than the
3807           value of "PL_perl_destruct_level" its value is used instead.
3808
3809           On threaded perls, each thread has an independent copy of this
3810           variable; each initialized at creation time with the current value
3811           of the creating thread's copy.
3812
3813            signed char  PL_perl_destruct_level
3814
3815       "ptr_table_fetch"
3816           Look for "sv" in the pointer-mapping table "tbl", returning its
3817           value, or NULL if not found.
3818
3819            void *  ptr_table_fetch(PTR_TBL_t * const tbl,
3820                                    const void * const sv)
3821
3822       "ptr_table_free"
3823           Clear and free a ptr table
3824
3825            void  ptr_table_free(PTR_TBL_t * const tbl)
3826
3827       "ptr_table_new"
3828           Create a new pointer-mapping table
3829
3830            PTR_TBL_t *  ptr_table_new()
3831
3832       "ptr_table_split"
3833           Double the hash bucket size of an existing ptr table
3834
3835            void  ptr_table_split(PTR_TBL_t * const tbl)
3836
3837       "ptr_table_store"
3838           Add a new entry to a pointer-mapping table "tbl".  In hash terms,
3839           "oldsv" is the key; Cnewsv> is the value.
3840
3841           The names "old" and "new" are specific to the core's typical use of
3842           ptr_tables in thread cloning.
3843
3844            void  ptr_table_store(PTR_TBL_t * const tbl,
3845                                  const void * const oldsv,
3846                                  void * const newsv)
3847
3848       "require_pv"
3849           Tells Perl to "require" the file named by the string argument.  It
3850           is analogous to the Perl code "eval "require '$file'"".  It's even
3851           implemented that way; consider using load_module instead.
3852
3853           NOTE: the perl_require_pv() form is deprecated.
3854
3855            void  require_pv(const char *pv)
3856
3857       "vload_module"
3858           Like "load_module" but the arguments are an encapsulated argument
3859           list.
3860
3861            void  vload_module(U32 flags, SV *name, SV *ver, va_list *args)
3862

Errno

3864       "sv_string_from_errnum"
3865           Generates the message string describing an OS error and returns it
3866           as an SV.  "errnum" must be a value that "errno" could take,
3867           identifying the type of error.
3868
3869           If "tgtsv" is non-null then the string will be written into that SV
3870           (overwriting existing content) and it will be returned.  If "tgtsv"
3871           is a null pointer then the string will be written into a new mortal
3872           SV which will be returned.
3873
3874           The message will be taken from whatever locale would be used by $!,
3875           and will be encoded in the SV in whatever manner would be used by
3876           $!.  The details of this process are subject to future change.
3877           Currently, the message is taken from the C locale by default
3878           (usually producing an English message), and from the currently
3879           selected locale when in the scope of the "use locale" pragma.  A
3880           heuristic attempt is made to decode the message from the locale's
3881           character encoding, but it will only be decoded as either UTF-8 or
3882           ISO-8859-1.  It is always correctly decoded in a UTF-8 locale,
3883           usually in an ISO-8859-1 locale, and never in any other locale.
3884
3885           The SV is always returned containing an actual string, and with no
3886           other OK bits set.  Unlike $!, a message is even yielded for
3887           "errnum" zero (meaning success), and if no useful message is
3888           available then a useless string (currently empty) is returned.
3889
3890            SV *  sv_string_from_errnum(int errnum, SV *tgtsv)
3891

Exception Handling (simple) Macros

3893       "dXCPT"
3894           Set up necessary local variables for exception handling.  See
3895           "Exception Handling" in perlguts.
3896
3897              dXCPT;
3898
3899       "JMPENV_JUMP"
3900           Described in perlinterp.
3901
3902            void  JMPENV_JUMP(int v)
3903
3904       "JMPENV_PUSH"
3905           Described in perlinterp.
3906
3907            void  JMPENV_PUSH(int v)
3908
3909       "PL_restartop"
3910           Described in perlinterp.
3911
3912       "XCPT_CATCH"
3913           Introduces a catch block.  See "Exception Handling" in perlguts.
3914
3915       "XCPT_RETHROW"
3916           Rethrows a previously caught exception.  See "Exception Handling"
3917           in perlguts.
3918
3919              XCPT_RETHROW;
3920
3921       "XCPT_TRY_END"
3922           Ends a try block.  See "Exception Handling" in perlguts.
3923
3924       "XCPT_TRY_START"
3925           Starts a try block.  See "Exception Handling" in perlguts.
3926

Filesystem configuration values

3928       Also see "List of capability HAS_foo symbols".
3929
3930       "DIRNAMLEN"
3931           This symbol, if defined, indicates to the C program that the length
3932           of directory entry names is provided by a "d_namlen" field.
3933           Otherwise you need to do strlen() on the "d_name" field.
3934
3935       "DOSUID"
3936           This symbol, if defined, indicates that the C program should check
3937           the script that it is executing for setuid/setgid bits, and attempt
3938           to emulate setuid/setgid on systems that have disabled setuid #!
3939           scripts because the kernel can't do it securely.  It is up to the
3940           package designer to make sure that this emulation is done securely.
3941           Among other things, it should do an fstat on the script it just
3942           opened to make sure it really is a setuid/setgid script, it should
3943           make sure the arguments passed correspond exactly to the argument
3944           on the #! line, and it should not trust any subprocesses to which
3945           it must pass the filename rather than the file descriptor of the
3946           script to be executed.
3947
3948       "EOF_NONBLOCK"
3949           This symbol, if defined, indicates to the C program that a read()
3950           on a non-blocking file descriptor will return 0 on "EOF", and not
3951           the value held in "RD_NODATA" (-1 usually, in that case!).
3952
3953       "FCNTL_CAN_LOCK"
3954           This symbol, if defined, indicates that fcntl() can be used for
3955           file locking.  Normally on Unix systems this is defined.  It may be
3956           undefined on "VMS".
3957
3958       "FFLUSH_ALL"
3959           This symbol, if defined, tells that to flush all pending stdio
3960           output one must loop through all the stdio file handles stored in
3961           an array and fflush them.  Note that if "fflushNULL" is defined,
3962           fflushall will not even be probed for and will be left undefined.
3963
3964       "FFLUSH_NULL"
3965           This symbol, if defined, tells that fflush(NULL) correctly flushes
3966           all pending stdio output without side effects. In particular, on
3967           some platforms calling fflush(NULL) *still* corrupts "STDIN" if it
3968           is a pipe.
3969
3970       "FILE_base"
3971           This macro is used to access the "_base" field (or equivalent) of
3972           the "FILE" structure pointed to by its argument. This macro will
3973           always be defined if "USE_STDIO_BASE" is defined.
3974
3975            void *  FILE_base(FILE * f)
3976
3977       "FILE_bufsiz"
3978           This macro is used to determine the number of bytes in the I/O
3979           buffer pointed to by "_base" field (or equivalent) of the "FILE"
3980           structure pointed to its argument. This macro will always be
3981           defined if "USE_STDIO_BASE" is defined.
3982
3983            Size_t  FILE_bufsiz(FILE *f)
3984
3985       "FILE_cnt"
3986           This macro is used to access the "_cnt" field (or equivalent) of
3987           the "FILE" structure pointed to by its argument. This macro will
3988           always be defined if "USE_STDIO_PTR" is defined.
3989
3990            Size_t  FILE_cnt(FILE * f)
3991
3992       "FILE_ptr"
3993           This macro is used to access the "_ptr" field (or equivalent) of
3994           the "FILE" structure pointed to by its argument. This macro will
3995           always be defined if "USE_STDIO_PTR" is defined.
3996
3997            void *  FILE_ptr(FILE * f)
3998
3999       "FLEXFILENAMES"
4000           This symbol, if defined, indicates that the system supports
4001           filenames longer than 14 characters.
4002
4003       "HAS_DIR_DD_FD"
4004           This symbol, if defined, indicates that the "DIR"* dirstream
4005           structure contains a member variable named "dd_fd".
4006
4007       "HAS_DUP2"
4008           This symbol, if defined, indicates that the "dup2" routine is
4009           available to duplicate file descriptors.
4010
4011       "HAS_DUP3"
4012           This symbol, if defined, indicates that the "dup3" routine is
4013           available to duplicate file descriptors.
4014
4015       "HAS_FAST_STDIO"
4016           This symbol, if defined, indicates that the "fast stdio" is
4017           available to manipulate the stdio buffers directly.
4018
4019       "HAS_FCHDIR"
4020           This symbol, if defined, indicates that the "fchdir" routine is
4021           available to change directory using a file descriptor.
4022
4023       "HAS_FCNTL"
4024           This symbol, if defined, indicates to the C program that the
4025           fcntl() function exists.
4026
4027       "HAS_FDCLOSE"
4028           This symbol, if defined, indicates that the "fdclose" routine is
4029           available to free a "FILE" structure without closing the underlying
4030           file descriptor.  This function appeared in "FreeBSD" 10.2.
4031
4032       "HAS_FPATHCONF"
4033           This symbol, if defined, indicates that pathconf() is available to
4034           determine file-system related limits and options associated with a
4035           given open file descriptor.
4036
4037       "HAS_FPOS64_T"
4038           This symbol will be defined if the C compiler supports "fpos64_t".
4039
4040       "HAS_FSTATFS"
4041           This symbol, if defined, indicates that the "fstatfs" routine is
4042           available to stat filesystems by file descriptors.
4043
4044       "HAS_FSTATVFS"
4045           This symbol, if defined, indicates that the "fstatvfs" routine is
4046           available to stat filesystems by file descriptors.
4047
4048       "HAS_GETFSSTAT"
4049           This symbol, if defined, indicates that the "getfsstat" routine is
4050           available to stat filesystems in bulk.
4051
4052       "HAS_GETMNT"
4053           This symbol, if defined, indicates that the "getmnt" routine is
4054           available to get filesystem mount info by filename.
4055
4056       "HAS_GETMNTENT"
4057           This symbol, if defined, indicates that the "getmntent" routine is
4058           available to iterate through mounted file systems to get their
4059           info.
4060
4061       "HAS_HASMNTOPT"
4062           This symbol, if defined, indicates that the "hasmntopt" routine is
4063           available to query the mount options of file systems.
4064
4065       "HAS_LSEEK_PROTO"
4066           This symbol, if defined, indicates that the system provides a
4067           prototype for the lseek() function.  Otherwise, it is up to the
4068           program to supply one.  A good guess is
4069
4070            extern off_t lseek(int, off_t, int);
4071
4072       "HAS_MKDIR"
4073           This symbol, if defined, indicates that the "mkdir" routine is
4074           available to create directories.  Otherwise you should fork off a
4075           new process to exec /bin/mkdir.
4076
4077       "HAS_OFF64_T"
4078           This symbol will be defined if the C compiler supports "off64_t".
4079
4080       "HAS_OPENAT"
4081           This symbol is defined if the openat() routine is available.
4082
4083       "HAS_OPEN3"
4084           This manifest constant lets the C program know that the three
4085           argument form of open(2) is available.
4086
4087       "HAS_POLL"
4088           This symbol, if defined, indicates that the "poll" routine is
4089           available to "poll" active file descriptors.  Please check "I_POLL"
4090           and "I_SYS_POLL" to know which header should be included as well.
4091
4092       "HAS_READDIR"
4093           This symbol, if defined, indicates that the "readdir" routine is
4094           available to read directory entries. You may have to include
4095           dirent.h. See "I_DIRENT".
4096
4097       "HAS_READDIR64_R"
4098           This symbol, if defined, indicates that the "readdir64_r" routine
4099           is available to readdir64 re-entrantly.
4100
4101       "HAS_REWINDDIR"
4102           This symbol, if defined, indicates that the "rewinddir" routine is
4103           available. You may have to include dirent.h. See "I_DIRENT".
4104
4105       "HAS_RMDIR"
4106           This symbol, if defined, indicates that the "rmdir" routine is
4107           available to remove directories. Otherwise you should fork off a
4108           new process to exec /bin/rmdir.
4109
4110       "HAS_SEEKDIR"
4111           This symbol, if defined, indicates that the "seekdir" routine is
4112           available. You may have to include dirent.h. See "I_DIRENT".
4113
4114       "HAS_SELECT"
4115           This symbol, if defined, indicates that the "select" routine is
4116           available to "select" active file descriptors. If the timeout field
4117           is used, sys/time.h may need to be included.
4118
4119       "HAS_SETVBUF"
4120           This symbol, if defined, indicates that the "setvbuf" routine is
4121           available to change buffering on an open stdio stream.  to a line-
4122           buffered mode.
4123
4124       "HAS_STDIO_STREAM_ARRAY"
4125           This symbol, if defined, tells that there is an array holding the
4126           stdio streams.
4127
4128       "HAS_STRUCT_FS_DATA"
4129           This symbol, if defined, indicates that the "struct fs_data" to do
4130           statfs() is supported.
4131
4132       "HAS_STRUCT_STATFS"
4133           This symbol, if defined, indicates that the "struct statfs" to do
4134           statfs() is supported.
4135
4136       "HAS_STRUCT_STATFS_F_FLAGS"
4137           This symbol, if defined, indicates that the "struct statfs" does
4138           have the "f_flags" member containing the mount flags of the
4139           filesystem containing the file.  This kind of "struct statfs" is
4140           coming from sys/mount.h ("BSD" 4.3), not from sys/statfs.h
4141           ("SYSV").  Older "BSDs" (like Ultrix) do not have statfs() and
4142           "struct statfs", they have ustat() and getmnt() with "struct ustat"
4143           and "struct fs_data".
4144
4145       "HAS_TELLDIR"
4146           This symbol, if defined, indicates that the "telldir" routine is
4147           available. You may have to include dirent.h. See "I_DIRENT".
4148
4149       "HAS_USTAT"
4150           This symbol, if defined, indicates that the "ustat" system call is
4151           available to query file system statistics by "dev_t".
4152
4153       "I_FCNTL"
4154           This manifest constant tells the C program to include fcntl.h.
4155
4156            #ifdef I_FCNTL
4157                #include <fcntl.h>
4158            #endif
4159
4160       "I_SYS_DIR"
4161           This symbol, if defined, indicates to the C program that it should
4162           include sys/dir.h.
4163
4164            #ifdef I_SYS_DIR
4165                #include <sys_dir.h>
4166            #endif
4167
4168       "I_SYS_FILE"
4169           This symbol, if defined, indicates to the C program that it should
4170           include sys/file.h to get definition of "R_OK" and friends.
4171
4172            #ifdef I_SYS_FILE
4173                #include <sys_file.h>
4174            #endif
4175
4176       "I_SYS_NDIR"
4177           This symbol, if defined, indicates to the C program that it should
4178           include sys/ndir.h.
4179
4180            #ifdef I_SYS_NDIR
4181                #include <sys_ndir.h>
4182            #endif
4183
4184       "I_SYS_STATFS"
4185           This symbol, if defined, indicates that sys/statfs.h exists.
4186
4187            #ifdef I_SYS_STATFS
4188                #include <sys_statfs.h>
4189            #endif
4190
4191       "LSEEKSIZE"
4192           This symbol holds the number of bytes used by the "Off_t".
4193
4194       "RD_NODATA"
4195           This symbol holds the return code from read() when no data is
4196           present on the non-blocking file descriptor. Be careful! If
4197           "EOF_NONBLOCK" is not defined, then you can't distinguish between
4198           no data and "EOF" by issuing a read(). You'll have to find another
4199           way to tell for sure!
4200
4201       "READDIR64_R_PROTO"
4202           This symbol encodes the prototype of "readdir64_r".  It is zero if
4203           "d_readdir64_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
4204           macros of reentr.h if "d_readdir64_r" is defined.
4205
4206       "STDCHAR"
4207           This symbol is defined to be the type of char used in stdio.h.  It
4208           has the values "unsigned char" or "char".
4209
4210       "STDIO_CNT_LVALUE"
4211           This symbol is defined if the "FILE_cnt" macro can be used as an
4212           lvalue.
4213
4214       "STDIO_PTR_LVAL_NOCHANGE_CNT"
4215           This symbol is defined if using the "FILE_ptr" macro as an lvalue
4216           to increase the pointer by n leaves File_cnt(fp) unchanged.
4217
4218       "STDIO_PTR_LVAL_SETS_CNT"
4219           This symbol is defined if using the "FILE_ptr" macro as an lvalue
4220           to increase the pointer by n has the side effect of decreasing the
4221           value of File_cnt(fp) by n.
4222
4223       "STDIO_PTR_LVALUE"
4224           This symbol is defined if the "FILE_ptr" macro can be used as an
4225           lvalue.
4226
4227       "STDIO_STREAM_ARRAY"
4228           This symbol tells the name of the array holding the stdio streams.
4229           Usual values include "_iob", "__iob", and "__sF".
4230
4231       "ST_INO_SIGN"
4232           This symbol holds the signedness of "struct stat"'s "st_ino".  1
4233           for unsigned, -1 for signed.
4234
4235       "ST_INO_SIZE"
4236           This variable contains the size of "struct stat"'s "st_ino" in
4237           bytes.
4238
4239       "VAL_EAGAIN"
4240           This symbol holds the errno error code set by read() when no data
4241           was present on the non-blocking file descriptor.
4242
4243       "VAL_O_NONBLOCK"
4244           This symbol is to be used during open() or fcntl(F_SETFL) to turn
4245           on non-blocking I/O for the file descriptor. Note that there is no
4246           way back, i.e. you cannot turn it blocking again this way. If you
4247           wish to alternatively switch between blocking and non-blocking, use
4248           the ioctl(FIOSNBIO) call instead, but that is not supported by all
4249           devices.
4250
4251       "VOID_CLOSEDIR"
4252           This symbol, if defined, indicates that the closedir() routine does
4253           not return a value.
4254

Floating point

4256       Also "List of capability HAS_foo symbols" lists capabilities that arent
4257       in this section.  For example "HAS_ASINH", for the hyperbolic sine
4258       function.
4259
4260       "CASTFLAGS"
4261           This symbol contains flags that say what difficulties the compiler
4262           has casting odd floating values to unsigned long:
4263
4264            0 = ok
4265            1 = couldn't cast < 0
4266            2 = couldn't cast >= 0x80000000
4267            4 = couldn't cast in argument expression list
4268
4269       "CASTNEGFLOAT"
4270           This symbol is defined if the C compiler can cast negative numbers
4271           to unsigned longs, ints and shorts.
4272
4273       "DOUBLE_HAS_INF"
4274           This symbol, if defined, indicates that the double has the
4275           infinity.
4276
4277       "DOUBLE_HAS_NAN"
4278           This symbol, if defined, indicates that the double has the not-a-
4279           number.
4280
4281       "DOUBLE_HAS_NEGATIVE_ZERO"
4282           This symbol, if defined, indicates that the double has the
4283           "negative_zero".
4284
4285       "DOUBLE_HAS_SUBNORMALS"
4286           This symbol, if defined, indicates that the double has the
4287           subnormals (denormals).
4288
4289       "DOUBLEINFBYTES"
4290           This symbol, if defined, is a comma-separated list of hexadecimal
4291           bytes for the double precision infinity.
4292
4293       "DOUBLEKIND"
4294           "DOUBLEKIND" will be one of
4295           "DOUBLE_IS_IEEE_754_32_BIT_LITTLE_ENDIAN"
4296           "DOUBLE_IS_IEEE_754_32_BIT_BIG_ENDIAN"
4297           "DOUBLE_IS_IEEE_754_64_BIT_LITTLE_ENDIAN"
4298           "DOUBLE_IS_IEEE_754_64_BIT_BIG_ENDIAN"
4299           "DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN"
4300           "DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN"
4301           "DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_LE_BE"
4302           "DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_BE_LE"
4303           "DOUBLE_IS_VAX_F_FLOAT" "DOUBLE_IS_VAX_D_FLOAT"
4304           "DOUBLE_IS_VAX_G_FLOAT" "DOUBLE_IS_IBM_SINGLE_32_BIT"
4305           "DOUBLE_IS_IBM_DOUBLE_64_BIT" "DOUBLE_IS_CRAY_SINGLE_64_BIT"
4306           "DOUBLE_IS_UNKNOWN_FORMAT"
4307
4308       "DOUBLEMANTBITS"
4309           This symbol, if defined, tells how many mantissa bits there are in
4310           double precision floating point format.  Note that this is usually
4311           "DBL_MANT_DIG" minus one, since with the standard "IEEE" 754
4312           formats "DBL_MANT_DIG" includes the implicit bit, which doesn't
4313           really exist.
4314
4315       "DOUBLENANBYTES"
4316           This symbol, if defined, is a comma-separated list of hexadecimal
4317           bytes (0xHH) for the double precision not-a-number.
4318
4319       "DOUBLESIZE"
4320           This symbol contains the size of a double, so that the C
4321           preprocessor can make decisions based on it.
4322
4323       "DOUBLE_STYLE_CRAY"
4324           This symbol, if defined, indicates that the double is the 64-bit
4325           "CRAY" mainframe format.
4326
4327       "DOUBLE_STYLE_IBM"
4328           This symbol, if defined, indicates that the double is the 64-bit
4329           "IBM" mainframe format.
4330
4331       "DOUBLE_STYLE_IEEE"
4332           This symbol, if defined, indicates that the double is the 64-bit
4333           "IEEE" 754.
4334
4335       "DOUBLE_STYLE_VAX"
4336           This symbol, if defined, indicates that the double is the 64-bit
4337           "VAX" format D or G.
4338
4339       "HAS_ATOLF"
4340           This symbol, if defined, indicates that the "atolf" routine is
4341           available to convert strings into long doubles.
4342
4343       "HAS_CLASS"
4344           This symbol, if defined, indicates that the "class" routine is
4345           available to classify doubles.  Available for example in "AIX".
4346           The returned values are defined in float.h and are:
4347
4348            FP_PLUS_NORM    Positive normalized, nonzero
4349            FP_MINUS_NORM   Negative normalized, nonzero
4350            FP_PLUS_DENORM  Positive denormalized, nonzero
4351            FP_MINUS_DENORM Negative denormalized, nonzero
4352            FP_PLUS_ZERO    +0.0
4353            FP_MINUS_ZERO   -0.0
4354            FP_PLUS_INF     +INF
4355            FP_MINUS_INF    -INF
4356            FP_NANS         Signaling Not a Number (NaNS)
4357            FP_NANQ         Quiet Not a Number (NaNQ)
4358
4359       "HAS_FINITE"
4360           This symbol, if defined, indicates that the "finite" routine is
4361           available to check whether a double is "finite" (non-infinity non-
4362           NaN).
4363
4364       "HAS_FINITEL"
4365           This symbol, if defined, indicates that the "finitel" routine is
4366           available to check whether a long double is finite (non-infinity
4367           non-NaN).
4368
4369       "HAS_FPCLASS"
4370           This symbol, if defined, indicates that the "fpclass" routine is
4371           available to classify doubles.  Available for example in
4372           Solaris/"SVR4".  The returned values are defined in ieeefp.h and
4373           are:
4374
4375            FP_SNAN         signaling NaN
4376            FP_QNAN         quiet NaN
4377            FP_NINF         negative infinity
4378            FP_PINF         positive infinity
4379            FP_NDENORM      negative denormalized non-zero
4380            FP_PDENORM      positive denormalized non-zero
4381            FP_NZERO        negative zero
4382            FP_PZERO        positive zero
4383            FP_NNORM        negative normalized non-zero
4384            FP_PNORM        positive normalized non-zero
4385
4386       "HAS_FP_CLASS"
4387           This symbol, if defined, indicates that the "fp_class" routine is
4388           available to classify doubles.  Available for example in Digital
4389           "UNIX".  The returned values are defined in math.h and are:
4390
4391            FP_SNAN           Signaling NaN (Not-a-Number)
4392            FP_QNAN           Quiet NaN (Not-a-Number)
4393            FP_POS_INF        +infinity
4394            FP_NEG_INF        -infinity
4395            FP_POS_NORM       Positive normalized
4396            FP_NEG_NORM       Negative normalized
4397            FP_POS_DENORM     Positive denormalized
4398            FP_NEG_DENORM     Negative denormalized
4399            FP_POS_ZERO       +0.0 (positive zero)
4400            FP_NEG_ZERO       -0.0 (negative zero)
4401
4402       "HAS_FPCLASSIFY"
4403           This symbol, if defined, indicates that the "fpclassify" routine is
4404           available to classify doubles.  Available for example in HP-UX.
4405           The returned values are defined in math.h and are
4406
4407            FP_NORMAL     Normalized
4408            FP_ZERO       Zero
4409            FP_INFINITE   Infinity
4410            FP_SUBNORMAL  Denormalized
4411            FP_NAN        NaN
4412
4413       "HAS_FP_CLASSIFY"
4414           This symbol, if defined, indicates that the "fp_classify" routine
4415           is available to classify doubles. The values are defined in math.h
4416
4417            FP_NORMAL     Normalized
4418            FP_ZERO       Zero
4419            FP_INFINITE   Infinity
4420            FP_SUBNORMAL  Denormalized
4421            FP_NAN        NaN
4422
4423       "HAS_FPCLASSL"
4424           This symbol, if defined, indicates that the "fpclassl" routine is
4425           available to classify long doubles.  Available for example in
4426           "IRIX".  The returned values are defined in ieeefp.h and are:
4427
4428            FP_SNAN         signaling NaN
4429            FP_QNAN         quiet NaN
4430            FP_NINF         negative infinity
4431            FP_PINF         positive infinity
4432            FP_NDENORM      negative denormalized non-zero
4433            FP_PDENORM      positive denormalized non-zero
4434            FP_NZERO        negative zero
4435            FP_PZERO        positive zero
4436            FP_NNORM        negative normalized non-zero
4437            FP_PNORM        positive normalized non-zero
4438
4439       "HAS_FP_CLASSL"
4440           This symbol, if defined, indicates that the "fp_classl" routine is
4441           available to classify long doubles.  Available for example in
4442           Digital "UNIX".  See for possible values "HAS_FP_CLASS".
4443
4444       "HAS_FPGETROUND"
4445           This symbol, if defined, indicates that the "fpgetround" routine is
4446           available to get the floating point rounding mode.
4447
4448       "HAS_FREXPL"
4449           This symbol, if defined, indicates that the "frexpl" routine is
4450           available to break a long double floating-point number into a
4451           normalized fraction and an integral power of 2.
4452
4453       "HAS_ILOGB"
4454           This symbol, if defined, indicates that the "ilogb" routine is
4455           available to get integer exponent of a floating-point value.
4456
4457       "HAS_ISFINITE"
4458           This symbol, if defined, indicates that the "isfinite" routine is
4459           available to check whether a double is finite (non-infinity non-
4460           NaN).
4461
4462       "HAS_ISFINITEL"
4463           This symbol, if defined, indicates that the "isfinitel" routine is
4464           available to check whether a long double is finite.  (non-infinity
4465           non-NaN).
4466
4467       "HAS_ISINF"
4468           This symbol, if defined, indicates that the "isinf" routine is
4469           available to check whether a double is an infinity.
4470
4471       "HAS_ISINFL"
4472           This symbol, if defined, indicates that the "isinfl" routine is
4473           available to check whether a long double is an infinity.
4474
4475       "HAS_ISNAN"
4476           This symbol, if defined, indicates that the "isnan" routine is
4477           available to check whether a double is a NaN.
4478
4479       "HAS_ISNANL"
4480           This symbol, if defined, indicates that the "isnanl" routine is
4481           available to check whether a long double is a NaN.
4482
4483       "HAS_ISNORMAL"
4484           This symbol, if defined, indicates that the "isnormal" routine is
4485           available to check whether a double is normal (non-zero
4486           normalized).
4487
4488       "HAS_J0L"
4489           This symbol, if defined, indicates to the C program that the j0l()
4490           function is available for Bessel functions of the first kind of the
4491           order zero, for long doubles.
4492
4493       "HAS_J0"
4494           This symbol, if defined, indicates to the C program that the j0()
4495           function is available for Bessel functions of the first kind of the
4496           order zero, for doubles.
4497
4498       "HAS_LDBL_DIG"
4499           This symbol, if defined, indicates that this system's float.h or
4500           limits.h defines the symbol "LDBL_DIG", which is the number of
4501           significant digits in a long double precision number. Unlike for
4502           "DBL_DIG", there's no good guess for "LDBL_DIG" if it is undefined.
4503
4504       "HAS_LDEXPL"
4505           This symbol, if defined, indicates that the "ldexpl" routine is
4506           available to shift a long double floating-point number by an
4507           integral power of 2.
4508
4509       "HAS_LLRINT"
4510           This symbol, if defined, indicates that the "llrint" routine is
4511           available to return the long long value closest to a double
4512           (according to the current rounding mode).
4513
4514       "HAS_LLRINTL"
4515           This symbol, if defined, indicates that the "llrintl" routine is
4516           available to return the long long value closest to a long double
4517           (according to the current rounding mode).
4518
4519       "HAS_LLROUNDL"
4520           This symbol, if defined, indicates that the "llroundl" routine is
4521           available to return the nearest long long value away from zero of
4522           the long double argument value.
4523
4524       "HAS_LONG_DOUBLE"
4525           This symbol will be defined if the C compiler supports long
4526           doubles.
4527
4528       "HAS_LRINT"
4529           This symbol, if defined, indicates that the "lrint" routine is
4530           available to return the integral value closest to a double
4531           (according to the current rounding mode).
4532
4533       "HAS_LRINTL"
4534           This symbol, if defined, indicates that the "lrintl" routine is
4535           available to return the integral value closest to a long double
4536           (according to the current rounding mode).
4537
4538       "HAS_LROUNDL"
4539           This symbol, if defined, indicates that the "lroundl" routine is
4540           available to return the nearest integral value away from zero of
4541           the long double argument value.
4542
4543       "HAS_MODFL"
4544           This symbol, if defined, indicates that the "modfl" routine is
4545           available to split a long double x into a fractional part f and an
4546           integer part i such that |f| < 1.0 and (f + i) = x.
4547
4548       "HAS_NAN"
4549           This symbol, if defined, indicates that the "nan" routine is
4550           available to generate NaN.
4551
4552       "HAS_NEXTTOWARD"
4553           This symbol, if defined, indicates that the "nexttoward" routine is
4554           available to return the next machine representable long double from
4555           x in direction y.
4556
4557       "HAS_REMAINDER"
4558           This symbol, if defined, indicates that the "remainder" routine is
4559           available to return the floating-point "remainder".
4560
4561       "HAS_SCALBN"
4562           This symbol, if defined, indicates that the "scalbn" routine is
4563           available to multiply floating-point number by integral power of
4564           radix.
4565
4566       "HAS_SIGNBIT"
4567           This symbol, if defined, indicates that the "signbit" routine is
4568           available to check if the given number has the sign bit set.  This
4569           should include correct testing of -0.0.  This will only be set if
4570           the signbit() routine is safe to use with the NV type used
4571           internally in perl.  Users should call Perl_signbit(), which will
4572           be #defined to the system's signbit() function or macro if this
4573           symbol is defined.
4574
4575       "HAS_SQRTL"
4576           This symbol, if defined, indicates that the "sqrtl" routine is
4577           available to do long double square roots.
4578
4579       "HAS_STRTOD_L"
4580           This symbol, if defined, indicates that the "strtod_l" routine is
4581           available to convert strings to long doubles.
4582
4583       "HAS_STRTOLD"
4584           This symbol, if defined, indicates that the "strtold" routine is
4585           available to convert strings to long doubles.
4586
4587       "HAS_STRTOLD_L"
4588           This symbol, if defined, indicates that the "strtold_l" routine is
4589           available to convert strings to long doubles.
4590
4591       "HAS_TRUNC"
4592           This symbol, if defined, indicates that the "trunc" routine is
4593           available to round doubles towards zero.
4594
4595       "HAS_UNORDERED"
4596           This symbol, if defined, indicates that the "unordered" routine is
4597           available to check whether two doubles are "unordered"
4598           (effectively: whether either of them is NaN)
4599
4600       "I_FENV"
4601           This symbol, if defined, indicates to the C program that it should
4602           include fenv.h to get the floating point environment definitions.
4603
4604            #ifdef I_FENV
4605                #include <fenv.h>
4606            #endif
4607
4608       "I_QUADMATH"
4609           This symbol, if defined, indicates that quadmath.h exists and
4610           should be included.
4611
4612            #ifdef I_QUADMATH
4613                #include <quadmath.h>
4614            #endif
4615
4616       "LONGDBLINFBYTES"
4617           This symbol, if defined, is a comma-separated list of hexadecimal
4618           bytes for the long double precision infinity.
4619
4620       "LONGDBLMANTBITS"
4621           This symbol, if defined, tells how many mantissa bits there are in
4622           long double precision floating point format.  Note that this can be
4623           "LDBL_MANT_DIG" minus one, since "LDBL_MANT_DIG" can include the
4624           "IEEE" 754 implicit bit.  The common x86-style 80-bit long double
4625           does not have an implicit bit.
4626
4627       "LONGDBLNANBYTES"
4628           This symbol, if defined, is a comma-separated list of hexadecimal
4629           bytes (0xHH) for the long double precision not-a-number.
4630
4631       "LONG_DOUBLEKIND"
4632           "LONG_DOUBLEKIND" will be one of "LONG_DOUBLE_IS_DOUBLE"
4633           "LONG_DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN"
4634           "LONG_DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN"
4635           "LONG_DOUBLE_IS_X86_80_BIT_LITTLE_ENDIAN"
4636           "LONG_DOUBLE_IS_X86_80_BIT_BIG_ENDIAN"
4637           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_LE"
4638           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_BE"
4639           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_BE"
4640           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_LE"
4641           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LITTLE_ENDIAN"
4642           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BIG_ENDIAN"
4643           "LONG_DOUBLE_IS_VAX_H_FLOAT" "LONG_DOUBLE_IS_UNKNOWN_FORMAT" It is
4644           only defined if the system supports long doubles.
4645
4646       "LONG_DOUBLESIZE"
4647           This symbol contains the size of a long double, so that the C
4648           preprocessor can make decisions based on it.  It is only defined if
4649           the system supports long doubles.  Note that this is "sizeof(long
4650           double)", which may include unused bytes.
4651
4652       "LONG_DOUBLE_STYLE_IEEE"
4653           This symbol, if defined, indicates that the long double is any of
4654           the "IEEE" 754 style long doubles: "LONG_DOUBLE_STYLE_IEEE_STD",
4655           "LONG_DOUBLE_STYLE_IEEE_EXTENDED",
4656           "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE".
4657
4658       "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
4659           This symbol, if defined, indicates that the long double is the
4660           128-bit double-double.
4661
4662       "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
4663           This symbol, if defined, indicates that the long double is the
4664           80-bit "IEEE" 754. Note that despite the 'extended' this is less
4665           than the 'std', since this is an extension of the double precision.
4666
4667       "LONG_DOUBLE_STYLE_IEEE_STD"
4668           This symbol, if defined, indicates that the long double is the
4669           128-bit "IEEE" 754.
4670
4671       "LONG_DOUBLE_STYLE_VAX"
4672           This symbol, if defined, indicates that the long double is the
4673           128-bit "VAX" format H.
4674
4675       "NV"
4676           Described in perlguts.
4677
4678       "NVMANTBITS"
4679           This symbol, if defined, tells how many mantissa bits (not
4680           including implicit bit) there are in a Perl NV.  This depends on
4681           which floating point type was chosen.
4682
4683       "NV_OVERFLOWS_INTEGERS_AT"
4684           This symbol gives the largest integer value that NVs can hold. This
4685           value + 1.0 cannot be stored accurately. It is expressed as
4686           constant floating point expression to reduce the chance of
4687           decimal/binary conversion issues. If it can not be determined, the
4688           value 0 is given.
4689
4690       "NV_PRESERVES_UV"
4691           This symbol, if defined, indicates that a variable of type "NVTYPE"
4692           can preserve all the bits of a variable of type "UVTYPE".
4693
4694       "NV_PRESERVES_UV_BITS"
4695           This symbol contains the number of bits a variable of type "NVTYPE"
4696           can preserve of a variable of type "UVTYPE".
4697
4698       "NVSIZE"
4699           This symbol contains the sizeof(NV).  Note that some floating point
4700           formats have unused bytes.  The most notable example is the x86*
4701           80-bit extended precision which comes in byte sizes of 12 and 16
4702           (for 32 and 64 bit platforms, respectively), but which only uses 10
4703           bytes.  Perl compiled with "-Duselongdouble" on x86* is like this.
4704
4705       "NVTYPE"
4706           This symbol defines the C type used for Perl's NV.
4707
4708       "NV_ZERO_IS_ALLBITS_ZERO"
4709           This symbol, if defined, indicates that a variable of type "NVTYPE"
4710           stores 0.0 in memory as all bits zero.
4711

General Configuration

4713       This section contains configuration information not otherwise found in
4714       the more specialized sections of this document.  At the end is a list
4715       of "#defines" whose name should be enough to tell you what they do, and
4716       a list of #defines which tell you if you need to "#include" files to
4717       get the corresponding functionality.
4718
4719       "ASCIIish"
4720           A preprocessor symbol that is defined iff the system is an ASCII
4721           platform; this symbol would not be defined on "EBCDIC" platforms.
4722
4723            #ifdef  ASCIIish
4724
4725       "BYTEORDER"
4726           This symbol holds the hexadecimal constant defined in byteorder, in
4727           a UV, i.e. 0x1234 or 0x4321 or 0x12345678, etc...  If the compiler
4728           supports cross-compiling or multiple-architecture binaries, use
4729           compiler-defined macros to determine the byte order.
4730
4731       "CHARBITS"
4732           This symbol contains the size of a char, so that the C preprocessor
4733           can make decisions based on it.
4734
4735       "DB_VERSION_MAJOR_CFG"
4736           This symbol, if defined, defines the major version number of
4737           Berkeley DB found in the db.h header when Perl was configured.
4738
4739       "DB_VERSION_MINOR_CFG"
4740           This symbol, if defined, defines the minor version number of
4741           Berkeley DB found in the db.h header when Perl was configured.  For
4742           DB version 1 this is always 0.
4743
4744       "DB_VERSION_PATCH_CFG"
4745           This symbol, if defined, defines the patch version number of
4746           Berkeley DB found in the db.h header when Perl was configured.  For
4747           DB version 1 this is always 0.
4748
4749       "DEFAULT_INC_EXCLUDES_DOT"
4750           This symbol, if defined, removes the legacy default behavior of
4751           including '.' at the end of @"INC".
4752
4753       "DLSYM_NEEDS_UNDERSCORE"
4754           This symbol, if defined, indicates that we need to prepend an
4755           underscore to the symbol name before calling dlsym().  This only
4756           makes sense if you *have* dlsym, which we will presume is the case
4757           if you're using dl_dlopen.xs.
4758
4759       "EBCDIC"
4760           This symbol, if defined, indicates that this system uses "EBCDIC"
4761           encoding.
4762
4763       "HAS_CSH"
4764           This symbol, if defined, indicates that the C-shell exists.
4765
4766       "HAS_GETHOSTNAME"
4767           This symbol, if defined, indicates that the C program may use the
4768           gethostname() routine to derive the host name.  See also
4769           "HAS_UNAME" and "PHOSTNAME".
4770
4771       "HAS_GNULIBC"
4772           This symbol, if defined, indicates to the C program that the "GNU"
4773           C library is being used.  A better check is to use the "__GLIBC__"
4774           and "__GLIBC_MINOR__" symbols supplied with glibc.
4775
4776       "HAS_LGAMMA"
4777           This symbol, if defined, indicates that the "lgamma" routine is
4778           available to do the log gamma function.  See also "HAS_TGAMMA" and
4779           "HAS_LGAMMA_R".
4780
4781       "HAS_LGAMMA_R"
4782           This symbol, if defined, indicates that the "lgamma_r" routine is
4783           available to do the log gamma function without using the global
4784           signgam variable.
4785
4786       "HAS_NON_INT_BITFIELDS"
4787           This symbol, if defined, indicates that the C compiler accepts,
4788           without error or warning, "struct bitfields" that are declared with
4789           sizes other than plain 'int'; for example 'unsigned char' is
4790           accepted.
4791
4792       "HAS_PRCTL_SET_NAME"
4793           This symbol, if defined, indicates that the prctl routine is
4794           available to set process title and supports "PR_SET_NAME".
4795
4796       "HAS_PROCSELFEXE"
4797           This symbol is defined if "PROCSELFEXE_PATH" is a symlink to the
4798           absolute pathname of the executing program.
4799
4800       "HAS_PSEUDOFORK"
4801           This symbol, if defined, indicates that an emulation of the fork
4802           routine is available.
4803
4804       "HAS_REGCOMP"
4805           This symbol, if defined, indicates that the regcomp() routine is
4806           available to do some regular pattern matching (usually on "POSIX".2
4807           conforming systems).
4808
4809       "HAS_SETPGID"
4810           This symbol, if defined, indicates that the "setpgid(pid, gpid)"
4811           routine is available to set process group ID.
4812
4813       "HAS_SIGSETJMP"
4814           This variable indicates to the C program that the sigsetjmp()
4815           routine is available to save the calling process's registers and
4816           stack environment for later use by siglongjmp(), and to optionally
4817           save the process's signal mask.  See "Sigjmp_buf", "Sigsetjmp", and
4818           "Siglongjmp".
4819
4820       "HAS_STRUCT_CMSGHDR"
4821           This symbol, if defined, indicates that the "struct cmsghdr" is
4822           supported.
4823
4824       "HAS_STRUCT_MSGHDR"
4825           This symbol, if defined, indicates that the "struct msghdr" is
4826           supported.
4827
4828       "HAS_TGAMMA"
4829           This symbol, if defined, indicates that the "tgamma" routine is
4830           available to do the gamma function. See also "HAS_LGAMMA".
4831
4832       "HAS_UNAME"
4833           This symbol, if defined, indicates that the C program may use the
4834           uname() routine to derive the host name.  See also
4835           "HAS_GETHOSTNAME" and "PHOSTNAME".
4836
4837       "HAS_UNION_SEMUN"
4838           This symbol, if defined, indicates that the "union semun" is
4839           defined by including sys/sem.h.  If not, the user code probably
4840           needs to define it as:
4841
4842            union semun {
4843            int val;
4844            struct semid_ds *buf;
4845            unsigned short *array;
4846            }
4847
4848       "I_DIRENT"
4849           This symbol, if defined, indicates to the C program that it should
4850           include dirent.h. Using this symbol also triggers the definition of
4851           the "Direntry_t" define which ends up being '"struct dirent"' or
4852           '"struct direct"' depending on the availability of dirent.h.
4853
4854            #ifdef I_DIRENT
4855                #include <dirent.h>
4856            #endif
4857
4858       "I_POLL"
4859           This symbol, if defined, indicates that poll.h exists and should be
4860           included. (see also "HAS_POLL")
4861
4862            #ifdef I_POLL
4863                #include <poll.h>
4864            #endif
4865
4866       "I_SYS_RESOURCE"
4867           This symbol, if defined, indicates to the C program that it should
4868           include sys/resource.h.
4869
4870            #ifdef I_SYS_RESOURCE
4871                #include <sys_resource.h>
4872            #endif
4873
4874       "LIBM_LIB_VERSION"
4875           This symbol, if defined, indicates that libm exports "_LIB_VERSION"
4876           and that math.h defines the enum to manipulate it.
4877
4878       "NEED_VA_COPY"
4879           This symbol, if defined, indicates that the system stores the
4880           variable argument list datatype, "va_list", in a format that cannot
4881           be copied by simple assignment, so that some other means must be
4882           used when copying is required.  As such systems vary in their
4883           provision (or non-provision) of copying mechanisms, handy.h defines
4884           a platform- independent macro, "Perl_va_copy(src, dst)", to do the
4885           job.
4886
4887       "OSNAME"
4888           This symbol contains the name of the operating system, as
4889           determined by Configure.  You shouldn't rely on it too much; the
4890           specific feature tests from Configure are generally more reliable.
4891
4892       "OSVERS"
4893           This symbol contains the version of the operating system, as
4894           determined by Configure.  You shouldn't rely on it too much; the
4895           specific feature tests from Configure are generally more reliable.
4896
4897       "PERL_USE_GCC_BRACE_GROUPS"
4898           This C pre-processor value, if defined, indicates that it is
4899           permissible to use the GCC brace groups extension.  However, use of
4900           this extension is DISCOURAGED.  Use a "static inline" function
4901           instead.
4902
4903           The extension, of the form
4904
4905            ({ statement ... })
4906
4907           turns the block consisting of statement ... into an expression with
4908           a value, unlike plain C language blocks.  This can present
4909           optimization possibilities, BUT, unless you know for sure that this
4910           will never be compiled without this extension being available and
4911           not forbidden, you need to specify an alternative.  Thus two code
4912           paths have to be maintained, which can get out-of-sync.  All these
4913           issues are solved by using a "static inline" function instead.
4914
4915           Perl can be configured to not use this feature by passing the
4916           parameter "-Accflags=-DPERL_GCC_BRACE_GROUPS_FORBIDDEN" to
4917           Configure.
4918
4919            #ifdef  PERL_USE_GCC_BRACE_GROUPS
4920
4921       "PHOSTNAME"
4922           This symbol, if defined, indicates the command to feed to the
4923           popen() routine to derive the host name.  See also
4924           "HAS_GETHOSTNAME" and "HAS_UNAME".  Note that the command uses a
4925           fully qualified path, so that it is safe even if used by a process
4926           with super-user privileges.
4927
4928       "PROCSELFEXE_PATH"
4929           If "HAS_PROCSELFEXE" is defined this symbol is the filename of the
4930           symbolic link pointing to the absolute pathname of the executing
4931           program.
4932
4933       "PTRSIZE"
4934           This symbol contains the size of a pointer, so that the C
4935           preprocessor can make decisions based on it.  It will be
4936           "sizeof(void *)" if the compiler supports (void *); otherwise it
4937           will be "sizeof(char *)".
4938
4939       "RANDBITS"
4940           This symbol indicates how many bits are produced by the function
4941           used to generate normalized random numbers.  Values include 15, 16,
4942           31, and 48.
4943
4944       "SELECT_MIN_BITS"
4945           This symbol holds the minimum number of bits operated by select.
4946           That is, if you do "select(n, ...)", how many bits at least will be
4947           cleared in the masks if some activity is detected.  Usually this is
4948           either n or 32*ceil(n/32), especially many little-endians do the
4949           latter.  This is only useful if you have select(), naturally.
4950
4951       "SETUID_SCRIPTS_ARE_SECURE_NOW"
4952           This symbol, if defined, indicates that the bug that prevents
4953           setuid scripts from being secure is not present in this kernel.
4954
4955       "ST_DEV_SIGN"
4956           This symbol holds the signedness of "struct stat"'s "st_dev".  1
4957           for unsigned, -1 for signed.
4958
4959       "ST_DEV_SIZE"
4960           This variable contains the size of "struct stat"'s "st_dev" in
4961           bytes.
4962
4963   List of capability "HAS_foo" symbols
4964       This is a list of those symbols that dont appear elsewhere in ths
4965       document that indicate if the current platform has a certain
4966       capability.  Their names all begin with "HAS_".  Only those symbols
4967       whose capability is directly derived from the name are listed here.
4968       All others have their meaning expanded out elsewhere in this document.
4969       This (relatively) compact list is because we think that the expansion
4970       would add little or no value and take up a lot of space (because there
4971       are so many).  If you think certain ones should be expanded, send email
4972       to perl5-porters@perl.org <mailto:perl5-porters@perl.org>.
4973
4974       Each symbol here will be "#define"d if and only if the platform has the
4975       capability.  If you need more detail, see the corresponding entry in
4976       config.h.  For convenience, the list is split so that the ones that
4977       indicate there is a reentrant version of a capability are listed
4978       separately
4979
4980       "HAS_ACCEPT4",  "HAS_ACCESS",  "HAS_ACCESSX",  "HAS_ACOSH",
4981       "HAS_AINTL",  "HAS_ALARM",  "HAS_ASINH",  "HAS_ATANH",  "HAS_ATOLL",
4982       "HAS_CBRT",  "HAS_CHOWN",  "HAS_CHROOT",  "HAS_CHSIZE",
4983       "HAS_CLEARENV",  "HAS_COPYSIGN",  "HAS_COPYSIGNL",  "HAS_CRYPT",
4984       "HAS_CTERMID",  "HAS_CUSERID",  "HAS_DIRFD",  "HAS_DLADDR",
4985       "HAS_DLERROR",  "HAS_EACCESS",  "HAS_ENDHOSTENT",  "HAS_ENDNETENT",
4986       "HAS_ENDPROTOENT",  "HAS_ENDSERVENT",  "HAS_ERF",  "HAS_ERFC",
4987       "HAS_EXPM1",  "HAS_EXP2",  "HAS_FCHMOD",  "HAS_FCHMODAT",
4988       "HAS_FCHOWN",  "HAS_FDIM",  "HAS_FD_SET",  "HAS_FEGETROUND",
4989       "HAS_FFS",  "HAS_FFSL",  "HAS_FGETPOS",  "HAS_FLOCK",  "HAS_FMA",
4990       "HAS_FMAX",  "HAS_FMIN",  "HAS_FORK",  "HAS_FSEEKO",  "HAS_FSETPOS",
4991       "HAS_FSYNC",  "HAS_FTELLO",  "HAS__FWALK",  "HAS_GAI_STRERROR",
4992       "HAS_GETADDRINFO",  "HAS_GETCWD",  "HAS_GETESPWNAM",  "HAS_GETGROUPS",
4993       "HAS_GETHOSTBYADDR",  "HAS_GETHOSTBYNAME",  "HAS_GETHOSTENT",
4994       "HAS_GETLOGIN",  "HAS_GETNAMEINFO",  "HAS_GETNETBYADDR",
4995       "HAS_GETNETBYNAME",  "HAS_GETNETENT",  "HAS_GETPAGESIZE",
4996       "HAS_GETPGID",  "HAS_GETPGRP",  "HAS_GETPGRP2",  "HAS_GETPPID",
4997       "HAS_GETPRIORITY",  "HAS_GETPROTOBYNAME",  "HAS_GETPROTOBYNUMBER",
4998       "HAS_GETPROTOENT",  "HAS_GETPRPWNAM",  "HAS_GETSERVBYNAME",
4999       "HAS_GETSERVBYPORT",  "HAS_GETSERVENT",  "HAS_GETSPNAM",  "HAS_HTONL",
5000       "HAS_HTONS",  "HAS_HYPOT",  "HAS_ILOGBL",  "HAS_INET_ATON",
5001       "HAS_INETNTOP",  "HAS_INETPTON",  "HAS_IP_MREQ",
5002       "HAS_IP_MREQ_SOURCE",  "HAS_IPV6_MREQ",  "HAS_IPV6_MREQ_SOURCE",
5003       "HAS_ISASCII",  "HAS_ISBLANK",  "HAS_ISLESS",  "HAS_KILLPG",
5004       "HAS_LCHOWN",  "HAS_LINK",  "HAS_LINKAT",  "HAS_LLROUND",
5005       "HAS_LOCKF",  "HAS_LOGB",  "HAS_LOG1P",  "HAS_LOG2",  "HAS_LROUND",
5006       "HAS_LSTAT",  "HAS_MADVISE",  "HAS_MBLEN",  "HAS_MBRLEN",
5007       "HAS_MBRTOWC",  "HAS_MBSTOWCS",  "HAS_MBTOWC",  "HAS_MEMMEM",
5008       "HAS_MEMRCHR",  "HAS_MKDTEMP",  "HAS_MKFIFO",  "HAS_MKOSTEMP",
5009       "HAS_MKSTEMP",  "HAS_MKSTEMPS",  "HAS_MMAP",  "HAS_MPROTECT",
5010       "HAS_MSG",  "HAS_MSYNC",  "HAS_MUNMAP",  "HAS_NEARBYINT",
5011       "HAS_NEXTAFTER",  "HAS_NICE",  "HAS_NTOHL",  "HAS_NTOHS",
5012       "HAS_PATHCONF",  "HAS_PAUSE",  "HAS_PHOSTNAME",  "HAS_PIPE",
5013       "HAS_PIPE2",  "HAS_PRCTL",  "HAS_PTRDIFF_T",  "HAS_READLINK",
5014       "HAS_READV",  "HAS_RECVMSG",  "HAS_REMQUO",  "HAS_RENAME",
5015       "HAS_RENAMEAT",  "HAS_RINT",  "HAS_ROUND",  "HAS_SCALBNL",  "HAS_SEM",
5016       "HAS_SENDMSG",  "HAS_SETEGID",  "HAS_SETENV",  "HAS_SETEUID",
5017       "HAS_SETGROUPS",  "HAS_SETHOSTENT",  "HAS_SETLINEBUF",
5018       "HAS_SETNETENT",  "HAS_SETPGRP",  "HAS_SETPGRP2",  "HAS_SETPRIORITY",
5019       "HAS_SETPROCTITLE",  "HAS_SETPROTOENT",  "HAS_SETREGID",
5020       "HAS_SETRESGID",  "HAS_SETRESUID",  "HAS_SETREUID",  "HAS_SETRGID",
5021       "HAS_SETRUID",  "HAS_SETSERVENT",  "HAS_SETSID",  "HAS_SHM",
5022       "HAS_SIGACTION",  "HAS_SIGPROCMASK",  "HAS_SIN6_SCOPE_ID",
5023       "HAS_SNPRINTF",  "HAS_STAT",  "HAS_STRCOLL",  "HAS_STRERROR_L",
5024       "HAS_STRLCAT",  "HAS_STRLCPY",  "HAS_STRNLEN",  "HAS_STRTOD",
5025       "HAS_STRTOL",  "HAS_STRTOLL",  "HAS_STRTOQ",  "HAS_STRTOUL",
5026       "HAS_STRTOULL",  "HAS_STRTOUQ",  "HAS_STRXFRM",  "HAS_STRXFRM_L",
5027       "HAS_SYMLINK",  "HAS_SYSCALL",  "HAS_SYSCONF",  "HAS_SYS_ERRLIST",
5028       "HAS_SYSTEM",  "HAS_TCGETPGRP",  "HAS_TCSETPGRP",  "HAS_TOWLOWER",
5029       "HAS_TOWUPPER",  "HAS_TRUNCATE",  "HAS_TRUNCL",  "HAS_UALARM",
5030       "HAS_UMASK",  "HAS_UNLINKAT",  "HAS_UNSETENV",  "HAS_VFORK",
5031       "HAS_VSNPRINTF",  "HAS_WAITPID",  "HAS_WAIT4",  "HAS_WCRTOMB",
5032       "HAS_WCSCMP",  "HAS_WCSTOMBS",  "HAS_WCSXFRM",  "HAS_WCTOMB",
5033       "HAS_WRITEV"
5034
5035       And, the reentrant capabilities:
5036
5037       "HAS_CRYPT_R",  "HAS_CTERMID_R",  "HAS_DRAND48_R",
5038       "HAS_ENDHOSTENT_R",  "HAS_ENDNETENT_R",  "HAS_ENDPROTOENT_R",
5039       "HAS_ENDSERVENT_R",  "HAS_GETGRGID_R",  "HAS_GETGRNAM_R",
5040       "HAS_GETHOSTBYADDR_R",  "HAS_GETHOSTBYNAME_R",  "HAS_GETHOSTENT_R",
5041       "HAS_GETLOGIN_R",  "HAS_GETNETBYADDR_R",  "HAS_GETNETBYNAME_R",
5042       "HAS_GETNETENT_R",  "HAS_GETPROTOBYNAME_R",  "HAS_GETPROTOBYNUMBER_R",
5043       "HAS_GETPROTOENT_R",  "HAS_GETPWNAM_R",  "HAS_GETPWUID_R",
5044       "HAS_GETSERVBYNAME_R",  "HAS_GETSERVBYPORT_R",  "HAS_GETSERVENT_R",
5045       "HAS_GETSPNAM_R",  "HAS_RANDOM_R",  "HAS_READDIR_R",
5046       "HAS_SETHOSTENT_R",  "HAS_SETNETENT_R",  "HAS_SETPROTOENT_R",
5047       "HAS_SETSERVENT_R",  "HAS_SRANDOM_R",  "HAS_SRAND48_R",
5048       "HAS_STRERROR_R",  "HAS_TMPNAM_R",  "HAS_TTYNAME_R"
5049
5050       Example usage:
5051
5052        #ifdef HAS_STRNLEN
5053          use strnlen()
5054        #else
5055          use an alternative implementation
5056        #endif
5057
5058   List of "#include" needed symbols
5059       This list contains symbols that indicate if certain "#include" files
5060       are present on the platform.  If your code accesses the functionality
5061       that one of these is for, you will need to "#include" it if the symbol
5062       on this list is "#define"d.  For more detail, see the corresponding
5063       entry in config.h.
5064
5065       "I_ARPA_INET",  "I_BFD",  "I_CRYPT",  "I_DBM",  "I_DLFCN",
5066       "I_EXECINFO",  "I_FP",  "I_FP_CLASS",  "I_GDBM",  "I_GDBMNDBM",
5067       "I_GDBM_NDBM",  "I_GRP",  "I_IEEEFP",  "I_INTTYPES",  "I_LIBUTIL",
5068       "I_MNTENT",  "I_NDBM",  "I_NETDB",  "I_NET_ERRNO",  "I_NETINET_IN",
5069       "I_NETINET_TCP",  "I_PROT",  "I_PWD",  "I_RPCSVC_DBM",  "I_SGTTY",
5070       "I_SHADOW",  "I_STDBOOL",  "I_STDINT",  "I_SUNMATH",  "I_SYS_ACCESS",
5071       "I_SYS_IOCTL",  "I_SYSLOG",  "I_SYSMODE",  "I_SYS_MOUNT",
5072       "I_SYS_PARAM",  "I_SYS_POLL",  "I_SYS_SECURITY",  "I_SYS_SELECT",
5073       "I_SYS_STAT",  "I_SYS_STATVFS",  "I_SYS_SYSCALL",  "I_SYS_TIME",
5074       "I_SYS_TIME_KERNEL",  "I_SYS_TIMES",  "I_SYS_TYPES",  "I_SYSUIO",
5075       "I_SYS_UN",  "I_SYSUTSNAME",  "I_SYS_VFS",  "I_SYS_WAIT",  "I_TERMIO",
5076       "I_TERMIOS",  "I_UNISTD",  "I_USTAT",  "I_VFORK",  "I_WCHAR",
5077       "I_WCTYPE"
5078
5079       Example usage:
5080
5081        #ifdef I_WCHAR
5082          #include <wchar.h>
5083        #endif
5084

Global Variables

5086       These variables are global to an entire process.  They are shared
5087       between all interpreters and all threads in a process.  Any variables
5088       not documented here may be changed or removed without notice, so don't
5089       use them!  If you feel you really do need to use an unlisted variable,
5090       first send email to perl5-porters@perl.org
5091       <mailto:perl5-porters@perl.org>.  It may be that someone there will
5092       point out a way to accomplish what you need without using an internal
5093       variable.  But if not, you should get a go-ahead to document and then
5094       use the variable.
5095
5096       "PL_check"
5097           Array, indexed by opcode, of functions that will be called for the
5098           "check" phase of optree building during compilation of Perl code.
5099           For most (but not all) types of op, once the op has been initially
5100           built and populated with child ops it will be filtered through the
5101           check function referenced by the appropriate element of this array.
5102           The new op is passed in as the sole argument to the check function,
5103           and the check function returns the completed op.  The check
5104           function may (as the name suggests) check the op for validity and
5105           signal errors.  It may also initialise or modify parts of the ops,
5106           or perform more radical surgery such as adding or removing child
5107           ops, or even throw the op away and return a different op in its
5108           place.
5109
5110           This array of function pointers is a convenient place to hook into
5111           the compilation process.  An XS module can put its own custom check
5112           function in place of any of the standard ones, to influence the
5113           compilation of a particular type of op.  However, a custom check
5114           function must never fully replace a standard check function (or
5115           even a custom check function from another module).  A module
5116           modifying checking must instead wrap the preexisting check
5117           function.  A custom check function must be selective about when to
5118           apply its custom behaviour.  In the usual case where it decides not
5119           to do anything special with an op, it must chain the preexisting op
5120           function.  Check functions are thus linked in a chain, with the
5121           core's base checker at the end.
5122
5123           For thread safety, modules should not write directly to this array.
5124           Instead, use the function "wrap_op_checker".
5125
5126       "PL_infix_plugin"
5127           NOTE: "PL_infix_plugin" is experimental and may change or be
5128           removed without notice.
5129
5130           NOTE: This API exists entirely for the purpose of making the CPAN
5131           module "XS::Parse::Infix" work. It is not expected that additional
5132           modules will make use of it; rather, that they should use
5133           "XS::Parse::Infix" to provide parsing of new infix operators.
5134
5135           Function pointer, pointing at a function used to handle extended
5136           infix operators. The function should be declared as
5137
5138                   int infix_plugin_function(pTHX_
5139                           char *opname, STRLEN oplen,
5140                           struct Perl_custom_infix **infix_ptr)
5141
5142           The function is called from the tokenizer whenever a possible infix
5143           operator is seen. "opname" points to the operator name in the
5144           parser's input buffer, and "oplen" gives the maximum number of
5145           bytes of it that should be consumed; it is not null-terminated. The
5146           function is expected to examine the operator name and possibly
5147           other state such as %^H, to determine whether it wants to handle
5148           the operator name.
5149
5150           As compared to the single stage of "PL_keyword_plugin", parsing of
5151           additional infix operators occurs in three separate stages. This is
5152           because of the more complex interactions it has with the parser, to
5153           ensure that operator precedence rules work correctly. These stages
5154           are co-ordinated by the use of an additional information structure.
5155
5156           If the function wants to handle the infix operator, it must set the
5157           variable pointed to by "infix_ptr" to the address of a structure
5158           that provides this additional information about the subsequent
5159           parsing stages. If it does not, it should make a call to the next
5160           function in the chain.
5161
5162           This structure has the following definition:
5163
5164                   struct Perl_custom_infix {
5165                       enum Perl_custom_infix_precedence prec;
5166                       void (*parse)(pTHX_ SV **opdata,
5167                           struct Perl_custom_infix *);
5168                       OP *(*build_op)(pTHX_ SV **opdata, OP *lhs, OP *rhs,
5169                           struct Perl_custom_infix *);
5170                   };
5171
5172           The function must then return an integer giving the number of bytes
5173           consumed by the name of this operator. In the case of an operator
5174           whose name is composed of identifier characters, this must be equal
5175           to "oplen". In the case of an operator named by non-identifier
5176           characters, this is permitted to be shorter than "oplen", and any
5177           additional characters after it will not be claimed by the infix
5178           operator but instead will be consumed by the tokenizer and parser
5179           as normal.
5180
5181           If the optional "parse" function is provided, it is called
5182           immediately by the parser to let the operator's definition consume
5183           any additional syntax from the source code. This should not be used
5184           for normal operand parsing, but it may be useful when implementing
5185           things like parametric operators or meta-operators that consume
5186           more syntax themselves. This function may use the variable pointed
5187           to by "opdata" to provide an SV containing additional data to be
5188           passed into the "build_op" function later on.
5189
5190           The information structure gives the operator precedence level in
5191           the "prec" field. This is used to tell the parser how much of the
5192           surrounding syntax before and after should be considered as
5193           operands to the operator.
5194
5195           The tokenizer and parser will then continue to operate as normal
5196           until enough additional input has been parsed to form both the
5197           left- and right-hand side operands to the operator, according to
5198           the precedence level. At this point the "build_op" function is
5199           called, being passed the left- and right-hand operands as optree
5200           fragments. It is expected to combine them into the resulting optree
5201           fragment, which it should return.
5202
5203           After the "build_op" function has returned, if the variable pointed
5204           to by "opdata" was set to a non-"NULL" value, it will then be
5205           destroyed by calling SvREFCNT_dec().
5206
5207           For thread safety, modules should not set this variable directly.
5208           Instead, use the function "wrap_infix_plugin".
5209
5210           However, that all said, the introductory note above still applies.
5211           This variable is provided in core perl only for the benefit of the
5212           "XS::Parse::Infix" module. That module acts as a central registry
5213           for infix operators, automatically handling things like deparse
5214           support and discovery/reflection, and these abilities only work
5215           because it knows all the registered operators. Other modules should
5216           not use this interpreter variable directly to implement them
5217           because then those central features would no longer work properly.
5218
5219           Furthermore, it is likely that this (experimental) API will be
5220           replaced in a future Perl version by a more complete API that fully
5221           implements the central registry and other semantics currently
5222           provided by "XS::Parse::Infix", once the module has had sufficient
5223           experimental testing time. This current mechanism exists only as an
5224           interim measure to get to that stage.
5225
5226       "PL_keyword_plugin"
5227           NOTE: "PL_keyword_plugin" is experimental and may change or be
5228           removed without notice.
5229
5230           Function pointer, pointing at a function used to handle extended
5231           keywords.  The function should be declared as
5232
5233                   int keyword_plugin_function(pTHX_
5234                           char *keyword_ptr, STRLEN keyword_len,
5235                           OP **op_ptr)
5236
5237           The function is called from the tokeniser, whenever a possible
5238           keyword is seen.  "keyword_ptr" points at the word in the parser's
5239           input buffer, and "keyword_len" gives its length; it is not null-
5240           terminated.  The function is expected to examine the word, and
5241           possibly other state such as %^H, to decide whether it wants to
5242           handle it as an extended keyword.  If it does not, the function
5243           should return "KEYWORD_PLUGIN_DECLINE", and the normal parser
5244           process will continue.
5245
5246           If the function wants to handle the keyword, it first must parse
5247           anything following the keyword that is part of the syntax
5248           introduced by the keyword.  See "Lexer interface" for details.
5249
5250           When a keyword is being handled, the plugin function must build a
5251           tree of "OP" structures, representing the code that was parsed.
5252           The root of the tree must be stored in *op_ptr.  The function then
5253           returns a constant indicating the syntactic role of the construct
5254           that it has parsed: "KEYWORD_PLUGIN_STMT" if it is a complete
5255           statement, or "KEYWORD_PLUGIN_EXPR" if it is an expression.  Note
5256           that a statement construct cannot be used inside an expression
5257           (except via "do BLOCK" and similar), and an expression is not a
5258           complete statement (it requires at least a terminating semicolon).
5259
5260           When a keyword is handled, the plugin function may also have
5261           (compile-time) side effects.  It may modify "%^H", define
5262           functions, and so on.  Typically, if side effects are the main
5263           purpose of a handler, it does not wish to generate any ops to be
5264           included in the normal compilation.  In this case it is still
5265           required to supply an op tree, but it suffices to generate a single
5266           null op.
5267
5268           That's how the *PL_keyword_plugin function needs to behave overall.
5269           Conventionally, however, one does not completely replace the
5270           existing handler function.  Instead, take a copy of
5271           "PL_keyword_plugin" before assigning your own function pointer to
5272           it.  Your handler function should look for keywords that it is
5273           interested in and handle those.  Where it is not interested, it
5274           should call the saved plugin function, passing on the arguments it
5275           received.  Thus "PL_keyword_plugin" actually points at a chain of
5276           handler functions, all of which have an opportunity to handle
5277           keywords, and only the last function in the chain (built into the
5278           Perl core) will normally return "KEYWORD_PLUGIN_DECLINE".
5279
5280           For thread safety, modules should not set this variable directly.
5281           Instead, use the function "wrap_keyword_plugin".
5282
5283       "PL_phase"
5284           A value that indicates the current Perl interpreter's phase.
5285           Possible values include "PERL_PHASE_CONSTRUCT", "PERL_PHASE_START",
5286           "PERL_PHASE_CHECK", "PERL_PHASE_INIT", "PERL_PHASE_RUN",
5287           "PERL_PHASE_END", and "PERL_PHASE_DESTRUCT".
5288
5289           For example, the following determines whether the interpreter is in
5290           global destruction:
5291
5292               if (PL_phase == PERL_PHASE_DESTRUCT) {
5293                   // we are in global destruction
5294               }
5295
5296           "PL_phase" was introduced in Perl 5.14; in prior perls you can use
5297           "PL_dirty" (boolean) to determine whether the interpreter is in
5298           global destruction. (Use of "PL_dirty" is discouraged since 5.14.)
5299
5300            enum perl_phase  PL_phase
5301

GV Handling and Stashes

5303       A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
5304       It is a structure that holds a pointer to a scalar, an array, a hash
5305       etc, corresponding to $foo, @foo, %foo.
5306
5307       GVs are usually found as values in stashes (symbol table hashes) where
5308       Perl stores its global variables.
5309
5310       A stash is a hash that contains all variables that are defined within a
5311       package.  See "Stashes and Globs" in perlguts
5312
5313       "amagic_call"
5314           Perform the overloaded (active magic) operation given by "method".
5315           "method" is one of the values found in overload.h.
5316
5317           "flags" affects how the operation is performed, as follows:
5318
5319           "AMGf_noleft"
5320               "left" is not to be used in this operation.
5321
5322           "AMGf_noright"
5323               "right" is not to be used in this operation.
5324
5325           "AMGf_unary"
5326               The operation is done only on just one operand.
5327
5328           "AMGf_assign"
5329               The operation changes one of the operands, e.g., $x += 1
5330
5331            SV *  amagic_call(SV *left, SV *right, int method, int dir)
5332
5333       "amagic_deref_call"
5334           Perform "method" overloading dereferencing on "ref", returning the
5335           dereferenced result.  "method" must be one of the dereference
5336           operations given in overload.h.
5337
5338           If overloading is inactive on "ref", returns "ref" itself.
5339
5340            SV *  amagic_deref_call(SV *ref, int method)
5341
5342       "gv_add_by_type"
5343           Make sure there is a slot of type "type" in the GV "gv".
5344
5345            GV *  gv_add_by_type(GV *gv, svtype type)
5346
5347       "Gv_AMupdate"
5348           Recalculates overload magic in the package given by "stash".
5349
5350           Returns:
5351
5352           1 on success and there is some overload
5353           0 if there is no overload
5354           -1 if some error occurred and it couldn't croak (because
5355           "destructing" is true).
5356
5357            int  Gv_AMupdate(HV *stash, bool destructing)
5358
5359       "gv_autoload_pv"
5360       "gv_autoload_pvn"
5361       "gv_autoload_sv"
5362           These each search for an "AUTOLOAD" method, returning NULL if not
5363           found, or else returning a pointer to its GV, while setting the
5364           package $AUTOLOAD variable to "name" (fully qualified).  Also, if
5365           found and the GV's CV is an XSUB, the CV's PV will be set to
5366           "name", and its stash will be set to the stash of the GV.
5367
5368           Searching is done in "MRO" order, as specified in ""gv_fetchmeth"",
5369           beginning with "stash" if it isn't NULL.
5370
5371           The forms differ only in how "name" is specified.
5372
5373           In "gv_autoload_pv", "namepv" is a C language NUL-terminated
5374           string.
5375
5376           In "gv_autoload_pvn", "name" points to the first byte of the name,
5377           and an additional parameter, "len", specifies its length in bytes.
5378           Hence, *name may contain embedded-NUL characters.
5379
5380           In "gv_autoload_sv", *namesv is an SV, and the name is the PV
5381           extracted from that using ""SvPV"".  If the SV is marked as being
5382           in UTF-8, the extracted PV will also be.
5383
5384            GV *  gv_autoload_pv (HV *stash, const char *namepv, U32 flags)
5385            GV *  gv_autoload_pvn(HV *stash, const char *name, STRLEN len,
5386                                  U32 flags)
5387            GV *  gv_autoload_sv (HV *stash, SV *namesv, U32 flags)
5388
5389       "gv_autoload4"
5390           Equivalent to "gv_autoload_pvn".
5391
5392            GV *  gv_autoload4(HV *stash, const char *name, STRLEN len,
5393                               I32 method)
5394
5395       "GvAV"
5396           Return the AV from the GV.
5397
5398            AV*  GvAV(GV* gv)
5399
5400       "gv_AVadd"
5401       "gv_HVadd"
5402       "gv_IOadd"
5403       "gv_SVadd"
5404           Make sure there is a slot of the given type (AV, HV, IO, SV) in the
5405           GV "gv".
5406
5407            GV *  gv_AVadd(GV *gv)
5408
5409       "gv_const_sv"
5410           If "gv" is a typeglob whose subroutine entry is a constant sub
5411           eligible for inlining, or "gv" is a placeholder reference that
5412           would be promoted to such a typeglob, then returns the value
5413           returned by the sub.  Otherwise, returns "NULL".
5414
5415            SV *  gv_const_sv(GV *gv)
5416
5417       "GvCV"
5418           Return the CV from the GV.
5419
5420            CV*  GvCV(GV* gv)
5421
5422       "gv_efullname3"
5423       "gv_efullname4"
5424       "gv_fullname3"
5425       "gv_fullname4"
5426           Place the full package name of "gv" into "sv".  The "gv_e*" forms
5427           return instead the effective package name (see "HvENAME").
5428
5429           If "prefix" is non-NULL, it is considered to be a C language NUL-
5430           terminated string, and the stored name will be prefaced with it.
5431
5432           The other difference between the functions is that the *4 forms
5433           have an extra parameter, "keepmain".  If "true" an initial "main::"
5434           in the name is kept; if "false" it is stripped.  With the *3 forms,
5435           it is always kept.
5436
5437            void  gv_efullname3(SV *sv, const GV *gv, const char *prefix)
5438            void  gv_efullname4(SV *sv, const GV *gv, const char *prefix,
5439                                bool keepmain)
5440            void  gv_fullname3 (SV *sv, const GV *gv, const char *prefix)
5441            void  gv_fullname4 (SV *sv, const GV *gv, const char *prefix,
5442                                bool keepmain)
5443
5444       "gv_fetchfile"
5445       "gv_fetchfile_flags"
5446           These return the debugger glob for the file (compiled by Perl)
5447           whose name is given by the "name" parameter.
5448
5449           There are currently exactly two differences between these
5450           functions.
5451
5452           The "name" parameter to "gv_fetchfile" is a C string, meaning it is
5453           "NUL"-terminated; whereas the "name" parameter to
5454           "gv_fetchfile_flags" is a Perl string, whose length (in bytes) is
5455           passed in via the "namelen" parameter This means the name may
5456           contain embedded "NUL" characters.  "namelen" doesn't exist in
5457           plain "gv_fetchfile").
5458
5459           The other difference is that "gv_fetchfile_flags" has an extra
5460           "flags" parameter, which is currently completely ignored, but
5461           allows for possible future extensions.
5462
5463            GV *  gv_fetchfile      (const char *name)
5464            GV *  gv_fetchfile_flags(const char * const name,
5465                                     const STRLEN len, const U32 flags)
5466
5467       "gv_fetchmeth"
5468       "gv_fetchmeth_pv"
5469       "gv_fetchmeth_pvn"
5470       "gv_fetchmeth_sv"
5471           These each look for a glob with name "name", containing a defined
5472           subroutine, returning the GV of that glob if found, or "NULL" if
5473           not.
5474
5475           "stash" is always searched (first), unless it is "NULL".
5476
5477           If "stash" is NULL, or was searched but nothing was found in it,
5478           and the "GV_SUPER" bit is set in "flags", stashes accessible via
5479           @ISA are searched next.  Searching is conducted according to "MRO"
5480           order.
5481
5482           Finally, if no matches were found so far, and the "GV_NOUNIVERSAL"
5483           flag in "flags" is not set,  "UNIVERSAL::" is searched.
5484
5485           The argument "level" should be either 0 or -1.  If -1, the function
5486           will return without any side effects or caching.  If 0, the
5487           function makes sure there is a glob named "name" in "stash",
5488           creating one if necessary.  The subroutine slot in the glob will be
5489           set to any subroutine found in the "stash" and "SUPER::" search,
5490           hence caching any "SUPER::" result.  Note that subroutines found in
5491           "UNIVERSAL::" are not cached.
5492
5493           The GV returned from these may be a method cache entry, which is
5494           not visible to Perl code.  So when calling "call_sv", you should
5495           not use the GV directly; instead, you should use the method's CV,
5496           which can be obtained from the GV with the "GvCV" macro.
5497
5498           The only other significant value for "flags" is "SVf_UTF8",
5499           indicating that "name" is to be treated as being encoded in UTF-8.
5500
5501           Plain "gv_fetchmeth" lacks a "flags" parameter, hence always
5502           searches in "stash", then "UNIVERSAL::", and "name" is never UTF-8.
5503           Otherwise it is exactly like "gv_fetchmeth_pvn".
5504
5505           The other forms do have a "flags" parameter, and differ only in how
5506           the glob name is specified.
5507
5508           In "gv_fetchmeth_pv", "name" is a C language NUL-terminated string.
5509
5510           In "gv_fetchmeth_pvn", "name" points to the first byte of the name,
5511           and an additional parameter, "len", specifies its length in bytes.
5512           Hence, the name may contain embedded-NUL characters.
5513
5514           In "gv_fetchmeth_sv", *name is an SV, and the name is the PV
5515           extracted from that, using ""SvPV"".  If the SV is marked as being
5516           in UTF-8, the extracted PV will also be.
5517
5518            GV *  gv_fetchmeth    (HV *stash, const char *name, STRLEN len,
5519                                   I32 level)
5520            GV *  gv_fetchmeth_pv (HV *stash, const char *name, I32 level,
5521                                   U32 flags)
5522            GV *  gv_fetchmeth_pvn(HV *stash, const char *name, STRLEN len,
5523                                   I32 level, U32 flags)
5524            GV *  gv_fetchmeth_sv (HV *stash, SV *namesv, I32 level,
5525                                   U32 flags)
5526
5527       "gv_fetchmeth_autoload"
5528           This is the old form of "gv_fetchmeth_pvn_autoload", which has no
5529           flags parameter.
5530
5531            GV *  gv_fetchmeth_autoload(HV *stash, const char *name,
5532                                        STRLEN len, I32 level)
5533
5534       "gv_fetchmethod"
5535           See "gv_fetchmethod_autoload".
5536
5537            GV *  gv_fetchmethod(HV *stash, const char *name)
5538
5539       "gv_fetchmethod_autoload"
5540           Returns the glob which contains the subroutine to call to invoke
5541           the method on the "stash".  In fact in the presence of autoloading
5542           this may be the glob for "AUTOLOAD".  In this case the
5543           corresponding variable $AUTOLOAD is already setup.
5544
5545           The third parameter of "gv_fetchmethod_autoload" determines whether
5546           AUTOLOAD lookup is performed if the given method is not present:
5547           non-zero means yes, look for AUTOLOAD; zero means no, don't look
5548           for AUTOLOAD.  Calling "gv_fetchmethod" is equivalent to calling
5549           "gv_fetchmethod_autoload" with a non-zero "autoload" parameter.
5550
5551           These functions grant "SUPER" token as a prefix of the method name.
5552           Note that if you want to keep the returned glob for a long time,
5553           you need to check for it being "AUTOLOAD", since at the later time
5554           the call may load a different subroutine due to $AUTOLOAD changing
5555           its value.  Use the glob created as a side effect to do this.
5556
5557           These functions have the same side-effects as "gv_fetchmeth" with
5558           "level==0".  The warning against passing the GV returned by
5559           "gv_fetchmeth" to "call_sv" applies equally to these functions.
5560
5561            GV *  gv_fetchmethod_autoload(HV *stash, const char *name,
5562                                          I32 autoload)
5563
5564       "gv_fetchmeth_pv_autoload"
5565           Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-
5566           terminated string instead of a string/length pair.
5567
5568            GV *  gv_fetchmeth_pv_autoload(HV *stash, const char *name,
5569                                           I32 level, U32 flags)
5570
5571       "gv_fetchmeth_pvn_autoload"
5572           Same as gv_fetchmeth_pvn(), but looks for autoloaded subroutines
5573           too.  Returns a glob for the subroutine.
5574
5575           For an autoloaded subroutine without a GV, will create a GV even if
5576           "level < 0".  For an autoloaded subroutine without a stub, GvCV()
5577           of the result may be zero.
5578
5579           Currently, the only significant value for "flags" is "SVf_UTF8".
5580
5581            GV *  gv_fetchmeth_pvn_autoload(HV *stash, const char *name,
5582                                            STRLEN len, I32 level, U32 flags)
5583
5584       "gv_fetchmeth_sv_autoload"
5585           Exactly like "gv_fetchmeth_pvn_autoload", but takes the name string
5586           in the form of an SV instead of a string/length pair.
5587
5588            GV *  gv_fetchmeth_sv_autoload(HV *stash, SV *namesv, I32 level,
5589                                           U32 flags)
5590
5591       "gv_fetchpv"
5592       "gv_fetchpvn"
5593       "gv_fetchpvn_flags"
5594       "gv_fetchpvs"
5595       "gv_fetchsv"
5596       "gv_fetchsv_nomg"
5597           These all return the GV of type "sv_type" whose name is given by
5598           the inputs, or NULL if no GV of that name and type could be found.
5599           See "Stashes and Globs" in perlguts.
5600
5601           The only differences are how the input name is specified, and if
5602           'get' magic is normally used in getting that name.
5603
5604           Don't be fooled by the fact that only one form has "flags" in its
5605           name.  They all have a "flags" parameter in fact, and all the flag
5606           bits have the same meanings for all
5607
5608           If any of the flags "GV_ADD", "GV_ADDMG", "GV_ADDWARN",
5609           "GV_ADDMULTI", or "GV_NOINIT" is set, a GV is created if none
5610           already exists for the input name and type.  However, "GV_ADDMG"
5611           will only do the creation for magical GV's.  For all of these flags
5612           except "GV_NOINIT", "gv_init_pvn" is called after the addition.
5613           "GV_ADDWARN" is used when the caller expects that adding won't be
5614           necessary because the symbol should already exist; but if not, add
5615           it anyway, with a warning that it was unexpectedly absent.  The
5616           "GV_ADDMULTI" flag means to pretend that the GV has been seen
5617           before (i.e., suppress "Used once" warnings).
5618
5619           The flag "GV_NOADD_NOINIT" causes "gv_init_pvn" not be to called if
5620           the GV existed but isn't PVGV.
5621
5622           If the "SVf_UTF8" bit is set, the name is treated as being encoded
5623           in UTF-8; otherwise the name won't be considered to be UTF-8 in the
5624           "pv"-named forms, and the UTF-8ness of the underlying SVs will be
5625           used in the "sv" forms.
5626
5627           If the flag "GV_NOTQUAL" is set, the caller warrants that the input
5628           name is a plain symbol name, not qualified with a package,
5629           otherwise the name is checked for being a qualified one.
5630
5631           In "gv_fetchpv", "nambeg" is a C string, NUL-terminated with no
5632           intermediate NULs.
5633
5634           In "gv_fetchpvs", "name" is a literal C string, hence is enclosed
5635           in double quotes.
5636
5637           "gv_fetchpvn" and "gv_fetchpvn_flags" are identical.  In these,
5638           <nambeg> is a Perl string whose byte length is given by "full_len",
5639           and may contain embedded NULs.
5640
5641           In "gv_fetchsv" and "gv_fetchsv_nomg", the name is extracted from
5642           the PV of the input "name" SV.  The only difference between these
5643           two forms is that 'get' magic is normally done on "name" in
5644           "gv_fetchsv", and always skipped with "gv_fetchsv_nomg".  Including
5645           "GV_NO_SVGMAGIC" in the "flags" parameter to "gv_fetchsv" makes it
5646           behave identically to "gv_fetchsv_nomg".
5647
5648            GV *  gv_fetchpv       (const char *nambeg, I32 flags,
5649                                    const svtype sv_type)
5650            GV *  gv_fetchpvn      (const char * nambeg, STRLEN full_len,
5651                                    I32 flags, const svtype sv_type)
5652            GV *  gv_fetchpvn_flags(const char *name, STRLEN len, I32 flags,
5653                                    const svtype sv_type)
5654            GV *  gv_fetchpvs      ("name", I32 flags, const svtype sv_type)
5655            GV *  gv_fetchsv       (SV *name, I32 flags, const svtype sv_type)
5656            GV *  gv_fetchsv_nomg  (SV *name, I32 flags, const svtype sv_type)
5657
5658       "GvHV"
5659           Return the HV from the GV.
5660
5661            HV*  GvHV(GV* gv)
5662
5663       "gv_init"
5664           The old form of gv_init_pvn().  It does not work with UTF-8
5665           strings, as it has no flags parameter.  If the "multi" parameter is
5666           set, the "GV_ADDMULTI" flag will be passed to gv_init_pvn().
5667
5668            void  gv_init(GV *gv, HV *stash, const char *name, STRLEN len,
5669                          int multi)
5670
5671       "gv_init_pv"
5672           Same as gv_init_pvn(), but takes a nul-terminated string for the
5673           name instead of separate char * and length parameters.
5674
5675            void  gv_init_pv(GV *gv, HV *stash, const char *name, U32 flags)
5676
5677       "gv_init_pvn"
5678           Converts a scalar into a typeglob.  This is an incoercible
5679           typeglob; assigning a reference to it will assign to one of its
5680           slots, instead of overwriting it as happens with typeglobs created
5681           by "SvSetSV".  Converting any scalar that is SvOK() may produce
5682           unpredictable results and is reserved for perl's internal use.
5683
5684           "gv" is the scalar to be converted.
5685
5686           "stash" is the parent stash/package, if any.
5687
5688           "name" and "len" give the name.  The name must be unqualified; that
5689           is, it must not include the package name.  If "gv" is a stash
5690           element, it is the caller's responsibility to ensure that the name
5691           passed to this function matches the name of the element.  If it
5692           does not match, perl's internal bookkeeping will get out of sync.
5693
5694           "flags" can be set to "SVf_UTF8" if "name" is a UTF-8 string, or
5695           the return value of SvUTF8(sv).  It can also take the "GV_ADDMULTI"
5696           flag, which means to pretend that the GV has been seen before
5697           (i.e., suppress "Used once" warnings).
5698
5699            void  gv_init_pvn(GV *gv, HV *stash, const char *name, STRLEN len,
5700                              U32 flags)
5701
5702       "gv_init_sv"
5703           Same as gv_init_pvn(), but takes an SV * for the name instead of
5704           separate char * and length parameters.  "flags" is currently
5705           unused.
5706
5707            void  gv_init_sv(GV *gv, HV *stash, SV *namesv, U32 flags)
5708
5709       "gv_name_set"
5710           Set the name for GV "gv" to "name" which is "len" bytes long.  Thus
5711           it may contain embedded NUL characters.
5712
5713           If "flags" contains "SVf_UTF8", the name is treated as being
5714           encoded in UTF-8; otherwise not.
5715
5716            void  gv_name_set(GV *gv, const char *name, U32 len, U32 flags)
5717
5718       "gv_stashpv"
5719           Returns a pointer to the stash for a specified package.  Uses
5720           "strlen" to determine the length of "name", then calls
5721           gv_stashpvn().
5722
5723            HV *  gv_stashpv(const char *name, I32 flags)
5724
5725       "gv_stashpvn"
5726           Returns a pointer to the stash for a specified package.  The
5727           "namelen" parameter indicates the length of the "name", in bytes.
5728           "flags" is passed to gv_fetchpvn_flags(), so if set to "GV_ADD"
5729           then the package will be created if it does not already exist.  If
5730           the package does not exist and "flags" is 0 (or any other setting
5731           that does not create packages) then "NULL" is returned.
5732
5733           Flags may be one of:
5734
5735            GV_ADD           Create and initialize the package if doesn't
5736                             already exist
5737            GV_NOADD_NOINIT  Don't create the package,
5738            GV_ADDMG         GV_ADD iff the GV is magical
5739            GV_NOINIT        GV_ADD, but don't initialize
5740            GV_NOEXPAND      Don't expand SvOK() entries to PVGV
5741            SVf_UTF8         The name is in UTF-8
5742
5743           The most important of which are probably "GV_ADD" and "SVf_UTF8".
5744
5745           Note, use of "gv_stashsv" instead of "gv_stashpvn" where possible
5746           is strongly recommended for performance reasons.
5747
5748            HV *  gv_stashpvn(const char *name, U32 namelen, I32 flags)
5749
5750       "gv_stashpvs"
5751           Like "gv_stashpvn", but takes a literal string instead of a
5752           string/length pair.
5753
5754            HV*  gv_stashpvs("name", I32 create)
5755
5756       "gv_stashsv"
5757           Returns a pointer to the stash for a specified package.  See
5758           "gv_stashpvn".
5759
5760           Note this interface is strongly preferred over "gv_stashpvn" for
5761           performance reasons.
5762
5763            HV *  gv_stashsv(SV *sv, I32 flags)
5764
5765       "GvSV"
5766           Return the SV from the GV.
5767
5768           Prior to Perl v5.9.3, this would add a scalar if none existed.
5769           Nowadays, use "GvSVn" for that, or compile perl with
5770           "-DPERL_CREATE_GVSV".  See perl5100delta.
5771
5772            SV*  GvSV(GV* gv)
5773
5774       "GvSVn"
5775           Like "GvSV", but creates an empty scalar if none already exists.
5776
5777            SV*  GvSVn(GV* gv)
5778
5779       "newGVgen"
5780       "newGVgen_flags"
5781           Create a new, guaranteed to be unique, GV in the package given by
5782           the NUL-terminated C language string "pack", and return a pointer
5783           to it.
5784
5785           For "newGVgen" or if "flags" in "newGVgen_flags" is 0, "pack" is to
5786           be considered to be encoded in Latin-1.  The only other legal
5787           "flags" value is "SVf_UTF8", which indicates "pack" is to be
5788           considered to be encoded in UTF-8.
5789
5790            GV *  newGVgen      (const char *pack)
5791            GV *  newGVgen_flags(const char *pack, U32 flags)
5792
5793       "PL_curstash"
5794           The stash for the package code will be compiled into.
5795
5796           On threaded perls, each thread has an independent copy of this
5797           variable; each initialized at creation time with the current value
5798           of the creating thread's copy.
5799
5800            HV*  PL_curstash
5801
5802       "PL_defgv"
5803           The GV representing *_.  Useful for access to $_.
5804
5805           On threaded perls, each thread has an independent copy of this
5806           variable; each initialized at creation time with the current value
5807           of the creating thread's copy.
5808
5809            GV *  PL_defgv
5810
5811       "PL_defoutgv"
5812           See "setdefout".
5813
5814       "PL_defstash"
5815           Described in perlguts.
5816
5817       "save_gp"
5818           Saves the current GP of gv on the save stack to be restored on
5819           scope exit.
5820
5821           If "empty" is true, replace the GP with a new GP.
5822
5823           If "empty" is false, mark "gv" with "GVf_INTRO" so the next
5824           reference assigned is localized, which is how
5825           " local *foo = $someref; " works.
5826
5827            void  save_gp(GV *gv, I32 empty)
5828
5829       "setdefout"
5830           Sets "PL_defoutgv", the default file handle for output, to the
5831           passed in typeglob.  As "PL_defoutgv" "owns" a reference on its
5832           typeglob, the reference count of the passed in typeglob is
5833           increased by one, and the reference count of the typeglob that
5834           "PL_defoutgv" points to is decreased by one.
5835
5836            void  setdefout(GV *gv)
5837

Hook manipulation

5839       These functions provide convenient and thread-safe means of
5840       manipulating hook variables.
5841
5842       "rcpv_copy"
5843           refcount increment a shared memory refcounted string, and when the
5844           refcount goes to 0 free it using PerlMemShared_free().
5845
5846           It is the callers responsibility to ensure that the pv is the
5847           result of a rcpv_new() call.
5848
5849           Returns the same pointer that was passed in.
5850
5851               new = rcpv_copy(pv);
5852
5853            char *  rcpv_copy(char * const pv)
5854
5855       "rcpv_free"
5856           refcount decrement a shared memory refcounted string, and when the
5857           refcount goes to 0 free it using perlmemshared_free().
5858
5859           it is the callers responsibility to ensure that the pv is the
5860           result of a rcpv_new() call.
5861
5862           Always returns NULL so it can be used like this:
5863
5864               thing = rcpv_free(thing);
5865
5866            char *  rcpv_free(char * const pv)
5867
5868       "rcpv_new"
5869           Create a new shared memory refcounted string with the requested
5870           size, and with the requested initialization and a refcount of 1.
5871           The actual space allocated will be 1 byte more than requested and
5872           rcpv_new() will ensure that the extra byte is a null regardless of
5873           any flags settings.
5874
5875           If the RCPVf_NO_COPY flag is set then the pv argument will be
5876           ignored, otherwise the contents of the pv pointer will be copied
5877           into the new buffer or if it is NULL the function will do nothing
5878           and return NULL.
5879
5880           If the RCPVf_USE_STRLEN flag is set then the len argument is
5881           ignored and recomputed using strlen(pv). It is an error to combine
5882           RCPVf_USE_STRLEN and RCPVf_NO_COPY at the same time.
5883
5884           Under DEBUGGING rcpv_new() will assert() if it is asked to create a
5885           0 length shared string unless the RCPVf_ALLOW_EMPTY flag is set.
5886
5887           The return value from the function is suitable for passing into
5888           rcpv_copy() and rcpv_free(). To access the RCPV * from the returned
5889           value use the RCPVx() macro.  The 'len' member of the RCPV struct
5890           stores the allocated length (including the extra byte), but the
5891           RCPV_LEN() macro returns the requested length (not including the
5892           extra byte).
5893
5894           Note that rcpv_new() does NOT use a hash table or anything like
5895           that to dedupe inputs given the same text content. Each call with a
5896           non-null pv parameter will produce a distinct pointer with its own
5897           refcount regardless of the input content.
5898
5899            char *  rcpv_new(const char * const pv, STRLEN len, U32 flags)
5900
5901       "wrap_op_checker"
5902           Puts a C function into the chain of check functions for a specified
5903           op type.  This is the preferred way to manipulate the "PL_check"
5904           array.  "opcode" specifies which type of op is to be affected.
5905           "new_checker" is a pointer to the C function that is to be added to
5906           that opcode's check chain, and "old_checker_p" points to the
5907           storage location where a pointer to the next function in the chain
5908           will be stored.  The value of "new_checker" is written into the
5909           "PL_check" array, while the value previously stored there is
5910           written to *old_checker_p.
5911
5912           "PL_check" is global to an entire process, and a module wishing to
5913           hook op checking may find itself invoked more than once per
5914           process, typically in different threads.  To handle that situation,
5915           this function is idempotent.  The location *old_checker_p must
5916           initially (once per process) contain a null pointer.  A C variable
5917           of static duration (declared at file scope, typically also marked
5918           "static" to give it internal linkage) will be implicitly
5919           initialised appropriately, if it does not have an explicit
5920           initialiser.  This function will only actually modify the check
5921           chain if it finds *old_checker_p to be null.  This function is also
5922           thread safe on the small scale.  It uses appropriate locking to
5923           avoid race conditions in accessing "PL_check".
5924
5925           When this function is called, the function referenced by
5926           "new_checker" must be ready to be called, except for *old_checker_p
5927           being unfilled.  In a threading situation, "new_checker" may be
5928           called immediately, even before this function has returned.
5929           *old_checker_p will always be appropriately set before
5930           "new_checker" is called.  If "new_checker" decides not to do
5931           anything special with an op that it is given (which is the usual
5932           case for most uses of op check hooking), it must chain the check
5933           function referenced by *old_checker_p.
5934
5935           Taken all together, XS code to hook an op checker should typically
5936           look something like this:
5937
5938               static Perl_check_t nxck_frob;
5939               static OP *myck_frob(pTHX_ OP *op) {
5940                   ...
5941                   op = nxck_frob(aTHX_ op);
5942                   ...
5943                   return op;
5944               }
5945               BOOT:
5946                   wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
5947
5948           If you want to influence compilation of calls to a specific
5949           subroutine, then use "cv_set_call_checker_flags" rather than
5950           hooking checking of all "entersub" ops.
5951
5952            void  wrap_op_checker(Optype opcode, Perl_check_t new_checker,
5953                                  Perl_check_t *old_checker_p)
5954

HV Handling

5956       A HV structure represents a Perl hash.  It consists mainly of an array
5957       of pointers, each of which points to a linked list of HE structures.
5958       The array is indexed by the hash function of the key, so each linked
5959       list represents all the hash entries with the same hash value.  Each HE
5960       contains a pointer to the actual value, plus a pointer to a HEK
5961       structure which holds the key and hash value.
5962
5963       "get_hv"
5964           Returns the HV of the specified Perl hash.  "flags" are passed to
5965           "gv_fetchpv".  If "GV_ADD" is set and the Perl variable does not
5966           exist then it will be created.  If "flags" is zero (ignoring
5967           "SVf_UTF8") and the variable does not exist then "NULL" is
5968           returned.
5969
5970           NOTE: the perl_get_hv() form is deprecated.
5971
5972            HV *  get_hv(const char *name, I32 flags)
5973
5974       "HE"
5975           Described in perlguts.
5976
5977       "HEf_SVKEY"
5978           This flag, used in the length slot of hash entries and magic
5979           structures, specifies the structure contains an "SV*" pointer where
5980           a "char*" pointer is to be expected.  (For information only--not to
5981           be used).
5982
5983       "HeHASH"
5984           Returns the computed hash stored in the hash entry.
5985
5986            U32  HeHASH(HE* he)
5987
5988       "HeKEY"
5989           Returns the actual pointer stored in the key slot of the hash
5990           entry.  The pointer may be either "char*" or "SV*", depending on
5991           the value of HeKLEN().  Can be assigned to.  The HePV() or
5992           HeSVKEY() macros are usually preferable for finding the value of a
5993           key.
5994
5995            void*  HeKEY(HE* he)
5996
5997       "HeKLEN"
5998           If this is negative, and amounts to "HEf_SVKEY", it indicates the
5999           entry holds an "SV*" key.  Otherwise, holds the actual length of
6000           the key.  Can be assigned to.  The HePV() macro is usually
6001           preferable for finding key lengths.
6002
6003            STRLEN  HeKLEN(HE* he)
6004
6005       "HePV"
6006           Returns the key slot of the hash entry as a "char*" value, doing
6007           any necessary dereferencing of possibly "SV*" keys.  The length of
6008           the string is placed in "len" (this is a macro, so do not use
6009           &len).  If you do not care about what the length of the key is, you
6010           may use the global variable "PL_na", though this is rather less
6011           efficient than using a local variable.  Remember though, that hash
6012           keys in perl are free to contain embedded nulls, so using strlen()
6013           or similar is not a good way to find the length of hash keys.  This
6014           is very similar to the SvPV() macro described elsewhere in this
6015           document.  See also "HeUTF8".
6016
6017           If you are using "HePV" to get values to pass to newSVpvn() to
6018           create a new SV, you should consider using
6019           "newSVhek(HeKEY_hek(he))" as it is more efficient.
6020
6021            char*  HePV(HE* he, STRLEN len)
6022
6023       "HeSVKEY"
6024           Returns the key as an "SV*", or "NULL" if the hash entry does not
6025           contain an "SV*" key.
6026
6027            SV*  HeSVKEY(HE* he)
6028
6029       "HeSVKEY_force"
6030           Returns the key as an "SV*".  Will create and return a temporary
6031           mortal "SV*" if the hash entry contains only a "char*" key.
6032
6033            SV*  HeSVKEY_force(HE* he)
6034
6035       "HeSVKEY_set"
6036           Sets the key to a given "SV*", taking care to set the appropriate
6037           flags to indicate the presence of an "SV*" key, and returns the
6038           same "SV*".
6039
6040            SV*  HeSVKEY_set(HE* he, SV* sv)
6041
6042       "HeUTF8"
6043           Returns whether the "char *" value returned by "HePV" is encoded in
6044           UTF-8, doing any necessary dereferencing of possibly "SV*" keys.
6045           The value returned will be 0 or non-0, not necessarily 1 (or even a
6046           value with any low bits set), so do not blindly assign this to a
6047           "bool" variable, as "bool" may be a typedef for "char".
6048
6049            U32  HeUTF8(HE* he)
6050
6051       "HeVAL"
6052           Returns the value slot (type "SV*") stored in the hash entry.  Can
6053           be assigned to.
6054
6055             SV *foo= HeVAL(hv);
6056             HeVAL(hv)= sv;
6057
6058            SV*  HeVAL(HE* he)
6059
6060       "HV"
6061           Described in perlguts.
6062
6063       "hv_assert"
6064           Check that a hash is in an internally consistent state.
6065
6066           NOTE: "hv_assert" must be explicitly called as "Perl_hv_assert"
6067           with an "aTHX_" parameter.
6068
6069            void  Perl_hv_assert(pTHX_ HV *hv)
6070
6071       "hv_bucket_ratio"
6072           NOTE: "hv_bucket_ratio" is experimental and may change or be
6073           removed without notice.
6074
6075           If the hash is tied dispatches through to the SCALAR tied method,
6076           otherwise if the hash contains no keys returns 0, otherwise returns
6077           a mortal sv containing a string specifying the number of used
6078           buckets, followed by a slash, followed by the number of available
6079           buckets.
6080
6081           This function is expensive, it must scan all of the buckets to
6082           determine which are used, and the count is NOT cached.  In a large
6083           hash this could be a lot of buckets.
6084
6085            SV *  hv_bucket_ratio(HV *hv)
6086
6087       "hv_clear"
6088           Frees all the elements of a hash, leaving it empty.  The XS
6089           equivalent of "%hash = ()".  See also "hv_undef".
6090
6091           See "av_clear" for a note about the hash possibly being invalid on
6092           return.
6093
6094            void  hv_clear(HV *hv)
6095
6096       "hv_clear_placeholders"
6097           Clears any placeholders from a hash.  If a restricted hash has any
6098           of its keys marked as readonly and the key is subsequently deleted,
6099           the key is not actually deleted but is marked by assigning it a
6100           value of &PL_sv_placeholder.  This tags it so it will be ignored by
6101           future operations such as iterating over the hash, but will still
6102           allow the hash to have a value reassigned to the key at some future
6103           point.  This function clears any such placeholder keys from the
6104           hash.  See Hash::Util::lock_keys() for an example of its use.
6105
6106            void  hv_clear_placeholders(HV *hv)
6107
6108       "hv_copy_hints_hv"
6109           A specialised version of "newHVhv" for copying "%^H".  "ohv" must
6110           be a pointer to a hash (which may have "%^H" magic, but should be
6111           generally non-magical), or "NULL" (interpreted as an empty hash).
6112           The content of "ohv" is copied to a new hash, which has the
6113           "%^H"-specific magic added to it.  A pointer to the new hash is
6114           returned.
6115
6116            HV *  hv_copy_hints_hv(HV * const ohv)
6117
6118       "hv_delete"
6119           Deletes a key/value pair in the hash.  The value's SV is removed
6120           from the hash, made mortal, and returned to the caller.  The
6121           absolute value of "klen" is the length of the key.  If "klen" is
6122           negative the key is assumed to be in UTF-8-encoded Unicode.  The
6123           "flags" value will normally be zero; if set to "G_DISCARD" then
6124           "NULL" will be returned.  "NULL" will also be returned if the key
6125           is not found.
6126
6127            SV *  hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
6128
6129       "hv_delete_ent"
6130           Deletes a key/value pair in the hash.  The value SV is removed from
6131           the hash, made mortal, and returned to the caller.  The "flags"
6132           value will normally be zero; if set to "G_DISCARD" then "NULL" will
6133           be returned.  "NULL" will also be returned if the key is not found.
6134           "hash" can be a valid precomputed hash value, or 0 to ask for it to
6135           be computed.
6136
6137            SV *  hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
6138
6139       "HvENAME"
6140           Returns the effective name of a stash, or NULL if there is none.
6141           The effective name represents a location in the symbol table where
6142           this stash resides.  It is updated automatically when packages are
6143           aliased or deleted.  A stash that is no longer in the symbol table
6144           has no effective name.  This name is preferable to "HvNAME" for use
6145           in MRO linearisations and isa caches.
6146
6147            char*  HvENAME(HV* stash)
6148
6149       "HvENAMELEN"
6150           Returns the length of the stash's effective name.
6151
6152            STRLEN  HvENAMELEN(HV *stash)
6153
6154       "HvENAMEUTF8"
6155           Returns true if the effective name is in UTF-8 encoding.
6156
6157            unsigned char  HvENAMEUTF8(HV *stash)
6158
6159       "hv_exists"
6160           Returns a boolean indicating whether the specified hash key exists.
6161           The absolute value of "klen" is the length of the key.  If "klen"
6162           is negative the key is assumed to be in UTF-8-encoded Unicode.
6163
6164            bool  hv_exists(HV *hv, const char *key, I32 klen)
6165
6166       "hv_exists_ent"
6167           Returns a boolean indicating whether the specified hash key exists.
6168           "hash" can be a valid precomputed hash value, or 0 to ask for it to
6169           be computed.
6170
6171            bool  hv_exists_ent(HV *hv, SV *keysv, U32 hash)
6172
6173       "hv_fetch"
6174           Returns the SV which corresponds to the specified key in the hash.
6175           The absolute value of "klen" is the length of the key.  If "klen"
6176           is negative the key is assumed to be in UTF-8-encoded Unicode.  If
6177           "lval" is set then the fetch will be part of a store.  This means
6178           that if there is no value in the hash associated with the given
6179           key, then one is created and a pointer to it is returned.  The
6180           "SV*" it points to can be assigned to.  But always check that the
6181           return value is non-null before dereferencing it to an "SV*".
6182
6183           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
6184           for more information on how to use this function on tied hashes.
6185
6186            SV **  hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
6187
6188       "hv_fetch_ent"
6189           Returns the hash entry which corresponds to the specified key in
6190           the hash.  "hash" must be a valid precomputed hash number for the
6191           given "key", or 0 if you want the function to compute it.  IF
6192           "lval" is set then the fetch will be part of a store.  Make sure
6193           the return value is non-null before accessing it.  The return value
6194           when "hv" is a tied hash is a pointer to a static location, so be
6195           sure to make a copy of the structure if you need to store it
6196           somewhere.
6197
6198           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
6199           for more information on how to use this function on tied hashes.
6200
6201            HE *  hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
6202
6203       "hv_fetchs"
6204           Like "hv_fetch", but takes a literal string instead of a
6205           string/length pair.
6206
6207            SV**  hv_fetchs(HV* tb, "key", I32 lval)
6208
6209       "HvFILL"
6210           Returns the number of hash buckets that happen to be in use.
6211
6212           As of perl 5.25 this function is used only for debugging purposes,
6213           and the number of used hash buckets is not in any way cached, thus
6214           this function can be costly to execute as it must iterate over all
6215           the buckets in the hash.
6216
6217            STRLEN  HvFILL(HV *const hv)
6218
6219       "HvHasAUX"
6220           Returns true if the HV has a "struct xpvhv_aux" extension. Use this
6221           to check whether it is valid to call HvAUX().
6222
6223            bool  HvHasAUX(HV *const hv)
6224
6225       "hv_iterinit"
6226           Prepares a starting point to traverse a hash table.  Returns the
6227           number of keys in the hash, including placeholders (i.e. the same
6228           as HvTOTALKEYS(hv)).  The return value is currently only meaningful
6229           for hashes without tie magic.
6230
6231           NOTE: Before version 5.004_65, "hv_iterinit" used to return the
6232           number of hash buckets that happen to be in use.  If you still need
6233           that esoteric value, you can get it through the macro HvFILL(hv).
6234
6235            I32  hv_iterinit(HV *hv)
6236
6237       "hv_iterkey"
6238           Returns the key from the current position of the hash iterator.
6239           See "hv_iterinit".
6240
6241            char *  hv_iterkey(HE *entry, I32 *retlen)
6242
6243       "hv_iterkeysv"
6244           Returns the key as an "SV*" from the current position of the hash
6245           iterator.  The return value will always be a mortal copy of the
6246           key.  Also see "hv_iterinit".
6247
6248            SV *  hv_iterkeysv(HE *entry)
6249
6250       "hv_iternext"
6251           Returns entries from a hash iterator.  See "hv_iterinit".
6252
6253           You may call "hv_delete" or "hv_delete_ent" on the hash entry that
6254           the iterator currently points to, without losing your place or
6255           invalidating your iterator.  Note that in this case the current
6256           entry is deleted from the hash with your iterator holding the last
6257           reference to it.  Your iterator is flagged to free the entry on the
6258           next call to "hv_iternext", so you must not discard your iterator
6259           immediately else the entry will leak - call "hv_iternext" to
6260           trigger the resource deallocation.
6261
6262            HE *  hv_iternext(HV *hv)
6263
6264       "hv_iternext_flags"
6265           NOTE: "hv_iternext_flags" is experimental and may change or be
6266           removed without notice.
6267
6268           Returns entries from a hash iterator.  See "hv_iterinit" and
6269           "hv_iternext".  The "flags" value will normally be zero; if
6270           "HV_ITERNEXT_WANTPLACEHOLDERS" is set the placeholders keys (for
6271           restricted hashes) will be returned in addition to normal keys.  By
6272           default placeholders are automatically skipped over.  Currently a
6273           placeholder is implemented with a value that is &PL_sv_placeholder.
6274           Note that the implementation of placeholders and restricted hashes
6275           may change, and the implementation currently is insufficiently
6276           abstracted for any change to be tidy.
6277
6278            HE *  hv_iternext_flags(HV *hv, I32 flags)
6279
6280       "hv_iternextsv"
6281           Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in one
6282           operation.
6283
6284            SV *  hv_iternextsv(HV *hv, char **key, I32 *retlen)
6285
6286       "hv_iterval"
6287           Returns the value from the current position of the hash iterator.
6288           See "hv_iterkey".
6289
6290            SV *  hv_iterval(HV *hv, HE *entry)
6291
6292       "hv_ksplit"
6293           Attempt to grow the hash "hv" so it has at least "newmax" buckets
6294           available.  Perl chooses the actual number for its convenience.
6295
6296           This is the same as doing the following in Perl code:
6297
6298            keys %hv = newmax;
6299
6300            void  hv_ksplit(HV *hv, IV newmax)
6301
6302       "hv_magic"
6303           Adds magic to a hash.  See "sv_magic".
6304
6305            void  hv_magic(HV *hv, GV *gv, int how)
6306
6307       "HvNAME"
6308           Returns the package name of a stash, or "NULL" if "stash" isn't a
6309           stash.  See "SvSTASH", "CvSTASH".
6310
6311            char*  HvNAME(HV* stash)
6312
6313       "HvNAMELEN"
6314           Returns the length of the stash's name.
6315
6316           Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them
6317
6318            STRLEN  HvNAMELEN(HV *stash)
6319
6320       "hv_name_set"
6321       "hv_name_sets"
6322           These each set the name of stash "hv" to the specified name.
6323
6324           They differ only in how the name is specified.
6325
6326           In "hv_name_sets", the name is a literal C string, enclosed in
6327           double quotes.
6328
6329           In "hv_name_set", "name" points to the first byte of the name, and
6330           an additional parameter, "len", specifies its length in bytes.
6331           Hence, the name may contain embedded-NUL characters.
6332
6333           If "SVf_UTF8" is set in "flags", the name is treated as being in
6334           UTF-8; otherwise not.
6335
6336           If "HV_NAME_SETALL" is set in "flags", both the name and the
6337           effective name are set.
6338
6339            void  hv_name_set (HV *hv, const char *name, U32 len, U32 flags)
6340            void  hv_name_sets(HV *hv, "name", U32 flags)
6341
6342       "HvNAMEUTF8"
6343           Returns true if the name is in UTF-8 encoding.
6344
6345            unsigned char  HvNAMEUTF8(HV *stash)
6346
6347       "hv_scalar"
6348           Evaluates the hash in scalar context and returns the result.
6349
6350           When the hash is tied dispatches through to the SCALAR method,
6351           otherwise returns a mortal SV containing the number of keys in the
6352           hash.
6353
6354           Note, prior to 5.25 this function returned what is now returned by
6355           the hv_bucket_ratio() function.
6356
6357            SV *  hv_scalar(HV *hv)
6358
6359       "hv_store"
6360       "hv_stores"
6361           These each store SV "val" with the specified key in hash "hv",
6362           returning NULL if the operation failed or if the value did not need
6363           to be actually stored within the hash (as in the case of tied
6364           hashes).  Otherwise it can be dereferenced to get the original
6365           "SV*".
6366
6367           They differ only in how the hash key is specified.
6368
6369           In "hv_stores", the key is a C language string literal, enclosed in
6370           double quotes.  It is never treated as being in UTF-8.
6371
6372           In "hv_store", "key" is either NULL or points to the first byte of
6373           the string specifying the key, and its length in bytes is given by
6374           the absolute value of an additional parameter, "klen".  A NULL key
6375           indicates the key is to be treated as "undef", and "klen" is
6376           ignored; otherwise the key string may contain embedded-NUL bytes.
6377           If "klen" is negative, the string is treated as being encoded in
6378           UTF-8; otherwise not.
6379
6380           "hv_store" has another extra parameter, "hash", a precomputed hash
6381           of the key string, or zero if it has not been precomputed.  This
6382           parameter is omitted from "hv_stores", as it is computed
6383           automatically at compile time.
6384
6385           If <hv> is NULL, NULL is returned and no action is taken.
6386
6387           If "val" is NULL, it is treated as being "undef"; otherwise the
6388           caller is responsible for suitably incrementing the reference count
6389           of "val" before the call, and decrementing it if the function
6390           returned "NULL".  Effectively a successful "hv_store" takes
6391           ownership of one reference to "val".  This is usually what you
6392           want; a newly created SV has a reference count of one, so if all
6393           your code does is create SVs then store them in a hash, "hv_store"
6394           will own the only reference to the new SV, and your code doesn't
6395           need to do anything further to tidy up.
6396
6397           "hv_store" is not implemented as a call to ""hv_store_ent"", and
6398           does not create a temporary SV for the key, so if your key data is
6399           not already in SV form then use "hv_store" in preference to
6400           "hv_store_ent".
6401
6402           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
6403           for more information on how to use this function on tied hashes.
6404
6405            SV **  hv_store (HV *hv, const char *key, I32 klen, SV *val,
6406                             U32 hash)
6407            SV **  hv_stores(HV *hv, "key", SV *val)
6408
6409       "hv_store_ent"
6410           Stores "val" in a hash.  The hash key is specified as "key".  The
6411           "hash" parameter is the precomputed hash value; if it is zero then
6412           Perl will compute it.  The return value is the new hash entry so
6413           created.  It will be "NULL" if the operation failed or if the value
6414           did not need to be actually stored within the hash (as in the case
6415           of tied hashes).  Otherwise the contents of the return value can be
6416           accessed using the "He?" macros described here.  Note that the
6417           caller is responsible for suitably incrementing the reference count
6418           of "val" before the call, and decrementing it if the function
6419           returned NULL.  Effectively a successful "hv_store_ent" takes
6420           ownership of one reference to "val".  This is usually what you
6421           want; a newly created SV has a reference count of one, so if all
6422           your code does is create SVs then store them in a hash, "hv_store"
6423           will own the only reference to the new SV, and your code doesn't
6424           need to do anything further to tidy up.  Note that "hv_store_ent"
6425           only reads the "key"; unlike "val" it does not take ownership of
6426           it, so maintaining the correct reference count on "key" is entirely
6427           the caller's responsibility.  The reason it does not take
6428           ownership, is that "key" is not used after this function returns,
6429           and so can be freed immediately.  "hv_store" is not implemented as
6430           a call to "hv_store_ent", and does not create a temporary SV for
6431           the key, so if your key data is not already in SV form then use
6432           "hv_store" in preference to "hv_store_ent".
6433
6434           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
6435           for more information on how to use this function on tied hashes.
6436
6437            HE *  hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
6438
6439       "hv_undef"
6440           Undefines the hash.  The XS equivalent of undef(%hash).
6441
6442           As well as freeing all the elements of the hash (like hv_clear()),
6443           this also frees any auxiliary data and storage associated with the
6444           hash.
6445
6446           See "av_clear" for a note about the hash possibly being invalid on
6447           return.
6448
6449            void  hv_undef(HV *hv)
6450
6451       "newHV"
6452           Creates a new HV.  The reference count is set to 1.
6453
6454            HV *  newHV()
6455
6456       "newHVhv"
6457           The content of "ohv" is copied to a new hash.  A pointer to the new
6458           hash is returned.
6459
6460            HV *  newHVhv(HV *hv)
6461
6462       "Nullhv"
6463           "DEPRECATED!"  It is planned to remove "Nullhv" from a future
6464           release of Perl.  Do not use it for new code; remove it from
6465           existing code.
6466
6467           Null HV pointer.
6468
6469           (deprecated - use "(HV *)NULL" instead)
6470
6471       "PERL_HASH"
6472           Described in perlguts.
6473
6474            void  PERL_HASH(U32 hash, char *key, STRLEN klen)
6475
6476       "PL_modglobal"
6477           "PL_modglobal" is a general purpose, interpreter global HV for use
6478           by extensions that need to keep information on a per-interpreter
6479           basis.  In a pinch, it can also be used as a symbol table for
6480           extensions to share data among each other.  It is a good idea to
6481           use keys prefixed by the package name of the extension that owns
6482           the data.
6483
6484           On threaded perls, each thread has an independent copy of this
6485           variable; each initialized at creation time with the current value
6486           of the creating thread's copy.
6487
6488            HV*  PL_modglobal
6489

Input/Output

6491       "do_close"
6492           Close an I/O stream.  This implements Perl ""close"" in perlfunc.
6493
6494           "gv" is the glob associated with the stream.
6495
6496           "is_explict" is "true" if this is an explicit close of the stream;
6497           "false" if it is part of another operation, such as closing a pipe
6498           (which involves implicitly closing both ends).
6499
6500           Returns "true" if successful; otherwise returns "false" and sets
6501           "errno" to indicate the cause.
6502
6503            bool  do_close(GV *gv, bool is_explicit)
6504
6505       "IoDIRP"
6506           Described in perlguts.
6507
6508            DIR *  IoDIRP(IO *io)
6509
6510       "IOf_FLUSH"
6511           Described in perlguts.
6512
6513       "IoFLAGS"
6514           Described in perlguts.
6515
6516            U8  IoFLAGS(IO *io)
6517
6518       "IOf_UNTAINT"
6519           Described in perlguts.
6520
6521       "IoIFP"
6522           Described in perlguts.
6523
6524            PerlIO *  IoIFP(IO *io)
6525
6526       "IoOFP"
6527           Described in perlguts.
6528
6529            PerlIO *  IoOFP(IO *io)
6530
6531       "IoTYPE"
6532           Described in perlguts.
6533
6534            char  IoTYPE(IO *io)
6535
6536       "my_chsize"
6537           The C library chsize(3) if available, or a Perl implementation of
6538           it.
6539
6540            I32  my_chsize(int fd, Off_t length)
6541
6542       "my_dirfd"
6543           The C library dirfd(3) if available, or a Perl implementation of
6544           it, or die if not easily emulatable.
6545
6546            int  my_dirfd(DIR *dir)
6547
6548       "my_pclose"
6549           A wrapper for the C library pclose(3).  Don't use the latter, as
6550           the Perl version knows things that interact with the rest of the
6551           perl interpreter.
6552
6553            I32  my_pclose(PerlIO *ptr)
6554
6555       "my_popen"
6556           A wrapper for the C library popen(3).  Don't use the latter, as the
6557           Perl version knows things that interact with the rest of the perl
6558           interpreter.
6559
6560            PerlIO *  my_popen(const char *cmd, const char *mode)
6561
6562       "newIO"
6563           Create a new IO, setting the reference count to 1.
6564
6565            IO *  newIO()
6566
6567       "PERL_FLUSHALL_FOR_CHILD"
6568           This defines a way to flush all output buffers.  This may be a
6569           performance issue, so we allow people to disable it.  Also, if we
6570           are using stdio, there are broken implementations of fflush(NULL)
6571           out there, Solaris being the most prominent.
6572
6573            void  PERL_FLUSHALL_FOR_CHILD
6574
6575       "PerlIO_apply_layers"
6576       "PerlIO_binmode"
6577       "PerlIO_canset_cnt"
6578       "PerlIO_clearerr"
6579       "PerlIO_close"
6580       "PerlIO_debug"
6581       "PerlIO_eof"
6582       "PerlIO_error"
6583       "PerlIO_exportFILE"
6584       "PerlIO_fast_gets"
6585       "PerlIO_fdopen"
6586       "PerlIO_fileno"
6587       "PerlIO_fill"
6588       "PerlIO_findFILE"
6589       "PerlIO_flush"
6590       "PerlIO_get_base"
6591       "PerlIO_get_bufsiz"
6592       "PerlIO_get_cnt"
6593       "PerlIO_get_ptr"
6594       "PerlIO_getc"
6595       "PerlIO_getpos"
6596       "PerlIO_has_base"
6597       "PerlIO_has_cntptr"
6598       "PerlIO_importFILE"
6599       "PerlIO_open"
6600       "PerlIO_printf"
6601       "PerlIO_putc"
6602       "PerlIO_puts"
6603       "PerlIO_read"
6604       "PerlIO_releaseFILE"
6605       "PerlIO_reopen"
6606       "PerlIO_rewind"
6607       "PerlIO_seek"
6608       "PerlIO_set_cnt"
6609       "PerlIO_set_ptrcnt"
6610       "PerlIO_setlinebuf"
6611       "PerlIO_setpos"
6612       "PerlIO_stderr"
6613       "PerlIO_stdin"
6614       "PerlIO_stdout"
6615       "PerlIO_stdoutf"
6616       "PerlIO_tell"
6617       "PerlIO_ungetc"
6618       "PerlIO_unread"
6619       "PerlIO_vprintf"
6620       "PerlIO_write"
6621           Described in perlapio.
6622
6623            int        PerlIO_apply_layers(PerlIO *f, const char *mode,
6624                                           const char *layers)
6625            int        PerlIO_binmode     (PerlIO *f, int ptype, int imode,
6626                                           const char *layers)
6627            int        PerlIO_canset_cnt  (PerlIO *f)
6628            void       PerlIO_clearerr    (PerlIO *f)
6629            int        PerlIO_close       (PerlIO *f)
6630            void       PerlIO_debug       (const char *fmt, ...)
6631            int        PerlIO_eof         (PerlIO *f)
6632            int        PerlIO_error       (PerlIO *f)
6633            FILE *     PerlIO_exportFILE  (PerlIO *f, const char *mode)
6634            int        PerlIO_fast_gets   (PerlIO *f)
6635            PerlIO *   PerlIO_fdopen      (int fd, const char *mode)
6636            int        PerlIO_fileno      (PerlIO *f)
6637            int        PerlIO_fill        (PerlIO *f)
6638            FILE *     PerlIO_findFILE    (PerlIO *f)
6639            int        PerlIO_flush       (PerlIO *f)
6640            STDCHAR *  PerlIO_get_base    (PerlIO *f)
6641            SSize_t    PerlIO_get_bufsiz  (PerlIO *f)
6642            SSize_t    PerlIO_get_cnt     (PerlIO *f)
6643            STDCHAR *  PerlIO_get_ptr     (PerlIO *f)
6644            int        PerlIO_getc        (PerlIO *d)
6645            int        PerlIO_getpos      (PerlIO *f, SV *save)
6646            int        PerlIO_has_base    (PerlIO *f)
6647            int        PerlIO_has_cntptr  (PerlIO *f)
6648            PerlIO *   PerlIO_importFILE  (FILE *stdio, const char *mode)
6649            PerlIO *   PerlIO_open        (const char *path, const char *mode)
6650            int        PerlIO_printf      (PerlIO *f, const char *fmt, ...)
6651            int        PerlIO_putc        (PerlIO *f, int ch)
6652            int        PerlIO_puts        (PerlIO *f, const char *string)
6653            SSize_t    PerlIO_read        (PerlIO *f, void *vbuf,
6654                                           Size_t count)
6655            void       PerlIO_releaseFILE (PerlIO *f, FILE *stdio)
6656            PerlIO *   PerlIO_reopen      (const char *path, const char *mode,
6657                                           PerlIO *old)
6658            void       PerlIO_rewind      (PerlIO *f)
6659            int        PerlIO_seek        (PerlIO *f, Off_t offset,
6660                                           int whence)
6661            void       PerlIO_set_cnt     (PerlIO *f, SSize_t cnt)
6662            void       PerlIO_set_ptrcnt  (PerlIO *f, STDCHAR *ptr,
6663                                           SSize_t cnt)
6664            void       PerlIO_setlinebuf  (PerlIO *f)
6665            int        PerlIO_setpos      (PerlIO *f, SV *saved)
6666            PerlIO *   PerlIO_stderr      (PerlIO *f, const char *mode,
6667                                           const char *layers)
6668            PerlIO *   PerlIO_stdin       (PerlIO *f, const char *mode,
6669                                           const char *layers)
6670            PerlIO *   PerlIO_stdout      (PerlIO *f, const char *mode,
6671                                           const char *layers)
6672            int        PerlIO_stdoutf     (const char *fmt, ...)
6673            Off_t      PerlIO_tell        (PerlIO *f)
6674            int        PerlIO_ungetc      (PerlIO *f, int ch)
6675            SSize_t    PerlIO_unread      (PerlIO *f, const void *vbuf,
6676                                           Size_t count)
6677            int        PerlIO_vprintf     (PerlIO *f, const char *fmt,
6678                                           va_list args)
6679            SSize_t    PerlIO_write       (PerlIO *f, const void *vbuf,
6680                                           Size_t count)
6681
6682       "PERLIO_F_APPEND"
6683       "PERLIO_F_CANREAD"
6684       "PERLIO_F_CANWRITE"
6685       "PERLIO_F_CRLF"
6686       "PERLIO_F_EOF"
6687       "PERLIO_F_ERROR"
6688       "PERLIO_F_FASTGETS"
6689       "PERLIO_F_LINEBUF"
6690       "PERLIO_F_OPEN"
6691       "PERLIO_F_RDBUF"
6692       "PERLIO_F_TEMP"
6693       "PERLIO_F_TRUNCATE"
6694       "PERLIO_F_UNBUF"
6695       "PERLIO_F_UTF8"
6696       "PERLIO_F_WRBUF"
6697           Described in perliol.
6698
6699       "PERLIO_FUNCS_CAST"
6700           Cast the pointer "func" to be of type "PerlIO_funcs *".
6701
6702       "PERLIO_FUNCS_DECL"
6703           Declare "ftab" to be a PerlIO function table, that is, of type
6704           "PerlIO_funcs".
6705
6706              PERLIO_FUNCS_DECL(PerlIO * ftab)
6707
6708       "PERLIO_K_BUFFERED"
6709       "PERLIO_K_CANCRLF"
6710       "PERLIO_K_FASTGETS"
6711       "PERLIO_K_MULTIARG"
6712       "PERLIO_K_RAW"
6713           Described in perliol.
6714
6715       "PERLIO_NOT_STDIO"
6716           Described in perlapio.
6717
6718       "PL_maxsysfd"
6719           Described in perliol.
6720
6721       "repeatcpy"
6722           Make "count" copies of the "len" bytes beginning at "from", placing
6723           them into memory beginning at "to", which must be big enough to
6724           accommodate them all.
6725
6726            void  repeatcpy(char *to, const char *from, I32 len, IV count)
6727
6728       "USE_STDIO"
6729           Described in perlapio.
6730

Integer

6732       "CASTI32"
6733           This symbol is defined if the C compiler can cast negative or large
6734           floating point numbers to 32-bit ints.
6735
6736       "HAS_INT64_T"
6737           This symbol will defined if the C compiler supports "int64_t".
6738           Usually the inttypes.h needs to be included, but sometimes
6739           sys/types.h is enough.
6740
6741       "HAS_LONG_LONG"
6742           This symbol will be defined if the C compiler supports long long.
6743
6744       "HAS_QUAD"
6745           This symbol, if defined, tells that there's a 64-bit integer type,
6746           "Quad_t", and its unsigned counterpart, "Uquad_t". "QUADKIND" will
6747           be one of "QUAD_IS_INT", "QUAD_IS_LONG", "QUAD_IS_LONG_LONG",
6748           "QUAD_IS_INT64_T", or "QUAD_IS___INT64".
6749
6750       "I32df"
6751           This symbol defines the format string used for printing a Perl I32
6752           as a signed decimal integer.
6753
6754       "INT16_C"
6755       "INT32_C"
6756       "INT64_C"
6757           Returns a token the C compiler recognizes for the constant "number"
6758           of the corresponding integer type on the machine.
6759
6760           If the machine does not have a 64-bit type, "INT64_C" is undefined.
6761           Use "INTMAX_C" to get the largest type available on the platform.
6762
6763            I16  INT16_C(number)
6764            I32  INT32_C(number)
6765            I64  INT64_C(number)
6766
6767       "INTMAX_C"
6768           Returns a token the C compiler recognizes for the constant "number"
6769           of the widest integer type on the machine.  For example, if the
6770           machine has "long long"s, INTMAX_C(-1) would yield
6771
6772            -1LL
6773
6774           See also, for example, "INT32_C".
6775
6776           Use "IV" to declare variables of the maximum usable size on this
6777           platform.
6778
6779              INTMAX_C(number)
6780
6781       "INTSIZE"
6782           This symbol contains the value of sizeof(int) so that the C
6783           preprocessor can make decisions based on it.
6784
6785       "I8SIZE"
6786           This symbol contains the sizeof(I8).
6787
6788       "I16SIZE"
6789           This symbol contains the sizeof(I16).
6790
6791       "I32SIZE"
6792           This symbol contains the sizeof(I32).
6793
6794       "I64SIZE"
6795           This symbol contains the sizeof(I64).
6796
6797       "I8TYPE"
6798           This symbol defines the C type used for Perl's I8.
6799
6800       "I16TYPE"
6801           This symbol defines the C type used for Perl's I16.
6802
6803       "I32TYPE"
6804           This symbol defines the C type used for Perl's I32.
6805
6806       "I64TYPE"
6807           This symbol defines the C type used for Perl's I64.
6808
6809       "IV"
6810       "I8"
6811       "I16"
6812       "I32"
6813       "I64"
6814           Described in perlguts.
6815
6816       "IV_MAX"
6817           The largest signed integer that fits in an IV on this platform.
6818
6819            IV  IV_MAX
6820
6821       "IV_MIN"
6822           The negative signed integer furthest away from 0 that fits in an IV
6823           on this platform.
6824
6825            IV  IV_MIN
6826
6827       "IVSIZE"
6828           This symbol contains the sizeof(IV).
6829
6830       "IVTYPE"
6831           This symbol defines the C type used for Perl's IV.
6832
6833       "line_t"
6834           The typedef to use to declare variables that are to hold line
6835           numbers.
6836
6837       "LONGLONGSIZE"
6838           This symbol contains the size of a long long, so that the C
6839           preprocessor can make decisions based on it.  It is only defined if
6840           the system supports long long.
6841
6842       "LONGSIZE"
6843           This symbol contains the value of sizeof(long) so that the C
6844           preprocessor can make decisions based on it.
6845
6846       "memzero"
6847           Set the "l" bytes starting at *d to all zeroes.
6848
6849            void  memzero(void * d, Size_t l)
6850
6851       "PERL_INT_FAST8_T"
6852       "PERL_INT_FAST16_T"
6853       "PERL_UINT_FAST8_T"
6854       "PERL_UINT_FAST16_T"
6855           These are equivalent to the correspondingly-named C99 typedefs on
6856           platforms that have those; they evaluate to "int" and "unsigned
6857           int" on platforms that don't, so that you can portably take
6858           advantage of this C99 feature.
6859
6860       "PERL_INT_MAX"
6861       "PERL_INT_MIN"
6862       "PERL_LONG_MAX"
6863       "PERL_LONG_MIN"
6864       "PERL_QUAD_MAX"
6865       "PERL_QUAD_MIN"
6866       "PERL_SHORT_MAX"
6867       "PERL_SHORT_MIN"
6868       "PERL_UCHAR_MAX"
6869       "PERL_UCHAR_MIN"
6870       "PERL_UINT_MAX"
6871       "PERL_UINT_MIN"
6872       "PERL_ULONG_MAX"
6873       "PERL_ULONG_MIN"
6874       "PERL_UQUAD_MAX"
6875       "PERL_UQUAD_MIN"
6876       "PERL_USHORT_MAX"
6877       "PERL_USHORT_MIN"
6878           These give the largest and smallest number representable in the
6879           current platform in variables of the corresponding types.
6880
6881           For signed types, the smallest representable number is the most
6882           negative number, the one furthest away from zero.
6883
6884           For C99 and later compilers, these correspond to things like
6885           "INT_MAX", which are available to the C code.  But these constants,
6886           furnished by Perl, allow code compiled on earlier compilers to
6887           portably have access to the same constants.
6888
6889            int             PERL_INT_MAX
6890            int             PERL_INT_MIN
6891            long            PERL_LONG_MAX
6892            long            PERL_LONG_MIN
6893            IV              PERL_QUAD_MAX
6894            IV              PERL_QUAD_MIN
6895            short           PERL_SHORT_MAX
6896            short           PERL_SHORT_MIN
6897            U8              PERL_UCHAR_MAX
6898            U8              PERL_UCHAR_MIN
6899            unsigned int    PERL_UINT_MAX
6900            unsigned int    PERL_UINT_MIN
6901            unsigned long   PERL_ULONG_MAX
6902            unsigned long   PERL_ULONG_MIN
6903            UV              PERL_UQUAD_MAX
6904            UV              PERL_UQUAD_MIN
6905            unsigned short  PERL_USHORT_MAX
6906            unsigned short  PERL_USHORT_MIN
6907
6908       "SHORTSIZE"
6909           This symbol contains the value of sizeof(short) so that the C
6910           preprocessor can make decisions based on it.
6911
6912       "UINT16_C"
6913       "UINT32_C"
6914       "UINT64_C"
6915           Returns a token the C compiler recognizes for the constant "number"
6916           of the corresponding unsigned integer type on the machine.
6917
6918           If the machine does not have a 64-bit type, "UINT64_C" is
6919           undefined.  Use "UINTMAX_C" to get the largest type available on
6920           the platform.
6921
6922            U16  UINT16_C(number)
6923            U32  UINT32_C(number)
6924            U64  UINT64_C(number)
6925
6926       "UINTMAX_C"
6927           Returns a token the C compiler recognizes for the constant "number"
6928           of the widest unsigned integer type on the machine.  For example,
6929           if the machine has "long"s, UINTMAX_C(1) would yield
6930
6931            1UL
6932
6933           See also, for example, "UINT32_C".
6934
6935           Use "UV" to declare variables of the maximum usable size on this
6936           platform.
6937
6938              UINTMAX_C(number)
6939
6940       "U32of"
6941           This symbol defines the format string used for printing a Perl U32
6942           as an unsigned octal integer.
6943
6944       "U8SIZE"
6945           This symbol contains the sizeof(U8).
6946
6947       "U16SIZE"
6948           This symbol contains the sizeof(U16).
6949
6950       "U32SIZE"
6951           This symbol contains the sizeof(U32).
6952
6953       "U64SIZE"
6954           This symbol contains the sizeof(U64).
6955
6956       "U8TYPE"
6957           This symbol defines the C type used for Perl's U8.
6958
6959       "U16TYPE"
6960           This symbol defines the C type used for Perl's U16.
6961
6962       "U32TYPE"
6963           This symbol defines the C type used for Perl's U32.
6964
6965       "U64TYPE"
6966           This symbol defines the C type used for Perl's U64.
6967
6968       "U32uf"
6969           This symbol defines the format string used for printing a Perl U32
6970           as an unsigned decimal integer.
6971
6972       "UV"
6973       "U8"
6974       "U16"
6975       "U32"
6976       "U64"
6977           Described in perlguts.
6978
6979       "UV_MAX"
6980           The largest unsigned integer that fits in a UV on this platform.
6981
6982            UV  UV_MAX
6983
6984       "UV_MIN"
6985           The smallest unsigned integer that fits in a UV on this platform.
6986           It should equal zero.
6987
6988            UV  UV_MIN
6989
6990       "UVSIZE"
6991           This symbol contains the sizeof(UV).
6992
6993       "UVTYPE"
6994           This symbol defines the C type used for Perl's UV.
6995
6996       "U32Xf"
6997           This symbol defines the format string used for printing a Perl U32
6998           as an unsigned hexadecimal integer in uppercase "ABCDEF".
6999
7000       "U32xf"
7001           This symbol defines the format string used for printing a Perl U32
7002           as an unsigned hexadecimal integer in lowercase abcdef.
7003
7004       "WIDEST_UTYPE"
7005           Yields the widest unsigned integer type on the platform, currently
7006           either "U32" or "U64".  This can be used in declarations such as
7007
7008            WIDEST_UTYPE my_uv;
7009
7010           or casts
7011
7012            my_uv = (WIDEST_UTYPE) val;
7013

I/O Formats

7015       These are used for formatting the corresponding type For example,
7016       instead of saying
7017
7018        Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\n", iv);
7019
7020       use
7021
7022        Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\n", iv);
7023
7024       This keeps you from having to know if, say an IV, needs to be printed
7025       as %d, %ld, or something else.
7026
7027       "HvNAMEf"
7028           Described in perlguts.
7029
7030       "HvNAMEf_QUOTEDPREFIX"
7031           Described in perlguts.
7032
7033       "IVdf"
7034           This symbol defines the format string used for printing a Perl IV
7035           as a signed decimal integer.
7036
7037       "NVef"
7038           This symbol defines the format string used for printing a Perl NV
7039           using %e-ish floating point format.
7040
7041       "NVff"
7042           This symbol defines the format string used for printing a Perl NV
7043           using %f-ish floating point format.
7044
7045       "NVgf"
7046           This symbol defines the format string used for printing a Perl NV
7047           using %g-ish floating point format.
7048
7049       "PERL_PRIeldbl"
7050           This symbol, if defined, contains the string used by stdio to
7051           format long doubles (format 'e') for output.
7052
7053       "PERL_PRIfldbl"
7054           This symbol, if defined, contains the string used by stdio to
7055           format long doubles (format 'f') for output.
7056
7057       "PERL_PRIgldbl"
7058           This symbol, if defined, contains the string used by stdio to
7059           format long doubles (format 'g') for output.
7060
7061       "PERL_SCNfldbl"
7062           This symbol, if defined, contains the string used by stdio to
7063           format long doubles (format 'f') for input.
7064
7065       "PRINTF_FORMAT_NULL_OK"
7066           Allows "__printf__" format to be null when checking printf-style
7067
7068       "SVf"
7069           Described in perlguts.
7070
7071       "SVfARG"
7072           Described in perlguts.
7073
7074              SVfARG(SV *sv)
7075
7076       "SVf_QUOTEDPREFIX"
7077           Described in perlguts.
7078
7079       "UTF8f"
7080           Described in perlguts.
7081
7082       "UTF8fARG"
7083           Described in perlguts.
7084
7085              UTF8fARG(bool is_utf8, Size_t byte_len, char *str)
7086
7087       "UTF8f_QUOTEDPREFIX"
7088           Described in perlguts.
7089
7090       "UVf"
7091           "DEPRECATED!"  It is planned to remove "UVf" from a future release
7092           of Perl.  Do not use it for new code; remove it from existing code.
7093
7094           Obsolete form of "UVuf", which you should convert to instead use
7095
7096            const char *  UVf
7097
7098       "UVof"
7099           This symbol defines the format string used for printing a Perl UV
7100           as an unsigned octal integer.
7101
7102       "UVuf"
7103           This symbol defines the format string used for printing a Perl UV
7104           as an unsigned decimal integer.
7105
7106       "UVXf"
7107           This symbol defines the format string used for printing a Perl UV
7108           as an unsigned hexadecimal integer in uppercase "ABCDEF".
7109
7110       "UVxf"
7111           This symbol defines the format string used for printing a Perl UV
7112           as an unsigned hexadecimal integer in lowercase abcdef.
7113

Lexer interface

7115       This is the lower layer of the Perl parser, managing characters and
7116       tokens.
7117
7118       "BHK"
7119           Described in perlguts.
7120
7121       "lex_bufutf8"
7122           NOTE: "lex_bufutf8" is experimental and may change or be removed
7123           without notice.
7124
7125           Indicates whether the octets in the lexer buffer
7126           ("PL_parser->linestr") should be interpreted as the UTF-8 encoding
7127           of Unicode characters.  If not, they should be interpreted as
7128           Latin-1 characters.  This is analogous to the "SvUTF8" flag for
7129           scalars.
7130
7131           In UTF-8 mode, it is not guaranteed that the lexer buffer actually
7132           contains valid UTF-8.  Lexing code must be robust in the face of
7133           invalid encoding.
7134
7135           The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
7136           significant, but not the whole story regarding the input character
7137           encoding.  Normally, when a file is being read, the scalar contains
7138           octets and its "SvUTF8" flag is off, but the octets should be
7139           interpreted as UTF-8 if the "use utf8" pragma is in effect.  During
7140           a string eval, however, the scalar may have the "SvUTF8" flag on,
7141           and in this case its octets should be interpreted as UTF-8 unless
7142           the "use bytes" pragma is in effect.  This logic may change in the
7143           future; use this function instead of implementing the logic
7144           yourself.
7145
7146            bool  lex_bufutf8()
7147
7148       "lex_discard_to"
7149           NOTE: "lex_discard_to" is experimental and may change or be removed
7150           without notice.
7151
7152           Discards the first part of the "PL_parser->linestr" buffer, up to
7153           "ptr".  The remaining content of the buffer will be moved, and all
7154           pointers into the buffer updated appropriately.  "ptr" must not be
7155           later in the buffer than the position of "PL_parser->bufptr": it is
7156           not permitted to discard text that has yet to be lexed.
7157
7158           Normally it is not necessarily to do this directly, because it
7159           suffices to use the implicit discarding behaviour of
7160           "lex_next_chunk" and things based on it.  However, if a token
7161           stretches across multiple lines, and the lexing code has kept
7162           multiple lines of text in the buffer for that purpose, then after
7163           completion of the token it would be wise to explicitly discard the
7164           now-unneeded earlier lines, to avoid future multi-line tokens
7165           growing the buffer without bound.
7166
7167            void  lex_discard_to(char *ptr)
7168
7169       "lex_grow_linestr"
7170           NOTE: "lex_grow_linestr" is experimental and may change or be
7171           removed without notice.
7172
7173           Reallocates the lexer buffer ("PL_parser->linestr") to accommodate
7174           at least "len" octets (including terminating "NUL").  Returns a
7175           pointer to the reallocated buffer.  This is necessary before making
7176           any direct modification of the buffer that would increase its
7177           length.  "lex_stuff_pvn" provides a more convenient way to insert
7178           text into the buffer.
7179
7180           Do not use "SvGROW" or "sv_grow" directly on "PL_parser->linestr";
7181           this function updates all of the lexer's variables that point
7182           directly into the buffer.
7183
7184            char *  lex_grow_linestr(STRLEN len)
7185
7186       "lex_next_chunk"
7187           NOTE: "lex_next_chunk" is experimental and may change or be removed
7188           without notice.
7189
7190           Reads in the next chunk of text to be lexed, appending it to
7191           "PL_parser->linestr".  This should be called when lexing code has
7192           looked to the end of the current chunk and wants to know more.  It
7193           is usual, but not necessary, for lexing to have consumed the
7194           entirety of the current chunk at this time.
7195
7196           If "PL_parser->bufptr" is pointing to the very end of the current
7197           chunk (i.e., the current chunk has been entirely consumed),
7198           normally the current chunk will be discarded at the same time that
7199           the new chunk is read in.  If "flags" has the "LEX_KEEP_PREVIOUS"
7200           bit set, the current chunk will not be discarded.  If the current
7201           chunk has not been entirely consumed, then it will not be discarded
7202           regardless of the flag.
7203
7204           Returns true if some new text was added to the buffer, or false if
7205           the buffer has reached the end of the input text.
7206
7207            bool  lex_next_chunk(U32 flags)
7208
7209       "lex_peek_unichar"
7210           NOTE: "lex_peek_unichar" is experimental and may change or be
7211           removed without notice.
7212
7213           Looks ahead one (Unicode) character in the text currently being
7214           lexed.  Returns the codepoint (unsigned integer value) of the next
7215           character, or -1 if lexing has reached the end of the input text.
7216           To consume the peeked character, use "lex_read_unichar".
7217
7218           If the next character is in (or extends into) the next chunk of
7219           input text, the next chunk will be read in.  Normally the current
7220           chunk will be discarded at the same time, but if "flags" has the
7221           "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
7222           discarded.
7223
7224           If the input is being interpreted as UTF-8 and a UTF-8 encoding
7225           error is encountered, an exception is generated.
7226
7227            I32  lex_peek_unichar(U32 flags)
7228
7229       "lex_read_space"
7230           NOTE: "lex_read_space" is experimental and may change or be removed
7231           without notice.
7232
7233           Reads optional spaces, in Perl style, in the text currently being
7234           lexed.  The spaces may include ordinary whitespace characters and
7235           Perl-style comments.  "#line" directives are processed if
7236           encountered.  "PL_parser->bufptr" is moved past the spaces, so that
7237           it points at a non-space character (or the end of the input text).
7238
7239           If spaces extend into the next chunk of input text, the next chunk
7240           will be read in.  Normally the current chunk will be discarded at
7241           the same time, but if "flags" has the "LEX_KEEP_PREVIOUS" bit set,
7242           then the current chunk will not be discarded.
7243
7244            void  lex_read_space(U32 flags)
7245
7246       "lex_read_to"
7247           NOTE: "lex_read_to" is experimental and may change or be removed
7248           without notice.
7249
7250           Consume text in the lexer buffer, from "PL_parser->bufptr" up to
7251           "ptr".  This advances "PL_parser->bufptr" to match "ptr",
7252           performing the correct bookkeeping whenever a newline character is
7253           passed.  This is the normal way to consume lexed text.
7254
7255           Interpretation of the buffer's octets can be abstracted out by
7256           using the slightly higher-level functions "lex_peek_unichar" and
7257           "lex_read_unichar".
7258
7259            void  lex_read_to(char *ptr)
7260
7261       "lex_read_unichar"
7262           NOTE: "lex_read_unichar" is experimental and may change or be
7263           removed without notice.
7264
7265           Reads the next (Unicode) character in the text currently being
7266           lexed.  Returns the codepoint (unsigned integer value) of the
7267           character read, and moves "PL_parser->bufptr" past the character,
7268           or returns -1 if lexing has reached the end of the input text.  To
7269           non-destructively examine the next character, use
7270           "lex_peek_unichar" instead.
7271
7272           If the next character is in (or extends into) the next chunk of
7273           input text, the next chunk will be read in.  Normally the current
7274           chunk will be discarded at the same time, but if "flags" has the
7275           "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
7276           discarded.
7277
7278           If the input is being interpreted as UTF-8 and a UTF-8 encoding
7279           error is encountered, an exception is generated.
7280
7281            I32  lex_read_unichar(U32 flags)
7282
7283       "lex_start"
7284           NOTE: "lex_start" is experimental and may change or be removed
7285           without notice.
7286
7287           Creates and initialises a new lexer/parser state object, supplying
7288           a context in which to lex and parse from a new source of Perl code.
7289           A pointer to the new state object is placed in "PL_parser".  An
7290           entry is made on the save stack so that upon unwinding, the new
7291           state object will be destroyed and the former value of "PL_parser"
7292           will be restored.  Nothing else need be done to clean up the
7293           parsing context.
7294
7295           The code to be parsed comes from "line" and "rsfp".  "line", if
7296           non-null, provides a string (in SV form) containing code to be
7297           parsed.  A copy of the string is made, so subsequent modification
7298           of "line" does not affect parsing.  "rsfp", if non-null, provides
7299           an input stream from which code will be read to be parsed.  If both
7300           are non-null, the code in "line" comes first and must consist of
7301           complete lines of input, and "rsfp" supplies the remainder of the
7302           source.
7303
7304           The "flags" parameter is reserved for future use.  Currently it is
7305           only used by perl internally, so extensions should always pass
7306           zero.
7307
7308            void  lex_start(SV *line, PerlIO *rsfp, U32 flags)
7309
7310       "lex_stuff_pv"
7311           NOTE: "lex_stuff_pv" is experimental and may change or be removed
7312           without notice.
7313
7314           Insert characters into the lexer buffer ("PL_parser->linestr"),
7315           immediately after the current lexing point ("PL_parser->bufptr"),
7316           reallocating the buffer if necessary.  This means that lexing code
7317           that runs later will see the characters as if they had appeared in
7318           the input.  It is not recommended to do this as part of normal
7319           parsing, and most uses of this facility run the risk of the
7320           inserted characters being interpreted in an unintended manner.
7321
7322           The string to be inserted is represented by octets starting at "pv"
7323           and continuing to the first nul.  These octets are interpreted as
7324           either UTF-8 or Latin-1, according to whether the "LEX_STUFF_UTF8"
7325           flag is set in "flags".  The characters are recoded for the lexer
7326           buffer, according to how the buffer is currently being interpreted
7327           ("lex_bufutf8").  If it is not convenient to nul-terminate a string
7328           to be inserted, the "lex_stuff_pvn" function is more appropriate.
7329
7330            void  lex_stuff_pv(const char *pv, U32 flags)
7331
7332       "lex_stuff_pvn"
7333           NOTE: "lex_stuff_pvn" is experimental and may change or be removed
7334           without notice.
7335
7336           Insert characters into the lexer buffer ("PL_parser->linestr"),
7337           immediately after the current lexing point ("PL_parser->bufptr"),
7338           reallocating the buffer if necessary.  This means that lexing code
7339           that runs later will see the characters as if they had appeared in
7340           the input.  It is not recommended to do this as part of normal
7341           parsing, and most uses of this facility run the risk of the
7342           inserted characters being interpreted in an unintended manner.
7343
7344           The string to be inserted is represented by "len" octets starting
7345           at "pv".  These octets are interpreted as either UTF-8 or Latin-1,
7346           according to whether the "LEX_STUFF_UTF8" flag is set in "flags".
7347           The characters are recoded for the lexer buffer, according to how
7348           the buffer is currently being interpreted ("lex_bufutf8").  If a
7349           string to be inserted is available as a Perl scalar, the
7350           "lex_stuff_sv" function is more convenient.
7351
7352            void  lex_stuff_pvn(const char *pv, STRLEN len, U32 flags)
7353
7354       "lex_stuff_pvs"
7355           NOTE: "lex_stuff_pvs" is experimental and may change or be removed
7356           without notice.
7357
7358           Like "lex_stuff_pvn", but takes a literal string instead of a
7359           string/length pair.
7360
7361            void  lex_stuff_pvs("pv", U32 flags)
7362
7363       "lex_stuff_sv"
7364           NOTE: "lex_stuff_sv" is experimental and may change or be removed
7365           without notice.
7366
7367           Insert characters into the lexer buffer ("PL_parser->linestr"),
7368           immediately after the current lexing point ("PL_parser->bufptr"),
7369           reallocating the buffer if necessary.  This means that lexing code
7370           that runs later will see the characters as if they had appeared in
7371           the input.  It is not recommended to do this as part of normal
7372           parsing, and most uses of this facility run the risk of the
7373           inserted characters being interpreted in an unintended manner.
7374
7375           The string to be inserted is the string value of "sv".  The
7376           characters are recoded for the lexer buffer, according to how the
7377           buffer is currently being interpreted ("lex_bufutf8").  If a string
7378           to be inserted is not already a Perl scalar, the "lex_stuff_pvn"
7379           function avoids the need to construct a scalar.
7380
7381            void  lex_stuff_sv(SV *sv, U32 flags)
7382
7383       "lex_unstuff"
7384           NOTE: "lex_unstuff" is experimental and may change or be removed
7385           without notice.
7386
7387           Discards text about to be lexed, from "PL_parser->bufptr" up to
7388           "ptr".  Text following "ptr" will be moved, and the buffer
7389           shortened.  This hides the discarded text from any lexing code that
7390           runs later, as if the text had never appeared.
7391
7392           This is not the normal way to consume lexed text.  For that, use
7393           "lex_read_to".
7394
7395            void  lex_unstuff(char *ptr)
7396
7397       "parse_arithexpr"
7398           NOTE: "parse_arithexpr" is experimental and may change or be
7399           removed without notice.
7400
7401           Parse a Perl arithmetic expression.  This may contain operators of
7402           precedence down to the bit shift operators.  The expression must be
7403           followed (and thus terminated) either by a comparison or lower-
7404           precedence operator or by something that would normally terminate
7405           an expression such as semicolon.  If "flags" has the
7406           "PARSE_OPTIONAL" bit set, then the expression is optional,
7407           otherwise it is mandatory.  It is up to the caller to ensure that
7408           the dynamic parser state ("PL_parser" et al) is correctly set to
7409           reflect the source of the code to be parsed and the lexical context
7410           for the expression.
7411
7412           The op tree representing the expression is returned.  If an
7413           optional expression is absent, a null pointer is returned,
7414           otherwise the pointer will be non-null.
7415
7416           If an error occurs in parsing or compilation, in most cases a valid
7417           op tree is returned anyway.  The error is reflected in the parser
7418           state, normally resulting in a single exception at the top level of
7419           parsing which covers all the compilation errors that occurred.
7420           Some compilation errors, however, will throw an exception
7421           immediately.
7422
7423            OP *  parse_arithexpr(U32 flags)
7424
7425       "parse_barestmt"
7426           NOTE: "parse_barestmt" is experimental and may change or be removed
7427           without notice.
7428
7429           Parse a single unadorned Perl statement.  This may be a normal
7430           imperative statement or a declaration that has compile-time effect.
7431           It does not include any label or other affixture.  It is up to the
7432           caller to ensure that the dynamic parser state ("PL_parser" et al)
7433           is correctly set to reflect the source of the code to be parsed and
7434           the lexical context for the statement.
7435
7436           The op tree representing the statement is returned.  This may be a
7437           null pointer if the statement is null, for example if it was
7438           actually a subroutine definition (which has compile-time side
7439           effects).  If not null, it will be ops directly implementing the
7440           statement, suitable to pass to "newSTATEOP".  It will not normally
7441           include a "nextstate" or equivalent op (except for those embedded
7442           in a scope contained entirely within the statement).
7443
7444           If an error occurs in parsing or compilation, in most cases a valid
7445           op tree (most likely null) is returned anyway.  The error is
7446           reflected in the parser state, normally resulting in a single
7447           exception at the top level of parsing which covers all the
7448           compilation errors that occurred.  Some compilation errors,
7449           however, will throw an exception immediately.
7450
7451           The "flags" parameter is reserved for future use, and must always
7452           be zero.
7453
7454            OP *  parse_barestmt(U32 flags)
7455
7456       "parse_block"
7457           NOTE: "parse_block" is experimental and may change or be removed
7458           without notice.
7459
7460           Parse a single complete Perl code block.  This consists of an
7461           opening brace, a sequence of statements, and a closing brace.  The
7462           block constitutes a lexical scope, so "my" variables and various
7463           compile-time effects can be contained within it.  It is up to the
7464           caller to ensure that the dynamic parser state ("PL_parser" et al)
7465           is correctly set to reflect the source of the code to be parsed and
7466           the lexical context for the statement.
7467
7468           The op tree representing the code block is returned.  This is
7469           always a real op, never a null pointer.  It will normally be a
7470           "lineseq" list, including "nextstate" or equivalent ops.  No ops to
7471           construct any kind of runtime scope are included by virtue of it
7472           being a block.
7473
7474           If an error occurs in parsing or compilation, in most cases a valid
7475           op tree (most likely null) is returned anyway.  The error is
7476           reflected in the parser state, normally resulting in a single
7477           exception at the top level of parsing which covers all the
7478           compilation errors that occurred.  Some compilation errors,
7479           however, will throw an exception immediately.
7480
7481           The "flags" parameter is reserved for future use, and must always
7482           be zero.
7483
7484            OP *  parse_block(U32 flags)
7485
7486       "parse_fullexpr"
7487           NOTE: "parse_fullexpr" is experimental and may change or be removed
7488           without notice.
7489
7490           Parse a single complete Perl expression.  This allows the full
7491           expression grammar, including the lowest-precedence operators such
7492           as "or".  The expression must be followed (and thus terminated) by
7493           a token that an expression would normally be terminated by: end-of-
7494           file, closing bracketing punctuation, semicolon, or one of the
7495           keywords that signals a postfix expression-statement modifier.  If
7496           "flags" has the "PARSE_OPTIONAL" bit set, then the expression is
7497           optional, otherwise it is mandatory.  It is up to the caller to
7498           ensure that the dynamic parser state ("PL_parser" et al) is
7499           correctly set to reflect the source of the code to be parsed and
7500           the lexical context for the expression.
7501
7502           The op tree representing the expression is returned.  If an
7503           optional expression is absent, a null pointer is returned,
7504           otherwise the pointer will be non-null.
7505
7506           If an error occurs in parsing or compilation, in most cases a valid
7507           op tree is returned anyway.  The error is reflected in the parser
7508           state, normally resulting in a single exception at the top level of
7509           parsing which covers all the compilation errors that occurred.
7510           Some compilation errors, however, will throw an exception
7511           immediately.
7512
7513            OP *  parse_fullexpr(U32 flags)
7514
7515       "parse_fullstmt"
7516           NOTE: "parse_fullstmt" is experimental and may change or be removed
7517           without notice.
7518
7519           Parse a single complete Perl statement.  This may be a normal
7520           imperative statement or a declaration that has compile-time effect,
7521           and may include optional labels.  It is up to the caller to ensure
7522           that the dynamic parser state ("PL_parser" et al) is correctly set
7523           to reflect the source of the code to be parsed and the lexical
7524           context for the statement.
7525
7526           The op tree representing the statement is returned.  This may be a
7527           null pointer if the statement is null, for example if it was
7528           actually a subroutine definition (which has compile-time side
7529           effects).  If not null, it will be the result of a "newSTATEOP"
7530           call, normally including a "nextstate" or equivalent op.
7531
7532           If an error occurs in parsing or compilation, in most cases a valid
7533           op tree (most likely null) is returned anyway.  The error is
7534           reflected in the parser state, normally resulting in a single
7535           exception at the top level of parsing which covers all the
7536           compilation errors that occurred.  Some compilation errors,
7537           however, will throw an exception immediately.
7538
7539           The "flags" parameter is reserved for future use, and must always
7540           be zero.
7541
7542            OP *  parse_fullstmt(U32 flags)
7543
7544       "parse_label"
7545           NOTE: "parse_label" is experimental and may change or be removed
7546           without notice.
7547
7548           Parse a single label, possibly optional, of the type that may
7549           prefix a Perl statement.  It is up to the caller to ensure that the
7550           dynamic parser state ("PL_parser" et al) is correctly set to
7551           reflect the source of the code to be parsed.  If "flags" has the
7552           "PARSE_OPTIONAL" bit set, then the label is optional, otherwise it
7553           is mandatory.
7554
7555           The name of the label is returned in the form of a fresh scalar.
7556           If an optional label is absent, a null pointer is returned.
7557
7558           If an error occurs in parsing, which can only occur if the label is
7559           mandatory, a valid label is returned anyway.  The error is
7560           reflected in the parser state, normally resulting in a single
7561           exception at the top level of parsing which covers all the
7562           compilation errors that occurred.
7563
7564            SV *  parse_label(U32 flags)
7565
7566       "parse_listexpr"
7567           NOTE: "parse_listexpr" is experimental and may change or be removed
7568           without notice.
7569
7570           Parse a Perl list expression.  This may contain operators of
7571           precedence down to the comma operator.  The expression must be
7572           followed (and thus terminated) either by a low-precedence logic
7573           operator such as "or" or by something that would normally terminate
7574           an expression such as semicolon.  If "flags" has the
7575           "PARSE_OPTIONAL" bit set, then the expression is optional,
7576           otherwise it is mandatory.  It is up to the caller to ensure that
7577           the dynamic parser state ("PL_parser" et al) is correctly set to
7578           reflect the source of the code to be parsed and the lexical context
7579           for the expression.
7580
7581           The op tree representing the expression is returned.  If an
7582           optional expression is absent, a null pointer is returned,
7583           otherwise the pointer will be non-null.
7584
7585           If an error occurs in parsing or compilation, in most cases a valid
7586           op tree is returned anyway.  The error is reflected in the parser
7587           state, normally resulting in a single exception at the top level of
7588           parsing which covers all the compilation errors that occurred.
7589           Some compilation errors, however, will throw an exception
7590           immediately.
7591
7592            OP *  parse_listexpr(U32 flags)
7593
7594       "parse_stmtseq"
7595           NOTE: "parse_stmtseq" is experimental and may change or be removed
7596           without notice.
7597
7598           Parse a sequence of zero or more Perl statements.  These may be
7599           normal imperative statements, including optional labels, or
7600           declarations that have compile-time effect, or any mixture thereof.
7601           The statement sequence ends when a closing brace or end-of-file is
7602           encountered in a place where a new statement could have validly
7603           started.  It is up to the caller to ensure that the dynamic parser
7604           state ("PL_parser" et al) is correctly set to reflect the source of
7605           the code to be parsed and the lexical context for the statements.
7606
7607           The op tree representing the statement sequence is returned.  This
7608           may be a null pointer if the statements were all null, for example
7609           if there were no statements or if there were only subroutine
7610           definitions (which have compile-time side effects).  If not null,
7611           it will be a "lineseq" list, normally including "nextstate" or
7612           equivalent ops.
7613
7614           If an error occurs in parsing or compilation, in most cases a valid
7615           op tree is returned anyway.  The error is reflected in the parser
7616           state, normally resulting in a single exception at the top level of
7617           parsing which covers all the compilation errors that occurred.
7618           Some compilation errors, however, will throw an exception
7619           immediately.
7620
7621           The "flags" parameter is reserved for future use, and must always
7622           be zero.
7623
7624            OP *  parse_stmtseq(U32 flags)
7625
7626       "parse_subsignature"
7627           NOTE: "parse_subsignature" is experimental and may change or be
7628           removed without notice.
7629
7630           Parse a subroutine signature declaration. This is the contents of
7631           the parentheses following a named or anonymous subroutine
7632           declaration when the "signatures" feature is enabled. Note that
7633           this function neither expects nor consumes the opening and closing
7634           parentheses around the signature; it is the caller's job to handle
7635           these.
7636
7637           This function must only be called during parsing of a subroutine;
7638           after "start_subparse" has been called. It might allocate lexical
7639           variables on the pad for the current subroutine.
7640
7641           The op tree to unpack the arguments from the stack at runtime is
7642           returned.  This op tree should appear at the beginning of the
7643           compiled function. The caller may wish to use "op_append_list" to
7644           build their function body after it, or splice it together with the
7645           body before calling "newATTRSUB".
7646
7647           The "flags" parameter is reserved for future use, and must always
7648           be zero.
7649
7650            OP *  parse_subsignature(U32 flags)
7651
7652       "parse_termexpr"
7653           NOTE: "parse_termexpr" is experimental and may change or be removed
7654           without notice.
7655
7656           Parse a Perl term expression.  This may contain operators of
7657           precedence down to the assignment operators.  The expression must
7658           be followed (and thus terminated) either by a comma or lower-
7659           precedence operator or by something that would normally terminate
7660           an expression such as semicolon.  If "flags" has the
7661           "PARSE_OPTIONAL" bit set, then the expression is optional,
7662           otherwise it is mandatory.  It is up to the caller to ensure that
7663           the dynamic parser state ("PL_parser" et al) is correctly set to
7664           reflect the source of the code to be parsed and the lexical context
7665           for the expression.
7666
7667           The op tree representing the expression is returned.  If an
7668           optional expression is absent, a null pointer is returned,
7669           otherwise the pointer will be non-null.
7670
7671           If an error occurs in parsing or compilation, in most cases a valid
7672           op tree is returned anyway.  The error is reflected in the parser
7673           state, normally resulting in a single exception at the top level of
7674           parsing which covers all the compilation errors that occurred.
7675           Some compilation errors, however, will throw an exception
7676           immediately.
7677
7678            OP *  parse_termexpr(U32 flags)
7679
7680       "PL_parser"
7681           Pointer to a structure encapsulating the state of the parsing
7682           operation currently in progress.  The pointer can be locally
7683           changed to perform a nested parse without interfering with the
7684           state of an outer parse.  Individual members of "PL_parser" have
7685           their own documentation.
7686
7687       "PL_parser->bufend"
7688           NOTE: "PL_parser->bufend" is experimental and may change or be
7689           removed without notice.
7690
7691           Direct pointer to the end of the chunk of text currently being
7692           lexed, the end of the lexer buffer.  This is equal to
7693           "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)".  A "NUL"
7694           character (zero octet) is always located at the end of the buffer,
7695           and does not count as part of the buffer's contents.
7696
7697       "PL_parser->bufptr"
7698           NOTE: "PL_parser->bufptr" is experimental and may change or be
7699           removed without notice.
7700
7701           Points to the current position of lexing inside the lexer buffer.
7702           Characters around this point may be freely examined, within the
7703           range delimited by SvPVX("PL_parser->linestr") and
7704           "PL_parser->bufend".  The octets of the buffer may be intended to
7705           be interpreted as either UTF-8 or Latin-1, as indicated by
7706           "lex_bufutf8".
7707
7708           Lexing code (whether in the Perl core or not) moves this pointer
7709           past the characters that it consumes.  It is also expected to
7710           perform some bookkeeping whenever a newline character is consumed.
7711           This movement can be more conveniently performed by the function
7712           "lex_read_to", which handles newlines appropriately.
7713
7714           Interpretation of the buffer's octets can be abstracted out by
7715           using the slightly higher-level functions "lex_peek_unichar" and
7716           "lex_read_unichar".
7717
7718       "PL_parser->linestart"
7719           NOTE: "PL_parser->linestart" is experimental and may change or be
7720           removed without notice.
7721
7722           Points to the start of the current line inside the lexer buffer.
7723           This is useful for indicating at which column an error occurred,
7724           and not much else.  This must be updated by any lexing code that
7725           consumes a newline; the function "lex_read_to" handles this detail.
7726
7727       "PL_parser->linestr"
7728           NOTE: "PL_parser->linestr" is experimental and may change or be
7729           removed without notice.
7730
7731           Buffer scalar containing the chunk currently under consideration of
7732           the text currently being lexed.  This is always a plain string
7733           scalar (for which "SvPOK" is true).  It is not intended to be used
7734           as a scalar by normal scalar means; instead refer to the buffer
7735           directly by the pointer variables described below.
7736
7737           The lexer maintains various "char*" pointers to things in the
7738           "PL_parser->linestr" buffer.  If "PL_parser->linestr" is ever
7739           reallocated, all of these pointers must be updated.  Don't attempt
7740           to do this manually, but rather use "lex_grow_linestr" if you need
7741           to reallocate the buffer.
7742
7743           The content of the text chunk in the buffer is commonly exactly one
7744           complete line of input, up to and including a newline terminator,
7745           but there are situations where it is otherwise.  The octets of the
7746           buffer may be intended to be interpreted as either UTF-8 or
7747           Latin-1.  The function "lex_bufutf8" tells you which.  Do not use
7748           the "SvUTF8" flag on this scalar, which may disagree with it.
7749
7750           For direct examination of the buffer, the variable
7751           "PL_parser->bufend" points to the end of the buffer.  The current
7752           lexing position is pointed to by "PL_parser->bufptr".  Direct use
7753           of these pointers is usually preferable to examination of the
7754           scalar through normal scalar means.
7755
7756       "suspend_compcv"
7757           Implements part of the concept of a "suspended compilation CV",
7758           which can be used to pause the parser and compiler during parsing a
7759           CV in order to come back to it later on.
7760
7761           This function saves the current state of the subroutine under
7762           compilation ("PL_compcv") into the supplied buffer.  This should be
7763           used initially to create the state in the buffer, as the final
7764           thing before a "LEAVE" within a block.
7765
7766               ENTER;
7767               start_subparse(0);
7768               ...
7769
7770               suspend_compcv(&buffer);
7771               LEAVE;
7772
7773           Once suspended, the "resume_compcv" or "resume_compcv_and_save"
7774           function can later be used to continue the parsing from the point
7775           this stopped.
7776
7777            void  suspend_compcv(struct suspended_compcv *buffer)
7778
7779       "wrap_infix_plugin"
7780           NOTE: "wrap_infix_plugin" is experimental and may change or be
7781           removed without notice.
7782
7783           NOTE: This API exists entirely for the purpose of making the CPAN
7784           module "XS::Parse::Infix" work. It is not expected that additional
7785           modules will make use of it; rather, that they should use
7786           "XS::Parse::Infix" to provide parsing of new infix operators.
7787
7788           Puts a C function into the chain of infix plugins.  This is the
7789           preferred way to manipulate the "PL_infix_plugin" variable.
7790           "new_plugin" is a pointer to the C function that is to be added to
7791           the infix plugin chain, and "old_plugin_p" points to a storage
7792           location where a pointer to the next function in the chain will be
7793           stored.  The value of "new_plugin" is written into the
7794           "PL_infix_plugin" variable, while the value previously stored there
7795           is written to *old_plugin_p.
7796
7797           Direct access to "PL_infix_plugin" should be avoided.
7798
7799            void  wrap_infix_plugin(Perl_infix_plugin_t new_plugin,
7800                                    Perl_infix_plugin_t *old_plugin_p)
7801
7802       "wrap_keyword_plugin"
7803           NOTE: "wrap_keyword_plugin" is experimental and may change or be
7804           removed without notice.
7805
7806           Puts a C function into the chain of keyword plugins.  This is the
7807           preferred way to manipulate the "PL_keyword_plugin" variable.
7808           "new_plugin" is a pointer to the C function that is to be added to
7809           the keyword plugin chain, and "old_plugin_p" points to the storage
7810           location where a pointer to the next function in the chain will be
7811           stored.  The value of "new_plugin" is written into the
7812           "PL_keyword_plugin" variable, while the value previously stored
7813           there is written to *old_plugin_p.
7814
7815           "PL_keyword_plugin" is global to an entire process, and a module
7816           wishing to hook keyword parsing may find itself invoked more than
7817           once per process, typically in different threads.  To handle that
7818           situation, this function is idempotent.  The location *old_plugin_p
7819           must initially (once per process) contain a null pointer.  A C
7820           variable of static duration (declared at file scope, typically also
7821           marked "static" to give it internal linkage) will be implicitly
7822           initialised appropriately, if it does not have an explicit
7823           initialiser.  This function will only actually modify the plugin
7824           chain if it finds *old_plugin_p to be null.  This function is also
7825           thread safe on the small scale.  It uses appropriate locking to
7826           avoid race conditions in accessing "PL_keyword_plugin".
7827
7828           When this function is called, the function referenced by
7829           "new_plugin" must be ready to be called, except for *old_plugin_p
7830           being unfilled.  In a threading situation, "new_plugin" may be
7831           called immediately, even before this function has returned.
7832           *old_plugin_p will always be appropriately set before "new_plugin"
7833           is called.  If "new_plugin" decides not to do anything special with
7834           the identifier that it is given (which is the usual case for most
7835           calls to a keyword plugin), it must chain the plugin function
7836           referenced by *old_plugin_p.
7837
7838           Taken all together, XS code to install a keyword plugin should
7839           typically look something like this:
7840
7841               static Perl_keyword_plugin_t next_keyword_plugin;
7842               static OP *my_keyword_plugin(pTHX_
7843                   char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
7844               {
7845                   if (memEQs(keyword_ptr, keyword_len,
7846                              "my_new_keyword")) {
7847                       ...
7848                   } else {
7849                       return next_keyword_plugin(aTHX_
7850                           keyword_ptr, keyword_len, op_ptr);
7851                   }
7852               }
7853               BOOT:
7854                   wrap_keyword_plugin(my_keyword_plugin,
7855                                       &next_keyword_plugin);
7856
7857           Direct access to "PL_keyword_plugin" should be avoided.
7858
7859            void  wrap_keyword_plugin(Perl_keyword_plugin_t new_plugin,
7860                                      Perl_keyword_plugin_t *old_plugin_p)
7861

Locales

7863       "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
7864           This macro should be used as a statement.  It declares a private
7865           variable (whose name begins with an underscore) that is needed by
7866           the other macros in this section.  Failing to include this
7867           correctly should lead to a syntax error.  For compatibility with
7868           C89 C compilers it should be placed in a block before any
7869           executable statements.
7870
7871            void  DECLARATION_FOR_LC_NUMERIC_MANIPULATION
7872
7873       "foldEQ_locale"
7874           Returns true if the leading "len" bytes of the strings "s1" and
7875           "s2" are the same case-insensitively in the current locale; false
7876           otherwise.
7877
7878            I32  foldEQ_locale(const char *a, const char *b, I32 len)
7879
7880       "HAS_DUPLOCALE"
7881           This symbol, if defined, indicates that the "duplocale" routine is
7882           available to duplicate a locale object.
7883
7884       "HAS_FREELOCALE"
7885           This symbol, if defined, indicates that the "freelocale" routine is
7886           available to deallocates the resources associated with a locale
7887           object.
7888
7889       "HAS_LC_MONETARY_2008"
7890           This symbol, if defined, indicates that the localeconv routine is
7891           available and has the additional members added in "POSIX"
7892           1003.1-2008.
7893
7894       "HAS_LOCALECONV"
7895           This symbol, if defined, indicates that the "localeconv" routine is
7896           available for numeric and monetary formatting conventions.
7897
7898       "HAS_LOCALECONV_L"
7899           This symbol, if defined, indicates that the "localeconv_l" routine
7900           is available to query certain information about a locale.
7901
7902       "HAS_NEWLOCALE"
7903           This symbol, if defined, indicates that the "newlocale" routine is
7904           available to return a new locale object or modify an existing
7905           locale object.
7906
7907       "HAS_NL_LANGINFO"
7908           This symbol, if defined, indicates that the "nl_langinfo" routine
7909           is available to return local data.  You will also need langinfo.h
7910           and therefore "I_LANGINFO".
7911
7912       "HAS_NL_LANGINFO_L"
7913           This symbol, when defined, indicates presence of the
7914           nl_langinfo_l() function
7915
7916       "HAS_QUERYLOCALE"
7917           This symbol, if defined, indicates that the "querylocale" routine
7918           is available to return the name of the locale for a category mask.
7919
7920       "HAS_SETLOCALE"
7921           This symbol, if defined, indicates that the "setlocale" routine is
7922           available to handle locale-specific ctype implementations.
7923
7924       "HAS_SETLOCALE_R"
7925           This symbol, if defined, indicates that the "setlocale_r" routine
7926           is available to setlocale re-entrantly.
7927
7928       "HAS_THREAD_SAFE_NL_LANGINFO_L"
7929           This symbol, when defined, indicates presence of the
7930           nl_langinfo_l() function, and that it is thread-safe.
7931
7932       "HAS_USELOCALE"
7933           This symbol, if defined, indicates that the "uselocale" routine is
7934           available to set the current locale for the calling thread.
7935
7936       "I_LANGINFO"
7937           This symbol, if defined, indicates that langinfo.h exists and
7938           should be included.
7939
7940            #ifdef I_LANGINFO
7941                #include <langinfo.h>
7942            #endif
7943
7944       "I_LOCALE"
7945           This symbol, if defined, indicates to the C program that it should
7946           include locale.h.
7947
7948            #ifdef I_LOCALE
7949                #include <locale.h>
7950            #endif
7951
7952       "IN_LOCALE"
7953           Evaluates to TRUE if the plain locale pragma without a parameter
7954           ("use locale") is in effect.
7955
7956            bool  IN_LOCALE
7957
7958       "IN_LOCALE_COMPILETIME"
7959           Evaluates to TRUE if, when compiling a perl program (including an
7960           "eval") if the plain locale pragma without a parameter
7961           ("use locale") is in effect.
7962
7963            bool  IN_LOCALE_COMPILETIME
7964
7965       "IN_LOCALE_RUNTIME"
7966           Evaluates to TRUE if, when executing a perl program (including an
7967           "eval") if the plain locale pragma without a parameter
7968           ("use locale") is in effect.
7969
7970            bool  IN_LOCALE_RUNTIME
7971
7972       "I_XLOCALE"
7973           This symbol, if defined, indicates to the C program that the header
7974           xlocale.h is available.  See also "NEED_XLOCALE_H"
7975
7976            #ifdef I_XLOCALE
7977                #include <xlocale.h>
7978            #endif
7979
7980       "NEED_XLOCALE_H"
7981           This symbol, if defined, indicates that the C program should
7982           include xlocale.h to get newlocale() and its friends.
7983
7984       "Perl_langinfo"
7985       "Perl_langinfo8"
7986           "Perl_langinfo" is an (almost) drop-in replacement for the system
7987           nl_langinfo(3), taking the same "item" parameter values, and
7988           returning the same information.  But it is more thread-safe than
7989           regular nl_langinfo(), and hides the quirks of Perl's locale
7990           handling from your code, and can be used on systems that lack a
7991           native "nl_langinfo".
7992
7993           However, you should instead use the improved version of this:
7994           "Perl_langinfo8", which behaves identically except for an
7995           additional parameter, a pointer to a variable declared as
7996           ""utf8ness_t"", into which it returns to you how you should treat
7997           the returned string with regards to it being encoded in UTF-8 or
7998           not.
7999
8000           Concerning the differences between these and plain nl_langinfo():
8001
8002           a.  "Perl_langinfo8" has an extra parameter, described above.
8003               Besides this, the other reason they aren't quite a drop-in
8004               replacement is actually an advantage.  The "const"ness of the
8005               return allows the compiler to catch attempts to write into the
8006               returned buffer, which is illegal and could cause run-time
8007               crashes.
8008
8009           b.  They deliver the correct results for the "RADIXCHAR" and
8010               "THOUSEP" items, without you having to write extra code.  The
8011               reason for the extra code would be because these are from the
8012               "LC_NUMERIC" locale category, which is normally kept set by
8013               Perl so that the radix is a dot, and the separator is the empty
8014               string, no matter what the underlying locale is supposed to be,
8015               and so to get the expected results, you have to temporarily
8016               toggle into the underlying locale, and later toggle back.  (You
8017               could use plain "nl_langinfo" and
8018               "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" for this but then you
8019               wouldn't get the other advantages of Perl_langinfo(); not
8020               keeping "LC_NUMERIC" in the C (or equivalent) locale would
8021               break a lot of CPAN, which is expecting the radix (decimal
8022               point) character to be a dot.)
8023
8024           c.  The system function they replace can have its static return
8025               buffer trashed, not only by a subsequent call to that function,
8026               but by a "freelocale", "setlocale", or other locale change.
8027               The returned buffer of these functions is not changed until the
8028               next call to one or the other, so the buffer is never in a
8029               trashed state.
8030
8031           d.  The return buffer is per-thread, so it also is never
8032               overwritten by a call to these functions from another thread;
8033               unlike the function it replaces.
8034
8035           e.  But most importantly, they work on systems that don't have
8036               "nl_langinfo", such as Windows, hence making your code more
8037               portable.  Of the fifty-some possible items specified by the
8038               POSIX 2008 standard,
8039               <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
8040               only one is completely unimplemented, though on non-Windows
8041               platforms, another significant one is not fully implemented).
8042               They use various techniques to recover the other items,
8043               including calling localeconv(3), and strftime(3), both of which
8044               are specified in C89, so should be always be available.  Later
8045               strftime() versions have additional capabilities; What the C
8046               locale yields or "" is returned for any item not available on
8047               your system.
8048
8049               It is important to note that, when called with an item that is
8050               recovered by using "localeconv", the buffer from any previous
8051               explicit call to localeconv(3) will be overwritten.  But you
8052               shouldn't be using "localeconv" anyway because it is is very
8053               much not thread-safe, and suffers from the same problems
8054               outlined in item 'b.' above for the fields it returns that are
8055               controlled by the LC_NUMERIC locale category.  Instead, avoid
8056               all of those problems by calling "Perl_localeconv", which is
8057               thread-safe; or by using the methods given in perlcall  to call
8058               POSIX::localeconv(), which is also thread-safe.
8059
8060           The details for those items which may deviate from what this
8061           emulation returns and what a native nl_langinfo() would return are
8062           specified in I18N::Langinfo.
8063
8064           When using "Perl_langinfo8" (or plain "Perl_langinfo") on systems
8065           that don't have a native nl_langinfo(), you must
8066
8067            #include "perl_langinfo.h"
8068
8069           before the "perl.h" "#include".  You can replace your langinfo.h
8070           "#include" with this one.  (Doing it this way keeps out the symbols
8071           that plain langinfo.h would try to import into the namespace for
8072           code that doesn't need it.)
8073
8074            const char *  Perl_langinfo (const int item)
8075            const char *  Perl_langinfo8(const int item, utf8ness_t *utf8ness)
8076
8077       "Perl_localeconv"
8078           This is a thread-safe version of the libc localeconv(3).  It is the
8079           same as POSIX::localeconv (returning a hash of the localeconv()
8080           fields), but directly callable from XS code.
8081
8082            HV *  Perl_localeconv(pTHX)
8083
8084       "Perl_setlocale"
8085           This is an (almost) drop-in replacement for the system
8086           setlocale(3), taking the same parameters, and returning the same
8087           information, except that it returns the correct underlying
8088           "LC_NUMERIC" locale.  Regular "setlocale" will instead return "C"
8089           if the underlying locale has a non-dot decimal point character, or
8090           a non-empty thousands separator for displaying floating point
8091           numbers.  This is because perl keeps that locale category such that
8092           it has a dot and empty separator, changing the locale briefly
8093           during the operations where the underlying one is required.
8094           "Perl_setlocale" knows about this, and compensates; regular
8095           "setlocale" doesn't.
8096
8097           Another reason it isn't completely a drop-in replacement is that it
8098           is declared to return "const char *", whereas the system setlocale
8099           omits the "const" (presumably because its API was specified long
8100           ago, and can't be updated; it is illegal to change the information
8101           "setlocale" returns; doing so leads to segfaults.)
8102
8103           Finally, "Perl_setlocale" works under all circumstances, whereas
8104           plain "setlocale" can be completely ineffective on some platforms
8105           under some configurations.
8106
8107           Changing the locale is not a good idea when more than one thread is
8108           running, except on systems where the predefined variable
8109           "${^SAFE_LOCALES}" is 1.  This is because on such systems the
8110           locale is global to the whole process and not local to just the
8111           thread calling the function.  So changing it in one thread
8112           instantaneously changes it in all.  On some such systems, the
8113           system setlocale() is ineffective, returning the wrong information,
8114           and failing to actually change the locale.  z/OS refuses to try to
8115           change the locale once a second thread is created.
8116           "Perl_setlocale", should give you accurate results of what actually
8117           happened on these problematic platforms, returning NULL if the
8118           system forbade the locale change.
8119
8120           The return points to a per-thread static buffer, which is
8121           overwritten the next time "Perl_setlocale" is called from the same
8122           thread.
8123
8124            const char *  Perl_setlocale(const int category,
8125                                         const char *locale)
8126
8127       "RESTORE_LC_NUMERIC"
8128           This is used in conjunction with one of the macros
8129           "STORE_LC_NUMERIC_SET_TO_NEEDED" and
8130           "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
8131           "LC_NUMERIC" state.
8132
8133           A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
8134           made to declare at compile time a private variable used by this
8135           macro and the two "STORE" ones.  This macro should be called as a
8136           single statement, not an expression, but with an empty argument
8137           list, like this:
8138
8139            {
8140               DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
8141                ...
8142               RESTORE_LC_NUMERIC();
8143                ...
8144            }
8145
8146            void  RESTORE_LC_NUMERIC()
8147
8148       "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
8149           This symbol, if defined, indicates that the setlocale routine is
8150           available and it accepts any input locale name as valid.
8151
8152       "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
8153           This is used by XS code that is "LC_NUMERIC" locale-aware to force
8154           the locale for category "LC_NUMERIC" to be what perl thinks is the
8155           current underlying locale.  (The perl interpreter could be wrong
8156           about what the underlying locale actually is if some C or XS code
8157           has called the C library function setlocale(3) behind its back;
8158           calling "sync_locale" before calling this macro will update perl's
8159           records.)
8160
8161           A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
8162           made to declare at compile time a private variable used by this
8163           macro.  This macro should be called as a single statement, not an
8164           expression, but with an empty argument list, like this:
8165
8166            {
8167               DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
8168                ...
8169               STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
8170                ...
8171               RESTORE_LC_NUMERIC();
8172                ...
8173            }
8174
8175           The private variable is used to save the current locale state, so
8176           that the requisite matching call to "RESTORE_LC_NUMERIC" can
8177           restore it.
8178
8179           On threaded perls not operating with thread-safe functionality,
8180           this macro uses a mutex to force a critical section.  Therefore the
8181           matching RESTORE should be close by, and guaranteed to be called.
8182
8183            void  STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
8184
8185       "STORE_LC_NUMERIC_SET_TO_NEEDED"
8186           This is used to help wrap XS or C code that is "LC_NUMERIC" locale-
8187           aware.  This locale category is generally kept set to a locale
8188           where the decimal radix character is a dot, and the separator
8189           between groups of digits is empty.  This is because most XS code
8190           that reads floating point numbers is expecting them to have this
8191           syntax.
8192
8193           This macro makes sure the current "LC_NUMERIC" state is set
8194           properly, to be aware of locale if the call to the XS or C code
8195           from the Perl program is from within the scope of a "use locale";
8196           or to ignore locale if the call is instead from outside such scope.
8197
8198           This macro is the start of wrapping the C or XS code; the wrap
8199           ending is done by calling the "RESTORE_LC_NUMERIC" macro after the
8200           operation.  Otherwise the state can be changed that will adversely
8201           affect other XS code.
8202
8203           A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
8204           made to declare at compile time a private variable used by this
8205           macro.  This macro should be called as a single statement, not an
8206           expression, but with an empty argument list, like this:
8207
8208            {
8209               DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
8210                ...
8211               STORE_LC_NUMERIC_SET_TO_NEEDED();
8212                ...
8213               RESTORE_LC_NUMERIC();
8214                ...
8215            }
8216
8217           On threaded perls not operating with thread-safe functionality,
8218           this macro uses a mutex to force a critical section.  Therefore the
8219           matching RESTORE should be close by, and guaranteed to be called;
8220           see "WITH_LC_NUMERIC_SET_TO_NEEDED" for a more contained way to
8221           ensure that.
8222
8223            void  STORE_LC_NUMERIC_SET_TO_NEEDED()
8224
8225       "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
8226           Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
8227           provided as the precalculated value of IN_LC(LC_NUMERIC). It is the
8228           caller's responsibility to ensure that the status of "PL_compiling"
8229           and "PL_hints" cannot have changed since the precalculation.
8230
8231            void  STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric)
8232
8233       "WITH_LC_NUMERIC_SET_TO_NEEDED"
8234           This macro invokes the supplied statement or block within the
8235           context of a "STORE_LC_NUMERIC_SET_TO_NEEDED" ..
8236           "RESTORE_LC_NUMERIC" pair if required, so eg:
8237
8238             WITH_LC_NUMERIC_SET_TO_NEEDED(
8239               SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
8240             );
8241
8242           is equivalent to:
8243
8244             {
8245           #ifdef USE_LOCALE_NUMERIC
8246               DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
8247               STORE_LC_NUMERIC_SET_TO_NEEDED();
8248           #endif
8249               SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
8250           #ifdef USE_LOCALE_NUMERIC
8251               RESTORE_LC_NUMERIC();
8252           #endif
8253             }
8254
8255            void  WITH_LC_NUMERIC_SET_TO_NEEDED(block)
8256
8257       "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
8258           Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
8259           as the precalculated value of IN_LC(LC_NUMERIC). It is the caller's
8260           responsibility to ensure that the status of "PL_compiling" and
8261           "PL_hints" cannot have changed since the precalculation.
8262
8263            void  WITH_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric, block)
8264

Magic

8266       "Magic" is special data attached to SV structures in order to give them
8267       "magical" properties.  When any Perl code tries to read from, or assign
8268       to, an SV marked as magical, it calls the 'get' or 'set' function
8269       associated with that SV's magic.  A get is called prior to reading an
8270       SV, in order to give it a chance to update its internal value (get on
8271       $. writes the line number of the last read filehandle into the SV's IV
8272       slot), while set is called after an SV has been written to, in order to
8273       allow it to make use of its changed value (set on $/ copies the SV's
8274       new value to the PL_rs global variable).
8275
8276       Magic is implemented as a linked list of MAGIC structures attached to
8277       the SV.  Each MAGIC struct holds the type of the magic, a pointer to an
8278       array of functions that implement the get(), set(), length() etc
8279       functions, plus space for some flags and pointers.  For example, a tied
8280       variable has a MAGIC structure that contains a pointer to the object
8281       associated with the tie.
8282
8283       "mg_clear"
8284           Clear something magical that the SV represents.  See "sv_magic".
8285
8286            int  mg_clear(SV *sv)
8287
8288       "mg_copy"
8289           Copies the magic from one SV to another.  See "sv_magic".
8290
8291            int  mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
8292
8293       "MGf_COPY"
8294       "MGf_DUP"
8295       "MGf_LOCAL"
8296           Described in perlguts.
8297
8298       "mg_find"
8299           Finds the magic pointer for "type" matching the SV.  See
8300           "sv_magic".
8301
8302            MAGIC *  mg_find(const SV *sv, int type)
8303
8304       "mg_findext"
8305           Finds the magic pointer of "type" with the given "vtbl" for the
8306           "SV".  See "sv_magicext".
8307
8308            MAGIC *  mg_findext(const SV *sv, int type, const MGVTBL *vtbl)
8309
8310       "mg_free"
8311           Free any magic storage used by the SV.  See "sv_magic".
8312
8313            int  mg_free(SV *sv)
8314
8315       "mg_freeext"
8316           Remove any magic of type "how" using virtual table "vtbl" from the
8317           SV "sv".  See "sv_magic".
8318
8319           "mg_freeext(sv, how, NULL)" is equivalent to "mg_free_type(sv,
8320           how)".
8321
8322            void  mg_freeext(SV *sv, int how, const MGVTBL *vtbl)
8323
8324       "mg_free_type"
8325           Remove any magic of type "how" from the SV "sv".  See "sv_magic".
8326
8327            void  mg_free_type(SV *sv, int how)
8328
8329       "mg_get"
8330           Do magic before a value is retrieved from the SV.  The type of SV
8331           must be >= "SVt_PVMG".  See "sv_magic".
8332
8333            int  mg_get(SV *sv)
8334
8335       "mg_magical"
8336           Turns on the magical status of an SV.  See "sv_magic".
8337
8338            void  mg_magical(SV *sv)
8339
8340       "mg_set"
8341           Do magic after a value is assigned to the SV.  See "sv_magic".
8342
8343            int  mg_set(SV *sv)
8344
8345       "MGVTBL"
8346           Described in perlguts.
8347
8348       "PERL_MAGIC_arylen"
8349       "PERL_MAGIC_arylen_p"
8350       "PERL_MAGIC_backref"
8351       "PERL_MAGIC_bm"
8352       "PERL_MAGIC_checkcall"
8353       "PERL_MAGIC_collxfrm"
8354       "PERL_MAGIC_dbfile"
8355       "PERL_MAGIC_dbline"
8356       "PERL_MAGIC_debugvar"
8357       "PERL_MAGIC_defelem"
8358       "PERL_MAGIC_destruct"
8359       "PERL_MAGIC_env"
8360       "PERL_MAGIC_envelem"
8361       "PERL_MAGIC_ext"
8362       "PERL_MAGIC_extvalue"
8363       "PERL_MAGIC_fm"
8364       "PERL_MAGIC_hints"
8365       "PERL_MAGIC_hintselem"
8366       "PERL_MAGIC_hook"
8367       "PERL_MAGIC_hookelem"
8368       "PERL_MAGIC_isa"
8369       "PERL_MAGIC_isaelem"
8370       "PERL_MAGIC_lvref"
8371       "PERL_MAGIC_nkeys"
8372       "PERL_MAGIC_nonelem"
8373       "PERL_MAGIC_overload_table"
8374       "PERL_MAGIC_pos"
8375       "PERL_MAGIC_qr"
8376       "PERL_MAGIC_regdata"
8377       "PERL_MAGIC_regdatum"
8378       "PERL_MAGIC_regex_global"
8379       "PERL_MAGIC_rhash"
8380       "PERL_MAGIC_shared"
8381       "PERL_MAGIC_shared_scalar"
8382       "PERL_MAGIC_sig"
8383       "PERL_MAGIC_sigelem"
8384       "PERL_MAGIC_substr"
8385       "PERL_MAGIC_sv"
8386       "PERL_MAGIC_symtab"
8387       "PERL_MAGIC_taint"
8388       "PERL_MAGIC_tied"
8389       "PERL_MAGIC_tiedelem"
8390       "PERL_MAGIC_tiedscalar"
8391       "PERL_MAGIC_utf8"
8392       "PERL_MAGIC_uvar"
8393       "PERL_MAGIC_uvar_elem"
8394       "PERL_MAGIC_vec"
8395       "PERL_MAGIC_vstring"
8396           Described in perlguts.
8397
8398       "SvTIED_obj"
8399           Described in perlinterp.
8400
8401              SvTIED_obj(SV *sv, MAGIC *mg)
8402

Memory Management

8404       "dump_mstats"
8405           When enabled by compiling with "-DDEBUGGING_MSTATS", print out
8406           statistics about malloc as two lines of numbers, one showing the
8407           length of the free list for each size category, the second showing
8408           the number of mallocs - frees for each size category.
8409
8410           "s", if not NULL, is used as a phrase to include in the output,
8411           such as "after compilation".
8412
8413            void  dump_mstats(const char *s)
8414
8415       "HASATTRIBUTE_MALLOC"
8416           Can we handle "GCC" attribute for malloc-style functions.
8417
8418       "HAS_MALLOC_GOOD_SIZE"
8419           This symbol, if defined, indicates that the "malloc_good_size"
8420           routine is available for use.
8421
8422       "HAS_MALLOC_SIZE"
8423           This symbol, if defined, indicates that the "malloc_size" routine
8424           is available for use.
8425
8426       "I_MALLOCMALLOC"
8427           This symbol, if defined, indicates to the C program that it should
8428           include malloc/malloc.h.
8429
8430            #ifdef I_MALLOCMALLOC
8431                #include <mallocmalloc.h>
8432            #endif
8433
8434       "MYMALLOC"
8435           This symbol, if defined, indicates that we're using our own malloc.
8436
8437       "Newx"
8438       "safemalloc"
8439           The XSUB-writer's interface to the C "malloc" function.
8440
8441           Memory obtained by this should ONLY be freed with "Safefree".
8442
8443           In 5.9.3, Newx() and friends replace the older New() API, and drops
8444           the first parameter, x, a debug aid which allowed callers to
8445           identify themselves.  This aid has been superseded by a new build
8446           option, PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhacktips).  The
8447           older API is still there for use in XS modules supporting older
8448           perls.
8449
8450            void   Newx      (void* ptr, int nitems, type)
8451            void*  safemalloc(size_t size)
8452
8453       "Newxc"
8454           The XSUB-writer's interface to the C "malloc" function, with cast.
8455           See also "Newx".
8456
8457           Memory obtained by this should ONLY be freed with "Safefree".
8458
8459            void  Newxc(void* ptr, int nitems, type, cast)
8460
8461       "Newxz"
8462       "safecalloc"
8463           The XSUB-writer's interface to the C "malloc" function.  The
8464           allocated memory is zeroed with "memzero".  See also "Newx".
8465
8466           Memory obtained by this should ONLY be freed with "Safefree".
8467
8468            void   Newxz     (void* ptr, int nitems, type)
8469            void*  safecalloc(size_t nitems, size_t item_size)
8470
8471       "PERL_MALLOC_WRAP"
8472           This symbol, if defined, indicates that we'd like malloc wrap
8473           checks.
8474
8475       "Renew"
8476       "saferealloc"
8477           The XSUB-writer's interface to the C "realloc" function.
8478
8479           Memory obtained by this should ONLY be freed with "Safefree".
8480
8481            void   Renew      (void* ptr, int nitems, type)
8482            void*  saferealloc(void *ptr, size_t size)
8483
8484       "Renewc"
8485           The XSUB-writer's interface to the C "realloc" function, with cast.
8486
8487           Memory obtained by this should ONLY be freed with "Safefree".
8488
8489            void  Renewc(void* ptr, int nitems, type, cast)
8490
8491       "Safefree"
8492           The XSUB-writer's interface to the C "free" function.
8493
8494           This should ONLY be used on memory obtained using "Newx" and
8495           friends.
8496
8497            void  Safefree(void* ptr)
8498
8499       "safesyscalloc"
8500           Safe version of system's calloc()
8501
8502            Malloc_t  safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
8503
8504       "safesysfree"
8505           Safe version of system's free()
8506
8507            Free_t  safesysfree(Malloc_t where)
8508
8509       "safesysmalloc"
8510           Paranoid version of system's malloc()
8511
8512            Malloc_t  safesysmalloc(MEM_SIZE nbytes)
8513
8514       "safesysrealloc"
8515           Paranoid version of system's realloc()
8516
8517            Malloc_t  safesysrealloc(Malloc_t where, MEM_SIZE nbytes)
8518

MRO

8520       These functions are related to the method resolution order of perl
8521       classes Also see perlmroapi.
8522
8523       "HvMROMETA"
8524           Described in perlmroapi.
8525
8526            struct mro_meta *  HvMROMETA(HV *hv)
8527
8528       "mro_get_from_name"
8529           Returns the previously registered mro with the given "name", or
8530           NULL if not registered.  See ""mro_register"".
8531
8532           NOTE: "mro_get_from_name" must be explicitly called as
8533           "Perl_mro_get_from_name" with an "aTHX_" parameter.
8534
8535            const struct mro_alg *  Perl_mro_get_from_name(pTHX_ SV *name)
8536
8537       "mro_get_linear_isa"
8538           Returns the mro linearisation for the given stash.  By default,
8539           this will be whatever "mro_get_linear_isa_dfs" returns unless some
8540           other MRO is in effect for the stash.  The return value is a read-
8541           only AV* whose values are string SVs giving class names.
8542
8543           You are responsible for SvREFCNT_inc() on the return value if you
8544           plan to store it anywhere semi-permanently (otherwise it might be
8545           deleted out from under you the next time the cache is invalidated).
8546
8547            AV *  mro_get_linear_isa(HV *stash)
8548
8549       "MRO_GET_PRIVATE_DATA"
8550           Described in perlmroapi.
8551
8552            SV*  MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta,
8553                                      const struct mro_alg *const which)
8554
8555       "mro_method_changed_in"
8556           Invalidates method caching on any child classes of the given stash,
8557           so that they might notice the changes in this one.
8558
8559           Ideally, all instances of "PL_sub_generation++" in perl source
8560           outside of mro.c should be replaced by calls to this.
8561
8562           Perl automatically handles most of the common ways a method might
8563           be redefined.  However, there are a few ways you could change a
8564           method in a stash without the cache code noticing, in which case
8565           you need to call this method afterwards:
8566
8567           1) Directly manipulating the stash HV entries from XS code.
8568
8569           2) Assigning a reference to a readonly scalar constant into a stash
8570           entry in order to create a constant subroutine (like constant.pm
8571           does).
8572
8573           This same method is available from pure perl via,
8574           mro::method_changed_in(classname).
8575
8576            void  mro_method_changed_in(HV *stash)
8577
8578       "mro_register"
8579           Registers a custom mro plugin.  See perlmroapi for details on this
8580           and other mro functions.
8581
8582           NOTE: "mro_register" must be explicitly called as
8583           "Perl_mro_register" with an "aTHX_" parameter.
8584
8585            void  Perl_mro_register(pTHX_ const struct mro_alg *mro)
8586
8587       "mro_set_mro"
8588           Set "meta" to the value contained in the registered mro plugin
8589           whose name is "name".
8590
8591           Croaks if "name" hasn't been registered
8592
8593           NOTE: "mro_set_mro" must be explicitly called as "Perl_mro_set_mro"
8594           with an "aTHX_" parameter.
8595
8596            void  Perl_mro_set_mro(pTHX_ struct mro_meta * const meta,
8597                                   SV * const name)
8598
8599       "mro_set_private_data"
8600           Described in perlmroapi.
8601
8602           NOTE: "mro_set_private_data" must be explicitly called as
8603           "Perl_mro_set_private_data" with an "aTHX_" parameter.
8604
8605            SV *  Perl_mro_set_private_data(pTHX_
8606                                           struct mro_meta * const smeta,
8607                                           const struct mro_alg * const which,
8608                                           SV * const data)
8609

Multicall Functions

8611       "dMULTICALL"
8612           Declare local variables for a multicall.  See "LIGHTWEIGHT
8613           CALLBACKS" in perlcall.
8614
8615              dMULTICALL;
8616
8617       "MULTICALL"
8618           Make a lightweight callback.  See "LIGHTWEIGHT CALLBACKS" in
8619           perlcall.
8620
8621              MULTICALL;
8622
8623       "POP_MULTICALL"
8624           Closing bracket for a lightweight callback.  See "LIGHTWEIGHT
8625           CALLBACKS" in perlcall.
8626
8627              POP_MULTICALL;
8628
8629       "PUSH_MULTICALL"
8630           Opening bracket for a lightweight callback.  See "LIGHTWEIGHT
8631           CALLBACKS" in perlcall.
8632
8633              PUSH_MULTICALL(CV* the_cv);
8634

Numeric Functions

8636       "Atol"
8637           "DEPRECATED!"  It is planned to remove "Atol" from a future release
8638           of Perl.  Do not use it for new code; remove it from existing code.
8639
8640           Described in perlhacktips.
8641
8642              Atol(const char * nptr)
8643
8644       "Atoul"
8645           "DEPRECATED!"  It is planned to remove "Atoul" from a future
8646           release of Perl.  Do not use it for new code; remove it from
8647           existing code.
8648
8649           Described in perlhacktips.
8650
8651              Atoul(const char * nptr)
8652
8653       "Drand01"
8654           This macro is to be used to generate uniformly distributed random
8655           numbers over the range [0., 1.[.  You may have to supply an 'extern
8656           double drand48();' in your program since SunOS 4.1.3 doesn't
8657           provide you with anything relevant in its headers.  See
8658           "HAS_DRAND48_PROTO".
8659
8660            double  Drand01()
8661
8662       "Gconvert"
8663           This preprocessor macro is defined to convert a floating point
8664           number to a string without a trailing decimal point.  This emulates
8665           the behavior of sprintf("%g"), but is sometimes much more
8666           efficient.  If gconvert() is not available, but gcvt() drops the
8667           trailing decimal point, then gcvt() is used.  If all else fails, a
8668           macro using sprintf("%g") is used. Arguments for the Gconvert macro
8669           are: value, number of digits, whether trailing zeros should be
8670           retained, and the output buffer.  The usual values are:
8671
8672            d_Gconvert='gconvert((x),(n),(t),(b))'
8673            d_Gconvert='gcvt((x),(n),(b))'
8674            d_Gconvert='sprintf((b),"%.*g",(n),(x))'
8675
8676           The last two assume trailing zeros should not be kept.
8677
8678            char *  Gconvert(double x, Size_t n, bool t, char * b)
8679
8680       "grok_atoUV"
8681           parse a string, looking for a decimal unsigned integer.
8682
8683           On entry, "pv" points to the beginning of the string; "valptr"
8684           points to a UV that will receive the converted value, if found;
8685           "endptr" is either NULL or points to a variable that points to one
8686           byte beyond the point in "pv" that this routine should examine.  If
8687           "endptr" is NULL, "pv" is assumed to be NUL-terminated.
8688
8689           Returns FALSE if "pv" doesn't represent a valid unsigned integer
8690           value (with no leading zeros).  Otherwise it returns TRUE, and sets
8691           *valptr to that value.
8692
8693           If you constrain the portion of "pv" that is looked at by this
8694           function (by passing a non-NULL "endptr"), and if the initial bytes
8695           of that portion form a valid value, it will return TRUE, setting
8696           *endptr to the byte following the final digit of the value.  But if
8697           there is no constraint at what's looked at, all of "pv" must be
8698           valid in order for TRUE to be returned.  *endptr is unchanged from
8699           its value on input if FALSE is returned;
8700
8701           The only characters this accepts are the decimal digits '0'..'9'.
8702
8703           As opposed to atoi(3) or strtol(3), "grok_atoUV" does NOT allow
8704           optional leading whitespace, nor negative inputs.  If such features
8705           are required, the calling code needs to explicitly implement those.