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 can 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       "COP Hint Hashes"
87       "Custom Operators"
88       "CV Handling"
89       "Debugging"
90       "Display functions"
91       "Embedding and Interpreter Cloning"
92       "Errno"
93       "Exception Handling (simple) Macros"
94       "Filesystem configuration values"
95       "Floating point configuration values"
96       "Formats"
97       "General Configuration"
98       "Global Variables"
99       "GV Handling"
100       "Hook manipulation"
101       "HV Handling"
102       "Input/Output"
103       "Integer configuration values"
104       "Lexer interface"
105       "Locales"
106       "Magic"
107       "Memory Management"
108       "MRO"
109       "Multicall Functions"
110       "Numeric Functions"
111       "Optree construction"
112       "Optree Manipulation Functions"
113       "Pack and Unpack"
114       "Pad Data Structures"
115       "Password and Group access"
116       "Paths to system commands"
117       "Prototype information"
118       "REGEXP Functions"
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       "Time"
128       "Typedef names"
129       "Unicode Support"
130       "Utility Functions"
131       "Versioning"
132       "Warning and Dieing"
133       "XS"
134       "Undocumented elements"
135
136       The listing below is alphabetical, case insensitive.
137

AV Handling

139       "AV"
140           Described in perlguts.
141
142       "AvARRAY"
143           Returns a pointer to the AV's internal SV* array.
144
145           This is useful for doing pointer arithmetic on the array.  If all
146           you need is to look up an array element, then prefer "av_fetch".
147
148            SV**  AvARRAY(AV* av)
149
150       "av_clear"
151           Frees all the elements of an array, leaving it empty.  The XS
152           equivalent of "@array = ()".  See also "av_undef".
153
154           Note that it is possible that the actions of a destructor called
155           directly or indirectly by freeing an element of the array could
156           cause the reference count of the array itself to be reduced (e.g.
157           by deleting an entry in the symbol table). So it is a possibility
158           that the AV could have been freed (or even reallocated) on return
159           from the call unless you hold a reference to it.
160
161            void  av_clear(AV *av)
162
163       "av_count"
164           Returns the number of elements in the array "av".  This is the true
165           length of the array, including any undefined elements.  It is
166           always the same as "av_top_index(av) + 1".
167
168            Size_t  av_count(AV *av)
169
170       "av_create_and_push"
171           NOTE: "av_create_and_push" is experimental and may change or be
172           removed without notice.
173
174           Push an SV onto the end of the array, creating the array if
175           necessary.  A small internal helper function to remove a commonly
176           duplicated idiom.
177
178           NOTE: "av_create_and_push" must be explicitly called as
179           "Perl_av_create_and_push" with an "aTHX_" parameter.
180
181            void  Perl_av_create_and_push(pTHX_ AV **const avp,
182                                          SV *const val)
183
184       "av_create_and_unshift_one"
185           NOTE: "av_create_and_unshift_one" is experimental and may change or
186           be removed without notice.
187
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 of SVs.  The SVs are
274           copied into the array, so they may be freed after the call to
275           "av_make".  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_shift"
301           Removes one SV from the start of the array, reducing its size by
302           one and returning the SV (transferring control of one reference
303           count) to the caller.  Returns &PL_sv_undef if the array is empty.
304
305           Perl equivalent: "shift(@myarray);"
306
307            SV*  av_shift(AV *av)
308
309       "av_store"
310           Stores an SV in an array.  The array index is specified as "key".
311           The return value will be "NULL" if the operation failed or if the
312           value did not need to be actually stored within the array (as in
313           the case of tied arrays).  Otherwise, it can be dereferenced to get
314           the "SV*" that was stored there (= "val")).
315
316           Note that the caller is responsible for suitably incrementing the
317           reference count of "val" before the call, and decrementing it if
318           the function returned "NULL".
319
320           Approximate Perl equivalent: "splice(@myarray, $key, 1, $val)".
321
322           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
323           for more information on how to use this function on tied arrays.
324
325            SV**  av_store(AV *av, SSize_t key, SV *val)
326
327       "av_tindex"
328       "av_top_index"
329           These behave identically.  If the array "av" is empty, these return
330           -1; otherwise they return the maximum value of the indices of all
331           the array elements which are currently defined in "av".
332
333           They process 'get' magic.
334
335           The Perl equivalent for these is $#av.
336
337           Use "av_count" to get the number of elements in an array.
338
339            SSize_t  av_tindex(AV *av)
340
341       "av_undef"
342           Undefines the array. The XS equivalent of "undef(@array)".
343
344           As well as freeing all the elements of the array (like
345           "av_clear()"), this also frees the memory used by the av to store
346           its list of scalars.
347
348           See "av_clear" for a note about the array possibly being invalid on
349           return.
350
351            void  av_undef(AV *av)
352
353       "av_unshift"
354           Unshift the given number of "undef" values onto the beginning of
355           the array.  The array will grow automatically to accommodate the
356           addition.
357
358           Perl equivalent: "unshift @myarray, ((undef) x $num);"
359
360            void  av_unshift(AV *av, SSize_t num)
361
362       "get_av"
363           Returns the AV of the specified Perl global or package array with
364           the given name (so it won't work on lexical variables).  "flags"
365           are passed to "gv_fetchpv".  If "GV_ADD" is set and the Perl
366           variable does not exist then it will be created.  If "flags" is
367           zero and the variable does not exist then NULL is returned.
368
369           Perl equivalent: "@{"$name"}".
370
371           NOTE: the "perl_get_av()" form is deprecated.
372
373            AV*  get_av(const char *name, I32 flags)
374
375       "newAV"
376           Creates a new AV.  The reference count is set to 1.
377
378           Perl equivalent: "my @array;".
379
380            AV*  newAV()
381
382       "Nullav"
383           "DEPRECATED!"  It is planned to remove "Nullav" from a future
384           release of Perl.  Do not use it for new code; remove it from
385           existing code.
386
387           Null AV pointer.
388
389           (deprecated - use "(AV *)NULL" instead)
390

Callback Functions

392       "call_argv"
393           Performs a callback to the specified named and package-scoped Perl
394           subroutine with "argv" (a "NULL"-terminated array of strings) as
395           arguments.  See perlcall.
396
397           Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
398
399           NOTE: the "perl_call_argv()" form is deprecated.
400
401            I32  call_argv(const char* sub_name, I32 flags, char** argv)
402
403       "call_method"
404           Performs a callback to the specified Perl method.  The blessed
405           object must be on the stack.  See perlcall.
406
407           NOTE: the "perl_call_method()" form is deprecated.
408
409            I32  call_method(const char* methname, I32 flags)
410
411       "call_pv"
412           Performs a callback to the specified Perl sub.  See perlcall.
413
414           NOTE: the "perl_call_pv()" form is deprecated.
415
416            I32  call_pv(const char* sub_name, I32 flags)
417
418       "call_sv"
419           Performs a callback to the Perl sub specified by the SV.
420
421           If neither the "G_METHOD" nor "G_METHOD_NAMED" flag is supplied,
422           the SV may be any of a CV, a GV, a reference to a CV, a reference
423           to a GV or "SvPV(sv)" will be used as the name of the sub to call.
424
425           If the "G_METHOD" flag is supplied, the SV may be a reference to a
426           CV or "SvPV(sv)" will be used as the name of the method to call.
427
428           If the "G_METHOD_NAMED" flag is supplied, "SvPV(sv)" will be used
429           as the name of the method to call.
430
431           Some other values are treated specially for internal use and should
432           not be depended on.
433
434           See perlcall.
435
436           NOTE: the "perl_call_sv()" form is deprecated.
437
438            I32  call_sv(SV* sv, volatile I32 flags)
439
440       "ENTER"
441           Opening bracket on a callback.  See "LEAVE" and perlcall.
442
443              ENTER;
444
445       "ENTER_with_name"
446           Same as "ENTER", but when debugging is enabled it also associates
447           the given literal string with the new scope.
448
449              ENTER_with_name("name");
450
451       "eval_pv"
452           Tells Perl to "eval" the given string in scalar context and return
453           an SV* result.
454
455           NOTE: the "perl_eval_pv()" form is deprecated.
456
457            SV*  eval_pv(const char* p, I32 croak_on_error)
458
459       "eval_sv"
460           Tells Perl to "eval" the string in the SV.  It supports the same
461           flags as "call_sv", with the obvious exception of "G_EVAL".  See
462           perlcall.
463
464           The "G_RETHROW" flag can be used if you only need eval_sv() to
465           execute code specified by a string, but not catch any errors.
466
467           NOTE: the "perl_eval_sv()" form is deprecated.
468
469            I32  eval_sv(SV* sv, I32 flags)
470
471       "FREETMPS"
472           Closing bracket for temporaries on a callback.  See "SAVETMPS" and
473           perlcall.
474
475              FREETMPS;
476
477       "G_ARRAY"
478           Described in perlcall.
479
480       "G_DISCARD"
481           Described in perlcall.
482
483       "G_EVAL"
484           Described in perlcall.
485
486       "GIMME"
487           "DEPRECATED!"  It is planned to remove "GIMME" from a future
488           release of Perl.  Do not use it for new code; remove it from
489           existing code.
490
491           A backward-compatible version of "GIMME_V" which can only return
492           "G_SCALAR" or "G_ARRAY"; in a void context, it returns "G_SCALAR".
493           Deprecated.  Use "GIMME_V" instead.
494
495            U32  GIMME
496
497       "GIMME_V"
498           The XSUB-writer's equivalent to Perl's "wantarray".  Returns
499           "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list context,
500           respectively.  See perlcall for a usage example.
501
502            U32  GIMME_V
503
504       "G_KEEPERR"
505           Described in perlcall.
506
507       "G_NOARGS"
508           Described in perlcall.
509
510       "G_SCALAR"
511           Described in perlcall.
512
513       "G_VOID"
514           Described in perlcall.
515
516       "LEAVE"
517           Closing bracket on a callback.  See "ENTER" and perlcall.
518
519              LEAVE;
520
521       "LEAVE_with_name"
522           Same as "LEAVE", but when debugging is enabled it first checks that
523           the scope has the given name. "name" must be a literal string.
524
525              LEAVE_with_name("name");
526
527       "PL_errgv"
528           Described in perlcall.
529
530       "SAVETMPS"
531           Opening bracket for temporaries on a callback.  See "FREETMPS" and
532           perlcall.
533
534              SAVETMPS;
535

Casting

537       "cBOOL"
538           Cast-to-bool.  A simple "(bool) expr" cast may not do the right
539           thing: if "bool" is defined as "char", for example, then the cast
540           from "int" is implementation-defined.
541
542           "(bool)!!(cbool)" in a ternary triggers a bug in xlc on AIX
543
544            bool  cBOOL(bool expr)
545
546       "I_32"
547           Cast an NV to I32 while avoiding undefined C behavior
548
549            I32  I_32(NV what)
550
551       "INT2PTR"
552           Described in perlguts.
553
554            type  INT2PTR(type, int value)
555
556       "I_V"
557           Cast an NV to IV while avoiding undefined C behavior
558
559            IV  I_V(NV what)
560
561       "Perl_cpeep_t"
562           Described in perlguts.
563
564       "PTR2IV"
565           Described in perlguts.
566
567            IV  PTR2IV(void * ptr)
568
569       "PTR2nat"
570           Described in perlguts.
571
572            IV  PTR2nat(void *)
573
574       "PTR2NV"
575           Described in perlguts.
576
577            NV  PTR2NV(void * ptr)
578
579       "PTR2ul"
580           Described in perlguts.
581
582            unsigned long  PTR2ul(void *)
583
584       "PTR2UV"
585           Described in perlguts.
586
587            UV  PTR2UV(void * ptr)
588
589       "PTRV"
590           Described in perlguts.
591
592       "U_32"
593           Cast an NV to U32 while avoiding undefined C behavior
594
595            U32  U_32(NV what)
596
597       "U_V"
598           Cast an NV to UV while avoiding undefined C behavior
599
600            UV  U_V(NV what)
601
602       "XOP"
603           Described in perlguts.
604

Character case changing

606       Perl uses "full" Unicode case mappings.  This means that converting a
607       single character to another case may result in a sequence of more than
608       one character.  For example, the uppercase of "ss" (LATIN SMALL LETTER
609       SHARP S) is the two character sequence "SS".  This presents some
610       complications   The lowercase of all characters in the range 0..255 is
611       a single character, and thus "toLOWER_L1" is furnished.  But,
612       "toUPPER_L1" can't exist, as it couldn't return a valid result for all
613       legal inputs.  Instead "toUPPER_uvchr" has an API that does allow every
614       possible legal result to be returned.)  Likewise no other function that
615       is crippled by not being able to give the correct results for the full
616       range of possible inputs has been implemented here.
617
618       "toFOLD"
619           Converts the specified character to foldcase.  If the input is
620           anything but an ASCII uppercase character, that input character
621           itself is returned.  Variant "toFOLD_A" is equivalent.  (There is
622           no equivalent "to_FOLD_L1" for the full Latin1 range, as the full
623           generality of "toFOLD_uvchr" is needed there.)
624
625            U8  toFOLD(U8 ch)
626
627       "toFOLD_utf8"
628       "toFOLD_utf8_safe"
629           Converts the first UTF-8 encoded character in the sequence starting
630           at "p" and extending no further than "e - 1" to its foldcase
631           version, and stores that in UTF-8 in "s", and its length in bytes
632           in "lenp".  Note that the buffer pointed to by "s" needs to be at
633           least "UTF8_MAXBYTES_CASE+1" bytes since the foldcase version may
634           be longer than the original character.
635
636           The first code point of the foldcased version is returned (but
637           note, as explained at the top of this section, that there may be
638           more).
639
640           It will not attempt to read beyond "e - 1", provided that the
641           constraint "s < e" is true (this is asserted for in "-DDEBUGGING"
642           builds).  If the UTF-8 for the input character is malformed in some
643           way, the program may croak, or the function may return the
644           REPLACEMENT CHARACTER, at the discretion of the implementation, and
645           subject to change in future releases.
646
647           "toFOLD_utf8_safe" is now just a different spelling of plain
648           "toFOLD_utf8"
649
650            UV  toFOLD_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
651
652       "toFOLD_uvchr"
653           Converts the code point "cp" to its foldcase version, and stores
654           that in UTF-8 in "s", and its length in bytes in "lenp".  The code
655           point is interpreted as native if less than 256; otherwise as
656           Unicode.  Note that the buffer pointed to by "s" needs to be at
657           least "UTF8_MAXBYTES_CASE+1" bytes since the foldcase version may
658           be longer than the original character.
659
660           The first code point of the foldcased version is returned (but
661           note, as explained at the top of this section, that there may be
662           more).
663
664            UV  toFOLD_uvchr(UV cp, U8* s, STRLEN* lenp)
665
666       "toLOWER"
667       "toLOWER_A"
668       "toLOWER_L1"
669       "toLOWER_LATIN1"
670       "toLOWER_LC"
671       "toLOWER_uvchr"
672       "toLOWER_utf8"
673       "toLOWER_utf8_safe"
674           These all return the lowercase of a character.  The differences are
675           what domain they operate on, and whether the input is specified as
676           a code point (those forms with a "cp" parameter) or as a UTF-8
677           string (the others).  In the latter case, the code point to use is
678           the first one in the buffer of UTF-8 encoded code points,
679           delineated by the arguments "p .. e - 1".
680
681           "toLOWER" and "toLOWER_A" are synonyms of each other.  They return
682           the lowercase of any uppercase ASCII-range code point.  All other
683           inputs are returned unchanged.  Since these are macros, the input
684           type may be any integral one, and the output will occupy the same
685           number of bits as the input.
686
687           "toLOWER_L1" and "toLOWER_LATIN1" are synonyms of each other.  They
688           behave identically as "toLOWER" for ASCII-range input.  But
689           additionally will return the lowercase of any uppercase code point
690           in the entire 0..255 range, assuming a Latin-1 encoding (or the
691           EBCDIC equivalent on such platforms).
692
693           "toLOWER_LC" returns the lowercase of the input code point
694           according to the rules of the current POSIX locale.  Input code
695           points outside the range 0..255 are returned unchanged.
696
697           "toLOWER_uvchr" returns the lowercase of any Unicode code point.
698           The return value is identical to that of "toLOWER_L1" for input
699           code points in the 0..255 range.  The lowercase of the vast
700           majority of Unicode code points is the same as the code point
701           itself.  For these, and for code points above the legal Unicode
702           maximum, this returns the input code point unchanged.  It
703           additionally stores the UTF-8 of the result into the buffer
704           beginning at "s", and its length in bytes into *lenp.  The caller
705           must have made "s" large enough to contain at least
706           "UTF8_MAXBYTES_CASE+1" bytes to avoid possible overflow.
707
708           NOTE: the lowercase of a code point may be more than one code
709           point.  The return value of this function is only the first of
710           these.  The entire lowercase is returned in "s".  To determine if
711           the result is more than a single code point, you can do something
712           like this:
713
714            uc = toLOWER_uvchr(cp, s, &len);
715            if (len > UTF8SKIP(s)) { is multiple code points }
716            else { is a single code point }
717
718           "toLOWER_utf8" and "toLOWER_utf8_safe" are synonyms of each other.
719           The only difference between these and "toLOWER_uvchr" is that the
720           source for these is encoded in UTF-8, instead of being a code
721           point.  It is passed as a buffer starting at "p", with "e" pointing
722           to one byte beyond its end.  The "p" buffer may certainly contain
723           more than one code point; but only the first one (up through
724           "e - 1") is examined.  If the UTF-8 for the input character is
725           malformed in some way, the program may croak, or the function may
726           return the REPLACEMENT CHARACTER, at the discretion of the
727           implementation, and subject to change in future releases.
728
729            UV  toLOWER          (UV cp)
730            UV  toLOWER_A        (UV cp)
731            UV  toLOWER_L1       (UV cp)
732            UV  toLOWER_LATIN1   (UV cp)
733            UV  toLOWER_LC       (UV cp)
734            UV  toLOWER_uvchr    (UV cp, U8* s, STRLEN* lenp)
735            UV  toLOWER_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
736            UV  toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
737
738       "toTITLE"
739           Converts the specified character to titlecase.  If the input is
740           anything but an ASCII lowercase character, that input character
741           itself is returned.  Variant "toTITLE_A" is equivalent.  (There is
742           no "toTITLE_L1" for the full Latin1 range, as the full generality
743           of "toTITLE_uvchr" is needed there.  Titlecase is not a concept
744           used in locale handling, so there is no functionality for that.)
745
746            U8  toTITLE(U8 ch)
747
748       "toTITLE_utf8"
749       "toTITLE_utf8_safe"
750           Convert the first UTF-8 encoded character in the sequence starting
751           at "p" and extending no further than "e - 1" to its titlecase
752           version, and stores that in UTF-8 in "s", and its length in bytes
753           in "lenp".  Note that the buffer pointed to by "s" needs to be at
754           least "UTF8_MAXBYTES_CASE+1" bytes since the titlecase version may
755           be longer than the original character.
756
757           The first code point of the titlecased version is returned (but
758           note, as explained at the top of this section, that there may be
759           more).
760
761           It will not attempt to read beyond "e - 1", provided that the
762           constraint "s < e" is true (this is asserted for in "-DDEBUGGING"
763           builds).  If the UTF-8 for the input character is malformed in some
764           way, the program may croak, or the function may return the
765           REPLACEMENT CHARACTER, at the discretion of the implementation, and
766           subject to change in future releases.
767
768           "toTITLE_utf8_safe" is now just a different spelling of plain
769           "toTITLE_utf8"
770
771            UV  toTITLE_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
772
773       "toTITLE_uvchr"
774           Converts the code point "cp" to its titlecase version, and stores
775           that in UTF-8 in "s", and its length in bytes in "lenp".  The code
776           point is interpreted as native if less than 256; otherwise as
777           Unicode.  Note that the buffer pointed to by "s" needs to be at
778           least "UTF8_MAXBYTES_CASE+1" bytes since the titlecase version may
779           be longer than the original character.
780
781           The first code point of the titlecased version is returned (but
782           note, as explained at the top of this section, that there may be
783           more).
784
785            UV  toTITLE_uvchr(UV cp, U8* s, STRLEN* lenp)
786
787       "toUPPER"
788           Converts the specified character to uppercase.  If the input is
789           anything but an ASCII lowercase character, that input character
790           itself is returned.  Variant "toUPPER_A" is equivalent.
791
792            U8  toUPPER(int ch)
793
794       "toUPPER_utf8"
795       "toUPPER_utf8_safe"
796           Converts the first UTF-8 encoded character in the sequence starting
797           at "p" and extending no further than "e - 1" to its uppercase
798           version, and stores that in UTF-8 in "s", and its length in bytes
799           in "lenp".  Note that the buffer pointed to by "s" needs to be at
800           least "UTF8_MAXBYTES_CASE+1" bytes since the uppercase version may
801           be longer than the original character.
802
803           The first code point of the uppercased version is returned (but
804           note, as explained at the top of this section, that there may be
805           more).
806
807           It will not attempt to read beyond "e - 1", provided that the
808           constraint "s < e" is true (this is asserted for in "-DDEBUGGING"
809           builds).  If the UTF-8 for the input character is malformed in some
810           way, the program may croak, or the function may return the
811           REPLACEMENT CHARACTER, at the discretion of the implementation, and
812           subject to change in future releases.
813
814           "toUPPER_utf8_safe" is now just a different spelling of plain
815           "toUPPER_utf8"
816
817            UV  toUPPER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
818
819       "toUPPER_uvchr"
820           Converts the code point "cp" to its uppercase version, and stores
821           that in UTF-8 in "s", and its length in bytes in "lenp".  The code
822           point is interpreted as native if less than 256; otherwise as
823           Unicode.  Note that the buffer pointed to by "s" needs to be at
824           least "UTF8_MAXBYTES_CASE+1" bytes since the uppercase version may
825           be longer than the original character.
826
827           The first code point of the uppercased version is returned (but
828           note, as explained at the top of this section, that there may be
829           more.)
830
831            UV  toUPPER_uvchr(UV cp, U8* s, STRLEN* lenp)
832

Character classification

834       This section is about functions (really macros) that classify
835       characters into types, such as punctuation versus alphabetic, etc.
836       Most of these are analogous to regular expression character classes.
837       (See "POSIX Character Classes" in perlrecharclass.)  There are several
838       variants for each class.  (Not all macros have all variants; each item
839       below lists the ones valid for it.)  None are affected by "use bytes",
840       and only the ones with "LC" in the name are affected by the current
841       locale.
842
843       The base function, e.g., "isALPHA()", takes any signed or unsigned
844       value, treating it as a code point, and returns a boolean as to whether
845       or not the character represented by it is (or on non-ASCII platforms,
846       corresponds to) an ASCII character in the named class based on
847       platform, Unicode, and Perl rules.  If the input is a number that
848       doesn't fit in an octet, FALSE is returned.
849
850       Variant "isFOO_A" (e.g., "isALPHA_A()") is identical to the base
851       function with no suffix "_A".  This variant is used to emphasize by its
852       name that only ASCII-range characters can return TRUE.
853
854       Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivalent) character
855       set onto the platform.  That is, the code points that are ASCII are
856       unaffected, since ASCII is a subset of Latin-1.  But the non-ASCII code
857       points are treated as if they are Latin-1 characters.  For example,
858       "isWORDCHAR_L1()" will return true when called with the code point
859       0xDF, which is a word character in both ASCII and EBCDIC (though it
860       represents different characters in each).  If the input is a number
861       that doesn't fit in an octet, FALSE is returned.  (Perl's documentation
862       uses a colloquial definition of Latin-1, to include all code points
863       below 256.)
864
865       Variant "isFOO_uvchr" is exactly like the "isFOO_L1" variant, for
866       inputs below 256, but if the code point is larger than 255, Unicode
867       rules are used to determine if it is in the character class.  For
868       example, "isWORDCHAR_uvchr(0x100)" returns TRUE, since 0x100 is LATIN
869       CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.
870
871       Variants "isFOO_utf8" and "isFOO_utf8_safe" are like "isFOO_uvchr", but
872       are used for UTF-8 encoded strings.  The two forms are different names
873       for the same thing.  Each call to one of these classifies the first
874       character of the string starting at "p".  The second parameter, "e",
875       points to anywhere in the string beyond the first character, up to one
876       byte past the end of the entire string.  Although both variants are
877       identical, the suffix "_safe" in one name emphasizes that it will not
878       attempt to read beyond "e - 1", provided that the constraint "s < e" is
879       true (this is asserted for in "-DDEBUGGING" builds).  If the UTF-8 for
880       the input character is malformed in some way, the program may croak, or
881       the function may return FALSE, at the discretion of the implementation,
882       and subject to change in future releases.
883
884       Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but
885       the result is based on the current locale, which is what "LC" in the
886       name stands for.  If Perl can determine that the current locale is a
887       UTF-8 locale, it uses the published Unicode rules; otherwise, it uses
888       the C library function that gives the named classification.  For
889       example, "isDIGIT_LC()" when not in a UTF-8 locale returns the result
890       of calling "isdigit()".  FALSE is always returned if the input won't
891       fit into an octet.  On some platforms where the C library function is
892       known to be defective, Perl changes its result to follow the POSIX
893       standard's rules.
894
895       Variant "isFOO_LC_uvchr" acts exactly like "isFOO_LC" for inputs less
896       than 256, but for larger ones it returns the Unicode classification of
897       the code point.
898
899       Variants "isFOO_LC_utf8" and "isFOO_LC_utf8_safe" are like
900       "isFOO_LC_uvchr", but are used for UTF-8 encoded strings.  The two
901       forms are different names for the same thing.  Each call to one of
902       these classifies the first character of the string starting at "p".
903       The second parameter, "e", points to anywhere in the string beyond the
904       first character, up to one byte past the end of the entire string.
905       Although both variants are identical, the suffix "_safe" in one name
906       emphasizes that it will not attempt to read beyond "e - 1", provided
907       that the constraint "s < e" is true (this is asserted for in
908       "-DDEBUGGING" builds).  If the UTF-8 for the input character is
909       malformed in some way, the program may croak, or the function may
910       return FALSE, at the discretion of the implementation, and subject to
911       change in future releases.
912
913       "isALPHA"
914       "isALPHA_A"
915       "isALPHA_L1"
916       "isALPHA_uvchr"
917       "isALPHA_utf8_safe"
918       "isALPHA_utf8"
919       "isALPHA_LC"
920       "isALPHA_LC_uvchr"
921       "isALPHA_LC_utf8_safe"
922           Returns a boolean indicating whether the specified input is one of
923           "[A-Za-z]", analogous to "m/[[:alpha:]]/".  See the top of this
924           section for an explanation of the variants.
925
926            bool  isALPHA             (UV ch)
927            bool  isALPHA_A           (UV ch)
928            bool  isALPHA_L1          (UV ch)
929            bool  isALPHA_uvchr       (UV ch)
930            bool  isALPHA_utf8_safe   (U8 * s, U8 * end)
931            bool  isALPHA_utf8        (U8 * s, U8 * end)
932            bool  isALPHA_LC          (UV ch)
933            bool  isALPHA_LC_uvchr    (UV ch)
934            bool  isALPHA_LC_utf8_safe(U8 * s, U8 *end)
935
936       "isALPHANUMERIC"
937       "isALPHANUMERIC_A"
938       "isALPHANUMERIC_L1"
939       "isALPHANUMERIC_uvchr"
940       "isALPHANUMERIC_utf8_safe"
941       "isALPHANUMERIC_utf8"
942       "isALPHANUMERIC_LC"
943       "isALPHANUMERIC_LC_uvchr"
944       "isALPHANUMERIC_LC_utf8_safe"
945       "isALNUMC"
946       "isALNUMC_A"
947       "isALNUMC_L1"
948       "isALNUMC_LC"
949       "isALNUMC_LC_uvchr"
950           Returns a boolean indicating whether the specified character is one
951           of "[A-Za-z0-9]", analogous to "m/[[:alnum:]]/".  See the top of
952           this section for an explanation of the variants.
953
954           A (discouraged from use) synonym is "isALNUMC" (where the "C"
955           suffix means this corresponds to the C language alphanumeric
956           definition).  Also there are the variants "isALNUMC_A",
957           "isALNUMC_L1" "isALNUMC_LC", and "isALNUMC_LC_uvchr".
958
959            bool  isALPHANUMERIC             (UV ch)
960            bool  isALPHANUMERIC_A           (UV ch)
961            bool  isALPHANUMERIC_L1          (UV ch)
962            bool  isALPHANUMERIC_uvchr       (UV ch)
963            bool  isALPHANUMERIC_utf8_safe   (U8 * s, U8 * end)
964            bool  isALPHANUMERIC_utf8        (U8 * s, U8 * end)
965            bool  isALPHANUMERIC_LC          (UV ch)
966            bool  isALPHANUMERIC_LC_uvchr    (UV ch)
967            bool  isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end)
968            bool  isALNUMC                   (UV ch)
969            bool  isALNUMC_A                 (UV ch)
970            bool  isALNUMC_L1                (UV ch)
971            bool  isALNUMC_LC                (UV ch)
972            bool  isALNUMC_LC_uvchr          (UV ch)
973
974       "isASCII"
975       "isASCII_A"
976       "isASCII_L1"
977       "isASCII_uvchr"
978       "isASCII_utf8_safe"
979       "isASCII_utf8"
980       "isASCII_LC"
981       "isASCII_LC_uvchr"
982       "isASCII_LC_utf8_safe"
983           Returns a boolean indicating whether the specified character is one
984           of the 128 characters in the ASCII character set, analogous to
985           "m/[[:ascii:]]/".  On non-ASCII platforms, it returns TRUE iff this
986           character corresponds to an ASCII character.  Variants
987           "isASCII_A()" and "isASCII_L1()" are identical to "isASCII()".  See
988           the top of this section for an explanation of the variants.  Note,
989           however, that some platforms do not have the C library routine
990           "isascii()".  In these cases, the variants whose names contain "LC"
991           are the same as the corresponding ones without.
992
993           Also note, that because all ASCII characters are UTF-8 invariant
994           (meaning they have the exact same representation (always a single
995           byte) whether encoded in UTF-8 or not), "isASCII" will give the
996           correct results when called with any byte in any string encoded or
997           not in UTF-8.  And similarly "isASCII_utf8" and "isASCII_utf8_safe"
998           will work properly on any string encoded or not in UTF-8.
999
1000            bool  isASCII             (UV ch)
1001            bool  isASCII_A           (UV ch)
1002            bool  isASCII_L1          (UV ch)
1003            bool  isASCII_uvchr       (UV ch)
1004            bool  isASCII_utf8_safe   (U8 * s, U8 * end)
1005            bool  isASCII_utf8        (U8 * s, U8 * end)
1006            bool  isASCII_LC          (UV ch)
1007            bool  isASCII_LC_uvchr    (UV ch)
1008            bool  isASCII_LC_utf8_safe(U8 * s, U8 *end)
1009
1010       "isBLANK"
1011       "isBLANK_A"
1012       "isBLANK_L1"
1013       "isBLANK_uvchr"
1014       "isBLANK_utf8_safe"
1015       "isBLANK_utf8"
1016       "isBLANK_LC"
1017       "isBLANK_LC_uvchr"
1018       "isBLANK_LC_utf8_safe"
1019           Returns a boolean indicating whether the specified character is a
1020           character considered to be a blank, analogous to "m/[[:blank:]]/".
1021           See the top of this section for an explanation of the variants.
1022           Note, however, that some platforms do not have the C library
1023           routine "isblank()".  In these cases, the variants whose names
1024           contain "LC" are the same as the corresponding ones without.
1025
1026            bool  isBLANK             (UV ch)
1027            bool  isBLANK_A           (UV ch)
1028            bool  isBLANK_L1          (UV ch)
1029            bool  isBLANK_uvchr       (UV ch)
1030            bool  isBLANK_utf8_safe   (U8 * s, U8 * end)
1031            bool  isBLANK_utf8        (U8 * s, U8 * end)
1032            bool  isBLANK_LC          (UV ch)
1033            bool  isBLANK_LC_uvchr    (UV ch)
1034            bool  isBLANK_LC_utf8_safe(U8 * s, U8 *end)
1035
1036       "isCNTRL"
1037       "isCNTRL_A"
1038       "isCNTRL_L1"
1039       "isCNTRL_uvchr"
1040       "isCNTRL_utf8_safe"
1041       "isCNTRL_utf8"
1042       "isCNTRL_LC"
1043       "isCNTRL_LC_uvchr"
1044       "isCNTRL_LC_utf8_safe"
1045           Returns a boolean indicating whether the specified character is a
1046           control character, analogous to "m/[[:cntrl:]]/".  See the top of
1047           this section for an explanation of the variants.  On EBCDIC
1048           platforms, you almost always want to use the "isCNTRL_L1" variant.
1049
1050            bool  isCNTRL             (UV ch)
1051            bool  isCNTRL_A           (UV ch)
1052            bool  isCNTRL_L1          (UV ch)
1053            bool  isCNTRL_uvchr       (UV ch)
1054            bool  isCNTRL_utf8_safe   (U8 * s, U8 * end)
1055            bool  isCNTRL_utf8        (U8 * s, U8 * end)
1056            bool  isCNTRL_LC          (UV ch)
1057            bool  isCNTRL_LC_uvchr    (UV ch)
1058            bool  isCNTRL_LC_utf8_safe(U8 * s, U8 *end)
1059
1060       "isDIGIT"
1061       "isDIGIT_A"
1062       "isDIGIT_L1"
1063       "isDIGIT_uvchr"
1064       "isDIGIT_utf8_safe"
1065       "isDIGIT_utf8"
1066       "isDIGIT_LC"
1067       "isDIGIT_LC_uvchr"
1068       "isDIGIT_LC_utf8_safe"
1069           Returns a boolean indicating whether the specified character is a
1070           digit, analogous to "m/[[:digit:]]/".  Variants "isDIGIT_A" and
1071           "isDIGIT_L1" are identical to "isDIGIT".  See the top of this
1072           section for an explanation of the variants.
1073
1074            bool  isDIGIT             (UV ch)
1075            bool  isDIGIT_A           (UV ch)
1076            bool  isDIGIT_L1          (UV ch)
1077            bool  isDIGIT_uvchr       (UV ch)
1078            bool  isDIGIT_utf8_safe   (U8 * s, U8 * end)
1079            bool  isDIGIT_utf8        (U8 * s, U8 * end)
1080            bool  isDIGIT_LC          (UV ch)
1081            bool  isDIGIT_LC_uvchr    (UV ch)
1082            bool  isDIGIT_LC_utf8_safe(U8 * s, U8 *end)
1083
1084       "isGRAPH"
1085       "isGRAPH_A"
1086       "isGRAPH_L1"
1087       "isGRAPH_uvchr"
1088       "isGRAPH_utf8_safe"
1089       "isGRAPH_utf8"
1090       "isGRAPH_LC"
1091       "isGRAPH_LC_uvchr"
1092       "isGRAPH_LC_utf8_safe"
1093           Returns a boolean indicating whether the specified character is a
1094           graphic character, analogous to "m/[[:graph:]]/".  See the top of
1095           this section for an explanation of the variants.
1096
1097            bool  isGRAPH             (UV ch)
1098            bool  isGRAPH_A           (UV ch)
1099            bool  isGRAPH_L1          (UV ch)
1100            bool  isGRAPH_uvchr       (UV ch)
1101            bool  isGRAPH_utf8_safe   (U8 * s, U8 * end)
1102            bool  isGRAPH_utf8        (U8 * s, U8 * end)
1103            bool  isGRAPH_LC          (UV ch)
1104            bool  isGRAPH_LC_uvchr    (UV ch)
1105            bool  isGRAPH_LC_utf8_safe(U8 * s, U8 *end)
1106
1107       "isIDCONT"
1108       "isIDCONT_A"
1109       "isIDCONT_L1"
1110       "isIDCONT_uvchr"
1111       "isIDCONT_utf8_safe"
1112       "isIDCONT_utf8"
1113       "isIDCONT_LC"
1114       "isIDCONT_LC_uvchr"
1115       "isIDCONT_LC_utf8_safe"
1116           Returns a boolean indicating whether the specified character can be
1117           the second or succeeding character of an identifier.  This is very
1118           close to, but not quite the same as the official Unicode property
1119           "XID_Continue".  The difference is that this returns true only if
1120           the input character also matches "isWORDCHAR".  See the top of this
1121           section for an explanation of the variants.
1122
1123            bool  isIDCONT             (UV ch)
1124            bool  isIDCONT_A           (UV ch)
1125            bool  isIDCONT_L1          (UV ch)
1126            bool  isIDCONT_uvchr       (UV ch)
1127            bool  isIDCONT_utf8_safe   (U8 * s, U8 * end)
1128            bool  isIDCONT_utf8        (U8 * s, U8 * end)
1129            bool  isIDCONT_LC          (UV ch)
1130            bool  isIDCONT_LC_uvchr    (UV ch)
1131            bool  isIDCONT_LC_utf8_safe(U8 * s, U8 *end)
1132
1133       "isIDFIRST"
1134       "isIDFIRST_A"
1135       "isIDFIRST_L1"
1136       "isIDFIRST_uvchr"
1137       "isIDFIRST_utf8_safe"
1138       "isIDFIRST_utf8"
1139       "isIDFIRST_LC"
1140       "isIDFIRST_LC_uvchr"
1141       "isIDFIRST_LC_utf8_safe"
1142           Returns a boolean indicating whether the specified character can be
1143           the first character of an identifier.  This is very close to, but
1144           not quite the same as the official Unicode property "XID_Start".
1145           The difference is that this returns true only if the input
1146           character also matches "isWORDCHAR".  See the top of this section
1147           for an explanation of the variants.
1148
1149            bool  isIDFIRST             (UV ch)
1150            bool  isIDFIRST_A           (UV ch)
1151            bool  isIDFIRST_L1          (UV ch)
1152            bool  isIDFIRST_uvchr       (UV ch)
1153            bool  isIDFIRST_utf8_safe   (U8 * s, U8 * end)
1154            bool  isIDFIRST_utf8        (U8 * s, U8 * end)
1155            bool  isIDFIRST_LC          (UV ch)
1156            bool  isIDFIRST_LC_uvchr    (UV ch)
1157            bool  isIDFIRST_LC_utf8_safe(U8 * s, U8 *end)
1158
1159       "isLOWER"
1160       "isLOWER_A"
1161       "isLOWER_L1"
1162       "isLOWER_uvchr"
1163       "isLOWER_utf8_safe"
1164       "isLOWER_utf8"
1165       "isLOWER_LC"
1166       "isLOWER_LC_uvchr"
1167       "isLOWER_LC_utf8_safe"
1168           Returns a boolean indicating whether the specified character is a
1169           lowercase character, analogous to "m/[[:lower:]]/".  See the top of
1170           this section for an explanation of the variants
1171
1172            bool  isLOWER             (UV ch)
1173            bool  isLOWER_A           (UV ch)
1174            bool  isLOWER_L1          (UV ch)
1175            bool  isLOWER_uvchr       (UV ch)
1176            bool  isLOWER_utf8_safe   (U8 * s, U8 * end)
1177            bool  isLOWER_utf8        (U8 * s, U8 * end)
1178            bool  isLOWER_LC          (UV ch)
1179            bool  isLOWER_LC_uvchr    (UV ch)
1180            bool  isLOWER_LC_utf8_safe(U8 * s, U8 *end)
1181
1182       "isOCTAL"
1183       "isOCTAL_A"
1184       "isOCTAL_L1"
1185           Returns a boolean indicating whether the specified character is an
1186           octal digit, [0-7].  The only two variants are "isOCTAL_A" and
1187           "isOCTAL_L1"; each is identical to "isOCTAL".
1188
1189            bool  isOCTAL(UV ch)
1190
1191       "isPRINT"
1192       "isPRINT_A"
1193       "isPRINT_L1"
1194       "isPRINT_uvchr"
1195       "isPRINT_utf8_safe"
1196       "isPRINT_utf8"
1197       "isPRINT_LC"
1198       "isPRINT_LC_uvchr"
1199       "isPRINT_LC_utf8_safe"
1200           Returns a boolean indicating whether the specified character is a
1201           printable character, analogous to "m/[[:print:]]/".  See the top of
1202           this section for an explanation of the variants.
1203
1204            bool  isPRINT             (UV ch)
1205            bool  isPRINT_A           (UV ch)
1206            bool  isPRINT_L1          (UV ch)
1207            bool  isPRINT_uvchr       (UV ch)
1208            bool  isPRINT_utf8_safe   (U8 * s, U8 * end)
1209            bool  isPRINT_utf8        (U8 * s, U8 * end)
1210            bool  isPRINT_LC          (UV ch)
1211            bool  isPRINT_LC_uvchr    (UV ch)
1212            bool  isPRINT_LC_utf8_safe(U8 * s, U8 *end)
1213
1214       "isPSXSPC"
1215       "isPSXSPC_A"
1216       "isPSXSPC_L1"
1217       "isPSXSPC_uvchr"
1218       "isPSXSPC_utf8_safe"
1219       "isPSXSPC_utf8"
1220       "isPSXSPC_LC"
1221       "isPSXSPC_LC_uvchr"
1222       "isPSXSPC_LC_utf8_safe"
1223           (short for Posix Space) Starting in 5.18, this is identical in all
1224           its forms to the corresponding "isSPACE()" macros.  The locale
1225           forms of this macro are identical to their corresponding
1226           "isSPACE()" forms in all Perl releases.  In releases prior to 5.18,
1227           the non-locale forms differ from their "isSPACE()" forms only in
1228           that the "isSPACE()" forms don't match a Vertical Tab, and the
1229           "isPSXSPC()" forms do.  Otherwise they are identical.  Thus this
1230           macro is analogous to what "m/[[:space:]]/" matches in a regular
1231           expression.  See the top of this section for an explanation of the
1232           variants.
1233
1234            bool  isPSXSPC             (UV ch)
1235            bool  isPSXSPC_A           (UV ch)
1236            bool  isPSXSPC_L1          (UV ch)
1237            bool  isPSXSPC_uvchr       (UV ch)
1238            bool  isPSXSPC_utf8_safe   (U8 * s, U8 * end)
1239            bool  isPSXSPC_utf8        (U8 * s, U8 * end)
1240            bool  isPSXSPC_LC          (UV ch)
1241            bool  isPSXSPC_LC_uvchr    (UV ch)
1242            bool  isPSXSPC_LC_utf8_safe(U8 * s, U8 *end)
1243
1244       "isPUNCT"
1245       "isPUNCT_A"
1246       "isPUNCT_L1"
1247       "isPUNCT_uvchr"
1248       "isPUNCT_utf8_safe"
1249       "isPUNCT_utf8"
1250       "isPUNCT_LC"
1251       "isPUNCT_LC_uvchr"
1252       "isPUNCT_LC_utf8_safe"
1253           Returns a boolean indicating whether the specified character is a
1254           punctuation character, analogous to "m/[[:punct:]]/".  Note that
1255           the definition of what is punctuation isn't as straightforward as
1256           one might desire.  See "POSIX Character Classes" in perlrecharclass
1257           for details.  See the top of this section for an explanation of the
1258           variants.
1259
1260            bool  isPUNCT             (UV ch)
1261            bool  isPUNCT_A           (UV ch)
1262            bool  isPUNCT_L1          (UV ch)
1263            bool  isPUNCT_uvchr       (UV ch)
1264            bool  isPUNCT_utf8_safe   (U8 * s, U8 * end)
1265            bool  isPUNCT_utf8        (U8 * s, U8 * end)
1266            bool  isPUNCT_LC          (UV ch)
1267            bool  isPUNCT_LC_uvchr    (UV ch)
1268            bool  isPUNCT_LC_utf8_safe(U8 * s, U8 *end)
1269
1270       "isSPACE"
1271       "isSPACE_A"
1272       "isSPACE_L1"
1273       "isSPACE_uvchr"
1274       "isSPACE_utf8_safe"
1275       "isSPACE_utf8"
1276       "isSPACE_LC"
1277       "isSPACE_LC_uvchr"
1278       "isSPACE_LC_utf8_safe"
1279           Returns a boolean indicating whether the specified character is a
1280           whitespace character.  This is analogous to what "m/\s/" matches in
1281           a regular expression.  Starting in Perl 5.18 this also matches what
1282           "m/[[:space:]]/" does.  Prior to 5.18, only the locale forms of
1283           this macro (the ones with "LC" in their names) matched precisely
1284           what "m/[[:space:]]/" does.  In those releases, the only
1285           difference, in the non-locale variants, was that "isSPACE()" did
1286           not match a vertical tab.  (See "isPSXSPC" for a macro that matches
1287           a vertical tab in all releases.)  See the top of this section for
1288           an explanation of the variants.
1289
1290            bool  isSPACE             (UV ch)
1291            bool  isSPACE_A           (UV ch)
1292            bool  isSPACE_L1          (UV ch)
1293            bool  isSPACE_uvchr       (UV ch)
1294            bool  isSPACE_utf8_safe   (U8 * s, U8 * end)
1295            bool  isSPACE_utf8        (U8 * s, U8 * end)
1296            bool  isSPACE_LC          (UV ch)
1297            bool  isSPACE_LC_uvchr    (UV ch)
1298            bool  isSPACE_LC_utf8_safe(U8 * s, U8 *end)
1299
1300       "isUPPER"
1301       "isUPPER_A"
1302       "isUPPER_L1"
1303       "isUPPER_uvchr"
1304       "isUPPER_utf8_safe"
1305       "isUPPER_utf8"
1306       "isUPPER_LC"
1307       "isUPPER_LC_uvchr"
1308       "isUPPER_LC_utf8_safe"
1309           Returns a boolean indicating whether the specified character is an
1310           uppercase character, analogous to "m/[[:upper:]]/".  See the top of
1311           this section for an explanation of the variants.
1312
1313            bool  isUPPER             (UV ch)
1314            bool  isUPPER_A           (UV ch)
1315            bool  isUPPER_L1          (UV ch)
1316            bool  isUPPER_uvchr       (UV ch)
1317            bool  isUPPER_utf8_safe   (U8 * s, U8 * end)
1318            bool  isUPPER_utf8        (U8 * s, U8 * end)
1319            bool  isUPPER_LC          (UV ch)
1320            bool  isUPPER_LC_uvchr    (UV ch)
1321            bool  isUPPER_LC_utf8_safe(U8 * s, U8 *end)
1322
1323       "isWORDCHAR"
1324       "isWORDCHAR_A"
1325       "isWORDCHAR_L1"
1326       "isWORDCHAR_uvchr"
1327       "isWORDCHAR_utf8_safe"
1328       "isWORDCHAR_utf8"
1329       "isWORDCHAR_LC"
1330       "isWORDCHAR_LC_uvchr"
1331       "isWORDCHAR_LC_utf8_safe"
1332       "isALNUM"
1333       "isALNUM_A"
1334       "isALNUM_LC"
1335       "isALNUM_LC_uvchr"
1336           Returns a boolean indicating whether the specified character is a
1337           character that is a word character, analogous to what "m/\w/" and
1338           "m/[[:word:]]/" match in a regular expression.  A word character is
1339           an alphabetic character, a decimal digit, a connecting punctuation
1340           character (such as an underscore), or a "mark" character that
1341           attaches to one of those (like some sort of accent).  "isALNUM()"
1342           is a synonym provided for backward compatibility, even though a
1343           word character includes more than the standard C language meaning
1344           of alphanumeric.  See the top of this section for an explanation of
1345           the variants.  "isWORDCHAR_A", "isWORDCHAR_L1", "isWORDCHAR_uvchr",
1346           "isWORDCHAR_LC", "isWORDCHAR_LC_uvchr", "isWORDCHAR_LC_utf8", and
1347           "isWORDCHAR_LC_utf8_safe" are also as described there, but
1348           additionally include the platform's native underscore.
1349
1350            bool  isWORDCHAR             (UV ch)
1351            bool  isWORDCHAR_A           (UV ch)
1352            bool  isWORDCHAR_L1          (UV ch)
1353            bool  isWORDCHAR_uvchr       (UV ch)
1354            bool  isWORDCHAR_utf8_safe   (U8 * s, U8 * end)
1355            bool  isWORDCHAR_utf8        (U8 * s, U8 * end)
1356            bool  isWORDCHAR_LC          (UV ch)
1357            bool  isWORDCHAR_LC_uvchr    (UV ch)
1358            bool  isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end)
1359            bool  isALNUM                (UV ch)
1360            bool  isALNUM_A              (UV ch)
1361            bool  isALNUM_LC             (UV ch)
1362            bool  isALNUM_LC_uvchr       (UV ch)
1363
1364       "isXDIGIT"
1365       "isXDIGIT_A"
1366       "isXDIGIT_L1"
1367       "isXDIGIT_uvchr"
1368       "isXDIGIT_utf8_safe"
1369       "isXDIGIT_utf8"
1370       "isXDIGIT_LC"
1371       "isXDIGIT_LC_uvchr"
1372       "isXDIGIT_LC_utf8_safe"
1373           Returns a boolean indicating whether the specified character is a
1374           hexadecimal digit.  In the ASCII range these are "[0-9A-Fa-f]".
1375           Variants "isXDIGIT_A()" and "isXDIGIT_L1()" are identical to
1376           "isXDIGIT()".  See the top of this section for an explanation of
1377           the variants.
1378
1379            bool  isXDIGIT             (UV ch)
1380            bool  isXDIGIT_A           (UV ch)
1381            bool  isXDIGIT_L1          (UV ch)
1382            bool  isXDIGIT_uvchr       (UV ch)
1383            bool  isXDIGIT_utf8_safe   (U8 * s, U8 * end)
1384            bool  isXDIGIT_utf8        (U8 * s, U8 * end)
1385            bool  isXDIGIT_LC          (UV ch)
1386            bool  isXDIGIT_LC_uvchr    (UV ch)
1387            bool  isXDIGIT_LC_utf8_safe(U8 * s, U8 *end)
1388

Compiler and Preprocessor information

1390       "CPPLAST"
1391           This symbol is intended to be used along with "CPPRUN" in the same
1392           manner symbol "CPPMINUS" is used with "CPPSTDIN". It contains
1393           either "-" or "".
1394
1395       "CPPMINUS"
1396           This symbol contains the second part of the string which will
1397           invoke the C preprocessor on the standard input and produce to
1398           standard output.  This symbol will have the value "-" if "CPPSTDIN"
1399           needs a minus to specify standard input, otherwise the value is "".
1400
1401       "CPPRUN"
1402           This symbol contains the string which will invoke a C preprocessor
1403           on the standard input and produce to standard output. It needs to
1404           end with "CPPLAST", after all other preprocessor flags have been
1405           specified.  The main difference with "CPPSTDIN" is that this
1406           program will never be a pointer to a shell wrapper, i.e. it will be
1407           empty if no preprocessor is available directly to the user. Note
1408           that it may well be different from the preprocessor used to compile
1409           the C program.
1410
1411       "CPPSTDIN"
1412           This symbol contains the first part of the string which will invoke
1413           the C preprocessor on the standard input and produce to standard
1414           output.  Typical value of "cc -E" or "/lib/cpp", but it can also
1415           call a wrapper. See "CPPRUN".
1416
1417       "HASATTRIBUTE_ALWAYS_INLINE"
1418           Can we handle "GCC" attribute for functions that should always be
1419           inlined.
1420
1421       "HASATTRIBUTE_DEPRECATED"
1422           Can we handle "GCC" attribute for marking deprecated "APIs"
1423
1424       "HASATTRIBUTE_FORMAT"
1425           Can we handle "GCC" attribute for checking printf-style formats
1426
1427       "HASATTRIBUTE_NONNULL"
1428           Can we handle "GCC" attribute for nonnull function parms.
1429
1430       "HASATTRIBUTE_NORETURN"
1431           Can we handle "GCC" attribute for functions that do not return
1432
1433       "HASATTRIBUTE_PURE"
1434           Can we handle "GCC" attribute for pure functions
1435
1436       "HASATTRIBUTE_UNUSED"
1437           Can we handle "GCC" attribute for unused variables and arguments
1438
1439       "HASATTRIBUTE_WARN_UNUSED_RESULT"
1440           Can we handle "GCC" attribute for warning on unused results
1441
1442       "HAS_BUILTIN_ADD_OVERFLOW"
1443           This symbol, if defined, indicates that the compiler supports
1444           "__builtin_add_overflow" for adding integers with overflow checks.
1445
1446       "HAS_BUILTIN_CHOOSE_EXPR"
1447           Can we handle "GCC" builtin for compile-time ternary-like
1448           expressions
1449
1450       "HAS_BUILTIN_EXPECT"
1451           Can we handle "GCC" builtin for telling that certain values are
1452           more likely
1453
1454       "HAS_BUILTIN_MUL_OVERFLOW"
1455           This symbol, if defined, indicates that the compiler supports
1456           "__builtin_mul_overflow" for multiplying integers with overflow
1457           checks.
1458
1459       "HAS_BUILTIN_SUB_OVERFLOW"
1460           This symbol, if defined, indicates that the compiler supports
1461           "__builtin_sub_overflow" for subtracting integers with overflow
1462           checks.
1463
1464       "HAS_C99_VARIADIC_MACROS"
1465           If defined, the compiler supports C99 variadic macros.
1466
1467       "HAS_STATIC_INLINE"
1468           This symbol, if defined, indicates that the C compiler supports
1469           C99-style static inline.  That is, the function can't be called
1470           from another translation unit.
1471
1472       "MEM_ALIGNBYTES"
1473           This symbol contains the number of bytes required to align a
1474           double, or a long double when applicable. Usual values are 2, 4 and
1475           8. The default is eight, for safety.  For cross-compiling or
1476           multiarch support, Configure will set a minimum of 8.
1477
1478       "PERL_STATIC_INLINE"
1479           This symbol gives the best-guess incantation to use for static
1480           inline functions.  If "HAS_STATIC_INLINE" is defined, this will
1481           give C99-style inline.  If "HAS_STATIC_INLINE" is not defined, this
1482           will give a plain 'static'.  It will always be defined to something
1483           that gives static linkage.  Possibilities include
1484
1485            static inline       (c99)
1486            static __inline__   (gcc -ansi)
1487            static __inline     (MSVC)
1488            static _inline      (older MSVC)
1489            static              (c89 compilers)
1490
1491       "U32_ALIGNMENT_REQUIRED"
1492           This symbol, if defined, indicates that you must access character
1493           data through U32-aligned pointers.
1494

Compiler directives

1496       "ASSUME"
1497           "ASSUME" is like "assert()", but it has a benefit in a release
1498           build. It is a hint to a compiler about a statement of fact in a
1499           function call free expression, which allows the compiler to
1500           generate better machine code.  In a debug build, ASSUME(x) is a
1501           synonym for assert(x). ASSUME(0) means the control path is
1502           unreachable. In a for loop, "ASSUME" can be used to hint that a
1503           loop will run at least X times. "ASSUME" is based off MSVC's
1504           "__assume" intrinsic function, see its documents for more details.
1505
1506              ASSUME(bool expr)
1507
1508       "dNOOP"
1509           Declare nothing; typically used as a placeholder to replace
1510           something that used to declare something.  Works on compilers that
1511           require declarations before any code.
1512
1513              dNOOP;
1514
1515       "END_EXTERN_C"
1516           When not compiling using C++, expands to nothing.  Otherwise ends a
1517           section of code already begun by a "START_EXTERN_C".
1518
1519              END_EXTERN_C
1520
1521       "EXTERN_C"
1522           When not compiling using C++, expands to nothing.  Otherwise is
1523           used in a declaration of a function to indicate the function should
1524           have external C linkage.  This is required for things to work for
1525           just about all functions with external linkage compiled into perl.
1526           Often, you can use "START_EXTERN_C" ... "END_EXTERN_C" blocks
1527           surrounding all your code that you need to have this linkage.
1528
1529           Example usage:
1530
1531            EXTERN_C int flock(int fd, int op);
1532
1533       "LIKELY"
1534           Returns the input unchanged, but at the same time it gives a branch
1535           prediction hint to the compiler that this condition is likely to be
1536           true.
1537
1538              LIKELY(bool expr)
1539
1540       "NOOP"
1541           Do nothing; typically used as a placeholder to replace something
1542           that used to do something.
1543
1544              NOOP;
1545
1546       "PERL_UNUSED_ARG"
1547           This is used to suppress compiler warnings that a parameter to a
1548           function is not used.  This situation can arise, for example, when
1549           a parameter is needed under some configuration conditions, but not
1550           others, so that C preprocessor conditional compilation causes it be
1551           used just some times.
1552
1553              PERL_UNUSED_ARG(void x);
1554
1555       "PERL_UNUSED_CONTEXT"
1556           This is used to suppress compiler warnings that the thread context
1557           parameter to a function is not used.  This situation can arise, for
1558           example, when a C preprocessor conditional compilation causes it be
1559           used just some times.
1560
1561              PERL_UNUSED_CONTEXT;
1562
1563       "PERL_UNUSED_DECL"
1564           Tells the compiler that the parameter in the function prototype
1565           just before it is not necessarily expected to be used in the
1566           function.  Not that many compilers understand this, so this should
1567           only be used in cases where "PERL_UNUSED_ARG" can't conveniently be
1568           used.
1569
1570           Example usage:
1571
1572            Signal_t
1573            Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
1574                                  void *uap PERL_UNUSED_DECL, bool safe)
1575
1576       "PERL_UNUSED_RESULT"
1577           This macro indicates to discard the return value of the function
1578           call inside it, e.g.,
1579
1580            PERL_UNUSED_RESULT(foo(a, b))
1581
1582           The main reason for this is that the combination of "gcc
1583           -Wunused-result" (part of "-Wall") and the
1584           "__attribute__((warn_unused_result))" cannot be silenced with
1585           casting to "void".  This causes trouble when the system header
1586           files use the attribute.
1587
1588           Use "PERL_UNUSED_RESULT" sparingly, though, since usually the
1589           warning is there for a good reason: you might lose success/failure
1590           information, or leak resources, or changes in resources.
1591
1592           But sometimes you just want to ignore the return value, e.g., on
1593           codepaths soon ending up in abort, or in "best effort" attempts, or
1594           in situations where there is no good way to handle failures.
1595
1596           Sometimes "PERL_UNUSED_RESULT" might not be the most natural way:
1597           another possibility is that you can capture the return value and
1598           use "PERL_UNUSED_VAR" on that.
1599
1600              PERL_UNUSED_RESULT(void x)
1601
1602       "PERL_UNUSED_VAR"
1603           This is used to suppress compiler warnings that the variable x is
1604           not used.  This situation can arise, for example, when a C
1605           preprocessor conditional compilation causes it be used just some
1606           times.
1607
1608              PERL_UNUSED_VAR(void x);
1609
1610       "PERL_USE_GCC_BRACE_GROUPS"
1611           This C pre-processor value, if defined, indicates that it is
1612           permissible to use the GCC brace groups extension.  This extension,
1613           of the form
1614
1615            ({ statement ... })
1616
1617           turns the block consisting of statements ... into an expression
1618           with a value, unlike plain C language blocks.  This can present
1619           optimization possibilities, BUT you generally need to specify an
1620           alternative in case this ability doesn't exist or has otherwise
1621           been forbidden.
1622
1623           Example usage:
1624
1625            #ifdef PERL_USE_GCC_BRACE_GROUPS
1626              ...
1627            #else
1628              ...
1629            #endif
1630
1631       "START_EXTERN_C"
1632           When not compiling using C++, expands to nothing.  Otherwise begins
1633           a section of code in which every function will effectively have
1634           "EXTERN_C" applied to it, that is to have external C linkage.  The
1635           section is ended by a "END_EXTERN_C".
1636
1637              START_EXTERN_C
1638
1639       "STATIC"
1640           Described in perlguts.
1641
1642       "STMT_START"
1643       "STMT_END"
1644           This allows a series of statements in a macro to be used as a
1645           single statement, as in
1646
1647            if (x) STMT_START { ... } STMT_END else ...
1648
1649           Note that you can't return a value out of them, which limits their
1650           utility.  But see "PERL_USE_GCC_BRACE_GROUPS".
1651
1652       "UNLIKELY"
1653           Returns the input unchanged, but at the same time it gives a branch
1654           prediction hint to the compiler that this condition is likely to be
1655           false.
1656
1657              UNLIKELY(bool expr)
1658
1659       "__ASSERT_"
1660           This is a helper macro to avoid preprocessor issues, replaced by
1661           nothing unless under DEBUGGING, where it expands to an assert of
1662           its argument, followed by a comma (hence the comma operator).  If
1663           we just used a straight assert(), we would get a comma with nothing
1664           before it when not DEBUGGING.
1665
1666              __ASSERT_(bool expr)
1667

Compile-time scope hooks

1669       "BhkDISABLE"
1670           NOTE: "BhkDISABLE" is experimental and may change or be removed
1671           without notice.
1672
1673           Temporarily disable an entry in this BHK structure, by clearing the
1674           appropriate flag.  "which" is a preprocessor token indicating which
1675           entry to disable.
1676
1677            void  BhkDISABLE(BHK *hk, which)
1678
1679       "BhkENABLE"
1680           NOTE: "BhkENABLE" is experimental and may change or be removed
1681           without notice.
1682
1683           Re-enable an entry in this BHK structure, by setting the
1684           appropriate flag.  "which" is a preprocessor token indicating which
1685           entry to enable.  This will assert (under -DDEBUGGING) if the entry
1686           doesn't contain a valid pointer.
1687
1688            void  BhkENABLE(BHK *hk, which)
1689
1690       "BhkENTRY_set"
1691           NOTE: "BhkENTRY_set" is experimental and may change or be removed
1692           without notice.
1693
1694           Set an entry in the BHK structure, and set the flags to indicate it
1695           is valid.  "which" is a preprocessing token indicating which entry
1696           to set.  The type of "ptr" depends on the entry.
1697
1698            void  BhkENTRY_set(BHK *hk, which, void *ptr)
1699
1700       "blockhook_register"
1701           NOTE: "blockhook_register" is experimental and may change or be
1702           removed without notice.
1703
1704           Register a set of hooks to be called when the Perl lexical scope
1705           changes at compile time.  See "Compile-time scope hooks" in
1706           perlguts.
1707
1708           NOTE: "blockhook_register" must be explicitly called as
1709           "Perl_blockhook_register" with an "aTHX_" parameter.
1710
1711            void  Perl_blockhook_register(pTHX_ BHK *hk)
1712

Concurrency

1714       "aTHX"
1715           Described in perlguts.
1716
1717       "aTHX_"
1718           Described in perlguts.
1719
1720       "CPERLscope"
1721           "DEPRECATED!"  It is planned to remove "CPERLscope" from a future
1722           release of Perl.  Do not use it for new code; remove it from
1723           existing code.
1724
1725           Now a no-op.
1726
1727            void  CPERLscope(void x)
1728
1729       "dTHR"
1730           Described in perlguts.
1731
1732       "dTHX"
1733           Described in perlguts.
1734
1735       "dTHXa"
1736           On threaded perls, set "pTHX" to "a"; on unthreaded perls, do
1737           nothing
1738
1739       "dTHXoa"
1740           Now a synonym for "dTHXa".
1741
1742       "dVAR"
1743           This is now a synonym for dNOOP: declare nothing
1744
1745       "GETENV_PRESERVES_OTHER_THREAD"
1746           This symbol, if defined, indicates that the getenv system call
1747           doesn't zap the static buffer of "getenv()" in a different thread.
1748           The typical "getenv()" implementation will return a pointer to the
1749           proper position in **environ.  But some may instead copy them to a
1750           static buffer in "getenv()".  If there is a per-thread instance of
1751           that buffer, or the return points to **environ, then a
1752           many-reader/1-writer mutex will work; otherwise an exclusive
1753           locking mutex is required to prevent races.
1754
1755       "HAS_PTHREAD_ATFORK"
1756           This symbol, if defined, indicates that the "pthread_atfork"
1757           routine is available to setup fork handlers.
1758
1759       "HAS_PTHREAD_ATTR_SETSCOPE"
1760           This symbol, if defined, indicates that the "pthread_attr_setscope"
1761           system call is available to set the contention scope attribute of a
1762           thread attribute object.
1763
1764       "HAS_PTHREAD_YIELD"
1765           This symbol, if defined, indicates that the "pthread_yield" routine
1766           is available to yield the execution of the current thread.
1767           "sched_yield" is preferable to "pthread_yield".
1768
1769       "HAS_SCHED_YIELD"
1770           This symbol, if defined, indicates that the "sched_yield" routine
1771           is available to yield the execution of the current thread.
1772           "sched_yield" is preferable to "pthread_yield".
1773
1774       "I_MACH_CTHREADS"
1775           This symbol, if defined, indicates to the C program that it should
1776           include mach/cthreads.h.
1777
1778            #ifdef I_MACH_CTHREADS
1779                #include <mach_cthreads.h>
1780            #endif
1781
1782       "I_PTHREAD"
1783           This symbol, if defined, indicates to the C program that it should
1784           include pthread.h.
1785
1786            #ifdef I_PTHREAD
1787                #include <pthread.h>
1788            #endif
1789
1790       "MULTIPLICITY"
1791           This symbol, if defined, indicates that Perl should be built to use
1792           multiplicity.
1793
1794       "OLD_PTHREADS_API"
1795           This symbol, if defined, indicates that Perl should be built to use
1796           the old draft "POSIX" threads "API".
1797
1798       "OLD_PTHREAD_CREATE_JOINABLE"
1799           This symbol, if defined, indicates how to create pthread in
1800           joinable (aka undetached) state.  "NOTE": not defined if pthread.h
1801           already has defined "PTHREAD_CREATE_JOINABLE" (the new version of
1802           the constant).  If defined, known values are
1803           "PTHREAD_CREATE_UNDETACHED" and "__UNDETACHED".
1804
1805       "pTHX"
1806           Described in perlguts.
1807
1808       "pTHX_"
1809           Described in perlguts.
1810
1811       "SCHED_YIELD"
1812           This symbol defines the way to yield the execution of the current
1813           thread.  Known ways are "sched_yield", "pthread_yield", and
1814           "pthread_yield" with "NULL".
1815
1816       "SVf"
1817           Described in perlguts.
1818
1819       "SVfARG"
1820           Described in perlguts.
1821
1822              SVfARG(SV *sv)
1823

COP Hint Hashes

1825       "cop_fetch_label"
1826           NOTE: "cop_fetch_label" is experimental and may change or be
1827           removed without notice.
1828
1829           Returns the label attached to a cop, and stores its length in bytes
1830           into *len.  Upon return, *flags will be set to either "SVf_UTF8" or
1831           0.
1832
1833           Alternatively, use the macro "CopLABEL_len_flags"; or if you don't
1834           need to know if the label is UTF-8 or not, the macro
1835           "CopLABEL_len"; or if you additionally dont need to know the
1836           length, "CopLABEL".
1837
1838            const char *  cop_fetch_label(COP *const cop, STRLEN *len,
1839                                          U32 *flags)
1840
1841       "CopFILE"
1842           Returns the name of the file associated with the "COP" "c"
1843
1844            const char *  CopFILE(const COP * c)
1845
1846       "CopFILEAV"
1847           Returns the AV associated with the "COP" "c"
1848
1849            AV *  CopFILEAV(const COP * c)
1850
1851       "CopFILEGV"
1852           Returns the GV associated with the "COP" "c"
1853
1854            GV *  CopFILEGV(const COP * c)
1855
1856       "CopFILEGV_set"
1857           Available only on unthreaded perls.  Makes "pv" the name of the
1858           file associated with the "COP" "c"
1859
1860            void  CopFILEGV_set(COP * c, GV * gv)
1861
1862       "CopFILE_set"
1863           Makes "pv" the name of the file associated with the "COP" "c"
1864
1865            void  CopFILE_set(COP * c, const char * pv)
1866
1867       "CopFILESV"
1868           Returns the SV associated with the "COP" "c"
1869
1870            SV *  CopFILESV(const COP * c)
1871
1872       "cophh_2hv"
1873           NOTE: "cophh_2hv" is experimental and may change or be removed
1874           without notice.
1875
1876           Generates and returns a standard Perl hash representing the full
1877           set of key/value pairs in the cop hints hash "cophh".  "flags" is
1878           currently unused and must be zero.
1879
1880            HV *  cophh_2hv(const COPHH *cophh, U32 flags)
1881
1882       "cophh_copy"
1883           NOTE: "cophh_copy" is experimental and may change or be removed
1884           without notice.
1885
1886           Make and return a complete copy of the cop hints hash "cophh".
1887
1888            COPHH *  cophh_copy(COPHH *cophh)
1889
1890       "cophh_delete_pv"
1891           NOTE: "cophh_delete_pv" is experimental and may change or be
1892           removed without notice.
1893
1894           Like "cophh_delete_pvn", but takes a nul-terminated string instead
1895           of a string/length pair.
1896
1897            COPHH *  cophh_delete_pv(COPHH *cophh, char *key, U32 hash,
1898                                     U32 flags)
1899
1900       "cophh_delete_pvn"
1901           NOTE: "cophh_delete_pvn" is experimental and may change or be
1902           removed without notice.
1903
1904           Delete a key and its associated value from the cop hints hash
1905           "cophh", and returns the modified hash.  The returned hash pointer
1906           is in general not the same as the hash pointer that was passed in.
1907           The input hash is consumed by the function, and the pointer to it
1908           must not be subsequently used.  Use "cophh_copy" if you need both
1909           hashes.
1910
1911           The key is specified by "keypv" and "keylen".  If "flags" has the
1912           "COPHH_KEY_UTF8" bit set, the key octets are interpreted as UTF-8,
1913           otherwise they are interpreted as Latin-1.  "hash" is a precomputed
1914           hash of the key string, or zero if it has not been precomputed.
1915
1916            COPHH *  cophh_delete_pvn(COPHH *cophh, const char *keypv,
1917                                      STRLEN keylen, U32 hash, U32 flags)
1918
1919       "cophh_delete_pvs"
1920           NOTE: "cophh_delete_pvs" is experimental and may change or be
1921           removed without notice.
1922
1923           Like "cophh_delete_pvn", but takes a literal string instead of a
1924           string/length pair, and no precomputed hash.
1925
1926            COPHH *  cophh_delete_pvs(COPHH *cophh, "key", U32 flags)
1927
1928       "cophh_delete_sv"
1929           NOTE: "cophh_delete_sv" is experimental and may change or be
1930           removed without notice.
1931
1932           Like "cophh_delete_pvn", but takes a Perl scalar instead of a
1933           string/length pair.
1934
1935            COPHH *  cophh_delete_sv(COPHH *cophh, SV *key, U32 hash,
1936                                     U32 flags)
1937
1938       "cophh_exists_pv"
1939           NOTE: "cophh_exists_pv" is experimental and may change or be
1940           removed without notice.
1941
1942           Like "cophh_exists_pvn", but takes a nul-terminated string instead
1943           of a string/length pair.
1944
1945            bool  cophh_exists_pv(const COPHH *cophh, const char *key,
1946                                  U32 hash, U32 flags)
1947
1948       "cophh_exists_pvn"
1949           NOTE: "cophh_exists_pvn" is experimental and may change or be
1950           removed without notice.
1951
1952           Look up the entry in the cop hints hash "cophh" with the key
1953           specified by "keypv" and "keylen".  If "flags" has the
1954           "COPHH_KEY_UTF8" bit set, the key octets are interpreted as UTF-8,
1955           otherwise they are interpreted as Latin-1.  "hash" is a precomputed
1956           hash of the key string, or zero if it has not been precomputed.
1957           Returns true if a value exists, and false otherwise.
1958
1959            bool  cophh_exists_pvn(const COPHH *cophh, const char *keypv,
1960                                   STRLEN keylen, U32 hash, U32 flags)
1961
1962       "cophh_exists_pvs"
1963           NOTE: "cophh_exists_pvs" is experimental and may change or be
1964           removed without notice.
1965
1966           Like "cophh_exists_pvn", but takes a literal string instead of a
1967           string/length pair, and no precomputed hash.
1968
1969            bool  cophh_exists_pvs(const COPHH *cophh, "key", U32 flags)
1970
1971       "cophh_exists_sv"
1972           NOTE: "cophh_exists_sv" is experimental and may change or be
1973           removed without notice.
1974
1975           Like "cophh_exists_pvn", but takes a Perl scalar instead of a
1976           string/length pair.
1977
1978            bool  cophh_exists_sv(const COPHH *cophh, SV *key, U32 hash,
1979                                  U32 flags)
1980
1981       "cophh_fetch_pv"
1982           NOTE: "cophh_fetch_pv" is experimental and may change or be removed
1983           without notice.
1984
1985           Like "cophh_fetch_pvn", but takes a nul-terminated string instead
1986           of a string/length pair.
1987
1988            SV *  cophh_fetch_pv(const COPHH *cophh, const char *key,
1989                                 U32 hash, U32 flags)
1990
1991       "cophh_fetch_pvn"
1992           NOTE: "cophh_fetch_pvn" is experimental and may change or be
1993           removed without notice.
1994
1995           Look up the entry in the cop hints hash "cophh" with the key
1996           specified by "keypv" and "keylen".  If "flags" has the
1997           "COPHH_KEY_UTF8" bit set, the key octets are interpreted as UTF-8,
1998           otherwise they are interpreted as Latin-1.  "hash" is a precomputed
1999           hash of the key string, or zero if it has not been precomputed.
2000           Returns a mortal scalar copy of the value associated with the key,
2001           or &PL_sv_placeholder if there is no value associated with the key.
2002
2003            SV *  cophh_fetch_pvn(const COPHH *cophh, const char *keypv,
2004                                  STRLEN keylen, U32 hash, U32 flags)
2005
2006       "cophh_fetch_pvs"
2007           NOTE: "cophh_fetch_pvs" is experimental and may change or be
2008           removed without notice.
2009
2010           Like "cophh_fetch_pvn", but takes a literal string instead of a
2011           string/length pair, and no precomputed hash.
2012
2013            SV *  cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags)
2014
2015       "cophh_fetch_sv"
2016           NOTE: "cophh_fetch_sv" is experimental and may change or be removed
2017           without notice.
2018
2019           Like "cophh_fetch_pvn", but takes a Perl scalar instead of a
2020           string/length pair.
2021
2022            SV *  cophh_fetch_sv(const COPHH *cophh, SV *key, U32 hash,
2023                                 U32 flags)
2024
2025       "cophh_free"
2026           NOTE: "cophh_free" is experimental and may change or be removed
2027           without notice.
2028
2029           Discard the cop hints hash "cophh", freeing all resources
2030           associated with it.
2031
2032            void  cophh_free(COPHH *cophh)
2033
2034       "cophh_new_empty"
2035           NOTE: "cophh_new_empty" is experimental and may change or be
2036           removed without notice.
2037
2038           Generate and return a fresh cop hints hash containing no entries.
2039
2040            COPHH *  cophh_new_empty()
2041
2042       "cophh_store_pv"
2043           NOTE: "cophh_store_pv" is experimental and may change or be removed
2044           without notice.
2045
2046           Like "cophh_store_pvn", but takes a nul-terminated string instead
2047           of a string/length pair.
2048
2049            COPHH *  cophh_store_pv(COPHH *cophh, const char *key, U32 hash,
2050                                    SV *value, U32 flags)
2051
2052       "cophh_store_pvn"
2053           NOTE: "cophh_store_pvn" is experimental and may change or be
2054           removed without notice.
2055
2056           Stores a value, associated with a key, in the cop hints hash
2057           "cophh", and returns the modified hash.  The returned hash pointer
2058           is in general not the same as the hash pointer that was passed in.
2059           The input hash is consumed by the function, and the pointer to it
2060           must not be subsequently used.  Use "cophh_copy" if you need both
2061           hashes.
2062
2063           The key is specified by "keypv" and "keylen".  If "flags" has the
2064           "COPHH_KEY_UTF8" bit set, the key octets are interpreted as UTF-8,
2065           otherwise they are interpreted as Latin-1.  "hash" is a precomputed
2066           hash of the key string, or zero if it has not been precomputed.
2067
2068           "value" is the scalar value to store for this key.  "value" is
2069           copied by this function, which thus does not take ownership of any
2070           reference to it, and later changes to the scalar will not be
2071           reflected in the value visible in the cop hints hash.  Complex
2072           types of scalar will not be stored with referential integrity, but
2073           will be coerced to strings.
2074
2075            COPHH *  cophh_store_pvn(COPHH *cophh, const char *keypv,
2076                                     STRLEN keylen, U32 hash, SV *value,
2077                                     U32 flags)
2078
2079       "cophh_store_pvs"
2080           NOTE: "cophh_store_pvs" is experimental and may change or be
2081           removed without notice.
2082
2083           Like "cophh_store_pvn", but takes a literal string instead of a
2084           string/length pair, and no precomputed hash.
2085
2086            COPHH *  cophh_store_pvs(COPHH *cophh, "key", SV *value,
2087                                     U32 flags)
2088
2089       "cophh_store_sv"
2090           NOTE: "cophh_store_sv" is experimental and may change or be removed
2091           without notice.
2092
2093           Like "cophh_store_pvn", but takes a Perl scalar instead of a
2094           string/length pair.
2095
2096            COPHH *  cophh_store_sv(COPHH *cophh, SV *key, U32 hash,
2097                                    SV *value, U32 flags)
2098
2099       "cop_hints_2hv"
2100           Generates and returns a standard Perl hash representing the full
2101           set of hint entries in the cop "cop".  "flags" is currently unused
2102           and must be zero.
2103
2104            HV *  cop_hints_2hv(const COP *cop, U32 flags)
2105
2106       "cop_hints_exists_pv"
2107           Like "cop_hints_exists_pvn", but takes a nul-terminated string
2108           instead of a string/length pair.
2109
2110            bool  cop_hints_exists_pv(const COP *cop, const char *key,
2111                                      U32 hash, U32 flags)
2112
2113       "cop_hints_exists_pvn"
2114           Look up the hint entry in the cop "cop" with the key specified by
2115           "keypv" and "keylen".  If "flags" has the "COPHH_KEY_UTF8" bit set,
2116           the key octets are interpreted as UTF-8, otherwise they are
2117           interpreted as Latin-1.  "hash" is a precomputed hash of the key
2118           string, or zero if it has not been precomputed.  Returns true if a
2119           value exists, and false otherwise.
2120
2121            bool  cop_hints_exists_pvn(const COP *cop, const char *keypv,
2122                                       STRLEN keylen, U32 hash, U32 flags)
2123
2124       "cop_hints_exists_pvs"
2125           Like "cop_hints_exists_pvn", but takes a literal string instead of
2126           a string/length pair, and no precomputed hash.
2127
2128            bool  cop_hints_exists_pvs(const COP *cop, "key", U32 flags)
2129
2130       "cop_hints_exists_sv"
2131           Like "cop_hints_exists_pvn", but takes a Perl scalar instead of a
2132           string/length pair.
2133
2134            bool  cop_hints_exists_sv(const COP *cop, SV *key, U32 hash,
2135                                      U32 flags)
2136
2137       "cop_hints_fetch_pv"
2138           Like "cop_hints_fetch_pvn", but takes a nul-terminated string
2139           instead of a string/length pair.
2140
2141            SV *  cop_hints_fetch_pv(const COP *cop, const char *key,
2142                                     U32 hash, U32 flags)
2143
2144       "cop_hints_fetch_pvn"
2145           Look up the hint entry in the cop "cop" with the key specified by
2146           "keypv" and "keylen".  If "flags" has the "COPHH_KEY_UTF8" bit set,
2147           the key octets are interpreted as UTF-8, otherwise they are
2148           interpreted as Latin-1.  "hash" is a precomputed hash of the key
2149           string, or zero if it has not been precomputed.  Returns a mortal
2150           scalar copy of the value associated with the key, or
2151           &PL_sv_placeholder if there is no value associated with the key.
2152
2153            SV *  cop_hints_fetch_pvn(const COP *cop, const char *keypv,
2154                                      STRLEN keylen, U32 hash, U32 flags)
2155
2156       "cop_hints_fetch_pvs"
2157           Like "cop_hints_fetch_pvn", but takes a literal string instead of a
2158           string/length pair, and no precomputed hash.
2159
2160            SV *  cop_hints_fetch_pvs(const COP *cop, "key", U32 flags)
2161
2162       "cop_hints_fetch_sv"
2163           Like "cop_hints_fetch_pvn", but takes a Perl scalar instead of a
2164           string/length pair.
2165
2166            SV *  cop_hints_fetch_sv(const COP *cop, SV *key, U32 hash,
2167                                     U32 flags)
2168
2169       "CopLABEL"
2170           Returns the label attached to a cop.
2171
2172            const char *  CopLABEL(COP *const cop)
2173
2174       "CopLABEL_len"
2175           Returns the label attached to a cop, and stores its length in bytes
2176           into *len.
2177
2178            const char *  CopLABEL_len(COP *const cop, STRLEN *len)
2179
2180       "CopLABEL_len_flags"
2181           Returns the label attached to a cop, and stores its length in bytes
2182           into *len.  Upon return, *flags will be set to either "SVf_UTF8" or
2183           0.
2184
2185            const char *  CopLABEL_len_flags(COP *const cop, STRLEN *len,
2186                                             U32 *flags)
2187
2188       "CopLINE"
2189           Returns the line number in the source code associated with the
2190           "COP" "c"
2191
2192            STRLEN  CopLINE(const COP * c)
2193
2194       "CopSTASH"
2195           Returns the stash associated with "c".
2196
2197            HV *  CopSTASH(const COP * c)
2198
2199       "CopSTASH_eq"
2200           Returns a boolean as to whether or not "hv" is the stash associated
2201           with "c".
2202
2203            bool  CopSTASH_eq(const COP * c, const HV * hv)
2204
2205       "CopSTASHPV"
2206           Returns the package name of the stash associated with "c", or
2207           "NULL" if no associated stash
2208
2209            char *  CopSTASHPV(const COP * c)
2210
2211       "CopSTASHPV_set"
2212           Set the package name of the stash associated with "c", to the NUL-
2213           terminated C string "p", creating the package if necessary.
2214
2215            void  CopSTASHPV_set(COP * c, const char * pv)
2216
2217       "CopSTASH_set"
2218           Set the stash associated with "c" to "hv".
2219
2220            bool  CopSTASH_set(COP * c, HV * hv)
2221
2222       "cop_store_label"
2223           NOTE: "cop_store_label" is experimental and may change or be
2224           removed without notice.
2225
2226           Save a label into a "cop_hints_hash".  You need to set flags to
2227           "SVf_UTF8" for a UTF-8 label.  Any other flag is ignored.
2228
2229            void  cop_store_label(COP *const cop, const char *label,
2230                                  STRLEN len, U32 flags)
2231
2232       "PERL_SI"
2233           Use this typedef to declare variables that are to hold "struct
2234           stackinfo".
2235

Custom Operators

2237       "custom_op_desc"
2238           "DEPRECATED!"  It is planned to remove "custom_op_desc" from a
2239           future release of Perl.  Do not use it for new code; remove it from
2240           existing code.
2241
2242           Return the description of a given custom op.  This was once used by
2243           the "OP_DESC" macro, but is no longer: it has only been kept for
2244           compatibility, and should not be used.
2245
2246            const char *  custom_op_desc(const OP *o)
2247
2248       "custom_op_name"
2249           "DEPRECATED!"  It is planned to remove "custom_op_name" from a
2250           future release of Perl.  Do not use it for new code; remove it from
2251           existing code.
2252
2253           Return the name for a given custom op.  This was once used by the
2254           "OP_NAME" macro, but is no longer: it has only been kept for
2255           compatibility, and should not be used.
2256
2257            const char *  custom_op_name(const OP *o)
2258
2259       "custom_op_register"
2260           Register a custom op.  See "Custom Operators" in perlguts.
2261
2262           NOTE: "custom_op_register" must be explicitly called as
2263           "Perl_custom_op_register" with an "aTHX_" parameter.
2264
2265            void  Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr,
2266                                          const XOP *xop)
2267
2268       "Perl_custom_op_xop"
2269           Return the XOP structure for a given custom op.  This macro should
2270           be considered internal to "OP_NAME" and the other access macros:
2271           use them instead.  This macro does call a function.  Prior to
2272           5.19.6, this was implemented as a function.
2273
2274            const XOP *  Perl_custom_op_xop(pTHX_ const OP *o)
2275
2276       "XopDISABLE"
2277           Temporarily disable a member of the XOP, by clearing the
2278           appropriate flag.
2279
2280            void  XopDISABLE(XOP *xop, which)
2281
2282       "XopENABLE"
2283           Reenable a member of the XOP which has been disabled.
2284
2285            void  XopENABLE(XOP *xop, which)
2286
2287       "XopENTRY"
2288           Return a member of the XOP structure.  "which" is a cpp token
2289           indicating which entry to return.  If the member is not set this
2290           will return a default value.  The return type depends on "which".
2291           This macro evaluates its arguments more than once.  If you are
2292           using "Perl_custom_op_xop" to retrieve a "XOP *" from a "OP *", use
2293           the more efficient "XopENTRYCUSTOM" instead.
2294
2295              XopENTRY(XOP *xop, which)
2296
2297       "XopENTRYCUSTOM"
2298           Exactly like "XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o),
2299           which)" but more efficient.  The "which" parameter is identical to
2300           "XopENTRY".
2301
2302              XopENTRYCUSTOM(const OP *o, which)
2303
2304       "XopENTRY_set"
2305           Set a member of the XOP structure.  "which" is a cpp token
2306           indicating which entry to set.  See "Custom Operators" in perlguts
2307           for details about the available members and how they are used.
2308           This macro evaluates its argument more than once.
2309
2310            void  XopENTRY_set(XOP *xop, which, value)
2311
2312       "XopFLAGS"
2313           Return the XOP's flags.
2314
2315            U32  XopFLAGS(XOP *xop)
2316

CV Handling

2318       This section documents functions to manipulate CVs which are code-
2319       values, meaning subroutines.  For more information, see perlguts.
2320
2321       "caller_cx"
2322           The XSUB-writer's equivalent of caller().  The returned
2323           "PERL_CONTEXT" structure can be interrogated to find all the
2324           information returned to Perl by "caller".  Note that XSUBs don't
2325           get a stack frame, so "caller_cx(0, NULL)" will return information
2326           for the immediately-surrounding Perl code.
2327
2328           This function skips over the automatic calls to &DB::sub made on
2329           the behalf of the debugger.  If the stack frame requested was a sub
2330           called by "DB::sub", the return value will be the frame for the
2331           call to "DB::sub", since that has the correct line number/etc. for
2332           the call site.  If dbcxp is non-"NULL", it will be set to a pointer
2333           to the frame for the sub call itself.
2334
2335            const PERL_CONTEXT *  caller_cx(I32 level,
2336                                            const PERL_CONTEXT **dbcxp)
2337
2338       "CvGV"
2339           Returns the GV associated with the CV "sv", reifying it if
2340           necessary.
2341
2342            GV *  CvGV(CV *sv)
2343
2344       "CvSTASH"
2345           Returns the stash of the CV.  A stash is the symbol table hash,
2346           containing the package-scoped variables in the package where the
2347           subroutine was defined.  For more information, see perlguts.
2348
2349           This also has a special use with XS AUTOLOAD subs.  See
2350           "Autoloading with XSUBs" in perlguts.
2351
2352            HV*  CvSTASH(CV* cv)
2353
2354       "find_runcv"
2355           Locate the CV corresponding to the currently executing sub or eval.
2356           If "db_seqp" is non_null, skip CVs that are in the DB package and
2357           populate *db_seqp with the cop sequence number at the point that
2358           the DB:: code was entered.  (This allows debuggers to eval in the
2359           scope of the breakpoint rather than in the scope of the debugger
2360           itself.)
2361
2362            CV*  find_runcv(U32 *db_seqp)
2363
2364       "get_cv"
2365       "get_cvs"
2366       "get_cvn_flags"
2367           These return the CV of the specified Perl subroutine.  "flags" are
2368           passed to "gv_fetchpvn_flags".  If "GV_ADD" is set and the Perl
2369           subroutine does not exist then it will be declared (which has the
2370           same effect as saying "sub name;").  If "GV_ADD" is not set and the
2371           subroutine does not exist, then NULL is returned.
2372
2373           The forms differ only in how the subroutine is specified..  With
2374           "get_cvs", the name is a literal C string, enclosed in double
2375           quotes.  With "get_cv", the name is given by the "name" parameter,
2376           which must be a NUL-terminated C string.  With "get_cvn_flags", the
2377           name is also given by the "name" parameter, but it is a Perl string
2378           (possibly containing embedded NUL bytes), and its length in bytes
2379           is contained in the "len" parameter.
2380
2381           NOTE: the "perl_get_cv()" form is deprecated.
2382
2383           NOTE: the "perl_get_cvs()" form is deprecated.
2384
2385           NOTE: the "perl_get_cvn_flags()" form is deprecated.
2386
2387            CV*   get_cv       (const char* name, I32 flags)
2388            CV *  get_cvs      ("string", I32 flags)
2389            CV*   get_cvn_flags(const char* name, STRLEN len, I32 flags)
2390
2391       "Nullcv"
2392           "DEPRECATED!"  It is planned to remove "Nullcv" from a future
2393           release of Perl.  Do not use it for new code; remove it from
2394           existing code.
2395
2396           Null CV pointer.
2397
2398           (deprecated - use "(CV *)NULL" instead)
2399

Debugging

2401       "dump_all"
2402           Dumps the entire optree of the current program starting at
2403           "PL_main_root" to "STDERR".  Also dumps the optrees for all visible
2404           subroutines in "PL_defstash".
2405
2406            void  dump_all()
2407
2408       "dump_c_backtrace"
2409           Dumps the C backtrace to the given "fp".
2410
2411           Returns true if a backtrace could be retrieved, false if not.
2412
2413            bool  dump_c_backtrace(PerlIO* fp, int max_depth, int skip)
2414
2415       "dump_packsubs"
2416           Dumps the optrees for all visible subroutines in "stash".
2417
2418            void  dump_packsubs(const HV* stash)
2419
2420       "get_c_backtrace_dump"
2421           Returns a SV containing a dump of "depth" frames of the call stack,
2422           skipping the "skip" innermost ones.  "depth" of 20 is usually
2423           enough.
2424
2425           The appended output looks like:
2426
2427            ...
2428            1   10e004812:0082   Perl_croak   util.c:1716    /usr/bin/perl
2429            2   10df8d6d2:1d72   perl_parse   perl.c:3975    /usr/bin/perl
2430            ...
2431
2432           The fields are tab-separated.  The first column is the depth (zero
2433           being the innermost non-skipped frame).  In the hex:offset, the hex
2434           is where the program counter was in "S_parse_body", and the :offset
2435           (might be missing) tells how much inside the "S_parse_body" the
2436           program counter was.
2437
2438           The "util.c:1716" is the source code file and line number.
2439
2440           The /usr/bin/perl is obvious (hopefully).
2441
2442           Unknowns are "-".  Unknowns can happen unfortunately quite easily:
2443           if the platform doesn't support retrieving the information; if the
2444           binary is missing the debug information; if the optimizer has
2445           transformed the code by for example inlining.
2446
2447            SV*  get_c_backtrace_dump(int max_depth, int skip)
2448
2449       "HAS_BACKTRACE"
2450           This symbol, if defined, indicates that the "backtrace()" routine
2451           is available to get a stack trace.  The execinfo.h header must be
2452           included to use this routine.
2453
2454       "op_class"
2455           Given an op, determine what type of struct it has been allocated
2456           as.  Returns one of the OPclass enums, such as OPclass_LISTOP.
2457
2458            OPclass  op_class(const OP *o)
2459
2460       "op_dump"
2461           Dumps the optree starting at OP "o" to "STDERR".
2462
2463            void  op_dump(const OP *o)
2464
2465       "sv_dump"
2466           Dumps the contents of an SV to the "STDERR" filehandle.
2467
2468           For an example of its output, see Devel::Peek.
2469
2470            void  sv_dump(SV* sv)
2471

Display functions

2473       "form"
2474       "form_nocontext"
2475           These take a sprintf-style format pattern and conventional (non-SV)
2476           arguments and return the formatted string.
2477
2478               (char *) Perl_form(pTHX_ const char* pat, ...)
2479
2480           can be used any place a string (char *) is required:
2481
2482               char * s = Perl_form("%d.%d",major,minor);
2483
2484           They use a single (per-thread) private buffer so if you want to
2485           format several strings you must explicitly copy the earlier strings
2486           away (and free the copies when you are done).
2487
2488           The two forms differ only in that "form_nocontext" does not take a
2489           thread context ("aTHX") parameter, so is used in situations where
2490           the caller doesn't already have the thread context.
2491
2492           NOTE: "form" must be explicitly called as "Perl_form" with an
2493           "aTHX_" parameter.
2494
2495            char*  Perl_form     (pTHX_ const char* pat, ...)
2496            char*  form_nocontext(const char* pat, ...)
2497
2498       "mess"
2499       "mess_nocontext"
2500           These take a sprintf-style format pattern and argument list, which
2501           are used to generate a string message.  If the message does not end
2502           with a newline, then it will be extended with some indication of
2503           the current location in the code, as described for "mess_sv".
2504
2505           Normally, the resulting message is returned in a new mortal SV.
2506           But during global destruction a single SV may be shared between
2507           uses of this function.
2508
2509           The two forms differ only in that "mess_nocontext" does not take a
2510           thread context ("aTHX") parameter, so is used in situations where
2511           the caller doesn't already have the thread context.
2512
2513           NOTE: "mess" must be explicitly called as "Perl_mess" with an
2514           "aTHX_" parameter.
2515
2516            SV*  Perl_mess     (pTHX_ const char* pat, ...)
2517            SV*  mess_nocontext(const char* pat, ...)
2518
2519       "mess_sv"
2520           Expands a message, intended for the user, to include an indication
2521           of the current location in the code, if the message does not
2522           already appear to be complete.
2523
2524           "basemsg" is the initial message or object.  If it is a reference,
2525           it will be used as-is and will be the result of this function.
2526           Otherwise it is used as a string, and if it already ends with a
2527           newline, it is taken to be complete, and the result of this
2528           function will be the same string.  If the message does not end with
2529           a newline, then a segment such as "at foo.pl line 37" will be
2530           appended, and possibly other clauses indicating the current state
2531           of execution.  The resulting message will end with a dot and a
2532           newline.
2533
2534           Normally, the resulting message is returned in a new mortal SV.
2535           During global destruction a single SV may be shared between uses of
2536           this function.  If "consume" is true, then the function is
2537           permitted (but not required) to modify and return "basemsg" instead
2538           of allocating a new SV.
2539
2540            SV*  mess_sv(SV* basemsg, bool consume)
2541
2542       "pv_display"
2543           Similar to
2544
2545             pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
2546
2547           except that an additional "\0" will be appended to the string when
2548           len > cur and pv[cur] is "\0".
2549
2550           Note that the final string may be up to 7 chars longer than pvlim.
2551
2552            char*  pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len,
2553                              STRLEN pvlim)
2554
2555       "pv_escape"
2556           Escapes at most the first "count" chars of "pv" and puts the
2557           results into "dsv" such that the size of the escaped string will
2558           not exceed "max" chars and will not contain any incomplete escape
2559           sequences.  The number of bytes escaped will be returned in the
2560           "STRLEN *escaped" parameter if it is not null.  When the "dsv"
2561           parameter is null no escaping actually occurs, but the number of
2562           bytes that would be escaped were it not null will be calculated.
2563
2564           If flags contains "PERL_PV_ESCAPE_QUOTE" then any double quotes in
2565           the string will also be escaped.
2566
2567           Normally the SV will be cleared before the escaped string is
2568           prepared, but when "PERL_PV_ESCAPE_NOCLEAR" is set this will not
2569           occur.
2570
2571           If "PERL_PV_ESCAPE_UNI" is set then the input string is treated as
2572           UTF-8 if "PERL_PV_ESCAPE_UNI_DETECT" is set then the input string
2573           is scanned using "is_utf8_string()" to determine if it is UTF-8.
2574
2575           If "PERL_PV_ESCAPE_ALL" is set then all input chars will be output
2576           using "\x01F1" style escapes, otherwise if
2577           "PERL_PV_ESCAPE_NONASCII" is set, only non-ASCII chars will be
2578           escaped using this style; otherwise, only chars above 255 will be
2579           so escaped; other non printable chars will use octal or common
2580           escaped patterns like "\n".  Otherwise, if
2581           "PERL_PV_ESCAPE_NOBACKSLASH" then all chars below 255 will be
2582           treated as printable and will be output as literals.
2583
2584           If "PERL_PV_ESCAPE_FIRSTCHAR" is set then only the first char of
2585           the string will be escaped, regardless of max.  If the output is to
2586           be in hex, then it will be returned as a plain hex sequence.  Thus
2587           the output will either be a single char, an octal escape sequence,
2588           a special escape like "\n" or a hex value.
2589
2590           If "PERL_PV_ESCAPE_RE" is set then the escape char used will be a
2591           "%" and not a "\\".  This is because regexes very often contain
2592           backslashed sequences, whereas "%" is not a particularly common
2593           character in patterns.
2594
2595           Returns a pointer to the escaped text as held by "dsv".
2596
2597            char*  pv_escape(SV *dsv, char const * const str,
2598                             const STRLEN count, const STRLEN max,
2599                             STRLEN * const escaped, const U32 flags)
2600
2601       "pv_pretty"
2602           Converts a string into something presentable, handling escaping via
2603           "pv_escape()" and supporting quoting and ellipses.
2604
2605           If the "PERL_PV_PRETTY_QUOTE" flag is set then the result will be
2606           double quoted with any double quotes in the string escaped.
2607           Otherwise if the "PERL_PV_PRETTY_LTGT" flag is set then the result
2608           be wrapped in angle brackets.
2609
2610           If the "PERL_PV_PRETTY_ELLIPSES" flag is set and not all characters
2611           in string were output then an ellipsis "..." will be appended to
2612           the string.  Note that this happens AFTER it has been quoted.
2613
2614           If "start_color" is non-null then it will be inserted after the
2615           opening quote (if there is one) but before the escaped text.  If
2616           "end_color" is non-null then it will be inserted after the escaped
2617           text but before any quotes or ellipses.
2618
2619           Returns a pointer to the prettified text as held by "dsv".
2620
2621            char*  pv_pretty(SV *dsv, char const * const str,
2622                             const STRLEN count, const STRLEN max,
2623                             char const * const start_color,
2624                             char const * const end_color, const U32 flags)
2625
2626       "vform"
2627           Like "form" but but the arguments are an encapsulated argument
2628           list.
2629
2630            char*  vform(const char* pat, va_list* args)
2631
2632       "vmess"
2633           "pat" and "args" are a sprintf-style format pattern and
2634           encapsulated argument list, respectively.  These are used to
2635           generate a string message.  If the message does not end with a
2636           newline, then it will be extended with some indication of the
2637           current location in the code, as described for "mess_sv".
2638
2639           Normally, the resulting message is returned in a new mortal SV.
2640           During global destruction a single SV may be shared between uses of
2641           this function.
2642
2643            SV*  vmess(const char* pat, va_list* args)
2644

Embedding and Interpreter Cloning

2646       "cv_clone"
2647           Clone a CV, making a lexical closure.  "proto" supplies the
2648           prototype of the function: its code, pad structure, and other
2649           attributes.  The prototype is combined with a capture of outer
2650           lexicals to which the code refers, which are taken from the
2651           currently-executing instance of the immediately surrounding code.
2652
2653            CV*  cv_clone(CV* proto)
2654
2655       "cv_name"
2656           Returns an SV containing the name of the CV, mainly for use in
2657           error reporting.  The CV may actually be a GV instead, in which
2658           case the returned SV holds the GV's name.  Anything other than a GV
2659           or CV is treated as a string already holding the sub name, but this
2660           could change in the future.
2661
2662           An SV may be passed as a second argument.  If so, the name will be
2663           assigned to it and it will be returned.  Otherwise the returned SV
2664           will be a new mortal.
2665
2666           If "flags" has the "CV_NAME_NOTQUAL" bit set, then the package name
2667           will not be included.  If the first argument is neither a CV nor a
2668           GV, this flag is ignored (subject to change).
2669
2670            SV *  cv_name(CV *cv, SV *sv, U32 flags)
2671
2672       "cv_undef"
2673           Clear out all the active components of a CV.  This can happen
2674           either by an explicit "undef &foo", or by the reference count going
2675           to zero.  In the former case, we keep the "CvOUTSIDE" pointer, so
2676           that any anonymous children can still follow the full lexical scope
2677           chain.
2678
2679            void  cv_undef(CV* cv)
2680
2681       "find_rundefsv"
2682           Returns the global variable $_.
2683
2684            SV*  find_rundefsv()
2685
2686       "find_rundefsvoffset"
2687           "DEPRECATED!"  It is planned to remove "find_rundefsvoffset" from a
2688           future release of Perl.  Do not use it for new code; remove it from
2689           existing code.
2690
2691           Until the lexical $_ feature was removed, this function would find
2692           the position of the lexical $_ in the pad of the currently-
2693           executing function and return the offset in the current pad, or
2694           "NOT_IN_PAD".
2695
2696           Now it always returns "NOT_IN_PAD".
2697
2698            PADOFFSET  find_rundefsvoffset()
2699
2700       "intro_my"
2701           "Introduce" "my" variables to visible status.  This is called
2702           during parsing at the end of each statement to make lexical
2703           variables visible to subsequent statements.
2704
2705            U32  intro_my()
2706
2707       "load_module"
2708           Loads the module whose name is pointed to by the string part of
2709           "name".  Note that the actual module name, not its filename, should
2710           be given.  Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver, if
2711           specified and not NULL, provides version semantics similar to "use
2712           Foo::Bar VERSION". The optional trailing arguments can be used to
2713           specify arguments to the module's "import()" method, similar to
2714           "use Foo::Bar VERSION LIST"; their precise handling depends on the
2715           flags. The flags argument is a bitwise-ORed collection of any of
2716           "PERL_LOADMOD_DENY", "PERL_LOADMOD_NOIMPORT", or
2717           "PERL_LOADMOD_IMPORT_OPS" (or 0 for no flags).
2718
2719           If "PERL_LOADMOD_NOIMPORT" is set, the module is loaded as if with
2720           an empty import list, as in "use Foo::Bar ()"; this is the only
2721           circumstance in which the trailing optional arguments may be
2722           omitted entirely. Otherwise, if "PERL_LOADMOD_IMPORT_OPS" is set,
2723           the trailing arguments must consist of exactly one "OP*",
2724           containing the op tree that produces the relevant import arguments.
2725           Otherwise, the trailing arguments must all be "SV*" values that
2726           will be used as import arguments; and the list must be terminated
2727           with "(SV*) NULL". If neither "PERL_LOADMOD_NOIMPORT" nor
2728           "PERL_LOADMOD_IMPORT_OPS" is set, the trailing "NULL" pointer is
2729           needed even if no import arguments are desired. The reference count
2730           for each specified "SV*" argument is decremented. In addition, the
2731           "name" argument is modified.
2732
2733           If "PERL_LOADMOD_DENY" is set, the module is loaded as if with "no"
2734           rather than "use".
2735
2736            void  load_module(U32 flags, SV* name, SV* ver, ...)
2737
2738       "load_module_nocontext"
2739           Like "load_module" but does not take a thread context ("aTHX")
2740           parameter, so is used in situations where the caller doesn't
2741           already have the thread context.
2742
2743            void  load_module_nocontext(U32 flags, SV* name, SV* ver, ...)
2744
2745       "my_exit"
2746           A wrapper for the C library exit(3), honoring what "PL_exit_flags"
2747           in perlapi say to do.
2748
2749            void  my_exit(U32 status)
2750
2751       "newPADNAMELIST"
2752           NOTE: "newPADNAMELIST" is experimental and may change or be removed
2753           without notice.
2754
2755           Creates a new pad name list.  "max" is the highest index for which
2756           space is allocated.
2757
2758            PADNAMELIST *  newPADNAMELIST(size_t max)
2759
2760       "newPADNAMEouter"
2761           NOTE: "newPADNAMEouter" is experimental and may change or be
2762           removed without notice.
2763
2764           Constructs and returns a new pad name.  Only use this function for
2765           names that refer to outer lexicals.  (See also "newPADNAMEpvn".)
2766           "outer" is the outer pad name that this one mirrors.  The returned
2767           pad name has the "PADNAMEt_OUTER" flag already set.
2768
2769            PADNAME *  newPADNAMEouter(PADNAME *outer)
2770
2771       "newPADNAMEpvn"
2772           NOTE: "newPADNAMEpvn" is experimental and may change or be removed
2773           without notice.
2774
2775           Constructs and returns a new pad name.  "s" must be a UTF-8 string.
2776           Do not use this for pad names that point to outer lexicals.  See
2777           "newPADNAMEouter".
2778
2779            PADNAME *  newPADNAMEpvn(const char *s, STRLEN len)
2780
2781       "nothreadhook"
2782           Stub that provides thread hook for perl_destruct when there are no
2783           threads.
2784
2785            int  nothreadhook()
2786
2787       "pad_add_anon"
2788           Allocates a place in the currently-compiling pad (via "pad_alloc")
2789           for an anonymous function that is lexically scoped inside the
2790           currently-compiling function.  The function "func" is linked into
2791           the pad, and its "CvOUTSIDE" link to the outer scope is weakened to
2792           avoid a reference loop.
2793
2794           One reference count is stolen, so you may need to do
2795           "SvREFCNT_inc(func)".
2796
2797           "optype" should be an opcode indicating the type of operation that
2798           the pad entry is to support.  This doesn't affect operational
2799           semantics, but is used for debugging.
2800
2801            PADOFFSET  pad_add_anon(CV* func, I32 optype)
2802
2803       "pad_add_name_pv"
2804           Exactly like "pad_add_name_pvn", but takes a nul-terminated string
2805           instead of a string/length pair.
2806
2807            PADOFFSET  pad_add_name_pv(const char *name, const U32 flags,
2808                                       HV *typestash, HV *ourstash)
2809
2810       "pad_add_name_pvn"
2811           Allocates a place in the currently-compiling pad for a named
2812           lexical variable.  Stores the name and other metadata in the name
2813           part of the pad, and makes preparations to manage the variable's
2814           lexical scoping.  Returns the offset of the allocated pad slot.
2815
2816           "namepv"/"namelen" specify the variable's name, including leading
2817           sigil.  If "typestash" is non-null, the name is for a typed
2818           lexical, and this identifies the type.  If "ourstash" is non-null,
2819           it's a lexical reference to a package variable, and this identifies
2820           the package.  The following flags can be OR'ed together:
2821
2822            padadd_OUR          redundantly specifies if it's a package var
2823            padadd_STATE        variable will retain value persistently
2824            padadd_NO_DUP_CHECK skip check for lexical shadowing
2825
2826            PADOFFSET  pad_add_name_pvn(const char *namepv, STRLEN namelen,
2827                                        U32 flags, HV *typestash,
2828                                        HV *ourstash)
2829
2830       "pad_add_name_sv"
2831           Exactly like "pad_add_name_pvn", but takes the name string in the
2832           form of an SV instead of a string/length pair.
2833
2834            PADOFFSET  pad_add_name_sv(SV *name, U32 flags, HV *typestash,
2835                                       HV *ourstash)
2836
2837       "pad_alloc"
2838           NOTE: "pad_alloc" is experimental and may change or be removed
2839           without notice.
2840
2841           Allocates a place in the currently-compiling pad, returning the
2842           offset of the allocated pad slot.  No name is initially attached to
2843           the pad slot.  "tmptype" is a set of flags indicating the kind of
2844           pad entry required, which will be set in the value SV for the
2845           allocated pad entry:
2846
2847               SVs_PADMY    named lexical variable ("my", "our", "state")
2848               SVs_PADTMP   unnamed temporary store
2849               SVf_READONLY constant shared between recursion levels
2850
2851           "SVf_READONLY" has been supported here only since perl 5.20.  To
2852           work with earlier versions as well, use "SVf_READONLY|SVs_PADTMP".
2853           "SVf_READONLY" does not cause the SV in the pad slot to be marked
2854           read-only, but simply tells "pad_alloc" that it will be made read-
2855           only (by the caller), or at least should be treated as such.
2856
2857           "optype" should be an opcode indicating the type of operation that
2858           the pad entry is to support.  This doesn't affect operational
2859           semantics, but is used for debugging.
2860
2861            PADOFFSET  pad_alloc(I32 optype, U32 tmptype)
2862
2863       "pad_findmy_pv"
2864           Exactly like "pad_findmy_pvn", but takes a nul-terminated string
2865           instead of a string/length pair.
2866
2867            PADOFFSET  pad_findmy_pv(const char* name, U32 flags)
2868
2869       "pad_findmy_pvn"
2870           Given the name of a lexical variable, find its position in the
2871           currently-compiling pad.  "namepv"/"namelen" specify the variable's
2872           name, including leading sigil.  "flags" is reserved and must be
2873           zero.  If it is not in the current pad but appears in the pad of
2874           any lexically enclosing scope, then a pseudo-entry for it is added
2875           in the current pad.  Returns the offset in the current pad, or
2876           "NOT_IN_PAD" if no such lexical is in scope.
2877
2878            PADOFFSET  pad_findmy_pvn(const char* namepv, STRLEN namelen,
2879                                      U32 flags)
2880
2881       "pad_findmy_sv"
2882           Exactly like "pad_findmy_pvn", but takes the name string in the
2883           form of an SV instead of a string/length pair.
2884
2885            PADOFFSET  pad_findmy_sv(SV* name, U32 flags)
2886
2887       "padnamelist_fetch"
2888           NOTE: "padnamelist_fetch" is experimental and may change or be
2889           removed without notice.
2890
2891           Fetches the pad name from the given index.
2892
2893            PADNAME *  padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
2894
2895       "padnamelist_store"
2896           NOTE: "padnamelist_store" is experimental and may change or be
2897           removed without notice.
2898
2899           Stores the pad name (which may be null) at the given index, freeing
2900           any existing pad name in that slot.
2901
2902            PADNAME **  padnamelist_store(PADNAMELIST *pnl, SSize_t key,
2903                                          PADNAME *val)
2904
2905       "pad_tidy"
2906           NOTE: "pad_tidy" is experimental and may change or be removed
2907           without notice.
2908
2909           Tidy up a pad at the end of compilation of the code to which it
2910           belongs.  Jobs performed here are: remove most stuff from the pads
2911           of anonsub prototypes; give it a @_; mark temporaries as such.
2912           "type" indicates the kind of subroutine:
2913
2914               padtidy_SUB        ordinary subroutine
2915               padtidy_SUBCLONE   prototype for lexical closure
2916               padtidy_FORMAT     format
2917
2918            void  pad_tidy(padtidy_type type)
2919
2920       "perl_alloc"
2921           Allocates a new Perl interpreter.  See perlembed.
2922
2923            PerlInterpreter*  perl_alloc()
2924
2925       "PERL_ASYNC_CHECK"
2926           Described in perlinterp.
2927
2928            void  PERL_ASYNC_CHECK()
2929
2930       "perl_clone"
2931           Create and return a new interpreter by cloning the current one.
2932
2933           "perl_clone" takes these flags as parameters:
2934
2935           "CLONEf_COPY_STACKS" - is used to, well, copy the stacks also,
2936           without it we only clone the data and zero the stacks, with it we
2937           copy the stacks and the new perl interpreter is ready to run at the
2938           exact same point as the previous one.  The pseudo-fork code uses
2939           "COPY_STACKS" while the threads->create doesn't.
2940
2941           "CLONEf_KEEP_PTR_TABLE" - "perl_clone" keeps a ptr_table with the
2942           pointer of the old variable as a key and the new variable as a
2943           value, this allows it to check if something has been cloned and not
2944           clone it again, but rather just use the value and increase the
2945           refcount.  If "KEEP_PTR_TABLE" is not set then "perl_clone" will
2946           kill the ptr_table using the function
2947           "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;".  A reason to
2948           keep it around is if you want to dup some of your own variables
2949           which are outside the graph that perl scans.
2950
2951           "CLONEf_CLONE_HOST" - This is a win32 thing, it is ignored on unix,
2952           it tells perl's win32host code (which is c++) to clone itself, this
2953           is needed on win32 if you want to run two threads at the same time,
2954           if you just want to do some stuff in a separate perl interpreter
2955           and then throw it away and return to the original one, you don't
2956           need to do anything.
2957
2958            PerlInterpreter*  perl_clone(PerlInterpreter *proto_perl,
2959                                         UV flags)
2960
2961       "perl_construct"
2962           Initializes a new Perl interpreter.  See perlembed.
2963
2964            void  perl_construct(PerlInterpreter *my_perl)
2965
2966       "perl_destruct"
2967           Shuts down a Perl interpreter.  See perlembed for a tutorial.
2968
2969           "my_perl" points to the Perl interpreter.  It must have been
2970           previously created through the use of "perl_alloc" and
2971           "perl_construct".  It may have been initialised through
2972           "perl_parse", and may have been used through "perl_run" and other
2973           means.  This function should be called for any Perl interpreter
2974           that has been constructed with "perl_construct", even if subsequent
2975           operations on it failed, for example if "perl_parse" returned a
2976           non-zero value.
2977
2978           If the interpreter's "PL_exit_flags" word has the
2979           "PERL_EXIT_DESTRUCT_END" flag set, then this function will execute
2980           code in "END" blocks before performing the rest of destruction.  If
2981           it is desired to make any use of the interpreter between
2982           "perl_parse" and "perl_destruct" other than just calling
2983           "perl_run", then this flag should be set early on.  This matters if
2984           "perl_run" will not be called, or if anything else will be done in
2985           addition to calling "perl_run".
2986
2987           Returns a value be a suitable value to pass to the C library
2988           function "exit" (or to return from "main"), to serve as an exit
2989           code indicating the nature of the way the interpreter terminated.
2990           This takes into account any failure of "perl_parse" and any early
2991           exit from "perl_run".  The exit code is of the type required by the
2992           host operating system, so because of differing exit code
2993           conventions it is not portable to interpret specific numeric values
2994           as having specific meanings.
2995
2996            int  perl_destruct(PerlInterpreter *my_perl)
2997
2998       "perl_free"
2999           Releases a Perl interpreter.  See perlembed.
3000
3001            void  perl_free(PerlInterpreter *my_perl)
3002
3003       "perl_parse"
3004           Tells a Perl interpreter to parse a Perl script.  This performs
3005           most of the initialisation of a Perl interpreter.  See perlembed
3006           for a tutorial.
3007
3008           "my_perl" points to the Perl interpreter that is to parse the
3009           script.  It must have been previously created through the use of
3010           "perl_alloc" and "perl_construct".  "xsinit" points to a callback
3011           function that will be called to set up the ability for this Perl
3012           interpreter to load XS extensions, or may be null to perform no
3013           such setup.
3014
3015           "argc" and "argv" supply a set of command-line arguments to the
3016           Perl interpreter, as would normally be passed to the "main"
3017           function of a C program.  "argv[argc]" must be null.  These
3018           arguments are where the script to parse is specified, either by
3019           naming a script file or by providing a script in a "-e" option.  If
3020           $0 will be written to in the Perl interpreter, then the argument
3021           strings must be in writable memory, and so mustn't just be string
3022           constants.
3023
3024           "env" specifies a set of environment variables that will be used by
3025           this Perl interpreter.  If non-null, it must point to a null-
3026           terminated array of environment strings.  If null, the Perl
3027           interpreter will use the environment supplied by the "environ"
3028           global variable.
3029
3030           This function initialises the interpreter, and parses and compiles
3031           the script specified by the command-line arguments.  This includes
3032           executing code in "BEGIN", "UNITCHECK", and "CHECK" blocks.  It
3033           does not execute "INIT" blocks or the main program.
3034
3035           Returns an integer of slightly tricky interpretation.  The correct
3036           use of the return value is as a truth value indicating whether
3037           there was a failure in initialisation.  If zero is returned, this
3038           indicates that initialisation was successful, and it is safe to
3039           proceed to call "perl_run" and make other use of it.  If a non-zero
3040           value is returned, this indicates some problem that means the
3041           interpreter wants to terminate.  The interpreter should not be just
3042           abandoned upon such failure; the caller should proceed to shut the
3043           interpreter down cleanly with "perl_destruct" and free it with
3044           "perl_free".
3045
3046           For historical reasons, the non-zero return value also attempts to
3047           be a suitable value to pass to the C library function "exit" (or to
3048           return from "main"), to serve as an exit code indicating the nature
3049           of the way initialisation terminated.  However, this isn't
3050           portable, due to differing exit code conventions.  A historical bug
3051           is preserved for the time being: if the Perl built-in "exit" is
3052           called during this function's execution, with a type of exit
3053           entailing a zero exit code under the host operating system's
3054           conventions, then this function returns zero rather than a non-zero
3055           value.  This bug, [perl #2754], leads to "perl_run" being called
3056           (and therefore "INIT" blocks and the main program running) despite
3057           a call to "exit".  It has been preserved because a popular module-
3058           installing module has come to rely on it and needs time to be
3059           fixed.  This issue is [perl #132577], and the original bug is due
3060           to be fixed in Perl 5.30.
3061
3062            int  perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit,
3063                            int argc, char** argv, char** env)
3064
3065       "perl_run"
3066           Tells a Perl interpreter to run its main program.  See perlembed
3067           for a tutorial.
3068
3069           "my_perl" points to the Perl interpreter.  It must have been
3070           previously created through the use of "perl_alloc" and
3071           "perl_construct", and initialised through "perl_parse".  This
3072           function should not be called if "perl_parse" returned a non-zero
3073           value, indicating a failure in initialisation or compilation.
3074
3075           This function executes code in "INIT" blocks, and then executes the
3076           main program.  The code to be executed is that established by the
3077           prior call to "perl_parse".  If the interpreter's "PL_exit_flags"
3078           word does not have the "PERL_EXIT_DESTRUCT_END" flag set, then this
3079           function will also execute code in "END" blocks.  If it is desired
3080           to make any further use of the interpreter after calling this
3081           function, then "END" blocks should be postponed to "perl_destruct"
3082           time by setting that flag.
3083
3084           Returns an integer of slightly tricky interpretation.  The correct
3085           use of the return value is as a truth value indicating whether the
3086           program terminated non-locally.  If zero is returned, this
3087           indicates that the program ran to completion, and it is safe to
3088           make other use of the interpreter (provided that the
3089           "PERL_EXIT_DESTRUCT_END" flag was set as described above).  If a
3090           non-zero value is returned, this indicates that the interpreter
3091           wants to terminate early.  The interpreter should not be just
3092           abandoned because of this desire to terminate; the caller should
3093           proceed to shut the interpreter down cleanly with "perl_destruct"
3094           and free it with "perl_free".
3095
3096           For historical reasons, the non-zero return value also attempts to
3097           be a suitable value to pass to the C library function "exit" (or to
3098           return from "main"), to serve as an exit code indicating the nature
3099           of the way the program terminated.  However, this isn't portable,
3100           due to differing exit code conventions.  An attempt is made to
3101           return an exit code of the type required by the host operating
3102           system, but because it is constrained to be non-zero, it is not
3103           necessarily possible to indicate every type of exit.  It is only
3104           reliable on Unix, where a zero exit code can be augmented with a
3105           set bit that will be ignored.  In any case, this function is not
3106           the correct place to acquire an exit code: one should get that from
3107           "perl_destruct".
3108
3109            int  perl_run(PerlInterpreter *my_perl)
3110
3111       "PERL_SYS_INIT"
3112           Provides system-specific tune up of the C runtime environment
3113           necessary to run Perl interpreters.  This should be called only
3114           once, before creating any Perl interpreters.
3115
3116            void  PERL_SYS_INIT(int *argc, char*** argv)
3117
3118       "PERL_SYS_INIT3"
3119           Provides system-specific tune up of the C runtime environment
3120           necessary to run Perl interpreters.  This should be called only
3121           once, before creating any Perl interpreters.
3122
3123            void  PERL_SYS_INIT3(int *argc, char*** argv, char*** env)
3124
3125       "PERL_SYS_TERM"
3126           Provides system-specific clean up of the C runtime environment
3127           after running Perl interpreters.  This should be called only once,
3128           after freeing any remaining Perl interpreters.
3129
3130            void  PERL_SYS_TERM()
3131
3132       "PL_exit_flags"
3133           Contains flags controlling perl's behaviour on exit():
3134
3135           •   "PERL_EXIT_DESTRUCT_END"
3136
3137               If set, END blocks are executed when the interpreter is
3138               destroyed.  This is normally set by perl itself after the
3139               interpreter is constructed.
3140
3141           •   "PERL_EXIT_ABORT"
3142
3143               Call "abort()" on exit.  This is used internally by perl itself
3144               to abort if exit is called while processing exit.
3145
3146           •   "PERL_EXIT_WARN"
3147
3148               Warn on exit.
3149
3150           •   "PERL_EXIT_EXPECTED"
3151
3152               Set by the "exit" in perlfunc operator.
3153
3154            U8  PL_exit_flags
3155
3156       "PL_perl_destruct_level"
3157           This value may be set when embedding for full cleanup.
3158
3159           Possible values:
3160
3161           •   0 - none
3162
3163           •   1 - full
3164
3165           •   2 or greater - full with checks.
3166
3167           If $ENV{PERL_DESTRUCT_LEVEL} is set to an integer greater than the
3168           value of "PL_perl_destruct_level" its value is used instead.
3169
3170           On threaded perls, each thread has an independent copy of this
3171           variable; each initialized at creation time with the current value
3172           of the creating thread's copy.
3173
3174            signed char  PL_perl_destruct_level
3175
3176       "require_pv"
3177           Tells Perl to "require" the file named by the string argument.  It
3178           is analogous to the Perl code "eval "require '$file'"".  It's even
3179           implemented that way; consider using load_module instead.
3180
3181           NOTE: the "perl_require_pv()" form is deprecated.
3182
3183            void  require_pv(const char* pv)
3184
3185       "UVf"
3186           "DEPRECATED!"  It is planned to remove "UVf" from a future release
3187           of Perl.  Do not use it for new code; remove it from existing code.
3188
3189           Obsolete form of "UVuf", which you should convert to instead use
3190
3191            const char *  UVf
3192
3193       "vload_module"
3194           Like "load_module" but the arguments are an encapsulated argument
3195           list.
3196
3197            void  vload_module(U32 flags, SV* name, SV* ver, va_list* args)
3198

Errno

3200       "sv_string_from_errnum"
3201           Generates the message string describing an OS error and returns it
3202           as an SV.  "errnum" must be a value that "errno" could take,
3203           identifying the type of error.
3204
3205           If "tgtsv" is non-null then the string will be written into that SV
3206           (overwriting existing content) and it will be returned.  If "tgtsv"
3207           is a null pointer then the string will be written into a new mortal
3208           SV which will be returned.
3209
3210           The message will be taken from whatever locale would be used by $!,
3211           and will be encoded in the SV in whatever manner would be used by
3212           $!.  The details of this process are subject to future change.
3213           Currently, the message is taken from the C locale by default
3214           (usually producing an English message), and from the currently
3215           selected locale when in the scope of the "use locale" pragma.  A
3216           heuristic attempt is made to decode the message from the locale's
3217           character encoding, but it will only be decoded as either UTF-8 or
3218           ISO-8859-1.  It is always correctly decoded in a UTF-8 locale,
3219           usually in an ISO-8859-1 locale, and never in any other locale.
3220
3221           The SV is always returned containing an actual string, and with no
3222           other OK bits set.  Unlike $!, a message is even yielded for
3223           "errnum" zero (meaning success), and if no useful message is
3224           available then a useless string (currently empty) is returned.
3225
3226            SV*  sv_string_from_errnum(int errnum, SV* tgtsv)
3227

Exception Handling (simple) Macros

3229       "dXCPT"
3230           Set up necessary local variables for exception handling.  See
3231           "Exception Handling" in perlguts.
3232
3233              dXCPT;
3234
3235       "JMPENV_JUMP"
3236           Described in perlinterp.
3237
3238            void  JMPENV_JUMP(int v)
3239
3240       "JMPENV_PUSH"
3241           Described in perlinterp.
3242
3243            void  JMPENV_PUSH(int v)
3244
3245       "PL_restartop"
3246           Described in perlinterp.
3247
3248       "XCPT_CATCH"
3249           Introduces a catch block.  See "Exception Handling" in perlguts.
3250
3251       "XCPT_RETHROW"
3252           Rethrows a previously caught exception.  See "Exception Handling"
3253           in perlguts.
3254
3255              XCPT_RETHROW;
3256
3257       "XCPT_TRY_END"
3258           Ends a try block.  See "Exception Handling" in perlguts.
3259
3260       "XCPT_TRY_START"
3261           Starts a try block.  See "Exception Handling" in perlguts.
3262

Filesystem configuration values

3264       Also see "List of capability HAS_foo symbols".
3265
3266       "DIRNAMLEN"
3267           This symbol, if defined, indicates to the C program that the length
3268           of directory entry names is provided by a "d_namlen" field.
3269           Otherwise you need to do "strlen()" on the "d_name" field.
3270
3271       "DOSUID"
3272           This symbol, if defined, indicates that the C program should check
3273           the script that it is executing for setuid/setgid bits, and attempt
3274           to emulate setuid/setgid on systems that have disabled setuid #!
3275           scripts because the kernel can't do it securely.  It is up to the
3276           package designer to make sure that this emulation is done securely.
3277           Among other things, it should do an fstat on the script it just
3278           opened to make sure it really is a setuid/setgid script, it should
3279           make sure the arguments passed correspond exactly to the argument
3280           on the #! line, and it should not trust any subprocesses to which
3281           it must pass the filename rather than the file descriptor of the
3282           script to be executed.
3283
3284       "EOF_NONBLOCK"
3285           This symbol, if defined, indicates to the C program that a "read()"
3286           on a non-blocking file descriptor will return 0 on "EOF", and not
3287           the value held in "RD_NODATA" (-1 usually, in that case!).
3288
3289       "FCNTL_CAN_LOCK"
3290           This symbol, if defined, indicates that "fcntl()" can be used for
3291           file locking.  Normally on Unix systems this is defined.  It may be
3292           undefined on "VMS".
3293
3294       "FFLUSH_ALL"
3295           This symbol, if defined, tells that to flush all pending stdio
3296           output one must loop through all the stdio file handles stored in
3297           an array and fflush them.  Note that if "fflushNULL" is defined,
3298           fflushall will not even be probed for and will be left undefined.
3299
3300       "FFLUSH_NULL"
3301           This symbol, if defined, tells that "fflush(NULL)" correctly
3302           flushes all pending stdio output without side effects. In
3303           particular, on some platforms calling "fflush(NULL)" *still*
3304           corrupts "STDIN" if it is a pipe.
3305
3306       "FILE_base"
3307           This macro is used to access the "_base" field (or equivalent) of
3308           the "FILE" structure pointed to by its argument. This macro will
3309           always be defined if "USE_STDIO_BASE" is defined.
3310
3311            void *  FILE_base(FILE * f)
3312
3313       "FILE_bufsiz"
3314           This macro is used to determine the number of bytes in the I/O
3315           buffer pointed to by "_base" field (or equivalent) of the "FILE"
3316           structure pointed to its argument. This macro will always be
3317           defined if "USE_STDIO_BASE" is defined.
3318
3319            Size_t  FILE_bufsiz(FILE *f)
3320
3321       "FILE_cnt"
3322           This macro is used to access the "_cnt" field (or equivalent) of
3323           the "FILE" structure pointed to by its argument. This macro will
3324           always be defined if "USE_STDIO_PTR" is defined.
3325
3326            Size_t  FILE_cnt(FILE * f)
3327
3328       "FILE_ptr"
3329           This macro is used to access the "_ptr" field (or equivalent) of
3330           the "FILE" structure pointed to by its argument. This macro will
3331           always be defined if "USE_STDIO_PTR" is defined.
3332
3333            void *  FILE_ptr(FILE * f)
3334
3335       "FLEXFILENAMES"
3336           This symbol, if defined, indicates that the system supports
3337           filenames longer than 14 characters.
3338
3339       "HAS_DIR_DD_FD"
3340           This symbol, if defined, indicates that the the "DIR"* dirstream
3341           structure contains a member variable named "dd_fd".
3342
3343       "HAS_DUP2"
3344           This symbol, if defined, indicates that the "dup2" routine is
3345           available to duplicate file descriptors.
3346
3347       "HAS_DUP3"
3348           This symbol, if defined, indicates that the "dup3" routine is
3349           available to duplicate file descriptors.
3350
3351       "HAS_FAST_STDIO"
3352           This symbol, if defined, indicates that the "fast stdio" is
3353           available to manipulate the stdio buffers directly.
3354
3355       "HAS_FCHDIR"
3356           This symbol, if defined, indicates that the "fchdir" routine is
3357           available to change directory using a file descriptor.
3358
3359       "HAS_FCNTL"
3360           This symbol, if defined, indicates to the C program that the
3361           "fcntl()" function exists.
3362
3363       "HAS_FDCLOSE"
3364           This symbol, if defined, indicates that the "fdclose" routine is
3365           available to free a "FILE" structure without closing the underlying
3366           file descriptor.  This function appeared in "FreeBSD" 10.2.
3367
3368       "HAS_FPATHCONF"
3369           This symbol, if defined, indicates that "pathconf()" is available
3370           to determine file-system related limits and options associated with
3371           a given open file descriptor.
3372
3373       "HAS_FPOS64_T"
3374           This symbol will be defined if the C compiler supports "fpos64_t".
3375
3376       "HAS_FSTATFS"
3377           This symbol, if defined, indicates that the "fstatfs" routine is
3378           available to stat filesystems by file descriptors.
3379
3380       "HAS_FSTATVFS"
3381           This symbol, if defined, indicates that the "fstatvfs" routine is
3382           available to stat filesystems by file descriptors.
3383
3384       "HAS_GETFSSTAT"
3385           This symbol, if defined, indicates that the "getfsstat" routine is
3386           available to stat filesystems in bulk.
3387
3388       "HAS_GETMNT"
3389           This symbol, if defined, indicates that the "getmnt" routine is
3390           available to get filesystem mount info by filename.
3391
3392       "HAS_GETMNTENT"
3393           This symbol, if defined, indicates that the "getmntent" routine is
3394           available to iterate through mounted file systems to get their
3395           info.
3396
3397       "HAS_HASMNTOPT"
3398           This symbol, if defined, indicates that the "hasmntopt" routine is
3399           available to query the mount options of file systems.
3400
3401       "HAS_LSEEK_PROTO"
3402           This symbol, if defined, indicates that the system provides a
3403           prototype for the "lseek()" function.  Otherwise, it is up to the
3404           program to supply one.  A good guess is
3405
3406            extern off_t lseek(int, off_t, int);
3407
3408       "HAS_MKDIR"
3409           This symbol, if defined, indicates that the "mkdir" routine is
3410           available to create directories.  Otherwise you should fork off a
3411           new process to exec /bin/mkdir.
3412
3413       "HAS_OFF64_T"
3414           This symbol will be defined if the C compiler supports "off64_t".
3415
3416       "HAS_OPEN3"
3417           This manifest constant lets the C program know that the three
3418           argument form of open(2) is available.
3419
3420       "HAS_OPENAT"
3421           This symbol is defined if the "openat()" routine is available.
3422
3423       "HAS_POLL"
3424           This symbol, if defined, indicates that the "poll" routine is
3425           available to "poll" active file descriptors.  Please check "I_POLL"
3426           and "I_SYS_POLL" to know which header should be included as well.
3427
3428       "HAS_READDIR"
3429           This symbol, if defined, indicates that the "readdir" routine is
3430           available to read directory entries. You may have to include
3431           dirent.h. See "I_DIRENT".
3432
3433       "HAS_READDIR64_R"
3434           This symbol, if defined, indicates that the "readdir64_r" routine
3435           is available to readdir64 re-entrantly.
3436
3437       "HAS_REWINDDIR"
3438           This symbol, if defined, indicates that the "rewinddir" routine is
3439           available. You may have to include dirent.h. See "I_DIRENT".
3440
3441       "HAS_RMDIR"
3442           This symbol, if defined, indicates that the "rmdir" routine is
3443           available to remove directories. Otherwise you should fork off a
3444           new process to exec /bin/rmdir.
3445
3446       "HAS_SEEKDIR"
3447           This symbol, if defined, indicates that the "seekdir" routine is
3448           available. You may have to include dirent.h. See "I_DIRENT".
3449
3450       "HAS_SELECT"
3451           This symbol, if defined, indicates that the "select" routine is
3452           available to "select" active file descriptors. If the timeout field
3453           is used, sys/time.h may need to be included.
3454
3455       "HAS_SETVBUF"
3456           This symbol, if defined, indicates that the "setvbuf" routine is
3457           available to change buffering on an open stdio stream.  to a line-
3458           buffered mode.
3459
3460       "HAS_STDIO_STREAM_ARRAY"
3461           This symbol, if defined, tells that there is an array holding the
3462           stdio streams.
3463
3464       "HAS_STRUCT_FS_DATA"
3465           This symbol, if defined, indicates that the "struct fs_data" to do
3466           "statfs()" is supported.
3467
3468       "HAS_STRUCT_STATFS"
3469           This symbol, if defined, indicates that the "struct statfs" to do
3470           "statfs()" is supported.
3471
3472       "HAS_STRUCT_STATFS_F_FLAGS"
3473           This symbol, if defined, indicates that the "struct statfs" does
3474           have the "f_flags" member containing the mount flags of the
3475           filesystem containing the file.  This kind of "struct statfs" is
3476           coming from sys/mount.h ("BSD" 4.3), not from sys/statfs.h
3477           ("SYSV").  Older "BSDs" (like Ultrix) do not have "statfs()" and
3478           "struct statfs", they have "ustat()" and "getmnt()" with "struct
3479           ustat" and "struct fs_data".
3480
3481       "HAS_TELLDIR"
3482           This symbol, if defined, indicates that the "telldir" routine is
3483           available. You may have to include dirent.h. See "I_DIRENT".
3484
3485       "HAS_USTAT"
3486           This symbol, if defined, indicates that the "ustat" system call is
3487           available to query file system statistics by "dev_t".
3488
3489       "I_FCNTL"
3490           This manifest constant tells the C program to include fcntl.h.
3491
3492            #ifdef I_FCNTL
3493                #include <fcntl.h>
3494            #endif
3495
3496       "I_SYS_DIR"
3497           This symbol, if defined, indicates to the C program that it should
3498           include sys/dir.h.
3499
3500            #ifdef I_SYS_DIR
3501                #include <sys_dir.h>
3502            #endif
3503
3504       "I_SYS_FILE"
3505           This symbol, if defined, indicates to the C program that it should
3506           include sys/file.h to get definition of "R_OK" and friends.
3507
3508            #ifdef I_SYS_FILE
3509                #include <sys_file.h>
3510            #endif
3511
3512       "I_SYS_NDIR"
3513           This symbol, if defined, indicates to the C program that it should
3514           include sys/ndir.h.
3515
3516            #ifdef I_SYS_NDIR
3517                #include <sys_ndir.h>
3518            #endif
3519
3520       "I_SYS_STATFS"
3521           This symbol, if defined, indicates that sys/statfs.h exists.
3522
3523            #ifdef I_SYS_STATFS
3524                #include <sys_statfs.h>
3525            #endif
3526
3527       "LSEEKSIZE"
3528           This symbol holds the number of bytes used by the "Off_t".
3529
3530       "RD_NODATA"
3531           This symbol holds the return code from "read()" when no data is
3532           present on the non-blocking file descriptor. Be careful! If
3533           "EOF_NONBLOCK" is not defined, then you can't distinguish between
3534           no data and "EOF" by issuing a "read()". You'll have to find
3535           another way to tell for sure!
3536
3537       "READDIR64_R_PROTO"
3538           This symbol encodes the prototype of "readdir64_r".  It is zero if
3539           "d_readdir64_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
3540           macros of reentr.h if "d_readdir64_r" is defined.
3541
3542       "STDCHAR"
3543           This symbol is defined to be the type of char used in stdio.h.  It
3544           has the values "unsigned char" or "char".
3545
3546       "STDIO_CNT_LVALUE"
3547           This symbol is defined if the "FILE_cnt" macro can be used as an
3548           lvalue.
3549
3550       "STDIO_PTR_LVALUE"
3551           This symbol is defined if the "FILE_ptr" macro can be used as an
3552           lvalue.
3553
3554       "STDIO_PTR_LVAL_NOCHANGE_CNT"
3555           This symbol is defined if using the "FILE_ptr" macro as an lvalue
3556           to increase the pointer by n leaves "File_cnt(fp)" unchanged.
3557
3558       "STDIO_PTR_LVAL_SETS_CNT"
3559           This symbol is defined if using the "FILE_ptr" macro as an lvalue
3560           to increase the pointer by n has the side effect of decreasing the
3561           value of "File_cnt(fp)" by n.
3562
3563       "STDIO_STREAM_ARRAY"
3564           This symbol tells the name of the array holding the stdio streams.
3565           Usual values include "_iob", "__iob", and "__sF".
3566
3567       "ST_INO_SIGN"
3568           This symbol holds the signedness of "struct stat"'s "st_ino".  1
3569           for unsigned, -1 for signed.
3570
3571       "ST_INO_SIZE"
3572           This variable contains the size of "struct stat"'s "st_ino" in
3573           bytes.
3574
3575       "VAL_EAGAIN"
3576           This symbol holds the errno error code set by "read()" when no data
3577           was present on the non-blocking file descriptor.
3578
3579       "VAL_O_NONBLOCK"
3580           This symbol is to be used during "open()" or "fcntl(F_SETFL)" to
3581           turn on non-blocking I/O for the file descriptor. Note that there
3582           is no way back, i.e. you cannot turn it blocking again this way. If
3583           you wish to alternatively switch between blocking and non-blocking,
3584           use the "ioctl(FIOSNBIO)" call instead, but that is not supported
3585           by all devices.
3586
3587       "VOID_CLOSEDIR"
3588           This symbol, if defined, indicates that the "closedir()" routine
3589           does not return a value.
3590

Floating point configuration values

3592       Also "List of capability HAS_foo symbols" lists capabilities that arent
3593       in this section.  For example "HAS_ASINH", for the hyperbolic sine
3594       function.
3595
3596       "CASTFLAGS"
3597           This symbol contains flags that say what difficulties the compiler
3598           has casting odd floating values to unsigned long:
3599
3600            0 = ok
3601            1 = couldn't cast < 0
3602            2 = couldn't cast >= 0x80000000
3603            4 = couldn't cast in argument expression list
3604
3605       "CASTNEGFLOAT"
3606           This symbol is defined if the C compiler can cast negative numbers
3607           to unsigned longs, ints and shorts.
3608
3609       "DOUBLE_HAS_INF"
3610           This symbol, if defined, indicates that the double has the
3611           infinity.
3612
3613       "DOUBLE_HAS_NAN"
3614           This symbol, if defined, indicates that the double has the not-a-
3615           number.
3616
3617       "DOUBLE_HAS_NEGATIVE_ZERO"
3618           This symbol, if defined, indicates that the double has the
3619           "negative_zero".
3620
3621       "DOUBLE_HAS_SUBNORMALS"
3622           This symbol, if defined, indicates that the double has the
3623           subnormals (denormals).
3624
3625       "DOUBLEINFBYTES"
3626           This symbol, if defined, is a comma-separated list of hexadecimal
3627           bytes for the double precision infinity.
3628
3629       "DOUBLEKIND"
3630           "DOUBLEKIND" will be one of
3631           "DOUBLE_IS_IEEE_754_32_BIT_LITTLE_ENDIAN"
3632           "DOUBLE_IS_IEEE_754_32_BIT_BIG_ENDIAN"
3633           "DOUBLE_IS_IEEE_754_64_BIT_LITTLE_ENDIAN"
3634           "DOUBLE_IS_IEEE_754_64_BIT_BIG_ENDIAN"
3635           "DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN"
3636           "DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN"
3637           "DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_LE_BE"
3638           "DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_BE_LE"
3639           "DOUBLE_IS_VAX_F_FLOAT" "DOUBLE_IS_VAX_D_FLOAT"
3640           "DOUBLE_IS_VAX_G_FLOAT" "DOUBLE_IS_IBM_SINGLE_32_BIT"
3641           "DOUBLE_IS_IBM_DOUBLE_64_BIT" "DOUBLE_IS_CRAY_SINGLE_64_BIT"
3642           "DOUBLE_IS_UNKNOWN_FORMAT"
3643
3644       "DOUBLEMANTBITS"
3645           This symbol, if defined, tells how many mantissa bits there are in
3646           double precision floating point format.  Note that this is usually
3647           "DBL_MANT_DIG" minus one, since with the standard "IEEE" 754
3648           formats "DBL_MANT_DIG" includes the implicit bit, which doesn't
3649           really exist.
3650
3651       "DOUBLENANBYTES"
3652           This symbol, if defined, is a comma-separated list of hexadecimal
3653           bytes (0xHH) for the double precision not-a-number.
3654
3655       "DOUBLESIZE"
3656           This symbol contains the size of a double, so that the C
3657           preprocessor can make decisions based on it.
3658
3659       "DOUBLE_STYLE_CRAY"
3660           This symbol, if defined, indicates that the double is the 64-bit
3661           "CRAY" mainframe format.
3662
3663       "DOUBLE_STYLE_IBM"
3664           This symbol, if defined, indicates that the double is the 64-bit
3665           "IBM" mainframe format.
3666
3667       "DOUBLE_STYLE_IEEE"
3668           This symbol, if defined, indicates that the double is the 64-bit
3669           "IEEE" 754.
3670
3671       "DOUBLE_STYLE_VAX"
3672           This symbol, if defined, indicates that the double is the 64-bit
3673           "VAX" format D or G.
3674
3675       "HAS_ATOLF"
3676           This symbol, if defined, indicates that the "atolf" routine is
3677           available to convert strings into long doubles.
3678
3679       "HAS_CLASS"
3680           This symbol, if defined, indicates that the "class" routine is
3681           available to classify doubles.  Available for example in "AIX".
3682           The returned values are defined in float.h and are:
3683
3684            FP_PLUS_NORM    Positive normalized, nonzero
3685            FP_MINUS_NORM   Negative normalized, nonzero
3686            FP_PLUS_DENORM  Positive denormalized, nonzero
3687            FP_MINUS_DENORM Negative denormalized, nonzero
3688            FP_PLUS_ZERO    +0.0
3689            FP_MINUS_ZERO   -0.0
3690            FP_PLUS_INF     +INF
3691            FP_MINUS_INF    -INF
3692            FP_NANS         Signaling Not a Number (NaNS)
3693            FP_NANQ         Quiet Not a Number (NaNQ)
3694
3695       "HAS_FINITE"
3696           This symbol, if defined, indicates that the "finite" routine is
3697           available to check whether a double is "finite" (non-infinity non-
3698           NaN).
3699
3700       "HAS_FINITEL"
3701           This symbol, if defined, indicates that the "finitel" routine is
3702           available to check whether a long double is finite (non-infinity
3703           non-NaN).
3704
3705       "HAS_FPCLASS"
3706           This symbol, if defined, indicates that the "fpclass" routine is
3707           available to classify doubles.  Available for example in
3708           Solaris/"SVR4".  The returned values are defined in ieeefp.h and
3709           are:
3710
3711            FP_SNAN         signaling NaN
3712            FP_QNAN         quiet NaN
3713            FP_NINF         negative infinity
3714            FP_PINF         positive infinity
3715            FP_NDENORM      negative denormalized non-zero
3716            FP_PDENORM      positive denormalized non-zero
3717            FP_NZERO        negative zero
3718            FP_PZERO        positive zero
3719            FP_NNORM        negative normalized non-zero
3720            FP_PNORM        positive normalized non-zero
3721
3722       "HAS_FPCLASSIFY"
3723           This symbol, if defined, indicates that the "fpclassify" routine is
3724           available to classify doubles.  Available for example in HP-UX.
3725           The returned values are defined in math.h and are
3726
3727            FP_NORMAL     Normalized
3728            FP_ZERO       Zero
3729            FP_INFINITE   Infinity
3730            FP_SUBNORMAL  Denormalized
3731            FP_NAN        NaN
3732
3733       "HAS_FPCLASSL"
3734           This symbol, if defined, indicates that the "fpclassl" routine is
3735           available to classify long doubles.  Available for example in
3736           "IRIX".  The returned values are defined in ieeefp.h and are:
3737
3738            FP_SNAN         signaling NaN
3739            FP_QNAN         quiet NaN
3740            FP_NINF         negative infinity
3741            FP_PINF         positive infinity
3742            FP_NDENORM      negative denormalized non-zero
3743            FP_PDENORM      positive denormalized non-zero
3744            FP_NZERO        negative zero
3745            FP_PZERO        positive zero
3746            FP_NNORM        negative normalized non-zero
3747            FP_PNORM        positive normalized non-zero
3748
3749       "HAS_FPGETROUND"
3750           This symbol, if defined, indicates that the "fpgetround" routine is
3751           available to get the floating point rounding mode.
3752
3753       "HAS_FP_CLASS"
3754           This symbol, if defined, indicates that the "fp_class" routine is
3755           available to classify doubles.  Available for example in Digital
3756           "UNIX".  The returned values are defined in math.h and are:
3757
3758            FP_SNAN           Signaling NaN (Not-a-Number)
3759            FP_QNAN           Quiet NaN (Not-a-Number)
3760            FP_POS_INF        +infinity
3761            FP_NEG_INF        -infinity
3762            FP_POS_NORM       Positive normalized
3763            FP_NEG_NORM       Negative normalized
3764            FP_POS_DENORM     Positive denormalized
3765            FP_NEG_DENORM     Negative denormalized
3766            FP_POS_ZERO       +0.0 (positive zero)
3767            FP_NEG_ZERO       -0.0 (negative zero)
3768
3769       "HAS_FP_CLASSIFY"
3770           This symbol, if defined, indicates that the "fp_classify" routine
3771           is available to classify doubles. The values are defined in math.h
3772
3773            FP_NORMAL     Normalized
3774            FP_ZERO       Zero
3775            FP_INFINITE   Infinity
3776            FP_SUBNORMAL  Denormalized
3777            FP_NAN        NaN
3778
3779       "HAS_FP_CLASSL"
3780           This symbol, if defined, indicates that the "fp_classl" routine is
3781           available to classify long doubles.  Available for example in
3782           Digital "UNIX".  See for possible values "HAS_FP_CLASS".
3783
3784       "HAS_FREXPL"
3785           This symbol, if defined, indicates that the "frexpl" routine is
3786           available to break a long double floating-point number into a
3787           normalized fraction and an integral power of 2.
3788
3789       "HAS_ILOGB"
3790           This symbol, if defined, indicates that the "ilogb" routine is
3791           available to get integer exponent of a floating-point value.
3792
3793       "HAS_ISFINITE"
3794           This symbol, if defined, indicates that the "isfinite" routine is
3795           available to check whether a double is finite (non-infinity non-
3796           NaN).
3797
3798       "HAS_ISFINITEL"
3799           This symbol, if defined, indicates that the "isfinitel" routine is
3800           available to check whether a long double is finite.  (non-infinity
3801           non-NaN).
3802
3803       "HAS_ISINF"
3804           This symbol, if defined, indicates that the "isinf" routine is
3805           available to check whether a double is an infinity.
3806
3807       "HAS_ISINFL"
3808           This symbol, if defined, indicates that the "isinfl" routine is
3809           available to check whether a long double is an infinity.
3810
3811       "HAS_ISNAN"
3812           This symbol, if defined, indicates that the "isnan" routine is
3813           available to check whether a double is a NaN.
3814
3815       "HAS_ISNANL"
3816           This symbol, if defined, indicates that the "isnanl" routine is
3817           available to check whether a long double is a NaN.
3818
3819       "HAS_ISNORMAL"
3820           This symbol, if defined, indicates that the "isnormal" routine is
3821           available to check whether a double is normal (non-zero
3822           normalized).
3823
3824       "HAS_J0"
3825           This symbol, if defined, indicates to the C program that the "j0()"
3826           function is available for Bessel functions of the first kind of the
3827           order zero, for doubles.
3828
3829       "HAS_J0L"
3830           This symbol, if defined, indicates to the C program that the
3831           "j0l()" function is available for Bessel functions of the first
3832           kind of the order zero, for long doubles.
3833
3834       "HAS_LDBL_DIG"
3835           This symbol, if defined, indicates that this system's float.h or
3836           limits.h defines the symbol "LDBL_DIG", which is the number of
3837           significant digits in a long double precision number. Unlike for
3838           "DBL_DIG", there's no good guess for "LDBL_DIG" if it is undefined.
3839
3840       "HAS_LDEXPL"
3841           This symbol, if defined, indicates that the "ldexpl" routine is
3842           available to shift a long double floating-point number by an
3843           integral power of 2.
3844
3845       "HAS_LLRINT"
3846           This symbol, if defined, indicates that the "llrint" routine is
3847           available to return the long long value closest to a double
3848           (according to the current rounding mode).
3849
3850       "HAS_LLRINTL"
3851           This symbol, if defined, indicates that the "llrintl" routine is
3852           available to return the long long value closest to a long double
3853           (according to the current rounding mode).
3854
3855       "HAS_LLROUNDL"
3856           This symbol, if defined, indicates that the "llroundl" routine is
3857           available to return the nearest long long value away from zero of
3858           the long double argument value.
3859
3860       "HAS_LONG_DOUBLE"
3861           This symbol will be defined if the C compiler supports long
3862           doubles.
3863
3864       "HAS_LRINT"
3865           This symbol, if defined, indicates that the "lrint" routine is
3866           available to return the integral value closest to a double
3867           (according to the current rounding mode).
3868
3869       "HAS_LRINTL"
3870           This symbol, if defined, indicates that the "lrintl" routine is
3871           available to return the integral value closest to a long double
3872           (according to the current rounding mode).
3873
3874       "HAS_LROUNDL"
3875           This symbol, if defined, indicates that the "lroundl" routine is
3876           available to return the nearest integral value away from zero of
3877           the long double argument value.
3878
3879       "HAS_MODFL"
3880           This symbol, if defined, indicates that the "modfl" routine is
3881           available to split a long double x into a fractional part f and an
3882           integer part i such that |f| < 1.0 and (f + i) = x.
3883
3884       "HAS_NAN"
3885           This symbol, if defined, indicates that the "nan" routine is
3886           available to generate NaN.
3887
3888       "HAS_NEXTTOWARD"
3889           This symbol, if defined, indicates that the "nexttoward" routine is
3890           available to return the next machine representable long double from
3891           x in direction y.
3892
3893       "HAS_REMAINDER"
3894           This symbol, if defined, indicates that the "remainder" routine is
3895           available to return the floating-point "remainder".
3896
3897       "HAS_SCALBN"
3898           This symbol, if defined, indicates that the "scalbn" routine is
3899           available to multiply floating-point number by integral power of
3900           radix.
3901
3902       "HAS_SIGNBIT"
3903           This symbol, if defined, indicates that the "signbit" routine is
3904           available to check if the given number has the sign bit set.  This
3905           should include correct testing of -0.0.  This will only be set if
3906           the "signbit()" routine is safe to use with the NV type used
3907           internally in perl.  Users should call "Perl_signbit()", which will
3908           be #defined to the system's "signbit()" function or macro if this
3909           symbol is defined.
3910
3911       "HAS_SQRTL"
3912           This symbol, if defined, indicates that the "sqrtl" routine is
3913           available to do long double square roots.
3914
3915       "HAS_STRTOD_L"
3916           This symbol, if defined, indicates that the "strtod_l" routine is
3917           available to convert strings to long doubles.
3918
3919       "HAS_STRTOLD"
3920           This symbol, if defined, indicates that the "strtold" routine is
3921           available to convert strings to long doubles.
3922
3923       "HAS_STRTOLD_L"
3924           This symbol, if defined, indicates that the "strtold_l" routine is
3925           available to convert strings to long doubles.
3926
3927       "HAS_TRUNC"
3928           This symbol, if defined, indicates that the "trunc" routine is
3929           available to round doubles towards zero.
3930
3931       "HAS_UNORDERED"
3932           This symbol, if defined, indicates that the "unordered" routine is
3933           available to check whether two doubles are "unordered"
3934           (effectively: whether either of them is NaN)
3935
3936       "I_FENV"
3937           This symbol, if defined, indicates to the C program that it should
3938           include fenv.h to get the floating point environment definitions.
3939
3940            #ifdef I_FENV
3941                #include <fenv.h>
3942            #endif
3943
3944       "I_QUADMATH"
3945           This symbol, if defined, indicates that quadmath.h exists and
3946           should be included.
3947
3948            #ifdef I_QUADMATH
3949                #include <quadmath.h>
3950            #endif
3951
3952       "LONGDBLINFBYTES"
3953           This symbol, if defined, is a comma-separated list of hexadecimal
3954           bytes for the long double precision infinity.
3955
3956       "LONGDBLMANTBITS"
3957           This symbol, if defined, tells how many mantissa bits there are in
3958           long double precision floating point format.  Note that this can be
3959           "LDBL_MANT_DIG" minus one, since "LDBL_MANT_DIG" can include the
3960           "IEEE" 754 implicit bit.  The common x86-style 80-bit long double
3961           does not have an implicit bit.
3962
3963       "LONGDBLNANBYTES"
3964           This symbol, if defined, is a comma-separated list of hexadecimal
3965           bytes (0xHH) for the long double precision not-a-number.
3966
3967       "LONG_DOUBLEKIND"
3968           "LONG_DOUBLEKIND" will be one of "LONG_DOUBLE_IS_DOUBLE"
3969           "LONG_DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN"
3970           "LONG_DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN"
3971           "LONG_DOUBLE_IS_X86_80_BIT_LITTLE_ENDIAN"
3972           "LONG_DOUBLE_IS_X86_80_BIT_BIG_ENDIAN"
3973           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_LE"
3974           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_BE"
3975           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_BE"
3976           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_LE"
3977           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LITTLE_ENDIAN"
3978           "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BIG_ENDIAN"
3979           "LONG_DOUBLE_IS_VAX_H_FLOAT" "LONG_DOUBLE_IS_UNKNOWN_FORMAT" It is
3980           only defined if the system supports long doubles.
3981
3982       "LONG_DOUBLESIZE"
3983           This symbol contains the size of a long double, so that the C
3984           preprocessor can make decisions based on it.  It is only defined if
3985           the system supports long doubles.  Note that this is "sizeof(long
3986           double)", which may include unused bytes.
3987
3988       "LONG_DOUBLE_STYLE_IEEE"
3989           This symbol, if defined, indicates that the long double is any of
3990           the "IEEE" 754 style long doubles: "LONG_DOUBLE_STYLE_IEEE_STD",
3991           "LONG_DOUBLE_STYLE_IEEE_EXTENDED",
3992           "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE".
3993
3994       "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
3995           This symbol, if defined, indicates that the long double is the
3996           128-bit double-double.
3997
3998       "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
3999           This symbol, if defined, indicates that the long double is the
4000           80-bit "IEEE" 754. Note that despite the 'extended' this is less
4001           than the 'std', since this is an extension of the double precision.
4002
4003       "LONG_DOUBLE_STYLE_IEEE_STD"
4004           This symbol, if defined, indicates that the long double is the
4005           128-bit "IEEE" 754.
4006
4007       "LONG_DOUBLE_STYLE_VAX"
4008           This symbol, if defined, indicates that the long double is the
4009           128-bit "VAX" format H.
4010
4011       "NVMANTBITS"
4012           This symbol, if defined, tells how many mantissa bits (not
4013           including implicit bit) there are in a Perl NV.  This depends on
4014           which floating point type was chosen.
4015
4016       "NV_OVERFLOWS_INTEGERS_AT"
4017           This symbol gives the largest integer value that NVs can hold. This
4018           value + 1.0 cannot be stored accurately. It is expressed as
4019           constant floating point expression to reduce the chance of
4020           decimal/binary conversion issues. If it can not be determined, the
4021           value 0 is given.
4022
4023       "NV_PRESERVES_UV"
4024           This symbol, if defined, indicates that a variable of type "NVTYPE"
4025           can preserve all the bits of a variable of type "UVTYPE".
4026
4027       "NV_PRESERVES_UV_BITS"
4028           This symbol contains the number of bits a variable of type "NVTYPE"
4029           can preserve of a variable of type "UVTYPE".
4030
4031       "NVSIZE"
4032           This symbol contains the "sizeof(NV)".  Note that some floating
4033           point formats have unused bytes.  The most notable example is the
4034           x86* 80-bit extended precision which comes in byte sizes of 12 and
4035           16 (for 32 and 64 bit platforms, respectively), but which only uses
4036           10 bytes.  Perl compiled with "-Duselongdouble" on x86* is like
4037           this.
4038
4039       "NVTYPE"
4040           This symbol defines the C type used for Perl's NV.
4041
4042       "NV_ZERO_IS_ALLBITS_ZERO"
4043           This symbol, if defined, indicates that a variable of type "NVTYPE"
4044           stores 0.0 in memory as all bits zero.
4045

Formats

4047       These are used for formatting the corresponding type For example,
4048       instead of saying
4049
4050        Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\n", iv);
4051
4052       use
4053
4054        Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\n", iv);
4055
4056       This keeps you from having to know if, say an IV, needs to be printed
4057       as %d, %ld, or something else.
4058
4059       "IVdf"
4060           This symbol defines the format string used for printing a Perl IV
4061           as a signed decimal integer.
4062
4063       "NVef"
4064           This symbol defines the format string used for printing a Perl NV
4065           using %e-ish floating point format.
4066
4067       "NVff"
4068           This symbol defines the format string used for printing a Perl NV
4069           using %f-ish floating point format.
4070
4071       "NVgf"
4072           This symbol defines the format string used for printing a Perl NV
4073           using %g-ish floating point format.
4074
4075       "PERL_PRIeldbl"
4076           This symbol, if defined, contains the string used by stdio to
4077           format long doubles (format 'e') for output.
4078
4079       "PERL_PRIfldbl"
4080           This symbol, if defined, contains the string used by stdio to
4081           format long doubles (format 'f') for output.
4082
4083       "PERL_PRIgldbl"
4084           This symbol, if defined, contains the string used by stdio to
4085           format long doubles (format 'g') for output.
4086
4087       "PERL_SCNfldbl"
4088           This symbol, if defined, contains the string used by stdio to
4089           format long doubles (format 'f') for input.
4090
4091       "PRINTF_FORMAT_NULL_OK"
4092           Allows "__printf__" format to be null when checking printf-style
4093
4094       "UTF8f"
4095           Described in perlguts.
4096
4097       "UTF8fARG"
4098           Described in perlguts.
4099
4100              UTF8fARG(bool is_utf8, Size_t byte_len, char *str)
4101
4102       "UVof"
4103           This symbol defines the format string used for printing a Perl UV
4104           as an unsigned octal integer.
4105
4106       "UVuf"
4107           This symbol defines the format string used for printing a Perl UV
4108           as an unsigned decimal integer.
4109
4110       "UVXf"
4111           This symbol defines the format string used for printing a Perl UV
4112           as an unsigned hexadecimal integer in uppercase "ABCDEF".
4113
4114       "UVxf"
4115           This symbol defines the format string used for printing a Perl UV
4116           as an unsigned hexadecimal integer in lowercase abcdef.
4117

General Configuration

4119       This section contains configuration information not otherwise found in
4120       the more specialized sections of this document.  At the end is a list
4121       of "#defines" whose name should be enough to tell you what they do, and
4122       a list of #defines which tell you if you need to "#include" files to
4123       get the corresponding functionality.
4124
4125       "BYTEORDER"
4126           This symbol holds the hexadecimal constant defined in byteorder, in
4127           a UV, i.e. 0x1234 or 0x4321 or 0x12345678, etc...  If the compiler
4128           supports cross-compiling or multiple-architecture binaries, use
4129           compiler-defined macros to determine the byte order.
4130
4131       "CHARBITS"
4132           This symbol contains the size of a char, so that the C preprocessor
4133           can make decisions based on it.
4134
4135       "DB_VERSION_MAJOR_CFG"
4136           This symbol, if defined, defines the major version number of
4137           Berkeley DB found in the db.h header when Perl was configured.
4138
4139       "DB_VERSION_MINOR_CFG"
4140           This symbol, if defined, defines the minor version number of
4141           Berkeley DB found in the db.h header when Perl was configured.  For
4142           DB version 1 this is always 0.
4143
4144       "DB_VERSION_PATCH_CFG"
4145           This symbol, if defined, defines the patch version number of
4146           Berkeley DB found in the db.h header when Perl was configured.  For
4147           DB version 1 this is always 0.
4148
4149       "DEFAULT_INC_EXCLUDES_DOT"
4150           This symbol, if defined, removes the legacy default behavior of
4151           including '.' at the end of @"INC".
4152
4153       "DLSYM_NEEDS_UNDERSCORE"
4154           This symbol, if defined, indicates that we need to prepend an
4155           underscore to the symbol name before calling "dlsym()".  This only
4156           makes sense if you *have* dlsym, which we will presume is the case
4157           if you're using dl_dlopen.xs.
4158
4159       "EBCDIC"
4160           This symbol, if defined, indicates that this system uses "EBCDIC"
4161           encoding.
4162
4163       "HAS_CSH"
4164           This symbol, if defined, indicates that the C-shell exists.
4165
4166       "HAS_GETHOSTNAME"
4167           This symbol, if defined, indicates that the C program may use the
4168           "gethostname()" routine to derive the host name.  See also
4169           "HAS_UNAME" and "PHOSTNAME".
4170
4171       "HAS_GNULIBC"
4172           This symbol, if defined, indicates to the C program that the "GNU"
4173           C library is being used.  A better check is to use the "__GLIBC__"
4174           and "__GLIBC_MINOR__" symbols supplied with glibc.
4175
4176       "HAS_LGAMMA"
4177           This symbol, if defined, indicates that the "lgamma" routine is
4178           available to do the log gamma function.  See also "HAS_TGAMMA" and
4179           "HAS_LGAMMA_R".
4180
4181       "HAS_LGAMMA_R"
4182           This symbol, if defined, indicates that the "lgamma_r" routine is
4183           available to do the log gamma function without using the global
4184           signgam variable.
4185
4186       "HAS_PRCTL_SET_NAME"
4187           This symbol, if defined, indicates that the prctl routine is
4188           available to set process title and supports "PR_SET_NAME".
4189
4190       "HAS_PROCSELFEXE"
4191           This symbol is defined if "PROCSELFEXE_PATH" is a symlink to the
4192           absolute pathname of the executing program.
4193
4194       "HAS_PSEUDOFORK"
4195           This symbol, if defined, indicates that an emulation of the fork
4196           routine is available.
4197
4198       "HAS_REGCOMP"
4199           This symbol, if defined, indicates that the "regcomp()" routine is
4200           available to do some regular pattern matching (usually on "POSIX".2
4201           conforming systems).
4202
4203       "HAS_SETPGID"
4204           This symbol, if defined, indicates that the "setpgid(pid, gpid)"
4205           routine is available to set process group ID.
4206
4207       "HAS_SIGSETJMP"
4208           This variable indicates to the C program that the "sigsetjmp()"
4209           routine is available to save the calling process's registers and
4210           stack environment for later use by "siglongjmp()", and to
4211           optionally save the process's signal mask.  See "Sigjmp_buf",
4212           "Sigsetjmp", and "Siglongjmp".
4213
4214       "HAS_STRUCT_CMSGHDR"
4215           This symbol, if defined, indicates that the "struct cmsghdr" is
4216           supported.
4217
4218       "HAS_STRUCT_MSGHDR"
4219           This symbol, if defined, indicates that the "struct msghdr" is
4220           supported.
4221
4222       "HAS_TGAMMA"
4223           This symbol, if defined, indicates that the "tgamma" routine is
4224           available to do the gamma function. See also "HAS_LGAMMA".
4225
4226       "HAS_UNAME"
4227           This symbol, if defined, indicates that the C program may use the
4228           "uname()" routine to derive the host name.  See also
4229           "HAS_GETHOSTNAME" and "PHOSTNAME".
4230
4231       "HAS_UNION_SEMUN"
4232           This symbol, if defined, indicates that the "union semun" is
4233           defined by including sys/sem.h.  If not, the user code probably
4234           needs to define it as:
4235
4236            union semun {
4237            int val;
4238            struct semid_ds *buf;
4239            unsigned short *array;
4240            }
4241
4242       "I_DIRENT"
4243           This symbol, if defined, indicates to the C program that it should
4244           include dirent.h. Using this symbol also triggers the definition of
4245           the "Direntry_t" define which ends up being '"struct dirent"' or
4246           '"struct direct"' depending on the availability of dirent.h.
4247
4248            #ifdef I_DIRENT
4249                #include <dirent.h>
4250            #endif
4251
4252       "I_POLL"
4253           This symbol, if defined, indicates that poll.h exists and should be
4254           included. (see also "HAS_POLL")
4255
4256            #ifdef I_POLL
4257                #include <poll.h>
4258            #endif
4259
4260       "I_SYS_RESOURCE"
4261           This symbol, if defined, indicates to the C program that it should
4262           include sys/resource.h.
4263
4264            #ifdef I_SYS_RESOURCE
4265                #include <sys_resource.h>
4266            #endif
4267
4268       "LIBM_LIB_VERSION"
4269           This symbol, if defined, indicates that libm exports "_LIB_VERSION"
4270           and that math.h defines the enum to manipulate it.
4271
4272       "NEED_VA_COPY"
4273           This symbol, if defined, indicates that the system stores the
4274           variable argument list datatype, "va_list", in a format that cannot
4275           be copied by simple assignment, so that some other means must be
4276           used when copying is required.  As such systems vary in their
4277           provision (or non-provision) of copying mechanisms, handy.h defines
4278           a platform- independent macro, "Perl_va_copy(src, dst)", to do the
4279           job.
4280
4281       "OSNAME"
4282           This symbol contains the name of the operating system, as
4283           determined by Configure.  You shouldn't rely on it too much; the
4284           specific feature tests from Configure are generally more reliable.
4285
4286       "OSVERS"
4287           This symbol contains the version of the operating system, as
4288           determined by Configure.  You shouldn't rely on it too much; the
4289           specific feature tests from Configure are generally more reliable.
4290
4291       "PHOSTNAME"
4292           This symbol, if defined, indicates the command to feed to the
4293           "popen()" routine to derive the host name.  See also
4294           "HAS_GETHOSTNAME" and "HAS_UNAME".  Note that the command uses a
4295           fully qualified path, so that it is safe even if used by a process
4296           with super-user privileges.
4297
4298       "PROCSELFEXE_PATH"
4299           If "HAS_PROCSELFEXE" is defined this symbol is the filename of the
4300           symbolic link pointing to the absolute pathname of the executing
4301           program.
4302
4303       "PTRSIZE"
4304           This symbol contains the size of a pointer, so that the C
4305           preprocessor can make decisions based on it.  It will be
4306           "sizeof(void *)" if the compiler supports (void *); otherwise it
4307           will be "sizeof(char *)".
4308
4309       "RANDBITS"
4310           This symbol indicates how many bits are produced by the function
4311           used to generate normalized random numbers.  Values include 15, 16,
4312           31, and 48.
4313
4314       "SELECT_MIN_BITS"
4315           This symbol holds the minimum number of bits operated by select.
4316           That is, if you do "select(n, ...)", how many bits at least will be
4317           cleared in the masks if some activity is detected.  Usually this is
4318           either n or 32*"ceil(n/32)", especially many little-endians do the
4319           latter.  This is only useful if you have "select()", naturally.
4320
4321       "SETUID_SCRIPTS_ARE_SECURE_NOW"
4322           This symbol, if defined, indicates that the bug that prevents
4323           setuid scripts from being secure is not present in this kernel.
4324
4325   List of capability "HAS_foo" symbols
4326       This is a list of those symbols that dont appear elsewhere in ths
4327       document that indicate if the current platform has a certain
4328       capability.  Their names all begin with "HAS_".  Only those symbols
4329       whose capability is directly derived from the name are listed here.
4330       All others have their meaning expanded out elsewhere in this document.
4331       This (relatively) compact list is because we think that the expansion
4332       would add little or no value and take up a lot of space (because there
4333       are so many).  If you think certain ones should be expanded, send email
4334       to perl5-porters@perl.org <mailto:perl5-porters@perl.org>.
4335
4336       Each symbol here will be "#define"d if and only if the platform has the
4337       capability.  If you need more detail, see the corresponding entry in
4338       config.h.  For convenience, the list is split so that the ones that
4339       indicate there is a reentrant version of a capability are listed
4340       separately
4341
4342       "HAS_ACCEPT4",  "HAS_ACCESS",  "HAS_ACCESSX",  "HAS_ACOSH",
4343       "HAS_AINTL",  "HAS_ALARM",  "HAS_ASINH",  "HAS_ATANH",  "HAS_ATOLL",
4344       "HAS_CBRT",  "HAS_CHOWN",  "HAS_CHROOT",  "HAS_CHSIZE",
4345       "HAS_CLEARENV",  "HAS_COPYSIGN",  "HAS_COPYSIGNL",  "HAS_CRYPT",
4346       "HAS_CTERMID",  "HAS_CUSERID",  "HAS_DIRFD",  "HAS_DLADDR",
4347       "HAS_DLERROR",  "HAS_EACCESS",  "HAS_ENDHOSTENT",  "HAS_ENDNETENT",
4348       "HAS_ENDPROTOENT",  "HAS_ENDSERVENT",  "HAS_ERF",  "HAS_ERFC",
4349       "HAS_EXP2",  "HAS_EXPM1",  "HAS_FCHMOD",  "HAS_FCHMODAT",
4350       "HAS_FCHOWN",  "HAS_FDIM",  "HAS_FD_SET",  "HAS_FEGETROUND",
4351       "HAS_FGETPOS",  "HAS_FLOCK",  "HAS_FMA",  "HAS_FMAX",  "HAS_FMIN",
4352       "HAS_FORK",  "HAS_FSEEKO",  "HAS_FSETPOS",  "HAS_FSYNC",
4353       "HAS_FTELLO",  "HAS_GAI_STRERROR",  "HAS_GETADDRINFO",  "HAS_GETCWD",
4354       "HAS_GETESPWNAM",  "HAS_GETGROUPS",  "HAS_GETHOSTBYADDR",
4355       "HAS_GETHOSTBYNAME",  "HAS_GETHOSTENT",  "HAS_GETLOGIN",
4356       "HAS_GETNAMEINFO",  "HAS_GETNETBYADDR",  "HAS_GETNETBYNAME",
4357       "HAS_GETNETENT",  "HAS_GETPAGESIZE",  "HAS_GETPGID",  "HAS_GETPGRP",
4358       "HAS_GETPGRP2",  "HAS_GETPPID",  "HAS_GETPRIORITY",
4359       "HAS_GETPROTOBYNAME",  "HAS_GETPROTOBYNUMBER",  "HAS_GETPROTOENT",
4360       "HAS_GETPRPWNAM",  "HAS_GETSERVBYNAME",  "HAS_GETSERVBYPORT",
4361       "HAS_GETSERVENT",  "HAS_GETSPNAM",  "HAS_HTONL",  "HAS_HTONS",
4362       "HAS_HYPOT",  "HAS_ILOGBL",  "HAS_INETNTOP",  "HAS_INETPTON",
4363       "HAS_INET_ATON",  "HAS_IPV6_MREQ",  "HAS_IPV6_MREQ_SOURCE",
4364       "HAS_IP_MREQ",  "HAS_IP_MREQ_SOURCE",  "HAS_ISASCII",  "HAS_ISBLANK",
4365       "HAS_ISLESS",  "HAS_KILLPG",  "HAS_LCHOWN",  "HAS_LINK",
4366       "HAS_LINKAT",  "HAS_LLROUND",  "HAS_LOCKF",  "HAS_LOG1P",  "HAS_LOG2",
4367       "HAS_LOGB",  "HAS_LROUND",  "HAS_LSTAT",  "HAS_MADVISE",  "HAS_MBLEN",
4368       "HAS_MBRLEN",  "HAS_MBRTOWC",  "HAS_MBSTOWCS",  "HAS_MBTOWC",
4369       "HAS_MEMMEM",  "HAS_MEMRCHR",  "HAS_MKDTEMP",  "HAS_MKFIFO",
4370       "HAS_MKOSTEMP",  "HAS_MKSTEMP",  "HAS_MKSTEMPS",  "HAS_MMAP",
4371       "HAS_MPROTECT",  "HAS_MSG",  "HAS_MSYNC",  "HAS_MUNMAP",
4372       "HAS_NEARBYINT",  "HAS_NEXTAFTER",  "HAS_NICE",  "HAS_NTOHL",
4373       "HAS_NTOHS",  "HAS_PATHCONF",  "HAS_PAUSE",  "HAS_PHOSTNAME",
4374       "HAS_PIPE",  "HAS_PIPE2",  "HAS_PRCTL",  "HAS_PTRDIFF_T",
4375       "HAS_READLINK",  "HAS_READV",  "HAS_RECVMSG",  "HAS_REMQUO",
4376       "HAS_RENAME",  "HAS_RENAMEAT",  "HAS_RINT",  "HAS_ROUND",
4377       "HAS_SCALBNL",  "HAS_SEM",  "HAS_SENDMSG",  "HAS_SETEGID",
4378       "HAS_SETEUID",  "HAS_SETGROUPS",  "HAS_SETHOSTENT",  "HAS_SETLINEBUF",
4379       "HAS_SETNETENT",  "HAS_SETPGRP",  "HAS_SETPGRP2",  "HAS_SETPRIORITY",
4380       "HAS_SETPROCTITLE",  "HAS_SETPROTOENT",  "HAS_SETREGID",
4381       "HAS_SETRESGID",  "HAS_SETRESUID",  "HAS_SETREUID",  "HAS_SETRGID",
4382       "HAS_SETRUID",  "HAS_SETSERVENT",  "HAS_SETSID",  "HAS_SHM",
4383       "HAS_SIGACTION",  "HAS_SIGPROCMASK",  "HAS_SIN6_SCOPE_ID",
4384       "HAS_SNPRINTF",  "HAS_STAT",  "HAS_STRCOLL",  "HAS_STRERROR_L",
4385       "HAS_STRLCAT",  "HAS_STRLCPY",  "HAS_STRNLEN",  "HAS_STRTOD",
4386       "HAS_STRTOL",  "HAS_STRTOLL",  "HAS_STRTOQ",  "HAS_STRTOUL",
4387       "HAS_STRTOULL",  "HAS_STRTOUQ",  "HAS_STRXFRM",  "HAS_SYMLINK",
4388       "HAS_SYSCALL",  "HAS_SYSCONF",  "HAS_SYSTEM",  "HAS_SYS_ERRLIST",
4389       "HAS_TCGETPGRP",  "HAS_TCSETPGRP",  "HAS_TOWLOWER",  "HAS_TOWUPPER",
4390       "HAS_TRUNCATE",  "HAS_TRUNCL",  "HAS_UALARM",  "HAS_UMASK",
4391       "HAS_UNLINKAT",  "HAS_UNSETENV",  "HAS_VFORK",  "HAS_VSNPRINTF",
4392       "HAS_WAIT4",  "HAS_WAITPID",  "HAS_WCRTOMB",  "HAS_WCSCMP",
4393       "HAS_WCSTOMBS",  "HAS_WCSXFRM",  "HAS_WCTOMB",  "HAS_WRITEV",
4394       "HAS__FWALK"
4395
4396       And, the reentrant capabilities:
4397
4398       "HAS_CRYPT_R",  "HAS_CTERMID_R",  "HAS_DRAND48_R",
4399       "HAS_ENDHOSTENT_R",  "HAS_ENDNETENT_R",  "HAS_ENDPROTOENT_R",
4400       "HAS_ENDSERVENT_R",  "HAS_GETGRGID_R",  "HAS_GETGRNAM_R",
4401       "HAS_GETHOSTBYADDR_R",  "HAS_GETHOSTBYNAME_R",  "HAS_GETHOSTENT_R",
4402       "HAS_GETLOGIN_R",  "HAS_GETNETBYADDR_R",  "HAS_GETNETBYNAME_R",
4403       "HAS_GETNETENT_R",  "HAS_GETPROTOBYNAME_R",  "HAS_GETPROTOBYNUMBER_R",
4404       "HAS_GETPROTOENT_R",  "HAS_GETPWNAM_R",  "HAS_GETPWUID_R",
4405       "HAS_GETSERVBYNAME_R",  "HAS_GETSERVBYPORT_R",  "HAS_GETSERVENT_R",
4406       "HAS_GETSPNAM_R",  "HAS_RANDOM_R",  "HAS_READDIR_R",
4407       "HAS_SETHOSTENT_R",  "HAS_SETNETENT_R",  "HAS_SETPROTOENT_R",
4408       "HAS_SETSERVENT_R",  "HAS_SRAND48_R",  "HAS_SRANDOM_R",
4409       "HAS_STRERROR_R",  "HAS_TMPNAM_R",  "HAS_TTYNAME_R"
4410
4411       Example usage:
4412
4413        #ifdef HAS_STRNLEN
4414          use strnlen()
4415        #else
4416          use an alternative implementation
4417        #endif
4418
4419   List of "#include" needed symbols
4420       This list contains symbols that indicate if certain "#include" files
4421       are present on the platform.  If your code accesses the functionality
4422       that one of these is for, you will need to "#include" it if the symbol
4423       on this list is "#define"d.  For more detail, see the corresponding
4424       entry in config.h.
4425
4426       "I_ARPA_INET",  "I_BFD",  "I_CRYPT",  "I_DBM",  "I_DLFCN",
4427       "I_EXECINFO",  "I_FP",  "I_FP_CLASS",  "I_GDBM",  "I_GDBMNDBM",
4428       "I_GDBM_NDBM",  "I_GRP",  "I_IEEEFP",  "I_INTTYPES",  "I_LIBUTIL",
4429       "I_MNTENT",  "I_NDBM",  "I_NETDB",  "I_NETINET_IN",  "I_NETINET_TCP",
4430       "I_NET_ERRNO",  "I_PROT",  "I_PWD",  "I_RPCSVC_DBM",  "I_SGTTY",
4431       "I_SHADOW",  "I_STDBOOL",  "I_STDINT",  "I_SUNMATH",  "I_SYSLOG",
4432       "I_SYSMODE",  "I_SYSUIO",  "I_SYSUTSNAME",  "I_SYS_ACCESS",
4433       "I_SYS_IOCTL",  "I_SYS_MOUNT",  "I_SYS_PARAM",  "I_SYS_POLL",
4434       "I_SYS_SECURITY",  "I_SYS_SELECT",  "I_SYS_STAT",  "I_SYS_STATVFS",
4435       "I_SYS_TIME",  "I_SYS_TIMES",  "I_SYS_TIME_KERNEL",  "I_SYS_TYPES",
4436       "I_SYS_UN",  "I_SYS_VFS",  "I_SYS_WAIT",  "I_TERMIO",  "I_TERMIOS",
4437       "I_UNISTD",  "I_USTAT",  "I_VFORK",  "I_WCHAR",  "I_WCTYPE"
4438
4439       Example usage:
4440
4441        #ifdef I_WCHAR
4442          #include <wchar.h>
4443        #endif
4444

Global Variables

4446       These variables are global to an entire process.  They are shared
4447       between all interpreters and all threads in a process.  Any variables
4448       not documented here may be changed or removed without notice, so don't
4449       use them!  If you feel you really do need to use an unlisted variable,
4450       first send email to perl5-porters@perl.org
4451       <mailto:perl5-porters@perl.org>.  It may be that someone there will
4452       point out a way to accomplish what you need without using an internal
4453       variable.  But if not, you should get a go-ahead to document and then
4454       use the variable.
4455
4456       "PL_check"
4457           Array, indexed by opcode, of functions that will be called for the
4458           "check" phase of optree building during compilation of Perl code.
4459           For most (but not all) types of op, once the op has been initially
4460           built and populated with child ops it will be filtered through the
4461           check function referenced by the appropriate element of this array.
4462           The new op is passed in as the sole argument to the check function,
4463           and the check function returns the completed op.  The check
4464           function may (as the name suggests) check the op for validity and
4465           signal errors.  It may also initialise or modify parts of the ops,
4466           or perform more radical surgery such as adding or removing child
4467           ops, or even throw the op away and return a different op in its
4468           place.
4469
4470           This array of function pointers is a convenient place to hook into
4471           the compilation process.  An XS module can put its own custom check
4472           function in place of any of the standard ones, to influence the
4473           compilation of a particular type of op.  However, a custom check
4474           function must never fully replace a standard check function (or
4475           even a custom check function from another module).  A module
4476           modifying checking must instead wrap the preexisting check
4477           function.  A custom check function must be selective about when to
4478           apply its custom behaviour.  In the usual case where it decides not
4479           to do anything special with an op, it must chain the preexisting op
4480           function.  Check functions are thus linked in a chain, with the
4481           core's base checker at the end.
4482
4483           For thread safety, modules should not write directly to this array.
4484           Instead, use the function "wrap_op_checker".
4485
4486       "PL_keyword_plugin"
4487           NOTE: "PL_keyword_plugin" is experimental and may change or be
4488           removed without notice.
4489
4490           Function pointer, pointing at a function used to handle extended
4491           keywords.  The function should be declared as
4492
4493                   int keyword_plugin_function(pTHX_
4494                           char *keyword_ptr, STRLEN keyword_len,
4495                           OP **op_ptr)
4496
4497           The function is called from the tokeniser, whenever a possible
4498           keyword is seen.  "keyword_ptr" points at the word in the parser's
4499           input buffer, and "keyword_len" gives its length; it is not null-
4500           terminated.  The function is expected to examine the word, and
4501           possibly other state such as %^H, to decide whether it wants to
4502           handle it as an extended keyword.  If it does not, the function
4503           should return "KEYWORD_PLUGIN_DECLINE", and the normal parser
4504           process will continue.
4505
4506           If the function wants to handle the keyword, it first must parse
4507           anything following the keyword that is part of the syntax
4508           introduced by the keyword.  See "Lexer interface" for details.
4509
4510           When a keyword is being handled, the plugin function must build a
4511           tree of "OP" structures, representing the code that was parsed.
4512           The root of the tree must be stored in *op_ptr.  The function then
4513           returns a constant indicating the syntactic role of the construct
4514           that it has parsed: "KEYWORD_PLUGIN_STMT" if it is a complete
4515           statement, or "KEYWORD_PLUGIN_EXPR" if it is an expression.  Note
4516           that a statement construct cannot be used inside an expression
4517           (except via "do BLOCK" and similar), and an expression is not a
4518           complete statement (it requires at least a terminating semicolon).
4519
4520           When a keyword is handled, the plugin function may also have
4521           (compile-time) side effects.  It may modify "%^H", define
4522           functions, and so on.  Typically, if side effects are the main
4523           purpose of a handler, it does not wish to generate any ops to be
4524           included in the normal compilation.  In this case it is still
4525           required to supply an op tree, but it suffices to generate a single
4526           null op.
4527
4528           That's how the *PL_keyword_plugin function needs to behave overall.
4529           Conventionally, however, one does not completely replace the
4530           existing handler function.  Instead, take a copy of
4531           "PL_keyword_plugin" before assigning your own function pointer to
4532           it.  Your handler function should look for keywords that it is
4533           interested in and handle those.  Where it is not interested, it
4534           should call the saved plugin function, passing on the arguments it
4535           received.  Thus "PL_keyword_plugin" actually points at a chain of
4536           handler functions, all of which have an opportunity to handle
4537           keywords, and only the last function in the chain (built into the
4538           Perl core) will normally return "KEYWORD_PLUGIN_DECLINE".
4539
4540           For thread safety, modules should not set this variable directly.
4541           Instead, use the function "wrap_keyword_plugin".
4542
4543       "PL_phase"
4544           A value that indicates the current Perl interpreter's phase.
4545           Possible values include "PERL_PHASE_CONSTRUCT", "PERL_PHASE_START",
4546           "PERL_PHASE_CHECK", "PERL_PHASE_INIT", "PERL_PHASE_RUN",
4547           "PERL_PHASE_END", and "PERL_PHASE_DESTRUCT".
4548
4549           For example, the following determines whether the interpreter is in
4550           global destruction:
4551
4552               if (PL_phase == PERL_PHASE_DESTRUCT) {
4553                   // we are in global destruction
4554               }
4555
4556           "PL_phase" was introduced in Perl 5.14; in prior perls you can use
4557           "PL_dirty" (boolean) to determine whether the interpreter is in
4558           global destruction. (Use of "PL_dirty" is discouraged since 5.14.)
4559
4560            enum perl_phase  PL_phase
4561

GV Handling

4563       A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
4564       It is a structure that holds a pointer to a scalar, an array, a hash
4565       etc, corresponding to $foo, @foo, %foo.
4566
4567       GVs are usually found as values in stashes (symbol table hashes) where
4568       Perl stores its global variables.
4569
4570       "gv_autoload4"
4571           Equivalent to "gv_autoload_pvn".
4572
4573            GV*  gv_autoload4(HV* stash, const char* name, STRLEN len,
4574                              I32 method)
4575
4576       "GvAV"
4577           Return the AV from the GV.
4578
4579            AV*  GvAV(GV* gv)
4580
4581       "gv_const_sv"
4582           If "gv" is a typeglob whose subroutine entry is a constant sub
4583           eligible for inlining, or "gv" is a placeholder reference that
4584           would be promoted to such a typeglob, then returns the value
4585           returned by the sub.  Otherwise, returns "NULL".
4586
4587            SV*  gv_const_sv(GV* gv)
4588
4589       "GvCV"
4590           Return the CV from the GV.
4591
4592            CV*  GvCV(GV* gv)
4593
4594       "gv_fetchfile"
4595       "gv_fetchfile_flags"
4596           These return the debugger glob for the file (compiled by Perl)
4597           whose name is given by the "name" parameter.
4598
4599           There are currently exactly two differences between these
4600           functions.
4601
4602           The "name" parameter to "gv_fetchfile" is a C string, meaning it is
4603           "NUL"-terminated; whereas the "name" parameter to
4604           "gv_fetchfile_flags" is a Perl string, whose length (in bytes) is
4605           passed in via the "namelen" parameter This means the name may
4606           contain embedded "NUL" characters.  "namelen" doesn't exist in
4607           plain "gv_fetchfile").
4608
4609           The other difference is that "gv_fetchfile_flags" has an extra
4610           "flags" parameter, which is currently completely ignored, but
4611           allows for possible future extensions.
4612
4613            GV*  gv_fetchfile      (const char* name)
4614            GV*  gv_fetchfile_flags(const char *const name, const STRLEN len,
4615                                    const U32 flags)
4616
4617       "gv_fetchmeth"
4618           Like "gv_fetchmeth_pvn", but lacks a flags parameter.
4619
4620            GV*  gv_fetchmeth(HV* stash, const char* name, STRLEN len,
4621                              I32 level)
4622
4623       "gv_fetchmethod"
4624           See "gv_fetchmethod_autoload".
4625
4626            GV*  gv_fetchmethod(HV* stash, const char* name)
4627
4628       "gv_fetchmethod_autoload"
4629           Returns the glob which contains the subroutine to call to invoke
4630           the method on the "stash".  In fact in the presence of autoloading
4631           this may be the glob for "AUTOLOAD".  In this case the
4632           corresponding variable $AUTOLOAD is already setup.
4633
4634           The third parameter of "gv_fetchmethod_autoload" determines whether
4635           AUTOLOAD lookup is performed if the given method is not present:
4636           non-zero means yes, look for AUTOLOAD; zero means no, don't look
4637           for AUTOLOAD.  Calling "gv_fetchmethod" is equivalent to calling
4638           "gv_fetchmethod_autoload" with a non-zero "autoload" parameter.
4639
4640           These functions grant "SUPER" token as a prefix of the method name.
4641           Note that if you want to keep the returned glob for a long time,
4642           you need to check for it being "AUTOLOAD", since at the later time
4643           the call may load a different subroutine due to $AUTOLOAD changing
4644           its value.  Use the glob created as a side effect to do this.
4645
4646           These functions have the same side-effects as "gv_fetchmeth" with
4647           "level==0".  The warning against passing the GV returned by
4648           "gv_fetchmeth" to "call_sv" applies equally to these functions.
4649
4650            GV*  gv_fetchmethod_autoload(HV* stash, const char* name,
4651                                         I32 autoload)
4652
4653       "gv_fetchmeth_autoload"
4654           This is the old form of "gv_fetchmeth_pvn_autoload", which has no
4655           flags parameter.
4656
4657            GV*  gv_fetchmeth_autoload(HV* stash, const char* name,
4658                                       STRLEN len, I32 level)
4659
4660       "gv_fetchmeth_pv"
4661           Exactly like "gv_fetchmeth_pvn", but takes a nul-terminated string
4662           instead of a string/length pair.
4663
4664            GV*  gv_fetchmeth_pv(HV* stash, const char* name, I32 level,
4665                                 U32 flags)
4666
4667       "gv_fetchmeth_pvn"
4668           Returns the glob with the given "name" and a defined subroutine or
4669           "NULL".  The glob lives in the given "stash", or in the stashes
4670           accessible via @ISA and "UNIVERSAL::".
4671
4672           The argument "level" should be either 0 or -1.  If "level==0", as a
4673           side-effect creates a glob with the given "name" in the given
4674           "stash" which in the case of success contains an alias for the
4675           subroutine, and sets up caching info for this glob.
4676
4677           The only significant values for "flags" are "GV_SUPER",
4678           "GV_NOUNIVERSAL", and "SVf_UTF8".
4679
4680           "GV_SUPER" indicates that we want to look up the method in the
4681           superclasses of the "stash".
4682
4683           "GV_NOUNIVERSAL" indicates that we do not want to look up the
4684           method in the stash accessible by "UNIVERSAL::".
4685
4686           The GV returned from "gv_fetchmeth" may be a method cache entry,
4687           which is not visible to Perl code.  So when calling "call_sv", you
4688           should not use the GV directly; instead, you should use the
4689           method's CV, which can be obtained from the GV with the "GvCV"
4690           macro.
4691
4692            GV*  gv_fetchmeth_pvn(HV* stash, const char* name, STRLEN len,
4693                                  I32 level, U32 flags)
4694
4695       "gv_fetchmeth_pvn_autoload"
4696           Same as "gv_fetchmeth_pvn()", but looks for autoloaded subroutines
4697           too.  Returns a glob for the subroutine.
4698
4699           For an autoloaded subroutine without a GV, will create a GV even if
4700           "level < 0".  For an autoloaded subroutine without a stub, "GvCV()"
4701           of the result may be zero.
4702
4703           Currently, the only significant value for "flags" is "SVf_UTF8".
4704
4705            GV*  gv_fetchmeth_pvn_autoload(HV* stash, const char* name,
4706                                           STRLEN len, I32 level, U32 flags)
4707
4708       "gv_fetchmeth_pv_autoload"
4709           Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-
4710           terminated string instead of a string/length pair.
4711
4712            GV*  gv_fetchmeth_pv_autoload(HV* stash, const char* name,
4713                                          I32 level, U32 flags)
4714
4715       "gv_fetchmeth_sv"
4716           Exactly like "gv_fetchmeth_pvn", but takes the name string in the
4717           form of an SV instead of a string/length pair.
4718
4719            GV*  gv_fetchmeth_sv(HV* stash, SV* namesv, I32 level, U32 flags)
4720
4721       "gv_fetchmeth_sv_autoload"
4722           Exactly like "gv_fetchmeth_pvn_autoload", but takes the name string
4723           in the form of an SV instead of a string/length pair.
4724
4725            GV*  gv_fetchmeth_sv_autoload(HV* stash, SV* namesv, I32 level,
4726                                          U32 flags)
4727
4728       "gv_fetchpv"
4729       "gv_fetchpvn"
4730       "gv_fetchpvn_flags"
4731       "gv_fetchpvs"
4732       "gv_fetchsv"
4733       "gv_fetchsv_nomg"
4734           These all return the GV of type "sv_type" whose name is given by
4735           the inputs, or NULL if no GV of that name and type could be found.
4736           See "Stashes and Globs" in perlguts.
4737
4738           The only differences are how the input name is specified, and if
4739           'get' magic is normally used in getting that name.
4740
4741           Don't be fooled by the fact that only one form has "flags" in its
4742           name.  They all have a "flags" parameter in fact, and all the flag
4743           bits have the same meanings for all
4744
4745           If any of the flags "GV_ADD", "GV_ADDMG", "GV_ADDWARN",
4746           "GV_ADDMULTI", or "GV_NOINIT" is set, a GV is created if none
4747           already exists for the input name and type.  However, "GV_ADDMG"
4748           will only do the creation for magical GV's.  For all of these flags
4749           except "GV_NOINIT", "gv_init_pvn" is called after the addition.
4750           "GV_ADDWARN" is used when the caller expects that adding won't be
4751           necessary because the symbol should already exist; but if not, add
4752           it anyway, with a warning that it was unexpectedly absent.  The
4753           "GV_ADDMULTI" flag means to pretend that the GV has been seen
4754           before (i.e., suppress "Used once" warnings).
4755
4756           The flag "GV_NOADD_NOINIT" causes "gv_init_pvn" not be to called if
4757           the GV existed but isn't PVGV.
4758
4759           If the "SVf_UTF8" bit is set, the name is treated as being encoded
4760           in UTF-8; otherwise the name won't be considered to be UTF-8 in the
4761           "pv"-named forms, and the UTF-8ness of the underlying SVs will be
4762           used in the "sv" forms.
4763
4764           If the flag "GV_NOTQUAL" is set, the caller warrants that the input
4765           name is a plain symbol name, not qualified with a package,
4766           otherwise the name is checked for being a qualified one.
4767
4768           In "gv_fetchpv", "nambeg" is a C string, NUL-terminated with no
4769           intermediate NULs.
4770
4771           In "gv_fetchpvs", "name" is a literal C string, hence is enclosed
4772           in double quotes.
4773
4774           "gv_fetchpvn" and "gv_fetchpvn_flags" are identical.  In these,
4775           <nambeg> is a Perl string whose byte length is given by "full_len",
4776           and may contain embedded NULs.
4777
4778           In "gv_fetchsv" and "gv_fetchsv_nomg", the name is extracted from
4779           the PV of the input "name" SV.  The only difference between these
4780           two forms is that 'get' magic is normally done on "name" in
4781           "gv_fetchsv", and always skipped with "gv_fetchsv_nomg".  Including
4782           "GV_NO_SVGMAGIC" in the "flags" parameter to "gv_fetchsv" makes it
4783           behave identically to "gv_fetchsv_nomg".
4784
4785            GV*   gv_fetchpv       (const char *nambeg, I32 flags,
4786                                    const svtype sv_type)
4787            GV *  gv_fetchpvn      (const char * nambeg, STRLEN full_len,
4788                                    I32 flags, const svtype sv_type)
4789            GV*   gv_fetchpvn_flags(const char* name, STRLEN len, I32 flags,
4790                                    const svtype sv_type)
4791            GV *  gv_fetchpvs      ("name", I32 flags, const svtype sv_type)
4792            GV*   gv_fetchsv       (SV *name, I32 flags, const svtype sv_type)
4793            GV *  gv_fetchsv_nomg  (SV *name, I32 flags, const svtype sv_type)
4794
4795       "GvHV"
4796           Return the HV from the GV.
4797
4798            HV*  GvHV(GV* gv)
4799
4800       "gv_init"
4801           The old form of "gv_init_pvn()".  It does not work with UTF-8
4802           strings, as it has no flags parameter.  If the "multi" parameter is
4803           set, the "GV_ADDMULTI" flag will be passed to "gv_init_pvn()".
4804
4805            void  gv_init(GV* gv, HV* stash, const char* name, STRLEN len,
4806                          int multi)
4807
4808       "gv_init_pv"
4809           Same as "gv_init_pvn()", but takes a nul-terminated string for the
4810           name instead of separate char * and length parameters.
4811
4812            void  gv_init_pv(GV* gv, HV* stash, const char* name, U32 flags)
4813
4814       "gv_init_pvn"
4815           Converts a scalar into a typeglob.  This is an incoercible
4816           typeglob; assigning a reference to it will assign to one of its
4817           slots, instead of overwriting it as happens with typeglobs created
4818           by "SvSetSV".  Converting any scalar that is "SvOK()" may produce
4819           unpredictable results and is reserved for perl's internal use.
4820
4821           "gv" is the scalar to be converted.
4822
4823           "stash" is the parent stash/package, if any.
4824
4825           "name" and "len" give the name.  The name must be unqualified; that
4826           is, it must not include the package name.  If "gv" is a stash
4827           element, it is the caller's responsibility to ensure that the name
4828           passed to this function matches the name of the element.  If it
4829           does not match, perl's internal bookkeeping will get out of sync.
4830
4831           "flags" can be set to "SVf_UTF8" if "name" is a UTF-8 string, or
4832           the return value of SvUTF8(sv).  It can also take the "GV_ADDMULTI"
4833           flag, which means to pretend that the GV has been seen before
4834           (i.e., suppress "Used once" warnings).
4835
4836            void  gv_init_pvn(GV* gv, HV* stash, const char* name, STRLEN len,
4837                              U32 flags)
4838
4839       "gv_init_sv"
4840           Same as "gv_init_pvn()", but takes an SV * for the name instead of
4841           separate char * and length parameters.  "flags" is currently
4842           unused.
4843
4844            void  gv_init_sv(GV* gv, HV* stash, SV* namesv, U32 flags)
4845
4846       "gv_stashpv"
4847           Returns a pointer to the stash for a specified package.  Uses
4848           "strlen" to determine the length of "name", then calls
4849           "gv_stashpvn()".
4850
4851            HV*  gv_stashpv(const char* name, I32 flags)
4852
4853       "gv_stashpvn"
4854           Returns a pointer to the stash for a specified package.  The
4855           "namelen" parameter indicates the length of the "name", in bytes.
4856           "flags" is passed to "gv_fetchpvn_flags()", so if set to "GV_ADD"
4857           then the package will be created if it does not already exist.  If
4858           the package does not exist and "flags" is 0 (or any other setting
4859           that does not create packages) then "NULL" is returned.
4860
4861           Flags may be one of:
4862
4863            GV_ADD           Create and initialize the package if doesn't
4864                             already exist
4865            GV_NOADD_NOINIT  Don't create the package,
4866            GV_ADDMG         GV_ADD iff the GV is magical
4867            GV_NOINIT        GV_ADD, but don't initialize
4868            GV_NOEXPAND      Don't expand SvOK() entries to PVGV
4869            SVf_UTF8         The name is in UTF-8
4870
4871           The most important of which are probably "GV_ADD" and "SVf_UTF8".
4872
4873           Note, use of "gv_stashsv" instead of "gv_stashpvn" where possible
4874           is strongly recommended for performance reasons.
4875
4876            HV*  gv_stashpvn(const char* name, U32 namelen, I32 flags)
4877
4878       "gv_stashpvs"
4879           Like "gv_stashpvn", but takes a literal string instead of a
4880           string/length pair.
4881
4882            HV*  gv_stashpvs("name", I32 create)
4883
4884       "gv_stashsv"
4885           Returns a pointer to the stash for a specified package.  See
4886           "gv_stashpvn".
4887
4888           Note this interface is strongly preferred over "gv_stashpvn" for
4889           performance reasons.
4890
4891            HV*  gv_stashsv(SV* sv, I32 flags)
4892
4893       "GvSV"
4894           Return the SV from the GV.
4895
4896           Prior to Perl v5.9.3, this would add a scalar if none existed.
4897           Nowadays, use "GvSVn" for that, or compile perl with
4898           "-DPERL_CREATE_GVSV".  See perl5100delta.
4899
4900            SV*  GvSV(GV* gv)
4901
4902       "GvSVn"
4903           Like "GvSV", but creates an empty scalar if none already exists.
4904
4905            SV*  GvSVn(GV* gv)
4906
4907       "save_gp"
4908           Saves the current GP of gv on the save stack to be restored on
4909           scope exit.
4910
4911           If empty is true, replace the GP with a new GP.
4912
4913           If empty is false, mark gv with GVf_INTRO so the next reference
4914           assigned is localized, which is how " local *foo = $someref; "
4915           works.
4916
4917            void  save_gp(GV* gv, I32 empty)
4918
4919       "setdefout"
4920           Sets "PL_defoutgv", the default file handle for output, to the
4921           passed in typeglob.  As "PL_defoutgv" "owns" a reference on its
4922           typeglob, the reference count of the passed in typeglob is
4923           increased by one, and the reference count of the typeglob that
4924           "PL_defoutgv" points to is decreased by one.
4925
4926            void  setdefout(GV* gv)
4927

Hook manipulation

4929       These functions provide convenient and thread-safe means of
4930       manipulating hook variables.
4931
4932       "wrap_op_checker"
4933           Puts a C function into the chain of check functions for a specified
4934           op type.  This is the preferred way to manipulate the "PL_check"
4935           array.  "opcode" specifies which type of op is to be affected.
4936           "new_checker" is a pointer to the C function that is to be added to
4937           that opcode's check chain, and "old_checker_p" points to the
4938           storage location where a pointer to the next function in the chain
4939           will be stored.  The value of "new_checker" is written into the
4940           "PL_check" array, while the value previously stored there is
4941           written to *old_checker_p.
4942
4943           "PL_check" is global to an entire process, and a module wishing to
4944           hook op checking may find itself invoked more than once per
4945           process, typically in different threads.  To handle that situation,
4946           this function is idempotent.  The location *old_checker_p must
4947           initially (once per process) contain a null pointer.  A C variable
4948           of static duration (declared at file scope, typically also marked
4949           "static" to give it internal linkage) will be implicitly
4950           initialised appropriately, if it does not have an explicit
4951           initialiser.  This function will only actually modify the check
4952           chain if it finds *old_checker_p to be null.  This function is also
4953           thread safe on the small scale.  It uses appropriate locking to
4954           avoid race conditions in accessing "PL_check".
4955
4956           When this function is called, the function referenced by
4957           "new_checker" must be ready to be called, except for *old_checker_p
4958           being unfilled.  In a threading situation, "new_checker" may be
4959           called immediately, even before this function has returned.
4960           *old_checker_p will always be appropriately set before
4961           "new_checker" is called.  If "new_checker" decides not to do
4962           anything special with an op that it is given (which is the usual
4963           case for most uses of op check hooking), it must chain the check
4964           function referenced by *old_checker_p.
4965
4966           Taken all together, XS code to hook an op checker should typically
4967           look something like this:
4968
4969               static Perl_check_t nxck_frob;
4970               static OP *myck_frob(pTHX_ OP *op) {
4971                   ...
4972                   op = nxck_frob(aTHX_ op);
4973                   ...
4974                   return op;
4975               }
4976               BOOT:
4977                   wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
4978
4979           If you want to influence compilation of calls to a specific
4980           subroutine, then use "cv_set_call_checker_flags" rather than
4981           hooking checking of all "entersub" ops.
4982
4983            void  wrap_op_checker(Optype opcode, Perl_check_t new_checker,
4984                                  Perl_check_t *old_checker_p)
4985

HV Handling

4987       A HV structure represents a Perl hash.  It consists mainly of an array
4988       of pointers, each of which points to a linked list of HE structures.
4989       The array is indexed by the hash function of the key, so each linked
4990       list represents all the hash entries with the same hash value.  Each HE
4991       contains a pointer to the actual value, plus a pointer to a HEK
4992       structure which holds the key and hash value.
4993
4994       "get_hv"
4995           Returns the HV of the specified Perl hash.  "flags" are passed to
4996           "gv_fetchpv".  If "GV_ADD" is set and the Perl variable does not
4997           exist then it will be created.  If "flags" is zero and the variable
4998           does not exist then "NULL" is returned.
4999
5000           NOTE: the "perl_get_hv()" form is deprecated.
5001
5002            HV*  get_hv(const char *name, I32 flags)
5003
5004       "HEf_SVKEY"
5005           This flag, used in the length slot of hash entries and magic
5006           structures, specifies the structure contains an "SV*" pointer where
5007           a "char*" pointer is to be expected.  (For information only--not to
5008           be used).
5009
5010       "HeHASH"
5011           Returns the computed hash stored in the hash entry.
5012
5013            U32  HeHASH(HE* he)
5014
5015       "HeKEY"
5016           Returns the actual pointer stored in the key slot of the hash
5017           entry.  The pointer may be either "char*" or "SV*", depending on
5018           the value of "HeKLEN()".  Can be assigned to.  The "HePV()" or
5019           "HeSVKEY()" macros are usually preferable for finding the value of
5020           a key.
5021
5022            void*  HeKEY(HE* he)
5023
5024       "HeKLEN"
5025           If this is negative, and amounts to "HEf_SVKEY", it indicates the
5026           entry holds an "SV*" key.  Otherwise, holds the actual length of
5027           the key.  Can be assigned to.  The "HePV()" macro is usually
5028           preferable for finding key lengths.
5029
5030            STRLEN  HeKLEN(HE* he)
5031
5032       "HePV"
5033           Returns the key slot of the hash entry as a "char*" value, doing
5034           any necessary dereferencing of possibly "SV*" keys.  The length of
5035           the string is placed in "len" (this is a macro, so do not use
5036           &len).  If you do not care about what the length of the key is, you
5037           may use the global variable "PL_na", though this is rather less
5038           efficient than using a local variable.  Remember though, that hash
5039           keys in perl are free to contain embedded nulls, so using
5040           "strlen()" or similar is not a good way to find the length of hash
5041           keys.  This is very similar to the "SvPV()" macro described
5042           elsewhere in this document.  See also "HeUTF8".
5043
5044           If you are using "HePV" to get values to pass to "newSVpvn()" to
5045           create a new SV, you should consider using
5046           "newSVhek(HeKEY_hek(he))" as it is more efficient.
5047
5048            char*  HePV(HE* he, STRLEN len)
5049
5050       "HeSVKEY"
5051           Returns the key as an "SV*", or "NULL" if the hash entry does not
5052           contain an "SV*" key.
5053
5054            SV*  HeSVKEY(HE* he)
5055
5056       "HeSVKEY_force"
5057           Returns the key as an "SV*".  Will create and return a temporary
5058           mortal "SV*" if the hash entry contains only a "char*" key.
5059
5060            SV*  HeSVKEY_force(HE* he)
5061
5062       "HeSVKEY_set"
5063           Sets the key to a given "SV*", taking care to set the appropriate
5064           flags to indicate the presence of an "SV*" key, and returns the
5065           same "SV*".
5066
5067            SV*  HeSVKEY_set(HE* he, SV* sv)
5068
5069       "HeUTF8"
5070           Returns whether the "char *" value returned by "HePV" is encoded in
5071           UTF-8, doing any necessary dereferencing of possibly "SV*" keys.
5072           The value returned will be 0 or non-0, not necessarily 1 (or even a
5073           value with any low bits set), so do not blindly assign this to a
5074           "bool" variable, as "bool" may be a typedef for "char".
5075
5076            U32  HeUTF8(HE* he)
5077
5078       "HeVAL"
5079           Returns the value slot (type "SV*") stored in the hash entry.  Can
5080           be assigned to.
5081
5082             SV *foo= HeVAL(hv);
5083             HeVAL(hv)= sv;
5084
5085            SV*  HeVAL(HE* he)
5086
5087       "HV"
5088           Described in perlguts.
5089
5090       "hv_assert"
5091           Check that a hash is in an internally consistent state.
5092
5093           NOTE: "hv_assert" must be explicitly called as "Perl_hv_assert"
5094           with an "aTHX_" parameter.
5095
5096            void  Perl_hv_assert(pTHX_ HV *hv)
5097
5098       "hv_bucket_ratio"
5099           NOTE: "hv_bucket_ratio" is experimental and may change or be
5100           removed without notice.
5101
5102           If the hash is tied dispatches through to the SCALAR tied method,
5103           otherwise if the hash contains no keys returns 0, otherwise returns
5104           a mortal sv containing a string specifying the number of used
5105           buckets, followed by a slash, followed by the number of available
5106           buckets.
5107
5108           This function is expensive, it must scan all of the buckets to
5109           determine which are used, and the count is NOT cached.  In a large
5110           hash this could be a lot of buckets.
5111
5112            SV*  hv_bucket_ratio(HV *hv)
5113
5114       "hv_clear"
5115           Frees all the elements of a hash, leaving it empty.  The XS
5116           equivalent of "%hash = ()".  See also "hv_undef".
5117
5118           See "av_clear" for a note about the hash possibly being invalid on
5119           return.
5120
5121            void  hv_clear(HV *hv)
5122
5123       "hv_clear_placeholders"
5124           Clears any placeholders from a hash.  If a restricted hash has any
5125           of its keys marked as readonly and the key is subsequently deleted,
5126           the key is not actually deleted but is marked by assigning it a
5127           value of &PL_sv_placeholder.  This tags it so it will be ignored by
5128           future operations such as iterating over the hash, but will still
5129           allow the hash to have a value reassigned to the key at some future
5130           point.  This function clears any such placeholder keys from the
5131           hash.  See "Hash::Util::lock_keys()" for an example of its use.
5132
5133            void  hv_clear_placeholders(HV *hv)
5134
5135       "hv_copy_hints_hv"
5136           A specialised version of "newHVhv" for copying "%^H".  "ohv" must
5137           be a pointer to a hash (which may have "%^H" magic, but should be
5138           generally non-magical), or "NULL" (interpreted as an empty hash).
5139           The content of "ohv" is copied to a new hash, which has the
5140           "%^H"-specific magic added to it.  A pointer to the new hash is
5141           returned.
5142
5143            HV *  hv_copy_hints_hv(HV *const ohv)
5144
5145       "hv_delete"
5146           Deletes a key/value pair in the hash.  The value's SV is removed
5147           from the hash, made mortal, and returned to the caller.  The
5148           absolute value of "klen" is the length of the key.  If "klen" is
5149           negative the key is assumed to be in UTF-8-encoded Unicode.  The
5150           "flags" value will normally be zero; if set to "G_DISCARD" then
5151           "NULL" will be returned.  "NULL" will also be returned if the key
5152           is not found.
5153
5154            SV*  hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
5155
5156       "hv_delete_ent"
5157           Deletes a key/value pair in the hash.  The value SV is removed from
5158           the hash, made mortal, and returned to the caller.  The "flags"
5159           value will normally be zero; if set to "G_DISCARD" then "NULL" will
5160           be returned.  "NULL" will also be returned if the key is not found.
5161           "hash" can be a valid precomputed hash value, or 0 to ask for it to
5162           be computed.
5163
5164            SV*  hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
5165
5166       "HvENAME"
5167           Returns the effective name of a stash, or NULL if there is none.
5168           The effective name represents a location in the symbol table where
5169           this stash resides.  It is updated automatically when packages are
5170           aliased or deleted.  A stash that is no longer in the symbol table
5171           has no effective name.  This name is preferable to "HvNAME" for use
5172           in MRO linearisations and isa caches.
5173
5174            char*  HvENAME(HV* stash)
5175
5176       "HvENAMELEN"
5177           Returns the length of the stash's effective name.
5178
5179            STRLEN  HvENAMELEN(HV *stash)
5180
5181       "HvENAMEUTF8"
5182           Returns true if the effective name is in UTF-8 encoding.
5183
5184            unsigned char  HvENAMEUTF8(HV *stash)
5185
5186       "hv_exists"
5187           Returns a boolean indicating whether the specified hash key exists.
5188           The absolute value of "klen" is the length of the key.  If "klen"
5189           is negative the key is assumed to be in UTF-8-encoded Unicode.
5190
5191            bool  hv_exists(HV *hv, const char *key, I32 klen)
5192
5193       "hv_exists_ent"
5194           Returns a boolean indicating whether the specified hash key exists.
5195           "hash" can be a valid precomputed hash value, or 0 to ask for it to
5196           be computed.
5197
5198            bool  hv_exists_ent(HV *hv, SV *keysv, U32 hash)
5199
5200       "hv_fetch"
5201           Returns the SV which corresponds to the specified key in the hash.
5202           The absolute value of "klen" is the length of the key.  If "klen"
5203           is negative the key is assumed to be in UTF-8-encoded Unicode.  If
5204           "lval" is set then the fetch will be part of a store.  This means
5205           that if there is no value in the hash associated with the given
5206           key, then one is created and a pointer to it is returned.  The
5207           "SV*" it points to can be assigned to.  But always check that the
5208           return value is non-null before dereferencing it to an "SV*".
5209
5210           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5211           for more information on how to use this function on tied hashes.
5212
5213            SV**  hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
5214
5215       "hv_fetchs"
5216           Like "hv_fetch", but takes a literal string instead of a
5217           string/length pair.
5218
5219            SV**  hv_fetchs(HV* tb, "key", I32 lval)
5220
5221       "hv_fetch_ent"
5222           Returns the hash entry which corresponds to the specified key in
5223           the hash.  "hash" must be a valid precomputed hash number for the
5224           given "key", or 0 if you want the function to compute it.  IF
5225           "lval" is set then the fetch will be part of a store.  Make sure
5226           the return value is non-null before accessing it.  The return value
5227           when "hv" is a tied hash is a pointer to a static location, so be
5228           sure to make a copy of the structure if you need to store it
5229           somewhere.
5230
5231           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5232           for more information on how to use this function on tied hashes.
5233
5234            HE*  hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
5235
5236       "HvFILL"
5237           See "hv_fill".
5238
5239            STRLEN  HvFILL(HV *const hv)
5240
5241       "hv_fill"
5242           Returns the number of hash buckets that happen to be in use.
5243
5244           This function is wrapped by the macro "HvFILL".
5245
5246           As of perl 5.25 this function is used only for debugging purposes,
5247           and the number of used hash buckets is not in any way cached, thus
5248           this function can be costly to execute as it must iterate over all
5249           the buckets in the hash.
5250
5251           NOTE: "hv_fill" must be explicitly called as "Perl_hv_fill" with an
5252           "aTHX_" parameter.
5253
5254            STRLEN  Perl_hv_fill(pTHX_ HV *const hv)
5255
5256       "hv_iterinit"
5257           Prepares a starting point to traverse a hash table.  Returns the
5258           number of keys in the hash, including placeholders (i.e. the same
5259           as "HvTOTALKEYS(hv)").  The return value is currently only
5260           meaningful for hashes without tie magic.
5261
5262           NOTE: Before version 5.004_65, "hv_iterinit" used to return the
5263           number of hash buckets that happen to be in use.  If you still need
5264           that esoteric value, you can get it through the macro "HvFILL(hv)".
5265
5266            I32  hv_iterinit(HV *hv)
5267
5268       "hv_iterkey"
5269           Returns the key from the current position of the hash iterator.
5270           See "hv_iterinit".
5271
5272            char*  hv_iterkey(HE* entry, I32* retlen)
5273
5274       "hv_iterkeysv"
5275           Returns the key as an "SV*" from the current position of the hash
5276           iterator.  The return value will always be a mortal copy of the
5277           key.  Also see "hv_iterinit".
5278
5279            SV*  hv_iterkeysv(HE* entry)
5280
5281       "hv_iternext"
5282           Returns entries from a hash iterator.  See "hv_iterinit".
5283
5284           You may call "hv_delete" or "hv_delete_ent" on the hash entry that
5285           the iterator currently points to, without losing your place or
5286           invalidating your iterator.  Note that in this case the current
5287           entry is deleted from the hash with your iterator holding the last
5288           reference to it.  Your iterator is flagged to free the entry on the
5289           next call to "hv_iternext", so you must not discard your iterator
5290           immediately else the entry will leak - call "hv_iternext" to
5291           trigger the resource deallocation.
5292
5293            HE*  hv_iternext(HV *hv)
5294
5295       "hv_iternextsv"
5296           Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in one
5297           operation.
5298
5299            SV*  hv_iternextsv(HV *hv, char **key, I32 *retlen)
5300
5301       "hv_iternext_flags"
5302           NOTE: "hv_iternext_flags" is experimental and may change or be
5303           removed without notice.
5304
5305           Returns entries from a hash iterator.  See "hv_iterinit" and
5306           "hv_iternext".  The "flags" value will normally be zero; if
5307           "HV_ITERNEXT_WANTPLACEHOLDERS" is set the placeholders keys (for
5308           restricted hashes) will be returned in addition to normal keys.  By
5309           default placeholders are automatically skipped over.  Currently a
5310           placeholder is implemented with a value that is &PL_sv_placeholder.
5311           Note that the implementation of placeholders and restricted hashes
5312           may change, and the implementation currently is insufficiently
5313           abstracted for any change to be tidy.
5314
5315            HE*  hv_iternext_flags(HV *hv, I32 flags)
5316
5317       "hv_iterval"
5318           Returns the value from the current position of the hash iterator.
5319           See "hv_iterkey".
5320
5321            SV*  hv_iterval(HV *hv, HE *entry)
5322
5323       "hv_magic"
5324           Adds magic to a hash.  See "sv_magic".
5325
5326            void  hv_magic(HV *hv, GV *gv, int how)
5327
5328       "HvNAME"
5329           Returns the package name of a stash, or "NULL" if "stash" isn't a
5330           stash.  See "SvSTASH", "CvSTASH".
5331
5332            char*  HvNAME(HV* stash)
5333
5334       "HvNAMELEN"
5335           Returns the length of the stash's name.
5336
5337           Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them
5338
5339            STRLEN  HvNAMELEN(HV *stash)
5340
5341       "HvNAMEUTF8"
5342           Returns true if the name is in UTF-8 encoding.
5343
5344            unsigned char  HvNAMEUTF8(HV *stash)
5345
5346       "hv_scalar"
5347           Evaluates the hash in scalar context and returns the result.
5348
5349           When the hash is tied dispatches through to the SCALAR method,
5350           otherwise returns a mortal SV containing the number of keys in the
5351           hash.
5352
5353           Note, prior to 5.25 this function returned what is now returned by
5354           the hv_bucket_ratio() function.
5355
5356            SV*  hv_scalar(HV *hv)
5357
5358       "hv_store"
5359           Stores an SV in a hash.  The hash key is specified as "key" and the
5360           absolute value of "klen" is the length of the key.  If "klen" is
5361           negative the key is assumed to be in UTF-8-encoded Unicode.  The
5362           "hash" parameter is the precomputed hash value; if it is zero then
5363           Perl will compute it.
5364
5365           The return value will be "NULL" if the operation failed or if the
5366           value did not need to be actually stored within the hash (as in the
5367           case of tied hashes).  Otherwise it can be dereferenced to get the
5368           original "SV*".  Note that the caller is responsible for suitably
5369           incrementing the reference count of "val" before the call, and
5370           decrementing it if the function returned "NULL".  Effectively a
5371           successful "hv_store" takes ownership of one reference to "val".
5372           This is usually what you want; a newly created SV has a reference
5373           count of one, so if all your code does is create SVs then store
5374           them in a hash, "hv_store" will own the only reference to the new
5375           SV, and your code doesn't need to do anything further to tidy up.
5376           "hv_store" is not implemented as a call to "hv_store_ent", and does
5377           not create a temporary SV for the key, so if your key data is not
5378           already in SV form then use "hv_store" in preference to
5379           "hv_store_ent".
5380
5381           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5382           for more information on how to use this function on tied hashes.
5383
5384            SV**  hv_store(HV *hv, const char *key, I32 klen, SV *val,
5385                           U32 hash)
5386
5387       "hv_stores"
5388           Like "hv_store", but takes a literal string instead of a
5389           string/length pair and omits the hash parameter.
5390
5391            SV**  hv_stores(HV* tb, "key", SV* val)
5392
5393       "hv_store_ent"
5394           Stores "val" in a hash.  The hash key is specified as "key".  The
5395           "hash" parameter is the precomputed hash value; if it is zero then
5396           Perl will compute it.  The return value is the new hash entry so
5397           created.  It will be "NULL" if the operation failed or if the value
5398           did not need to be actually stored within the hash (as in the case
5399           of tied hashes).  Otherwise the contents of the return value can be
5400           accessed using the "He?" macros described here.  Note that the
5401           caller is responsible for suitably incrementing the reference count
5402           of "val" before the call, and decrementing it if the function
5403           returned NULL.  Effectively a successful "hv_store_ent" takes
5404           ownership of one reference to "val".  This is usually what you
5405           want; a newly created SV has a reference count of one, so if all
5406           your code does is create SVs then store them in a hash, "hv_store"
5407           will own the only reference to the new SV, and your code doesn't
5408           need to do anything further to tidy up.  Note that "hv_store_ent"
5409           only reads the "key"; unlike "val" it does not take ownership of
5410           it, so maintaining the correct reference count on "key" is entirely
5411           the caller's responsibility.  The reason it does not take
5412           ownership, is that "key" is not used after this function returns,
5413           and so can be freed immediately.  "hv_store" is not implemented as
5414           a call to "hv_store_ent", and does not create a temporary SV for
5415           the key, so if your key data is not already in SV form then use
5416           "hv_store" in preference to "hv_store_ent".
5417
5418           See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5419           for more information on how to use this function on tied hashes.
5420
5421            HE*  hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
5422
5423       "hv_undef"
5424           Undefines the hash.  The XS equivalent of "undef(%hash)".
5425
5426           As well as freeing all the elements of the hash (like
5427           "hv_clear()"), this also frees any auxiliary data and storage
5428           associated with the hash.
5429
5430           See "av_clear" for a note about the hash possibly being invalid on
5431           return.
5432
5433            void  hv_undef(HV *hv)
5434
5435       "MGVTBL"
5436           Described in perlguts.
5437
5438       "newHV"
5439           Creates a new HV.  The reference count is set to 1.
5440
5441            HV*  newHV()
5442
5443       "Nullhv"
5444           "DEPRECATED!"  It is planned to remove "Nullhv" from a future
5445           release of Perl.  Do not use it for new code; remove it from
5446           existing code.
5447
5448           Null HV pointer.
5449
5450           (deprecated - use "(HV *)NULL" instead)
5451
5452       "PERL_HASH"
5453           Described in perlguts.
5454
5455            void  PERL_HASH(U32 hash, char *key, STRLEN klen)
5456
5457       "PERL_MAGIC_arylen"
5458       "PERL_MAGIC_arylen_p"
5459       "PERL_MAGIC_backref"
5460       "PERL_MAGIC_bm"
5461       "PERL_MAGIC_checkcall"
5462       "PERL_MAGIC_collxfrm"
5463       "PERL_MAGIC_dbfile"
5464       "PERL_MAGIC_dbline"
5465       "PERL_MAGIC_debugvar"
5466       "PERL_MAGIC_defelem"
5467       "PERL_MAGIC_env"
5468       "PERL_MAGIC_envelem"
5469       "PERL_MAGIC_ext"
5470       "PERL_MAGIC_fm"
5471       "PERL_MAGIC_hints"
5472       "PERL_MAGIC_hintselem"
5473       "PERL_MAGIC_isa"
5474       "PERL_MAGIC_isaelem"
5475       "PERL_MAGIC_lvref"
5476       "PERL_MAGIC_nkeys"
5477       "PERL_MAGIC_nonelem"
5478       "PERL_MAGIC_overload_table"
5479       "PERL_MAGIC_pos"
5480       "PERL_MAGIC_qr"
5481       "PERL_MAGIC_regdata"
5482       "PERL_MAGIC_regdatum"
5483       "PERL_MAGIC_regex_global"
5484       "PERL_MAGIC_rhash"
5485       "PERL_MAGIC_shared"
5486       "PERL_MAGIC_shared_scalar"
5487       "PERL_MAGIC_sig"
5488       "PERL_MAGIC_sigelem"
5489       "PERL_MAGIC_substr"
5490       "PERL_MAGIC_sv"
5491       "PERL_MAGIC_symtab"
5492       "PERL_MAGIC_taint"
5493       "PERL_MAGIC_tied"
5494       "PERL_MAGIC_tiedelem"
5495       "PERL_MAGIC_tiedscalar"
5496       "PERL_MAGIC_utf8"
5497       "PERL_MAGIC_uvar"
5498       "PERL_MAGIC_uvar_elem"
5499       "PERL_MAGIC_vec"
5500       "PERL_MAGIC_vstring"
5501           Described in perlguts.
5502
5503       "PL_modglobal"
5504           "PL_modglobal" is a general purpose, interpreter global HV for use
5505           by extensions that need to keep information on a per-interpreter
5506           basis.  In a pinch, it can also be used as a symbol table for
5507           extensions to share data among each other.  It is a good idea to
5508           use keys prefixed by the package name of the extension that owns
5509           the data.
5510
5511           On threaded perls, each thread has an independent copy of this
5512           variable; each initialized at creation time with the current value
5513           of the creating thread's copy.
5514
5515            HV*  PL_modglobal
5516

Input/Output

5518       "PerlIO_apply_layers"
5519           Described in perlapio.
5520
5521            int  PerlIO_apply_layers(PerlIO *f, const char *mode,
5522                                     const char *layers)
5523
5524       "PerlIO_binmode"
5525           Described in perlapio.
5526
5527            int  PerlIO_binmode(PerlIO *f, int ptype, int imode,
5528                                const char *layers)
5529
5530       "PerlIO_canset_cnt"
5531           Described in perlapio.
5532
5533            int  PerlIO_canset_cnt(PerlIO *f)
5534
5535       "PerlIO_clearerr"
5536           Described in perlapio.
5537
5538            void  PerlIO_clearerr(PerlIO *f)
5539
5540       "PerlIO_close"
5541           Described in perlapio.
5542
5543            int  PerlIO_close(PerlIO *f)
5544
5545       "PerlIO_debug"
5546           Described in perlapio.
5547
5548            void  PerlIO_debug(const char *fmt, ...)
5549
5550       "PerlIO_eof"
5551           Described in perlapio.
5552
5553            int  PerlIO_eof(PerlIO *f)
5554
5555       "PerlIO_error"
5556           Described in perlapio.
5557
5558            int  PerlIO_error(PerlIO *f)
5559
5560       "PerlIO_exportFILE"
5561           Described in perlapio.
5562
5563            FILE  *  PerlIO_exportFILE(PerlIO *f, const char *mode)
5564
5565       "PerlIO_fast_gets"
5566           Described in perlapio.
5567
5568            int  PerlIO_fast_gets(PerlIO *f)
5569
5570       "PerlIO_fdopen"
5571           Described in perlapio.
5572
5573            PerlIO*  PerlIO_fdopen(int fd, const char *mode)
5574
5575       "PerlIO_fileno"
5576           Described in perlapio.
5577
5578            int  PerlIO_fileno(PerlIO *f)
5579
5580       "PerlIO_findFILE"
5581           Described in perlapio.
5582
5583            FILE  *  PerlIO_findFILE(PerlIO *f)
5584
5585       "PerlIO_flush"
5586           Described in perlapio.
5587
5588            int  PerlIO_flush(PerlIO *f)
5589
5590       "PERLIO_F_APPEND"
5591       "PERLIO_F_CANREAD"
5592       "PERLIO_F_CANWRITE"
5593       "PERLIO_F_CRLF"
5594       "PERLIO_F_EOF"
5595       "PERLIO_F_ERROR"
5596       "PERLIO_F_FASTGETS"
5597       "PERLIO_F_LINEBUF"
5598       "PERLIO_F_OPEN"
5599       "PERLIO_F_RDBUF"
5600       "PERLIO_F_TEMP"
5601       "PERLIO_F_TRUNCATE"
5602       "PERLIO_F_UNBUF"
5603       "PERLIO_F_UTF8"
5604       "PERLIO_F_WRBUF"
5605           Described in perliol.
5606
5607       "PerlIO_getc"
5608           Described in perlapio.
5609
5610            int  PerlIO_getc(PerlIO *d)
5611
5612       "PerlIO_getpos"
5613           Described in perlapio.
5614
5615            int  PerlIO_getpos(PerlIO *f, SV *save)
5616
5617       "PerlIO_get_base"
5618           Described in perlapio.
5619
5620            STDCHAR *  PerlIO_get_base(PerlIO *f)
5621
5622       "PerlIO_get_bufsiz"
5623           Described in perlapio.
5624
5625            SSize_t  PerlIO_get_bufsiz(PerlIO *f)
5626
5627       "PerlIO_get_cnt"
5628           Described in perlapio.
5629
5630            SSize_t  PerlIO_get_cnt(PerlIO *f)
5631
5632       "PerlIO_get_ptr"
5633           Described in perlapio.
5634
5635            STDCHAR *  PerlIO_get_ptr(PerlIO *f)
5636
5637       "PerlIO_has_base"
5638           Described in perlapio.
5639
5640            int  PerlIO_has_base(PerlIO *f)
5641
5642       "PerlIO_has_cntptr"
5643           Described in perlapio.
5644
5645            int  PerlIO_has_cntptr(PerlIO *f)
5646
5647       "PerlIO_importFILE"
5648           Described in perlapio.
5649
5650            PerlIO*  PerlIO_importFILE(FILE *stdio, const char *mode)
5651
5652       "PERLIO_K_BUFFERED"
5653       "PERLIO_K_CANCRLF"
5654       "PERLIO_K_FASTGETS"
5655       "PERLIO_K_MULTIARG"
5656       "PERLIO_K_RAW"
5657           Described in perliol.
5658
5659       "PerlIO_open"
5660           Described in perlapio.
5661
5662            PerlIO*  PerlIO_open(const char *path, const char *mode)
5663
5664       "PerlIO_printf"
5665           Described in perlapio.
5666
5667            int  PerlIO_printf(PerlIO *f, const char *fmt, ...)
5668
5669       "PerlIO_putc"
5670           Described in perlapio.
5671
5672            int  PerlIO_putc(PerlIO *f, int ch)
5673
5674       "PerlIO_puts"
5675           Described in perlapio.
5676
5677            int  PerlIO_puts(PerlIO *f, const char *string)
5678
5679       "PerlIO_read"
5680           Described in perlapio.
5681
5682            SSize_t  PerlIO_read(PerlIO *f, void *vbuf, Size_t count)
5683
5684       "PerlIO_releaseFILE"
5685           Described in perlapio.
5686
5687            void  PerlIO_releaseFILE(PerlIO *f, FILE *stdio)
5688
5689       "PerlIO_reopen"
5690           Described in perlapio.
5691
5692            PerlIO *  PerlIO_reopen(const char *path, const char *mode,
5693                                    PerlIO *old)
5694
5695       "PerlIO_rewind"
5696           Described in perlapio.
5697
5698            void  PerlIO_rewind(PerlIO *f)
5699
5700       "PerlIO_seek"
5701           Described in perlapio.
5702
5703            int  PerlIO_seek(PerlIO *f, Off_t offset, int whence)
5704
5705       "PerlIO_setlinebuf"
5706           Described in perlapio.
5707
5708            void  PerlIO_setlinebuf(PerlIO *f)
5709
5710       "PerlIO_setpos"
5711           Described in perlapio.
5712
5713            int  PerlIO_setpos(PerlIO *f, SV *saved)
5714
5715       "PerlIO_set_cnt"
5716           Described in perlapio.
5717
5718            void  PerlIO_set_cnt(PerlIO *f, SSize_t cnt)
5719
5720       "PerlIO_set_ptrcnt"
5721           Described in perlapio.
5722
5723            void  PerlIO_set_ptrcnt(PerlIO *f, STDCHAR *ptr, SSize_t cnt)
5724
5725       "PerlIO_stderr"
5726           Described in perlapio.
5727
5728            PerlIO *  PerlIO_stderr()
5729
5730       "PerlIO_stdin"
5731           Described in perlapio.
5732
5733            PerlIO *  PerlIO_stdin()
5734
5735       "PerlIO_stdout"
5736           Described in perlapio.
5737
5738            PerlIO *  PerlIO_stdout()
5739
5740       "PerlIO_stdoutf"
5741           Described in perlapio.
5742
5743            int  PerlIO_stdoutf(const char *fmt, ...)
5744
5745       "PerlIO_tell"
5746           Described in perlapio.
5747
5748            Off_t  PerlIO_tell(PerlIO *f)
5749
5750       "PerlIO_ungetc"
5751           Described in perlapio.
5752
5753            int  PerlIO_ungetc(PerlIO *f, int ch)
5754
5755       "PerlIO_vprintf"
5756           Described in perlapio.
5757
5758            int  PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args)
5759
5760       "PerlIO_write"
5761           Described in perlapio.
5762
5763            SSize_t  PerlIO_write(PerlIO *f, const void *vbuf, Size_t count)
5764
5765       "PL_maxsysfd"
5766           Described in perliol.
5767

Integer configuration values

5769       "CASTI32"
5770           This symbol is defined if the C compiler can cast negative or large
5771           floating point numbers to 32-bit ints.
5772
5773       "HAS_INT64_T"
5774           This symbol will defined if the C compiler supports "int64_t".
5775           Usually the inttypes.h needs to be included, but sometimes
5776           sys/types.h is enough.
5777
5778       "HAS_LONG_LONG"
5779           This symbol will be defined if the C compiler supports long long.
5780
5781       "HAS_QUAD"
5782           This symbol, if defined, tells that there's a 64-bit integer type,
5783           "Quad_t", and its unsigned counterpart, "Uquad_t". "QUADKIND" will
5784           be one of "QUAD_IS_INT", "QUAD_IS_LONG", "QUAD_IS_LONG_LONG",
5785           "QUAD_IS_INT64_T", or "QUAD_IS___INT64".
5786
5787       "HE"
5788           Described in perlguts.
5789
5790       "I8"
5791       "I16"
5792       "I32"
5793       "I64"
5794       "IV"
5795           Described in perlguts.
5796
5797       "I32SIZE"
5798           This symbol contains the "sizeof(I32)".
5799
5800       "I32TYPE"
5801           This symbol defines the C type used for Perl's I32.
5802
5803       "I64SIZE"
5804           This symbol contains the "sizeof(I64)".
5805
5806       "I64TYPE"
5807           This symbol defines the C type used for Perl's I64.
5808
5809       "I16SIZE"
5810           This symbol contains the "sizeof(I16)".
5811
5812       "I16TYPE"
5813           This symbol defines the C type used for Perl's I16.
5814
5815       "INT16_C"
5816       "INT32_C"
5817       "INT64_C"
5818           Returns a token the C compiler recognizes for the constant "number"
5819           of the corresponding integer type on the machine.
5820
5821           If the machine does not have a 64-bit type, "INT64_C" is undefined.
5822           Use "INTMAX_C" to get the largest type available on the platform.
5823
5824            I16  INT16_C(number)
5825            I32  INT32_C(number)
5826            I64  INT64_C(number)
5827
5828       "INTMAX_C"
5829           Returns a token the C compiler recognizes for the constant "number"
5830           of the widest integer type on the machine.  For example, if the
5831           machine has "long long"s, "INTMAX_C(-1)" would yield
5832
5833            -1LL
5834
5835           See also, for example, "INT32_C".
5836
5837           Use "IV" to declare variables of the maximum usable size on this
5838           platform.
5839
5840              INTMAX_C(number)
5841
5842       "INTSIZE"
5843           This symbol contains the value of "sizeof(int)" so that the C
5844           preprocessor can make decisions based on it.
5845
5846       "I8SIZE"
5847           This symbol contains the "sizeof(I8)".
5848
5849       "I8TYPE"
5850           This symbol defines the C type used for Perl's I8.
5851
5852       "IV_MAX"
5853           The largest signed integer that fits in an IV on this platform.
5854
5855            IV  IV_MAX
5856
5857       "IV_MIN"
5858           The negative signed integer furthest away from 0 that fits in an IV
5859           on this platform.
5860
5861            IV  IV_MIN
5862
5863       "IVSIZE"
5864           This symbol contains the "sizeof(IV)".
5865
5866       "IVTYPE"
5867           This symbol defines the C type used for Perl's IV.
5868
5869       "line_t"
5870           The typedef to use to declare variables that are to hold line
5871           numbers.
5872
5873       "LONGLONGSIZE"
5874           This symbol contains the size of a long long, so that the C
5875           preprocessor can make decisions based on it.  It is only defined if
5876           the system supports long long.
5877
5878       "LONGSIZE"
5879           This symbol contains the value of "sizeof(long)" so that the C
5880           preprocessor can make decisions based on it.
5881
5882       "memzero"
5883           Set the "l" bytes starting at *d to all zeroes.
5884
5885            void  memzero(void * d, Size_t l)
5886
5887       "NV"
5888           Described in perlguts.
5889
5890       "PERL_INT_FAST8_T"
5891       "PERL_INT_FAST16_T"
5892       "PERL_UINT_FAST8_T"
5893       "PERL_UINT_FAST16_T"
5894           These are equivalent to the correspondingly-named C99 typedefs on
5895           platforms that have those; they evaluate to "int" and "unsigned
5896           int" on platforms that don't, so that you can portably take
5897           advantage of this C99 feature.
5898
5899       "PERL_INT_MAX"
5900       "PERL_INT_MIN"
5901       "PERL_LONG_MAX"
5902       "PERL_LONG_MIN"
5903       "PERL_SHORT_MAX"
5904       "PERL_SHORT_MIN"
5905       "PERL_UCHAR_MAX"
5906       "PERL_UCHAR_MIN"
5907       "PERL_UINT_MAX"
5908       "PERL_UINT_MIN"
5909       "PERL_ULONG_MAX"
5910       "PERL_ULONG_MIN"
5911       "PERL_USHORT_MAX"
5912       "PERL_USHORT_MIN"
5913       "PERL_QUAD_MAX"
5914       "PERL_QUAD_MIN"
5915       "PERL_UQUAD_MAX"
5916       "PERL_UQUAD_MIN"
5917           These give the largest and smallest number representable in the
5918           current platform in variables of the corresponding types.
5919
5920           For signed types, the smallest representable number is the most
5921           negative number, the one furthest away from zero.
5922
5923           For C99 and later compilers, these correspond to things like
5924           "INT_MAX", which are available to the C code.  But these constants,
5925           furnished by Perl, allow code compiled on earlier compilers to
5926           portably have access to the same constants.
5927
5928       "SHORTSIZE"
5929           This symbol contains the value of "sizeof(short)" so that the C
5930           preprocessor can make decisions based on it.
5931
5932       "STRLEN"
5933           Described in perlguts.
5934
5935       "U8"
5936       "U16"
5937       "U32"
5938       "U64"
5939       "UV"
5940           Described in perlguts.
5941
5942       "U32SIZE"
5943           This symbol contains the "sizeof(U32)".
5944
5945       "U32TYPE"
5946           This symbol defines the C type used for Perl's U32.
5947
5948       "U64SIZE"
5949           This symbol contains the "sizeof(U64)".
5950
5951       "U64TYPE"
5952           This symbol defines the C type used for Perl's U64.
5953
5954       "U16SIZE"
5955           This symbol contains the "sizeof(U16)".
5956
5957       "U16TYPE"
5958           This symbol defines the C type used for Perl's U16.
5959
5960       "UINT16_C"
5961       "UINT32_C"
5962       "UINT64_C"
5963           Returns a token the C compiler recognizes for the constant "number"
5964           of the corresponding unsigned integer type on the machine.
5965
5966           If the machine does not have a 64-bit type, "UINT64_C" is
5967           undefined.  Use "UINTMAX_C" to get the largest type available on
5968           the platform.
5969
5970            U16  UINT16_C(number)
5971            U32  UINT32_C(number)
5972            U64  UINT64_C(number)
5973
5974       "UINTMAX_C"
5975           Returns a token the C compiler recognizes for the constant "number"
5976           of the widest unsigned integer type on the machine.  For example,
5977           if the machine has "long"s, UINTMAX_C(1) would yield
5978
5979            1UL
5980
5981           See also, for example, "UINT32_C".
5982
5983           Use "UV" to declare variables of the maximum usable size on this
5984           platform.
5985
5986              UINTMAX_C(number)
5987
5988       "U8SIZE"
5989           This symbol contains the "sizeof(U8)".
5990
5991       "U8TYPE"
5992           This symbol defines the C type used for Perl's U8.
5993
5994       "UV_MAX"
5995           The largest unsigned integer that fits in a UV on this platform.
5996
5997            UV  UV_MAX
5998
5999       "UV_MIN"
6000           The smallest unsigned integer that fits in a UV on this platform.
6001           It should equal zero.
6002
6003            UV  UV_MIN
6004
6005       "UVSIZE"
6006           This symbol contains the "sizeof(UV)".
6007
6008       "UVTYPE"
6009           This symbol defines the C type used for Perl's UV.
6010
6011       "WIDEST_UTYPE"
6012           Yields the widest unsigned integer type on the platform, currently
6013           either "U32" or "U64".  This can be used in declarations such as
6014
6015            WIDEST_UTYPE my_uv;
6016
6017           or casts
6018
6019            my_uv = (WIDEST_UTYPE) val;
6020

Lexer interface

6022       This is the lower layer of the Perl parser, managing characters and
6023       tokens.
6024
6025       "lex_bufutf8"
6026           NOTE: "lex_bufutf8" is experimental and may change or be removed
6027           without notice.
6028
6029           Indicates whether the octets in the lexer buffer
6030           ("PL_parser->linestr") should be interpreted as the UTF-8 encoding
6031           of Unicode characters.  If not, they should be interpreted as
6032           Latin-1 characters.  This is analogous to the "SvUTF8" flag for
6033           scalars.
6034
6035           In UTF-8 mode, it is not guaranteed that the lexer buffer actually
6036           contains valid UTF-8.  Lexing code must be robust in the face of
6037           invalid encoding.
6038
6039           The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
6040           significant, but not the whole story regarding the input character
6041           encoding.  Normally, when a file is being read, the scalar contains
6042           octets and its "SvUTF8" flag is off, but the octets should be
6043           interpreted as UTF-8 if the "use utf8" pragma is in effect.  During
6044           a string eval, however, the scalar may have the "SvUTF8" flag on,
6045           and in this case its octets should be interpreted as UTF-8 unless
6046           the "use bytes" pragma is in effect.  This logic may change in the
6047           future; use this function instead of implementing the logic
6048           yourself.
6049
6050            bool  lex_bufutf8()
6051
6052       "lex_discard_to"
6053           NOTE: "lex_discard_to" is experimental and may change or be removed
6054           without notice.
6055
6056           Discards the first part of the "PL_parser->linestr" buffer, up to
6057           "ptr".  The remaining content of the buffer will be moved, and all
6058           pointers into the buffer updated appropriately.  "ptr" must not be
6059           later in the buffer than the position of "PL_parser->bufptr": it is
6060           not permitted to discard text that has yet to be lexed.
6061
6062           Normally it is not necessarily to do this directly, because it
6063           suffices to use the implicit discarding behaviour of
6064           "lex_next_chunk" and things based on it.  However, if a token
6065           stretches across multiple lines, and the lexing code has kept
6066           multiple lines of text in the buffer for that purpose, then after
6067           completion of the token it would be wise to explicitly discard the
6068           now-unneeded earlier lines, to avoid future multi-line tokens
6069           growing the buffer without bound.
6070
6071            void  lex_discard_to(char* ptr)
6072
6073       "lex_grow_linestr"
6074           NOTE: "lex_grow_linestr" is experimental and may change or be
6075           removed without notice.
6076
6077           Reallocates the lexer buffer ("PL_parser->linestr") to accommodate
6078           at least "len" octets (including terminating "NUL").  Returns a
6079           pointer to the reallocated buffer.  This is necessary before making
6080           any direct modification of the buffer that would increase its
6081           length.  "lex_stuff_pvn" provides a more convenient way to insert
6082           text into the buffer.
6083
6084           Do not use "SvGROW" or "sv_grow" directly on "PL_parser->linestr";
6085           this function updates all of the lexer's variables that point
6086           directly into the buffer.
6087
6088            char*  lex_grow_linestr(STRLEN len)
6089
6090       "lex_next_chunk"
6091           NOTE: "lex_next_chunk" is experimental and may change or be removed
6092           without notice.
6093
6094           Reads in the next chunk of text to be lexed, appending it to
6095           "PL_parser->linestr".  This should be called when lexing code has
6096           looked to the end of the current chunk and wants to know more.  It
6097           is usual, but not necessary, for lexing to have consumed the
6098           entirety of the current chunk at this time.
6099
6100           If "PL_parser->bufptr" is pointing to the very end of the current
6101           chunk (i.e., the current chunk has been entirely consumed),
6102           normally the current chunk will be discarded at the same time that
6103           the new chunk is read in.  If "flags" has the "LEX_KEEP_PREVIOUS"
6104           bit set, the current chunk will not be discarded.  If the current
6105           chunk has not been entirely consumed, then it will not be discarded
6106           regardless of the flag.
6107
6108           Returns true if some new text was added to the buffer, or false if
6109           the buffer has reached the end of the input text.
6110
6111            bool  lex_next_chunk(U32 flags)
6112
6113       "lex_peek_unichar"
6114           NOTE: "lex_peek_unichar" is experimental and may change or be
6115           removed without notice.
6116
6117           Looks ahead one (Unicode) character in the text currently being
6118           lexed.  Returns the codepoint (unsigned integer value) of the next
6119           character, or -1 if lexing has reached the end of the input text.
6120           To consume the peeked character, use "lex_read_unichar".
6121
6122           If the next character is in (or extends into) the next chunk of
6123           input text, the next chunk will be read in.  Normally the current
6124           chunk will be discarded at the same time, but if "flags" has the
6125           "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
6126           discarded.
6127
6128           If the input is being interpreted as UTF-8 and a UTF-8 encoding
6129           error is encountered, an exception is generated.
6130
6131            I32  lex_peek_unichar(U32 flags)
6132
6133       "lex_read_space"
6134           NOTE: "lex_read_space" is experimental and may change or be removed
6135           without notice.
6136
6137           Reads optional spaces, in Perl style, in the text currently being
6138           lexed.  The spaces may include ordinary whitespace characters and
6139           Perl-style comments.  "#line" directives are processed if
6140           encountered.  "PL_parser->bufptr" is moved past the spaces, so that
6141           it points at a non-space character (or the end of the input text).
6142
6143           If spaces extend into the next chunk of input text, the next chunk
6144           will be read in.  Normally the current chunk will be discarded at
6145           the same time, but if "flags" has the "LEX_KEEP_PREVIOUS" bit set,
6146           then the current chunk will not be discarded.
6147
6148            void  lex_read_space(U32 flags)
6149
6150       "lex_read_to"
6151           NOTE: "lex_read_to" is experimental and may change or be removed
6152           without notice.
6153
6154           Consume text in the lexer buffer, from "PL_parser->bufptr" up to
6155           "ptr".  This advances "PL_parser->bufptr" to match "ptr",
6156           performing the correct bookkeeping whenever a newline character is
6157           passed.  This is the normal way to consume lexed text.
6158
6159           Interpretation of the buffer's octets can be abstracted out by
6160           using the slightly higher-level functions "lex_peek_unichar" and
6161           "lex_read_unichar".
6162
6163            void  lex_read_to(char* ptr)
6164
6165       "lex_read_unichar"
6166           NOTE: "lex_read_unichar" is experimental and may change or be
6167           removed without notice.
6168
6169           Reads the next (Unicode) character in the text currently being
6170           lexed.  Returns the codepoint (unsigned integer value) of the
6171           character read, and moves "PL_parser->bufptr" past the character,
6172           or returns -1 if lexing has reached the end of the input text.  To
6173           non-destructively examine the next character, use
6174           "lex_peek_unichar" instead.
6175
6176           If the next character is in (or extends into) the next chunk of
6177           input text, the next chunk will be read in.  Normally the current
6178           chunk will be discarded at the same time, but if "flags" has the
6179           "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
6180           discarded.
6181
6182           If the input is being interpreted as UTF-8 and a UTF-8 encoding
6183           error is encountered, an exception is generated.
6184
6185            I32  lex_read_unichar(U32 flags)
6186
6187       "lex_start"
6188           NOTE: "lex_start" is experimental and may change or be removed
6189           without notice.
6190
6191           Creates and initialises a new lexer/parser state object, supplying
6192           a context in which to lex and parse from a new source of Perl code.
6193           A pointer to the new state object is placed in "PL_parser".  An
6194           entry is made on the save stack so that upon unwinding, the new
6195           state object will be destroyed and the former value of "PL_parser"
6196           will be restored.  Nothing else need be done to clean up the
6197           parsing context.
6198
6199           The code to be parsed comes from "line" and "rsfp".  "line", if
6200           non-null, provides a string (in SV form) containing code to be
6201           parsed.  A copy of the string is made, so subsequent modification
6202           of "line" does not affect parsing.  "rsfp", if non-null, provides
6203           an input stream from which code will be read to be parsed.  If both
6204           are non-null, the code in "line" comes first and must consist of
6205           complete lines of input, and "rsfp" supplies the remainder of the
6206           source.
6207
6208           The "flags" parameter is reserved for future use.  Currently it is
6209           only used by perl internally, so extensions should always pass
6210           zero.
6211
6212            void  lex_start(SV* line, PerlIO *rsfp, U32 flags)
6213
6214       "lex_stuff_pv"
6215           NOTE: "lex_stuff_pv" is experimental and may change or be removed
6216           without notice.
6217
6218           Insert characters into the lexer buffer ("PL_parser->linestr"),
6219           immediately after the current lexing point ("PL_parser->bufptr"),
6220           reallocating the buffer if necessary.  This means that lexing code
6221           that runs later will see the characters as if they had appeared in
6222           the input.  It is not recommended to do this as part of normal
6223           parsing, and most uses of this facility run the risk of the
6224           inserted characters being interpreted in an unintended manner.
6225
6226           The string to be inserted is represented by octets starting at "pv"
6227           and continuing to the first nul.  These octets are interpreted as
6228           either UTF-8 or Latin-1, according to whether the "LEX_STUFF_UTF8"
6229           flag is set in "flags".  The characters are recoded for the lexer
6230           buffer, according to how the buffer is currently being interpreted
6231           ("lex_bufutf8").  If it is not convenient to nul-terminate a string
6232           to be inserted, the "lex_stuff_pvn" function is more appropriate.
6233
6234            void  lex_stuff_pv(const char* pv, U32 flags)
6235
6236       "lex_stuff_pvn"
6237           NOTE: "lex_stuff_pvn" is experimental and may change or be removed
6238           without notice.
6239
6240           Insert characters into the lexer buffer ("PL_parser->linestr"),
6241           immediately after the current lexing point ("PL_parser->bufptr"),
6242           reallocating the buffer if necessary.  This means that lexing code
6243           that runs later will see the characters as if they had appeared in
6244           the input.  It is not recommended to do this as part of normal
6245           parsing, and most uses of this facility run the risk of the
6246           inserted characters being interpreted in an unintended manner.
6247
6248           The string to be inserted is represented by "len" octets starting
6249           at "pv".  These octets are interpreted as either UTF-8 or Latin-1,
6250           according to whether the "LEX_STUFF_UTF8" flag is set in "flags".
6251           The characters are recoded for the lexer buffer, according to how
6252           the buffer is currently being interpreted ("lex_bufutf8").  If a
6253           string to be inserted is available as a Perl scalar, the
6254           "lex_stuff_sv" function is more convenient.
6255
6256            void  lex_stuff_pvn(const char* pv, STRLEN len, U32 flags)
6257
6258       "lex_stuff_pvs"
6259           NOTE: "lex_stuff_pvs" is experimental and may change or be removed
6260           without notice.
6261
6262           Like "lex_stuff_pvn", but takes a literal string instead of a
6263           string/length pair.
6264
6265            void  lex_stuff_pvs("pv", U32 flags)
6266
6267       "lex_stuff_sv"
6268           NOTE: "lex_stuff_sv" is experimental and may change or be removed
6269           without notice.
6270
6271           Insert characters into the lexer buffer ("PL_parser->linestr"),
6272           immediately after the current lexing point ("PL_parser->bufptr"),
6273           reallocating the buffer if necessary.  This means that lexing code
6274           that runs later will see the characters as if they had appeared in
6275           the input.  It is not recommended to do this as part of normal
6276           parsing, and most uses of this facility run the risk of the
6277           inserted characters being interpreted in an unintended manner.
6278
6279           The string to be inserted is the string value of "sv".  The
6280           characters are recoded for the lexer buffer, according to how the
6281           buffer is currently being interpreted ("lex_bufutf8").  If a string
6282           to be inserted is not already a Perl scalar, the "lex_stuff_pvn"
6283           function avoids the need to construct a scalar.
6284
6285            void  lex_stuff_sv(SV* sv, U32 flags)
6286
6287       "lex_unstuff"
6288           NOTE: "lex_unstuff" is experimental and may change or be removed
6289           without notice.
6290
6291           Discards text about to be lexed, from "PL_parser->bufptr" up to
6292           "ptr".  Text following "ptr" will be moved, and the buffer
6293           shortened.  This hides the discarded text from any lexing code that
6294           runs later, as if the text had never appeared.
6295
6296           This is not the normal way to consume lexed text.  For that, use
6297           "lex_read_to".
6298
6299            void  lex_unstuff(char* ptr)
6300
6301       "parse_arithexpr"
6302           NOTE: "parse_arithexpr" is experimental and may change or be
6303           removed without notice.
6304
6305           Parse a Perl arithmetic expression.  This may contain operators of
6306           precedence down to the bit shift operators.  The expression must be
6307           followed (and thus terminated) either by a comparison or lower-
6308           precedence operator or by something that would normally terminate
6309           an expression such as semicolon.  If "flags" has the
6310           "PARSE_OPTIONAL" bit set, then the expression is optional,
6311           otherwise it is mandatory.  It is up to the caller to ensure that
6312           the dynamic parser state ("PL_parser" et al) is correctly set to
6313           reflect the source of the code to be parsed and the lexical context
6314           for the expression.
6315
6316           The op tree representing the expression is returned.  If an
6317           optional expression is absent, a null pointer is returned,
6318           otherwise the pointer will be non-null.
6319
6320           If an error occurs in parsing or compilation, in most cases a valid
6321           op tree is returned anyway.  The error is reflected in the parser
6322           state, normally resulting in a single exception at the top level of
6323           parsing which covers all the compilation errors that occurred.
6324           Some compilation errors, however, will throw an exception
6325           immediately.
6326
6327            OP*  parse_arithexpr(U32 flags)
6328
6329       "parse_barestmt"
6330           NOTE: "parse_barestmt" is experimental and may change or be removed
6331           without notice.
6332
6333           Parse a single unadorned Perl statement.  This may be a normal
6334           imperative statement or a declaration that has compile-time effect.
6335           It does not include any label or other affixture.  It is up to the
6336           caller to ensure that the dynamic parser state ("PL_parser" et al)
6337           is correctly set to reflect the source of the code to be parsed and
6338           the lexical context for the statement.
6339
6340           The op tree representing the statement is returned.  This may be a
6341           null pointer if the statement is null, for example if it was
6342           actually a subroutine definition (which has compile-time side
6343           effects).  If not null, it will be ops directly implementing the
6344           statement, suitable to pass to "newSTATEOP".  It will not normally
6345           include a "nextstate" or equivalent op (except for those embedded
6346           in a scope contained entirely within the statement).
6347
6348           If an error occurs in parsing or compilation, in most cases a valid
6349           op tree (most likely null) is returned anyway.  The error is
6350           reflected in the parser state, normally resulting in a single
6351           exception at the top level of parsing which covers all the
6352           compilation errors that occurred.  Some compilation errors,
6353           however, will throw an exception immediately.
6354
6355           The "flags" parameter is reserved for future use, and must always
6356           be zero.
6357
6358            OP*  parse_barestmt(U32 flags)
6359
6360       "parse_block"
6361           NOTE: "parse_block" is experimental and may change or be removed
6362           without notice.
6363
6364           Parse a single complete Perl code block.  This consists of an
6365           opening brace, a sequence of statements, and a closing brace.  The
6366           block constitutes a lexical scope, so "my" variables and various
6367           compile-time effects can be contained within it.  It is up to the
6368           caller to ensure that the dynamic parser state ("PL_parser" et al)
6369           is correctly set to reflect the source of the code to be parsed and
6370           the lexical context for the statement.
6371
6372           The op tree representing the code block is returned.  This is
6373           always a real op, never a null pointer.  It will normally be a
6374           "lineseq" list, including "nextstate" or equivalent ops.  No ops to
6375           construct any kind of runtime scope are included by virtue of it
6376           being a block.
6377
6378           If an error occurs in parsing or compilation, in most cases a valid
6379           op tree (most likely null) is returned anyway.  The error is
6380           reflected in the parser state, normally resulting in a single
6381           exception at the top level of parsing which covers all the
6382           compilation errors that occurred.  Some compilation errors,
6383           however, will throw an exception immediately.
6384
6385           The "flags" parameter is reserved for future use, and must always
6386           be zero.
6387
6388            OP*  parse_block(U32 flags)
6389
6390       "parse_fullexpr"
6391           NOTE: "parse_fullexpr" is experimental and may change or be removed
6392           without notice.
6393
6394           Parse a single complete Perl expression.  This allows the full
6395           expression grammar, including the lowest-precedence operators such
6396           as "or".  The expression must be followed (and thus terminated) by
6397           a token that an expression would normally be terminated by: end-of-
6398           file, closing bracketing punctuation, semicolon, or one of the
6399           keywords that signals a postfix expression-statement modifier.  If
6400           "flags" has the "PARSE_OPTIONAL" bit set, then the expression is
6401           optional, otherwise it is mandatory.  It is up to the caller to
6402           ensure that the dynamic parser state ("PL_parser" et al) is
6403           correctly set to reflect the source of the code to be parsed and
6404           the lexical context for the expression.
6405
6406           The op tree representing the expression is returned.  If an
6407           optional expression is absent, a null pointer is returned,
6408           otherwise the pointer will be non-null.
6409
6410           If an error occurs in parsing or compilation, in most cases a valid
6411           op tree is returned anyway.  The error is reflected in the parser
6412           state, normally resulting in a single exception at the top level of
6413           parsing which covers all the compilation errors that occurred.
6414           Some compilation errors, however, will throw an exception
6415           immediately.
6416
6417            OP*  parse_fullexpr(U32 flags)
6418
6419       "parse_fullstmt"
6420           NOTE: "parse_fullstmt" is experimental and may change or be removed
6421           without notice.
6422
6423           Parse a single complete Perl statement.  This may be a normal
6424           imperative statement or a declaration that has compile-time effect,
6425           and may include optional labels.  It is up to the caller to ensure
6426           that the dynamic parser state ("PL_parser" et al) is correctly set
6427           to reflect the source of the code to be parsed and the lexical
6428           context for the statement.
6429
6430           The op tree representing the statement is returned.  This may be a
6431           null pointer if the statement is null, for example if it was
6432           actually a subroutine definition (which has compile-time side
6433           effects).  If not null, it will be the result of a "newSTATEOP"
6434           call, normally including a "nextstate" or equivalent op.
6435
6436           If an error occurs in parsing or compilation, in most cases a valid
6437           op tree (most likely null) is returned anyway.  The error is
6438           reflected in the parser state, normally resulting in a single
6439           exception at the top level of parsing which covers all the
6440           compilation errors that occurred.  Some compilation errors,
6441           however, will throw an exception immediately.
6442
6443           The "flags" parameter is reserved for future use, and must always
6444           be zero.
6445
6446            OP*  parse_fullstmt(U32 flags)
6447
6448       "parse_label"
6449           NOTE: "parse_label" is experimental and may change or be removed
6450           without notice.
6451
6452           Parse a single label, possibly optional, of the type that may
6453           prefix a Perl statement.  It is up to the caller to ensure that the
6454           dynamic parser state ("PL_parser" et al) is correctly set to
6455           reflect the source of the code to be parsed.  If "flags" has the
6456           "PARSE_OPTIONAL" bit set, then the label is optional, otherwise it
6457           is mandatory.
6458
6459           The name of the label is returned in the form of a fresh scalar.
6460           If an optional label is absent, a null pointer is returned.
6461
6462           If an error occurs in parsing, which can only occur if the label is
6463           mandatory, a valid label is returned anyway.  The error is
6464           reflected in the parser state, normally resulting in a single
6465           exception at the top level of parsing which covers all the
6466           compilation errors that occurred.
6467
6468            SV*  parse_label(U32 flags)
6469
6470       "parse_listexpr"
6471           NOTE: "parse_listexpr" is experimental and may change or be removed
6472           without notice.
6473
6474           Parse a Perl list expression.  This may contain operators of
6475           precedence down to the comma operator.  The expression must be
6476           followed (and thus terminated) either by a low-precedence logic
6477           operator such as "or" or by something that would normally terminate
6478           an expression such as semicolon.  If "flags" has the
6479           "PARSE_OPTIONAL" bit set, then the expression is optional,
6480           otherwise it is mandatory.  It is up to the caller to ensure that
6481           the dynamic parser state ("PL_parser" et al) is correctly set to
6482           reflect the source of the code to be parsed and the lexical context
6483           for the expression.
6484
6485           The op tree representing the expression is returned.  If an
6486           optional expression is absent, a null pointer is returned,
6487           otherwise the pointer will be non-null.
6488
6489           If an error occurs in parsing or compilation, in most cases a valid
6490           op tree is returned anyway.  The error is reflected in the parser
6491           state, normally resulting in a single exception at the top level of
6492           parsing which covers all the compilation errors that occurred.
6493           Some compilation errors, however, will throw an exception
6494           immediately.
6495
6496            OP*  parse_listexpr(U32 flags)
6497
6498       "parse_stmtseq"
6499           NOTE: "parse_stmtseq" is experimental and may change or be removed
6500           without notice.
6501
6502           Parse a sequence of zero or more Perl statements.  These may be
6503           normal imperative statements, including optional labels, or
6504           declarations that have compile-time effect, or any mixture thereof.
6505           The statement sequence ends when a closing brace or end-of-file is
6506           encountered in a place where a new statement could have validly
6507           started.  It is up to the caller to ensure that the dynamic parser
6508           state ("PL_parser" et al) is correctly set to reflect the source of
6509           the code to be parsed and the lexical context for the statements.
6510
6511           The op tree representing the statement sequence is returned.  This
6512           may be a null pointer if the statements were all null, for example
6513           if there were no statements or if there were only subroutine
6514           definitions (which have compile-time side effects).  If not null,
6515           it will be a "lineseq" list, normally including "nextstate" or
6516           equivalent ops.
6517
6518           If an error occurs in parsing or compilation, in most cases a valid
6519           op tree is returned anyway.  The error is reflected in the parser
6520           state, normally resulting in a single exception at the top level of
6521           parsing which covers all the compilation errors that occurred.
6522           Some compilation errors, however, will throw an exception
6523           immediately.
6524
6525           The "flags" parameter is reserved for future use, and must always
6526           be zero.
6527
6528            OP*  parse_stmtseq(U32 flags)
6529
6530       "parse_subsignature"
6531           NOTE: "parse_subsignature" is experimental and may change or be
6532           removed without notice.
6533
6534           Parse a subroutine signature declaration. This is the contents of
6535           the parentheses following a named or anonymous subroutine
6536           declaration when the "signatures" feature is enabled. Note that
6537           this function neither expects nor consumes the opening and closing
6538           parentheses around the signature; it is the caller's job to handle
6539           these.
6540
6541           This function must only be called during parsing of a subroutine;
6542           after "start_subparse" has been called. It might allocate lexical
6543           variables on the pad for the current subroutine.
6544
6545           The op tree to unpack the arguments from the stack at runtime is
6546           returned.  This op tree should appear at the beginning of the
6547           compiled function. The caller may wish to use "op_append_list" to
6548           build their function body after it, or splice it together with the
6549           body before calling "newATTRSUB".
6550
6551           The "flags" parameter is reserved for future use, and must always
6552           be zero.
6553
6554            OP*  parse_subsignature(U32 flags)
6555
6556       "parse_termexpr"
6557           NOTE: "parse_termexpr" is experimental and may change or be removed
6558           without notice.
6559
6560           Parse a Perl term expression.  This may contain operators of
6561           precedence down to the assignment operators.  The expression must
6562           be followed (and thus terminated) either by a comma or lower-
6563           precedence operator or by something that would normally terminate
6564           an expression such as semicolon.  If "flags" has the
6565           "PARSE_OPTIONAL" bit set, then the expression is optional,
6566           otherwise it is mandatory.  It is up to the caller to ensure that
6567           the dynamic parser state ("PL_parser" et al) is correctly set to
6568           reflect the source of the code to be parsed and the lexical context
6569           for the expression.
6570
6571           The op tree representing the expression is returned.  If an
6572           optional expression is absent, a null pointer is returned,
6573           otherwise the pointer will be non-null.
6574
6575           If an error occurs in parsing or compilation, in most cases a valid
6576           op tree is returned anyway.  The error is reflected in the parser
6577           state, normally resulting in a single exception at the top level of
6578           parsing which covers all the compilation errors that occurred.
6579           Some compilation errors, however, will throw an exception
6580           immediately.
6581
6582            OP*  parse_termexpr(U32 flags)
6583
6584       "PL_parser"
6585           Pointer to a structure encapsulating the state of the parsing
6586           operation currently in progress.  The pointer can be locally
6587           changed to perform a nested parse without interfering with the
6588           state of an outer parse.  Individual members of "PL_parser" have
6589           their own documentation.
6590
6591       "PL_parser->bufend"
6592           NOTE: "PL_parser->bufend" is experimental and may change or be
6593           removed without notice.
6594
6595           Direct pointer to the end of the chunk of text currently being
6596           lexed, the end of the lexer buffer.  This is equal to
6597           "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)".  A "NUL"
6598           character (zero octet) is always located at the end of the buffer,
6599           and does not count as part of the buffer's contents.
6600
6601       "PL_parser->bufptr"
6602           NOTE: "PL_parser->bufptr" is experimental and may change or be
6603           removed without notice.
6604
6605           Points to the current position of lexing inside the lexer buffer.
6606           Characters around this point may be freely examined, within the
6607           range delimited by "SvPVX("PL_parser->linestr")" and
6608           "PL_parser->bufend".  The octets of the buffer may be intended to
6609           be interpreted as either UTF-8 or Latin-1, as indicated by
6610           "lex_bufutf8".
6611
6612           Lexing code (whether in the Perl core or not) moves this pointer
6613           past the characters that it consumes.  It is also expected to
6614           perform some bookkeeping whenever a newline character is consumed.
6615           This movement can be more conveniently performed by the function
6616           "lex_read_to", which handles newlines appropriately.
6617
6618           Interpretation of the buffer's octets can be abstracted out by
6619           using the slightly higher-level functions "lex_peek_unichar" and
6620           "lex_read_unichar".
6621
6622       "PL_parser->linestart"
6623           NOTE: "PL_parser->linestart" is experimental and may change or be
6624           removed without notice.
6625
6626           Points to the start of the current line inside the lexer buffer.
6627           This is useful for indicating at which column an error occurred,
6628           and not much else.  This must be updated by any lexing code that
6629           consumes a newline; the function "lex_read_to" handles this detail.
6630
6631       "PL_parser->linestr"
6632           NOTE: "PL_parser->linestr" is experimental and may change or be
6633           removed without notice.
6634
6635           Buffer scalar containing the chunk currently under consideration of
6636           the text currently being lexed.  This is always a plain string
6637           scalar (for which "SvPOK" is true).  It is not intended to be used
6638           as a scalar by normal scalar means; instead refer to the buffer
6639           directly by the pointer variables described below.
6640
6641           The lexer maintains various "char*" pointers to things in the
6642           "PL_parser->linestr" buffer.  If "PL_parser->linestr" is ever
6643           reallocated, all of these pointers must be updated.  Don't attempt
6644           to do this manually, but rather use "lex_grow_linestr" if you need
6645           to reallocate the buffer.
6646
6647           The content of the text chunk in the buffer is commonly exactly one
6648           complete line of input, up to and including a newline terminator,
6649           but there are situations where it is otherwise.  The octets of the
6650           buffer may be intended to be interpreted as either UTF-8 or
6651           Latin-1.  The function "lex_bufutf8" tells you which.  Do not use
6652           the "SvUTF8" flag on this scalar, which may disagree with it.
6653
6654           For direct examination of the buffer, the variable
6655           "PL_parser->bufend" points to the end of the buffer.  The current
6656           lexing position is pointed to by "PL_parser->bufptr".  Direct use
6657           of these pointers is usually preferable to examination of the
6658           scalar through normal scalar means.
6659
6660       "wrap_keyword_plugin"
6661           NOTE: "wrap_keyword_plugin" is experimental and may change or be
6662           removed without notice.
6663
6664           Puts a C function into the chain of keyword plugins.  This is the
6665           preferred way to manipulate the "PL_keyword_plugin" variable.
6666           "new_plugin" is a pointer to the C function that is to be added to
6667           the keyword plugin chain, and "old_plugin_p" points to the storage
6668           location where a pointer to the next function in the chain will be
6669           stored.  The value of "new_plugin" is written into the
6670           "PL_keyword_plugin" variable, while the value previously stored
6671           there is written to *old_plugin_p.
6672
6673           "PL_keyword_plugin" is global to an entire process, and a module
6674           wishing to hook keyword parsing may find itself invoked more than
6675           once per process, typically in different threads.  To handle that
6676           situation, this function is idempotent.  The location *old_plugin_p
6677           must initially (once per process) contain a null pointer.  A C
6678           variable of static duration (declared at file scope, typically also
6679           marked "static" to give it internal linkage) will be implicitly
6680           initialised appropriately, if it does not have an explicit
6681           initialiser.  This function will only actually modify the plugin
6682           chain if it finds *old_plugin_p to be null.  This function is also
6683           thread safe on the small scale.  It uses appropriate locking to
6684           avoid race conditions in accessing "PL_keyword_plugin".
6685
6686           When this function is called, the function referenced by
6687           "new_plugin" must be ready to be called, except for *old_plugin_p
6688           being unfilled.  In a threading situation, "new_plugin" may be
6689           called immediately, even before this function has returned.
6690           *old_plugin_p will always be appropriately set before "new_plugin"
6691           is called.  If "new_plugin" decides not to do anything special with
6692           the identifier that it is given (which is the usual case for most
6693           calls to a keyword plugin), it must chain the plugin function
6694           referenced by *old_plugin_p.
6695
6696           Taken all together, XS code to install a keyword plugin should
6697           typically look something like this:
6698
6699               static Perl_keyword_plugin_t next_keyword_plugin;
6700               static OP *my_keyword_plugin(pTHX_
6701                   char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
6702               {
6703                   if (memEQs(keyword_ptr, keyword_len,
6704                              "my_new_keyword")) {
6705                       ...
6706                   } else {
6707                       return next_keyword_plugin(aTHX_
6708                           keyword_ptr, keyword_len, op_ptr);
6709                   }
6710               }
6711               BOOT:
6712                   wrap_keyword_plugin(my_keyword_plugin,
6713                                       &next_keyword_plugin);
6714
6715           Direct access to "PL_keyword_plugin" should be avoided.
6716
6717            void  wrap_keyword_plugin(Perl_keyword_plugin_t new_plugin,
6718                                      Perl_keyword_plugin_t *old_plugin_p)
6719

Locales

6721       "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
6722           This macro should be used as a statement.  It declares a private
6723           variable (whose name begins with an underscore) that is needed by
6724           the other macros in this section.  Failing to include this
6725           correctly should lead to a syntax error.  For compatibility with
6726           C89 C compilers it should be placed in a block before any
6727           executable statements.
6728
6729            void  DECLARATION_FOR_LC_NUMERIC_MANIPULATION
6730
6731       "foldEQ_locale"
6732           Returns true if the leading "len" bytes of the strings "s1" and
6733           "s2" are the same case-insensitively in the current locale; false
6734           otherwise.
6735
6736            I32  foldEQ_locale(const char* a, const char* b, I32 len)
6737
6738       "HAS_DUPLOCALE"
6739           This symbol, if defined, indicates that the "duplocale" routine is
6740           available to duplicate a locale object.
6741
6742       "HAS_FREELOCALE"
6743           This symbol, if defined, indicates that the "freelocale" routine is
6744           available to deallocates the resources associated with a locale
6745           object.
6746
6747       "HAS_LC_MONETARY_2008"
6748           This symbol, if defined, indicates that the localeconv routine is
6749           available and has the additional members added in "POSIX"
6750           1003.1-2008.
6751
6752       "HAS_LOCALECONV"
6753           This symbol, if defined, indicates that the "localeconv" routine is
6754           available for numeric and monetary formatting conventions.
6755
6756       "HAS_LOCALECONV_L"
6757           This symbol, if defined, indicates that the "localeconv_l" routine
6758           is available to query certain information about a locale.
6759
6760       "HAS_NEWLOCALE"
6761           This symbol, if defined, indicates that the "newlocale" routine is
6762           available to return a new locale object or modify an existing
6763           locale object.
6764
6765       "HAS_NL_LANGINFO"
6766           This symbol, if defined, indicates that the "nl_langinfo" routine
6767           is available to return local data.  You will also need langinfo.h
6768           and therefore "I_LANGINFO".
6769
6770       "HAS_QUERYLOCALE"
6771           This symbol, if defined, indicates that the "querylocale" routine
6772           is available to return the name of the locale for a category mask.
6773
6774       "HAS_SETLOCALE"
6775           This symbol, if defined, indicates that the "setlocale" routine is
6776           available to handle locale-specific ctype implementations.
6777
6778       "HAS_SETLOCALE_R"
6779           This symbol, if defined, indicates that the "setlocale_r" routine
6780           is available to setlocale re-entrantly.
6781
6782       "HAS_THREAD_SAFE_NL_LANGINFO_L"
6783           This symbol, when defined, indicates presence of the
6784           "nl_langinfo_l()" function, and that it is thread-safe.
6785
6786       "HAS_USELOCALE"
6787           This symbol, if defined, indicates that the "uselocale" routine is
6788           available to set the current locale for the calling thread.
6789
6790       "I_LANGINFO"
6791           This symbol, if defined, indicates that langinfo.h exists and
6792           should be included.
6793
6794            #ifdef I_LANGINFO
6795                #include <langinfo.h>
6796            #endif
6797
6798       "I_LOCALE"
6799           This symbol, if defined, indicates to the C program that it should
6800           include locale.h.
6801
6802            #ifdef I_LOCALE
6803                #include <locale.h>
6804            #endif
6805
6806       "IN_LOCALE"
6807           Evaluates to TRUE if the plain locale pragma without a parameter
6808           ("use locale") is in effect.
6809
6810            bool  IN_LOCALE
6811
6812       "IN_LOCALE_COMPILETIME"
6813           Evaluates to TRUE if, when compiling a perl program (including an
6814           "eval") if the plain locale pragma without a parameter
6815           ("use locale") is in effect.
6816
6817            bool  IN_LOCALE_COMPILETIME
6818
6819       "IN_LOCALE_RUNTIME"
6820           Evaluates to TRUE if, when executing a perl program (including an
6821           "eval") if the plain locale pragma without a parameter
6822           ("use locale") is in effect.
6823
6824            bool  IN_LOCALE_RUNTIME
6825
6826       "I_XLOCALE"
6827           This symbol, if defined, indicates to the C program that it should
6828           include xlocale.h to get "uselocale()" and its friends.
6829
6830            #ifdef I_XLOCALE
6831                #include <xlocale.h>
6832            #endif
6833
6834       "Perl_langinfo"
6835           This is an (almost) drop-in replacement for the system
6836           nl_langinfo(3), taking the same "item" parameter values, and
6837           returning the same information.  But it is more thread-safe than
6838           regular "nl_langinfo()", and hides the quirks of Perl's locale
6839           handling from your code, and can be used on systems that lack a
6840           native "nl_langinfo".
6841
6842           Expanding on these:
6843
6844           •   The reason it isn't quite a drop-in replacement is actually an
6845               advantage.  The only difference is that it returns
6846               "const char *", whereas plain "nl_langinfo()" returns "char *",
6847               but you are (only by documentation) forbidden to write into the
6848               buffer.  By declaring this "const", the compiler enforces this
6849               restriction, so if it is violated, you know at compilation
6850               time, rather than getting segfaults at runtime.
6851
6852           •   It delivers the correct results for the "RADIXCHAR" and
6853               "THOUSEP" items, without you having to write extra code.  The
6854               reason for the extra code would be because these are from the
6855               "LC_NUMERIC" locale category, which is normally kept set by
6856               Perl so that the radix is a dot, and the separator is the empty
6857               string, no matter what the underlying locale is supposed to be,
6858               and so to get the expected results, you have to temporarily
6859               toggle into the underlying locale, and later toggle back.  (You
6860               could use plain "nl_langinfo" and
6861               "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" for this but then you
6862               wouldn't get the other advantages of "Perl_langinfo()"; not
6863               keeping "LC_NUMERIC" in the C (or equivalent) locale would
6864               break a lot of CPAN, which is expecting the radix (decimal
6865               point) character to be a dot.)
6866
6867           •   The system function it replaces can have its static return
6868               buffer trashed, not only by a subsequent call to that function,
6869               but by a "freelocale", "setlocale", or other locale change.
6870               The returned buffer of this function is not changed until the
6871               next call to it, so the buffer is never in a trashed state.
6872
6873           •   Its return buffer is per-thread, so it also is never
6874               overwritten by a call to this function from another thread;
6875               unlike the function it replaces.
6876
6877           •   But most importantly, it works on systems that don't have
6878               "nl_langinfo", such as Windows, hence makes your code more
6879               portable.  Of the fifty-some possible items specified by the
6880               POSIX 2008 standard,
6881               <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
6882               only one is completely unimplemented, though on non-Windows
6883               platforms, another significant one is also not implemented).
6884               It uses various techniques to recover the other items,
6885               including calling localeconv(3), and strftime(3), both of which
6886               are specified in C89, so should be always be available.  Later
6887               "strftime()" versions have additional capabilities; "" is
6888               returned for those not available on your system.
6889
6890               It is important to note that when called with an item that is
6891               recovered by using "localeconv", the buffer from any previous
6892               explicit call to "localeconv" will be overwritten.  This means
6893               you must save that buffer's contents if you need to access them
6894               after a call to this function.  (But note that you might not
6895               want to be using "localeconv()" directly anyway, because of
6896               issues like the ones listed in the second item of this list
6897               (above) for "RADIXCHAR" and "THOUSEP".  You can use the methods
6898               given in perlcall to call "localeconv" in POSIX and avoid all
6899               the issues, but then you have a hash to unpack).
6900
6901               The details for those items which may deviate from what this
6902               emulation returns and what a native "nl_langinfo()" would
6903               return are specified in I18N::Langinfo.
6904
6905           When using "Perl_langinfo" on systems that don't have a native
6906           "nl_langinfo()", you must
6907
6908            #include "perl_langinfo.h"
6909
6910           before the "perl.h" "#include".  You can replace your "langinfo.h"
6911           "#include" with this one.  (Doing it this way keeps out the symbols
6912           that plain "langinfo.h" would try to import into the namespace for
6913           code that doesn't need it.)
6914
6915           The original impetus for "Perl_langinfo()" was so that code that
6916           needs to find out the current currency symbol, floating point radix
6917           character, or digit grouping separator can use, on all systems, the
6918           simpler and more thread-friendly "nl_langinfo" API instead of
6919           localeconv(3) which is a pain to make thread-friendly.  For other
6920           fields returned by "localeconv", it is better to use the methods
6921           given in perlcall to call "POSIX::localeconv()", which is thread-
6922           friendly.
6923
6924            const char*  Perl_langinfo(const nl_item item)
6925
6926       "Perl_setlocale"
6927           This is an (almost) drop-in replacement for the system
6928           setlocale(3), taking the same parameters, and returning the same
6929           information, except that it returns the correct underlying
6930           "LC_NUMERIC" locale.  Regular "setlocale" will instead return "C"
6931           if the underlying locale has a non-dot decimal point character, or
6932           a non-empty thousands separator for displaying floating point
6933           numbers.  This is because perl keeps that locale category such that
6934           it has a dot and empty separator, changing the locale briefly
6935           during the operations where the underlying one is required.
6936           "Perl_setlocale" knows about this, and compensates; regular
6937           "setlocale" doesn't.
6938
6939           Another reason it isn't completely a drop-in replacement is that it
6940           is declared to return "const char *", whereas the system setlocale
6941           omits the "const" (presumably because its API was specified long
6942           ago, and can't be updated; it is illegal to change the information
6943           "setlocale" returns; doing so leads to segfaults.)
6944
6945           Finally, "Perl_setlocale" works under all circumstances, whereas
6946           plain "setlocale" can be completely ineffective on some platforms
6947           under some configurations.
6948
6949           "Perl_setlocale" should not be used to change the locale except on
6950           systems where the predefined variable "${^SAFE_LOCALES}" is 1.  On
6951           some such systems, the system "setlocale()" is ineffective,
6952           returning the wrong information, and failing to actually change the
6953           locale.  "Perl_setlocale", however works properly in all
6954           circumstances.
6955
6956           The return points to a per-thread static buffer, which is
6957           overwritten the next time "Perl_setlocale" is called from the same
6958           thread.
6959
6960            const char*  Perl_setlocale(const int category,
6961                                        const char* locale)
6962
6963       "RESTORE_LC_NUMERIC"
6964           This is used in conjunction with one of the macros
6965           "STORE_LC_NUMERIC_SET_TO_NEEDED" and
6966           "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
6967           "LC_NUMERIC" state.
6968
6969           A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
6970           made to declare at compile time a private variable used by this
6971           macro and the two "STORE" ones.  This macro should be called as a
6972           single statement, not an expression, but with an empty argument
6973           list, like this:
6974
6975            {
6976               DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
6977                ...
6978               RESTORE_LC_NUMERIC();
6979                ...
6980            }
6981
6982            void  RESTORE_LC_NUMERIC()
6983
6984       "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
6985           This symbol, if defined, indicates that the setlocale routine is
6986           available and it accepts any input locale name as valid.
6987
6988       "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
6989           This is used by XS code that is "LC_NUMERIC" locale-aware to force
6990           the locale for category "LC_NUMERIC" to be what perl thinks is the
6991           current underlying locale.  (The perl interpreter could be wrong
6992           about what the underlying locale actually is if some C or XS code
6993           has called the C library function setlocale(3) behind its back;
6994           calling "sync_locale" before calling this macro will update perl's
6995           records.)
6996
6997           A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
6998           made to declare at compile time a private variable used by this
6999           macro.  This macro should be called as a single statement, not an
7000           expression, but with an empty argument list, like this:
7001
7002            {
7003               DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7004                ...
7005               STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
7006                ...
7007               RESTORE_LC_NUMERIC();
7008                ...
7009            }
7010
7011           The private variable is used to save the current locale state, so
7012           that the requisite matching call to "RESTORE_LC_NUMERIC" can
7013           restore it.
7014
7015           On threaded perls not operating with thread-safe functionality,
7016           this macro uses a mutex to force a critical section.  Therefore the
7017           matching RESTORE should be close by, and guaranteed to be called.
7018
7019            void  STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
7020
7021       "STORE_LC_NUMERIC_SET_TO_NEEDED"
7022           This is used to help wrap XS or C code that is "LC_NUMERIC" locale-
7023           aware.  This locale category is generally kept set to a locale
7024           where the decimal radix character is a dot, and the separator
7025           between groups of digits is empty.  This is because most XS code
7026           that reads floating point numbers is expecting them to have this
7027           syntax.
7028
7029           This macro makes sure the current "LC_NUMERIC" state is set
7030           properly, to be aware of locale if the call to the XS or C code
7031           from the Perl program is from within the scope of a "use locale";
7032           or to ignore locale if the call is instead from outside such scope.
7033
7034           This macro is the start of wrapping the C or XS code; the wrap
7035           ending is done by calling the "RESTORE_LC_NUMERIC" macro after the
7036           operation.  Otherwise the state can be changed that will adversely
7037           affect other XS code.
7038
7039           A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
7040           made to declare at compile time a private variable used by this
7041           macro.  This macro should be called as a single statement, not an
7042           expression, but with an empty argument list, like this:
7043
7044            {
7045               DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7046                ...
7047               STORE_LC_NUMERIC_SET_TO_NEEDED();
7048                ...
7049               RESTORE_LC_NUMERIC();
7050                ...
7051            }
7052
7053           On threaded perls not operating with thread-safe functionality,
7054           this macro uses a mutex to force a critical section.  Therefore the
7055           matching RESTORE should be close by, and guaranteed to be called;
7056           see "WITH_LC_NUMERIC_SET_TO_NEEDED" for a more contained way to
7057           ensure that.
7058
7059            void  STORE_LC_NUMERIC_SET_TO_NEEDED()
7060
7061       "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
7062           Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
7063           provided as the precalculated value of "IN_LC(LC_NUMERIC)". It is
7064           the caller's responsibility to ensure that the status of
7065           "PL_compiling" and "PL_hints" cannot have changed since the
7066           precalculation.
7067
7068            void  STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric)
7069
7070       "switch_to_global_locale"
7071           On systems without locale support, or on typical single-threaded
7072           builds, or on platforms that do not support per-thread locale
7073           operations, this function does nothing.  On such systems that do
7074           have locale support, only a locale global to the whole program is
7075           available.
7076
7077           On multi-threaded builds on systems that do have per-thread locale
7078           operations, this function converts the thread it is running in to
7079           use the global locale.  This is for code that has not yet or cannot
7080           be updated to handle multi-threaded locale operation.  As long as
7081           only a single thread is so-converted, everything works fine, as all
7082           the other threads continue to ignore the global one, so only this
7083           thread looks at it.
7084
7085           However, on Windows systems this isn't quite true prior to Visual
7086           Studio 15, at which point Microsoft fixed a bug.  A race can occur
7087           if you use the following operations on earlier Windows platforms:
7088
7089           POSIX::localeconv
7090           I18N::Langinfo, items "CRNCYSTR" and "THOUSEP"
7091           "Perl_langinfo" in perlapi, items "CRNCYSTR" and "THOUSEP"
7092
7093           The first item is not fixable (except by upgrading to a later
7094           Visual Studio release), but it would be possible to work around the
7095           latter two items by using the Windows API functions
7096           "GetNumberFormat" and "GetCurrencyFormat"; patches welcome.
7097
7098           Without this function call, threads that use the setlocale(3)
7099           system function will not work properly, as all the locale-sensitive
7100           functions will look at the per-thread locale, and "setlocale" will
7101           have no effect on this thread.
7102
7103           Perl code should convert to either call "Perl_setlocale" (which is
7104           a drop-in for the system "setlocale") or use the methods given in
7105           perlcall to call "POSIX::setlocale".  Either one will transparently
7106           properly handle all cases of single- vs multi-thread, POSIX
7107           2008-supported or not.
7108
7109           Non-Perl libraries, such as "gtk", that call the system "setlocale"
7110           can continue to work if this function is called before transferring
7111           control to the library.
7112
7113           Upon return from the code that needs to use the global locale,
7114           "sync_locale()" should be called to restore the safe multi-thread
7115           operation.
7116
7117            void  switch_to_global_locale()
7118
7119       "sync_locale"
7120           "Perl_setlocale" can be used at any time to query or change the
7121           locale (though changing the locale is antisocial and dangerous on
7122           multi-threaded systems that don't have multi-thread safe locale
7123           operations.  (See "Multi-threaded operation" in perllocale).  Using
7124           the system setlocale(3) should be avoided.  Nevertheless, certain
7125           non-Perl libraries called from XS, such as "Gtk" do so, and this
7126           can't be changed.  When the locale is changed by XS code that
7127           didn't use "Perl_setlocale", Perl needs to be told that the locale
7128           has changed.  Use this function to do so, before returning to Perl.
7129
7130           The return value is a boolean: TRUE if the global locale at the
7131           time of call was in effect; and FALSE if a per-thread locale was in
7132           effect.  This can be used by the caller that needs to restore
7133           things as-they-were to decide whether or not to call
7134           "Perl_switch_to_global_locale".
7135
7136            bool  sync_locale()
7137
7138       "WITH_LC_NUMERIC_SET_TO_NEEDED"
7139           This macro invokes the supplied statement or block within the
7140           context of a "STORE_LC_NUMERIC_SET_TO_NEEDED" ..
7141           "RESTORE_LC_NUMERIC" pair if required, so eg:
7142
7143             WITH_LC_NUMERIC_SET_TO_NEEDED(
7144               SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
7145             );
7146
7147           is equivalent to:
7148
7149             {
7150           #ifdef USE_LOCALE_NUMERIC
7151               DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7152               STORE_LC_NUMERIC_SET_TO_NEEDED();
7153           #endif
7154               SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
7155           #ifdef USE_LOCALE_NUMERIC
7156               RESTORE_LC_NUMERIC();
7157           #endif
7158             }
7159
7160            void  WITH_LC_NUMERIC_SET_TO_NEEDED(block)
7161
7162       "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
7163           Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
7164           as the precalculated value of "IN_LC(LC_NUMERIC)". It is the
7165           caller's responsibility to ensure that the status of "PL_compiling"
7166           and "PL_hints" cannot have changed since the precalculation.
7167
7168            void  WITH_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric, block)
7169

Magic

7171       "Magic" is special data attached to SV structures in order to give them
7172       "magical" properties.  When any Perl code tries to read from, or assign
7173       to, an SV marked as magical, it calls the 'get' or 'set' function
7174       associated with that SV's magic.  A get is called prior to reading an
7175       SV, in order to give it a chance to update its internal value (get on
7176       $. writes the line number of the last read filehandle into the SV's IV
7177       slot), while set is called after an SV has been written to, in order to
7178       allow it to make use of its changed value (set on $/ copies the SV's
7179       new value to the PL_rs global variable).
7180
7181       Magic is implemented as a linked list of MAGIC structures attached to
7182       the SV.  Each MAGIC struct holds the type of the magic, a pointer to an
7183       array of functions that implement the get(), set(), length() etc
7184       functions, plus space for some flags and pointers.  For example, a tied
7185       variable has a MAGIC structure that contains a pointer to the object
7186       associated with the tie.
7187
7188       "mg_clear"
7189           Clear something magical that the SV represents.  See "sv_magic".
7190
7191            int  mg_clear(SV* sv)
7192
7193       "mg_copy"
7194           Copies the magic from one SV to another.  See "sv_magic".
7195
7196            int  mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
7197
7198       "mg_find"
7199           Finds the magic pointer for "type" matching the SV.  See
7200           "sv_magic".
7201
7202            MAGIC*  mg_find(const SV* sv, int type)
7203
7204       "mg_findext"
7205           Finds the magic pointer of "type" with the given "vtbl" for the
7206           "SV".  See "sv_magicext".
7207
7208            MAGIC*  mg_findext(const SV* sv, int type, const MGVTBL *vtbl)
7209
7210       "mg_free"
7211           Free any magic storage used by the SV.  See "sv_magic".
7212
7213            int  mg_free(SV* sv)
7214
7215       "mg_freeext"
7216           Remove any magic of type "how" using virtual table "vtbl" from the
7217           SV "sv".  See "sv_magic".
7218
7219           "mg_freeext(sv, how, NULL)" is equivalent to "mg_free_type(sv,
7220           how)".
7221
7222            void  mg_freeext(SV* sv, int how, const MGVTBL *vtbl)
7223
7224       "mg_free_type"
7225           Remove any magic of type "how" from the SV "sv".  See "sv_magic".
7226
7227            void  mg_free_type(SV* sv, int how)
7228
7229       "mg_get"
7230           Do magic before a value is retrieved from the SV.  The type of SV
7231           must be >= "SVt_PVMG".  See "sv_magic".
7232
7233            int  mg_get(SV* sv)
7234
7235       "mg_length"
7236           "DEPRECATED!"  It is planned to remove "mg_length" from a future
7237           release of Perl.  Do not use it for new code; remove it from
7238           existing code.
7239
7240           Reports on the SV's length in bytes, calling length magic if
7241           available, but does not set the UTF8 flag on "sv".  It will fall
7242           back to 'get' magic if there is no 'length' magic, but with no
7243           indication as to whether it called 'get' magic.  It assumes "sv" is
7244           a "PVMG" or higher.  Use "sv_len()" instead.
7245
7246            U32  mg_length(SV* sv)
7247
7248       "mg_magical"
7249           Turns on the magical status of an SV.  See "sv_magic".
7250
7251            void  mg_magical(SV* sv)
7252
7253       "mg_set"
7254           Do magic after a value is assigned to the SV.  See "sv_magic".
7255
7256            int  mg_set(SV* sv)
7257
7258       "SvTIED_obj"
7259           Described in perlinterp.
7260
7261              SvTIED_obj(SV *sv, MAGIC *mg)
7262

Memory Management

7264       "HASATTRIBUTE_MALLOC"
7265           Can we handle "GCC" attribute for malloc-style functions.
7266
7267       "HAS_MALLOC_GOOD_SIZE"
7268           This symbol, if defined, indicates that the "malloc_good_size"
7269           routine is available for use.
7270
7271       "HAS_MALLOC_SIZE"
7272           This symbol, if defined, indicates that the "malloc_size" routine
7273           is available for use.
7274
7275       "I_MALLOCMALLOC"
7276           This symbol, if defined, indicates to the C program that it should
7277           include malloc/malloc.h.
7278
7279            #ifdef I_MALLOCMALLOC
7280                #include <mallocmalloc.h>
7281            #endif
7282
7283       "MYMALLOC"
7284           This symbol, if defined, indicates that we're using our own malloc.
7285
7286       "Newx"
7287           The XSUB-writer's interface to the C "malloc" function.
7288
7289           Memory obtained by this should ONLY be freed with "Safefree".
7290
7291           In 5.9.3, Newx() and friends replace the older New() API, and drops
7292           the first parameter, x, a debug aid which allowed callers to
7293           identify themselves.  This aid has been superseded by a new build
7294           option, PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhacktips).  The
7295           older API is still there for use in XS modules supporting older
7296           perls.
7297
7298            void  Newx(void* ptr, int nitems, type)
7299
7300       "Newxc"
7301           The XSUB-writer's interface to the C "malloc" function, with cast.
7302           See also "Newx".
7303
7304           Memory obtained by this should ONLY be freed with "Safefree".
7305
7306            void  Newxc(void* ptr, int nitems, type, cast)
7307
7308       "Newxz"
7309           The XSUB-writer's interface to the C "malloc" function.  The
7310           allocated memory is zeroed with "memzero".  See also "Newx".
7311
7312           Memory obtained by this should ONLY be freed with "Safefree".
7313
7314            void  Newxz(void* ptr, int nitems, type)
7315
7316       "PERL_MALLOC_WRAP"
7317           This symbol, if defined, indicates that we'd like malloc wrap
7318           checks.
7319
7320       "Renew"
7321           The XSUB-writer's interface to the C "realloc" function.
7322
7323           Memory obtained by this should ONLY be freed with "Safefree".
7324
7325            void  Renew(void* ptr, int nitems, type)
7326
7327       "Renewc"
7328           The XSUB-writer's interface to the C "realloc" function, with cast.
7329
7330           Memory obtained by this should ONLY be freed with "Safefree".
7331
7332            void  Renewc(void* ptr, int nitems, type, cast)
7333
7334       "Safefree"
7335           The XSUB-writer's interface to the C "free" function.
7336
7337           This should ONLY be used on memory obtained using "Newx" and
7338           friends.
7339
7340            void  Safefree(void* ptr)
7341
7342       "safesyscalloc"
7343           Safe version of system's calloc()
7344
7345            Malloc_t  safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
7346
7347       "safesysfree"
7348           Safe version of system's free()
7349
7350            Free_t  safesysfree(Malloc_t where)
7351
7352       "safesysmalloc"
7353           Paranoid version of system's malloc()
7354
7355            Malloc_t  safesysmalloc(MEM_SIZE nbytes)
7356
7357       "safesysrealloc"
7358           Paranoid version of system's realloc()
7359
7360            Malloc_t  safesysrealloc(Malloc_t where, MEM_SIZE nbytes)
7361

MRO

7363       These functions are related to the method resolution order of perl
7364       classes Also see perlmroapi.
7365
7366       "HvMROMETA"
7367           Described in perlmroapi.
7368
7369            struct mro_meta *  HvMROMETA(HV *hv)
7370
7371       "mro_get_linear_isa"
7372           Returns the mro linearisation for the given stash.  By default,
7373           this will be whatever "mro_get_linear_isa_dfs" returns unless some
7374           other MRO is in effect for the stash.  The return value is a read-
7375           only AV*.
7376
7377           You are responsible for "SvREFCNT_inc()" on the return value if you
7378           plan to store it anywhere semi-permanently (otherwise it might be
7379           deleted out from under you the next time the cache is invalidated).
7380
7381            AV*  mro_get_linear_isa(HV* stash)
7382
7383       "MRO_GET_PRIVATE_DATA"
7384           Described in perlmroapi.
7385
7386            SV*  MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta,
7387                                      const struct mro_alg *const which)
7388
7389       "mro_method_changed_in"
7390           Invalidates method caching on any child classes of the given stash,
7391           so that they might notice the changes in this one.
7392
7393           Ideally, all instances of "PL_sub_generation++" in perl source
7394           outside of mro.c should be replaced by calls to this.
7395
7396           Perl automatically handles most of the common ways a method might
7397           be redefined.  However, there are a few ways you could change a
7398           method in a stash without the cache code noticing, in which case
7399           you need to call this method afterwards:
7400
7401           1) Directly manipulating the stash HV entries from XS code.
7402
7403           2) Assigning a reference to a readonly scalar constant into a stash
7404           entry in order to create a constant subroutine (like constant.pm
7405           does).
7406
7407           This same method is available from pure perl via,
7408           "mro::method_changed_in(classname)".
7409
7410            void  mro_method_changed_in(HV* stash)
7411
7412       "mro_register"
7413           Registers a custom mro plugin.  See perlmroapi for details on this
7414           and other mro functions.
7415
7416           NOTE: "mro_register" must be explicitly called as
7417           "Perl_mro_register" with an "aTHX_" parameter.
7418
7419            void  Perl_mro_register(pTHX_ const struct mro_alg *mro)
7420
7421       "mro_set_private_data"
7422           Described in perlmroapi.
7423
7424           NOTE: "mro_set_private_data" must be explicitly called as
7425           "Perl_mro_set_private_data" with an "aTHX_" parameter.
7426
7427            SV*  Perl_mro_set_private_data(pTHX_
7428                                           struct mro_meta *const smeta,
7429                                           const struct mro_alg *const which,
7430                                           SV *const data)
7431

Multicall Functions

7433       "dMULTICALL"
7434           Declare local variables for a multicall.  See "LIGHTWEIGHT
7435           CALLBACKS" in perlcall.
7436
7437              dMULTICALL;
7438
7439       "MULTICALL"
7440           Make a lightweight callback.  See "LIGHTWEIGHT CALLBACKS" in
7441           perlcall.
7442
7443              MULTICALL;
7444
7445       "POP_MULTICALL"
7446           Closing bracket for a lightweight callback.  See "LIGHTWEIGHT
7447           CALLBACKS" in perlcall.
7448
7449              POP_MULTICALL;
7450
7451       "PUSH_MULTICALL"
7452           Opening bracket for a lightweight callback.  See "LIGHTWEIGHT
7453           CALLBACKS" in perlcall.
7454
7455              PUSH_MULTICALL(CV* the_cv);
7456

Numeric Functions

7458       "Drand01"
7459           This macro is to be used to generate uniformly distributed random
7460           numbers over the range [0., 1.[.  You may have to supply an 'extern
7461           double "drand48()";' in your program since SunOS 4.1.3 doesn't
7462           provide you with anything relevant in its headers.  See
7463           "HAS_DRAND48_PROTO".
7464
7465            double  Drand01()
7466
7467       "Gconvert"
7468           This preprocessor macro is defined to convert a floating point
7469           number to a string without a trailing decimal point.  This emulates
7470           the behavior of "sprintf("%g")", but is sometimes much more
7471           efficient.  If "gconvert()" is not available, but "gcvt()" drops
7472           the trailing decimal point, then "gcvt()" is used.  If all else
7473           fails, a macro using "sprintf("%g")" is used. Arguments for the
7474           Gconvert macro are: value, number of digits, whether trailing zeros
7475           should be retained, and the output buffer.  The usual values are:
7476
7477            d_Gconvert='gconvert((x),(n),(t),(b))'
7478            d_Gconvert='gcvt((x),(n),(b))'
7479            d_Gconvert='sprintf((b),"%.*g",(n),(x))'
7480
7481           The last two assume trailing zeros should not be kept.
7482
7483            char *  Gconvert(double x, Size_t n, bool t, char * b)
7484
7485       "grok_bin"
7486           converts a string representing a binary number to numeric form.
7487
7488           On entry "start" and *len_p give the string to scan, *flags gives
7489           conversion flags, and "result" should be "NULL" or a pointer to an
7490           NV.  The scan stops at the end of the string, or at just before the
7491           first invalid character.  Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
7492           in *flags, encountering an invalid character (except NUL) will also
7493           trigger a warning.  On return *len_p is set to the length of the
7494           scanned string, and *flags gives output flags.
7495
7496           If the value is <= "UV_MAX" it is returned as a UV, the output
7497           flags are clear, and nothing is written to *result.  If the value
7498           is > "UV_MAX", "grok_bin" returns "UV_MAX", sets
7499           "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
7500           approximation of the correct value into *result (which is an NV; or
7501           the approximation is discarded if "result" is NULL).
7502
7503           The binary number may optionally be prefixed with "0b" or "b"
7504           unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
7505
7506           If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
7507           pairs of digits may be separated from each other by a single
7508           underscore; also a single leading underscore is accepted.
7509
7510            UV  grok_bin(const char* start, STRLEN* len_p, I32* flags,
7511                         NV *result)
7512
7513       "grok_hex"
7514           converts a string representing a hex number to numeric form.
7515
7516           On entry "start" and *len_p give the string to scan, *flags gives
7517           conversion flags, and "result" should be "NULL" or a pointer to an
7518           NV.  The scan stops at the end of the string, or at just before the
7519           first invalid character.  Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
7520           in *flags, encountering an invalid character (except NUL) will also
7521           trigger a warning.  On return *len_p is set to the length of the
7522           scanned string, and *flags gives output flags.
7523
7524           If the value is <= "UV_MAX" it is returned as a UV, the output
7525           flags are clear, and nothing is written to *result.  If the value
7526           is > "UV_MAX", "grok_hex" returns "UV_MAX", sets
7527           "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
7528           approximation of the correct value into *result (which is an NV; or
7529           the approximation is discarded if "result" is NULL).
7530
7531           The hex number may optionally be prefixed with "0x" or "x" unless
7532           "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
7533
7534           If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
7535           pairs of digits may be separated from each other by a single
7536           underscore; also a single leading underscore is accepted.
7537
7538            UV  grok_hex(const char* start, STRLEN* len_p, I32* flags,
7539                         NV *result)
7540
7541       "grok_infnan"
7542           Helper for "grok_number()", accepts various ways of spelling
7543           "infinity" or "not a number", and returns one of the following flag
7544           combinations:
7545
7546             IS_NUMBER_INFINITY
7547             IS_NUMBER_NAN
7548             IS_NUMBER_INFINITY | IS_NUMBER_NEG
7549             IS_NUMBER_NAN | IS_NUMBER_NEG
7550             0
7551
7552           possibly |-ed with "IS_NUMBER_TRAILING".
7553
7554           If an infinity or a not-a-number is recognized, *sp will point to
7555           one byte past the end of the recognized string.  If the recognition
7556           fails, zero is returned, and *sp will not move.
7557
7558            int  grok_infnan(const char** sp, const char *send)
7559
7560       "grok_number"
7561           Identical to "grok_number_flags()" with "flags" set to zero.
7562
7563            int  grok_number(const char *pv, STRLEN len, UV *valuep)
7564
7565       "grok_number_flags"
7566           Recognise (or not) a number.  The type of the number is returned (0
7567           if unrecognised), otherwise it is a bit-ORed combination of
7568           "IS_NUMBER_IN_UV", "IS_NUMBER_GREATER_THAN_UV_MAX",
7569           "IS_NUMBER_NOT_INT", "IS_NUMBER_NEG", "IS_NUMBER_INFINITY",
7570           "IS_NUMBER_NAN" (defined in perl.h).
7571
7572           If the value of the number can fit in a UV, it is returned in
7573           *valuep.  "IS_NUMBER_IN_UV" will be set to indicate that *valuep is
7574           valid, "IS_NUMBER_IN_UV" will never be set unless *valuep is valid,
7575           but *valuep may have been assigned to during processing even though
7576           "IS_NUMBER_IN_UV" is not set on return.  If "valuep" is "NULL",
7577           "IS_NUMBER_IN_UV" will be set for the same cases as when "valuep"
7578           is non-"NULL", but no actual assignment (or SEGV) will occur.
7579
7580           "IS_NUMBER_NOT_INT" will be set with "IS_NUMBER_IN_UV" if trailing
7581           decimals were seen (in which case *valuep gives the true value
7582           truncated to an integer), and "IS_NUMBER_NEG" if the number is
7583           negative (in which case *valuep holds the absolute value).
7584           "IS_NUMBER_IN_UV" is not set if "e" notation was used or the number
7585           is larger than a UV.
7586
7587           "flags" allows only "PERL_SCAN_TRAILING", which allows for trailing
7588           non-numeric text on an otherwise successful grok, setting
7589           "IS_NUMBER_TRAILING" on the result.
7590
7591            int  grok_number_flags(const char *pv, STRLEN len, UV *valuep,
7592                                   U32 flags)
7593
7594       "GROK_NUMERIC_RADIX"
7595           A synonym for "grok_numeric_radix"
7596
7597            bool  GROK_NUMERIC_RADIX(NN const char **sp, NN const char *send)
7598
7599       "grok_numeric_radix"
7600           Scan and skip for a numeric decimal separator (radix).
7601
7602            bool  grok_numeric_radix(const char **sp, const char *send)
7603
7604       "grok_oct"
7605           converts a string representing an octal number to numeric form.
7606
7607           On entry "start" and *len_p give the string to scan, *flags gives
7608           conversion flags, and "result" should be "NULL" or a pointer to an
7609           NV.  The scan stops at the end of the string, or at just before the
7610           first invalid character.  Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
7611           in *flags, encountering an invalid character (except NUL) will also
7612           trigger a warning.  On return *len_p is set to the length of the
7613           scanned string, and *flags gives output flags.
7614
7615           If the value is <= "UV_MAX" it is returned as a UV, the output
7616           flags are clear, and nothing is written to *result.  If the value
7617           is > "UV_MAX", "grok_oct" returns "UV_MAX", sets
7618           "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
7619           approximation of the correct value into *result (which is an NV; or
7620           the approximation is discarded if "result" is NULL).
7621
7622           If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
7623           pairs of digits may be separated from each other by a single
7624           underscore; also a single leading underscore is accepted.
7625
7626           The "PERL_SCAN_DISALLOW_PREFIX" flag is always treated as being set
7627           for this function.
7628
7629            UV  grok_oct(const char* start, STRLEN* len_p, I32* flags,
7630                         NV *result)
7631
7632       "isinfnan"
7633           "Perl_isinfnan()" is a utility function that returns true if the NV
7634           argument is either an infinity or a "NaN", false otherwise.  To
7635           test in more detail, use "Perl_isinf()" and "Perl_isnan()".
7636
7637           This is also the logical inverse of Perl_isfinite().
7638
7639            bool  isinfnan(NV nv)
7640
7641       "my_atof"
7642           "atof"(3), but properly works with Perl locale handling, accepting
7643           a dot radix character always, but also the current locale's radix
7644           character if and only if called from within the lexical scope of a
7645           Perl "use locale" statement.
7646
7647           N.B. "s" must be NUL terminated.
7648
7649            NV  my_atof(const char *s)
7650
7651       "my_strtod"
7652           This function is equivalent to the libc strtod() function, and is
7653           available even on platforms that lack plain strtod().  Its return
7654           value is the best available precision depending on platform
7655           capabilities and Configure options.
7656
7657           It properly handles the locale radix character, meaning it expects
7658           a dot except when called from within the scope of "use locale", in
7659           which case the radix character should be that specified by the
7660           current locale.
7661
7662           The synonym Strtod() may be used instead.
7663
7664            NV  my_strtod(const char * const s, char ** e)
7665
7666       "PERL_ABS"
7667           Typeless "abs" or "fabs", etc.  (The usage below indicates it is
7668           for integers, but it works for any type.)  Use instead of these,
7669           since the C library ones force their argument to be what it is
7670           expecting, potentially leading to disaster.  But also beware that
7671           this evaluates its argument twice, so no "x++".
7672
7673            int  PERL_ABS(int x)
7674
7675       "Perl_acos"
7676       "Perl_asin"
7677       "Perl_atan"
7678       "Perl_atan2"
7679       "Perl_ceil"
7680       "Perl_cos"
7681       "Perl_cosh"
7682       "Perl_exp"
7683       "Perl_floor"
7684       "Perl_fmod"
7685       "Perl_frexp"
7686       "Perl_isfinite"
7687       "Perl_isinf"
7688       "Perl_isnan"
7689       "Perl_ldexp"
7690       "Perl_log"
7691       "Perl_log10"
7692       "Perl_modf"
7693       "Perl_pow"
7694       "Perl_sin"
7695       "Perl_sinh"
7696       "Perl_sqrt"
7697       "Perl_tan"
7698       "Perl_tanh"
7699           These perform the corresponding mathematical operation on the
7700           operand(s), using the libc function designed for the task that has
7701           just enough precision for an NV on this platform.  If no such
7702           function with sufficient precision exists, the highest precision
7703           one available is used.
7704
7705            NV  Perl_acos    (NV x)
7706            NV  Perl_asin    (NV x)
7707            NV  Perl_atan    (NV x)
7708            NV  Perl_atan2   (NV x, NV y)
7709            NV  Perl_ceil    (NV x)
7710            NV  Perl_cos     (NV x)
7711            NV  Perl_cosh    (NV x)
7712            NV  Perl_exp     (NV x)
7713            NV  Perl_floor   (NV x)
7714            NV  Perl_fmod    (NV x, NV y)
7715            NV  Perl_frexp   (NV x, int *exp)
7716            IV  Perl_isfinite(NV x)
7717            IV  Perl_isinf   (NV x)
7718            IV  Perl_isnan   (NV x)
7719            NV  Perl_ldexp   (NV x, int exp)
7720            NV  Perl_log     (NV x)
7721            NV  Perl_log10   (NV x)
7722            NV  Perl_modf    (NV x, NV *iptr)
7723            NV  Perl_pow     (NV x, NV y)
7724            NV  Perl_sin     (NV x)
7725            NV  Perl_sinh    (NV x)
7726            NV  Perl_sqrt    (NV x)
7727            NV  Perl_tan     (NV x)
7728            NV  Perl_tanh    (NV x)
7729
7730       "Perl_signbit"
7731           NOTE: "Perl_signbit" is experimental and may change or be removed
7732           without notice.
7733
7734           Return a non-zero integer if the sign bit on an NV is set, and 0 if
7735           it is not.
7736
7737           If Configure detects this system has a "signbit()" that will work
7738           with our NVs, then we just use it via the "#define" in perl.h.
7739           Otherwise, fall back on this implementation.  The main use of this
7740           function is catching "-0.0".
7741
7742           "Configure" notes:  This function is called 'Perl_signbit' instead
7743           of a plain 'signbit' because it is easy to imagine a system having
7744           a "signbit()" function or macro that doesn't happen to work with
7745           our particular choice of NVs.  We shouldn't just re-"#define"
7746           "signbit" as "Perl_signbit" and expect the standard system headers
7747           to be happy.  Also, this is a no-context function (no "pTHX_")
7748           because "Perl_signbit()" is usually re-"#defined" in perl.h as a
7749           simple macro call to the system's "signbit()".  Users should just
7750           always call "Perl_signbit()".
7751
7752            int  Perl_signbit(NV f)
7753
7754       "PL_hexdigit"
7755           This array, indexed by an integer, converts that value into the
7756           character that represents it.  For example, if the input is 8, the
7757           return will be a string whose first character is '8'.  What is
7758           actually returned is a pointer into a string.  All you are
7759           interested in is the first character of that string.  To get
7760           uppercase letters (for the values 10..15), add 16 to the index.
7761           Hence, "PL_hexdigit[11]" is 'b', and "PL_hexdigit[11+16]" is 'B'.
7762           Adding 16 to an index whose representation is '0'..'9' yields the
7763           same as not adding 16.  Indices outside the range 0..31 result in
7764           (bad) undedefined behavior.
7765
7766       "READ_XDIGIT"
7767           Returns the value of an ASCII-range hex digit and advances the
7768           string pointer.  Behaviour is only well defined when isXDIGIT(*str)
7769           is true.
7770
7771            U8  READ_XDIGIT(char str*)
7772
7773       "scan_bin"
7774           For backwards compatibility.  Use "grok_bin" instead.
7775
7776            NV  scan_bin(const char* start, STRLEN len, STRLEN* retlen)
7777
7778       "scan_hex"
7779           For backwards compatibility.  Use "grok_hex" instead.
7780
7781            NV  scan_hex(const char* start, STRLEN len, STRLEN* retlen)
7782
7783       "scan_oct"
7784           For backwards compatibility.  Use "grok_oct" instead.
7785
7786            NV  scan_oct(const char* start, STRLEN len, STRLEN* retlen)
7787
7788       "seedDrand01"
7789           This symbol defines the macro to be used in seeding the random
7790           number generator (see "Drand01").
7791
7792            void  seedDrand01(Rand_seed_t x)
7793
7794       "Strtod"
7795           This is a synonym for "my_strtod".
7796
7797            NV  Strtod(NN const char * const s, NULLOK char ** e)
7798
7799       "Strtol"
7800           Platform and configuration independent "strtol".  This expands to
7801           the appropriate "strotol"-like function based on the platform and
7802           Configure options>.  For example it could expand to "strtoll" or
7803           "strtoq" instead of "strtol".
7804
7805            NV  Strtol(NN const char * const s, NULLOK char ** e, int base)
7806
7807       "Strtoul"
7808           Platform and configuration independent "strtoul".  This expands to
7809           the appropriate "strotoul"-like function based on the platform and
7810           Configure options>.  For example it could expand to "strtoull" or
7811           "strtouq" instead of "strtoul".
7812
7813            NV  Strtoul(NN const char * const s, NULLOK char ** e, int base)
7814

Optree construction

7816       "newASSIGNOP"
7817           Constructs, checks, and returns an assignment op.  "left" and
7818           "right" supply the parameters of the assignment; they are consumed
7819           by this function and become part of the constructed op tree.
7820
7821           If "optype" is "OP_ANDASSIGN", "OP_ORASSIGN", or "OP_DORASSIGN",
7822           then a suitable conditional optree is constructed.  If "optype" is
7823           the opcode of a binary operator, such as "OP_BIT_OR", then an op is
7824           constructed that performs the binary operation and assigns the
7825           result to the left argument.  Either way, if "optype" is non-zero
7826           then "flags" has no effect.
7827
7828           If "optype" is zero, then a plain scalar or list assignment is
7829           constructed.  Which type of assignment it is is automatically
7830           determined.  "flags" gives the eight bits of "op_flags", except
7831           that "OPf_KIDS" will be set automatically, and, shifted up eight
7832           bits, the eight bits of "op_private", except that the bit with
7833           value 1 or 2 is automatically set as required.
7834
7835            OP*  newASSIGNOP(I32 flags, OP* left, I32 optype, OP* right)
7836
7837       "newBINOP"
7838           Constructs, checks, and returns an op of any binary type.  "type"
7839           is the opcode.  "flags" gives the eight bits of "op_flags", except
7840           that "OPf_KIDS" will be set automatically, and, shifted up eight
7841           bits, the eight bits of "op_private", except that the bit with
7842           value 1 or 2 is automatically set as required.  "first" and "last"
7843           supply up to two ops to be the direct children of the binary op;
7844           they are consumed by this function and become part of the
7845           constructed op tree.
7846
7847            OP*  newBINOP(I32 type, I32 flags, OP* first, OP* last)
7848
7849       "newCONDOP"
7850           Constructs, checks, and returns a conditional-expression
7851           ("cond_expr") op.  "flags" gives the eight bits of "op_flags",
7852           except that "OPf_KIDS" will be set automatically, and, shifted up
7853           eight bits, the eight bits of "op_private", except that the bit
7854           with value 1 is automatically set.  "first" supplies the expression
7855           selecting between the two branches, and "trueop" and "falseop"
7856           supply the branches; they are consumed by this function and become
7857           part of the constructed op tree.
7858
7859            OP*  newCONDOP(I32 flags, OP* first, OP* trueop, OP* falseop)
7860
7861       "newDEFSVOP"
7862           Constructs and returns an op to access $_.
7863
7864            OP*  newDEFSVOP()
7865
7866       "newFOROP"
7867           Constructs, checks, and returns an op tree expressing a "foreach"
7868           loop (iteration through a list of values).  This is a heavyweight
7869           loop, with structure that allows exiting the loop by "last" and
7870           suchlike.
7871
7872           "sv" optionally supplies the variable that will be aliased to each
7873           item in turn; if null, it defaults to $_.  "expr" supplies the list
7874           of values to iterate over.  "block" supplies the main body of the
7875           loop, and "cont" optionally supplies a "continue" block that
7876           operates as a second half of the body.  All of these optree inputs
7877           are consumed by this function and become part of the constructed op
7878           tree.
7879
7880           "flags" gives the eight bits of "op_flags" for the "leaveloop" op
7881           and, shifted up eight bits, the eight bits of "op_private" for the
7882           "leaveloop" op, except that (in both cases) some bits will be set
7883           automatically.
7884
7885            OP*  newFOROP(I32 flags, OP* sv, OP* expr, OP* block, OP* cont)
7886
7887       "newGIVENOP"
7888           Constructs, checks, and returns an op tree expressing a "given"
7889           block.  "cond" supplies the expression to whose value $_ will be
7890           locally aliased, and "block" supplies the body of the "given"
7891           construct; they are consumed by this function and become part of
7892           the constructed op tree.  "defsv_off" must be zero (it used to
7893           identity the pad slot of lexical $_).
7894
7895            OP*  newGIVENOP(OP* cond, OP* block, PADOFFSET defsv_off)
7896
7897       "newGVOP"
7898           Constructs, checks, and returns an op of any type that involves an
7899           embedded reference to a GV.  "type" is the opcode.  "flags" gives
7900           the eight bits of "op_flags".  "gv" identifies the GV that the op
7901           should reference; calling this function does not transfer ownership
7902           of any reference to it.
7903
7904            OP*  newGVOP(I32 type, I32 flags, GV* gv)
7905
7906       "newLISTOP"
7907           Constructs, checks, and returns an op of any list type.  "type" is
7908           the opcode.  "flags" gives the eight bits of "op_flags", except
7909           that "OPf_KIDS" will be set automatically if required.  "first" and
7910           "last" supply up to two ops to be direct children of the list op;
7911           they are consumed by this function and become part of the
7912           constructed op tree.
7913
7914           For most list operators, the check function expects all the kid ops
7915           to be present already, so calling "newLISTOP(OP_JOIN, ...)" (e.g.)
7916           is not appropriate.  What you want to do in that case is create an
7917           op of type "OP_LIST", append more children to it, and then call
7918           "op_convert_list".  See "op_convert_list" for more information.
7919
7920            OP*  newLISTOP(I32 type, I32 flags, OP* first, OP* last)
7921
7922       "newLOGOP"
7923           Constructs, checks, and returns a logical (flow control) op.
7924           "type" is the opcode.  "flags" gives the eight bits of "op_flags",
7925           except that "OPf_KIDS" will be set automatically, and, shifted up
7926           eight bits, the eight bits of "op_private", except that the bit
7927           with value 1 is automatically set.  "first" supplies the expression
7928           controlling the flow, and "other" supplies the side (alternate)
7929           chain of ops; they are consumed by this function and become part of
7930           the constructed op tree.
7931
7932            OP*  newLOGOP(I32 optype, I32 flags, OP *first, OP *other)
7933
7934       "newLOOPEX"
7935           Constructs, checks, and returns a loop-exiting op (such as "goto"
7936           or "last").  "type" is the opcode.  "label" supplies the parameter
7937           determining the target of the op; it is consumed by this function
7938           and becomes part of the constructed op tree.
7939
7940            OP*  newLOOPEX(I32 type, OP* label)
7941
7942       "newLOOPOP"
7943           Constructs, checks, and returns an op tree expressing a loop.  This
7944           is only a loop in the control flow through the op tree; it does not
7945           have the heavyweight loop structure that allows exiting the loop by
7946           "last" and suchlike.  "flags" gives the eight bits of "op_flags"
7947           for the top-level op, except that some bits will be set
7948           automatically as required.  "expr" supplies the expression
7949           controlling loop iteration, and "block" supplies the body of the
7950           loop; they are consumed by this function and become part of the
7951           constructed op tree.  "debuggable" is currently unused and should
7952           always be 1.
7953
7954            OP*  newLOOPOP(I32 flags, I32 debuggable, OP* expr, OP* block)
7955
7956       "newMETHOP"
7957           Constructs, checks, and returns an op of method type with a method
7958           name evaluated at runtime.  "type" is the opcode.  "flags" gives
7959           the eight bits of "op_flags", except that "OPf_KIDS" will be set
7960           automatically, and, shifted up eight bits, the eight bits of
7961           "op_private", except that the bit with value 1 is automatically
7962           set.  "dynamic_meth" supplies an op which evaluates method name; it
7963           is consumed by this function and become part of the constructed op
7964           tree.  Supported optypes: "OP_METHOD".
7965
7966            OP*  newMETHOP(I32 type, I32 flags, OP* dynamic_meth)
7967
7968       "newMETHOP_named"
7969           Constructs, checks, and returns an op of method type with a
7970           constant method name.  "type" is the opcode.  "flags" gives the
7971           eight bits of "op_flags", and, shifted up eight bits, the eight
7972           bits of "op_private".  "const_meth" supplies a constant method
7973           name; it must be a shared COW string.  Supported optypes:
7974           "OP_METHOD_NAMED".
7975
7976            OP*  newMETHOP_named(I32 type, I32 flags, SV* const_meth)
7977
7978       "newNULLLIST"
7979           Constructs, checks, and returns a new "stub" op, which represents
7980           an empty list expression.
7981
7982            OP*  newNULLLIST()
7983
7984       "newOP"
7985           Constructs, checks, and returns an op of any base type (any type
7986           that has no extra fields).  "type" is the opcode.  "flags" gives
7987           the eight bits of "op_flags", and, shifted up eight bits, the eight
7988           bits of "op_private".
7989
7990            OP*  newOP(I32 optype, I32 flags)
7991
7992       "newPADOP"
7993           Constructs, checks, and returns an op of any type that involves a
7994           reference to a pad element.  "type" is the opcode.  "flags" gives
7995           the eight bits of "op_flags".  A pad slot is automatically
7996           allocated, and is populated with "sv"; this function takes
7997           ownership of one reference to it.
7998
7999           This function only exists if Perl has been compiled to use
8000           ithreads.
8001
8002            OP*  newPADOP(I32 type, I32 flags, SV* sv)
8003
8004       "newPMOP"
8005           Constructs, checks, and returns an op of any pattern matching type.
8006           "type" is the opcode.  "flags" gives the eight bits of "op_flags"
8007           and, shifted up eight bits, the eight bits of "op_private".
8008
8009            OP*  newPMOP(I32 type, I32 flags)
8010
8011       "newPVOP"
8012           Constructs, checks, and returns an op of any type that involves an
8013           embedded C-level pointer (PV).  "type" is the opcode.  "flags"
8014           gives the eight bits of "op_flags".  "pv" supplies the C-level
8015           pointer.  Depending on the op type, the memory referenced by "pv"
8016           may be freed when the op is destroyed.  If the op is of a freeing
8017           type, "pv" must have been allocated using "PerlMemShared_malloc".
8018
8019            OP*  newPVOP(I32 type, I32 flags, char* pv)
8020
8021       "newRANGE"
8022           Constructs and returns a "range" op, with subordinate "flip" and
8023           "flop" ops.  "flags" gives the eight bits of "op_flags" for the
8024           "flip" op and, shifted up eight bits, the eight bits of
8025           "op_private" for both the "flip" and "range" ops, except that the
8026           bit with value 1 is automatically set.  "left" and "right" supply
8027           the expressions controlling the endpoints of the range; they are
8028           consumed by this function and become part of the constructed op
8029           tree.
8030
8031            OP*  newRANGE(I32 flags, OP* left, OP* right)
8032
8033       "newSLICEOP"
8034           Constructs, checks, and returns an "lslice" (list slice) op.
8035           "flags" gives the eight bits of "op_flags", except that "OPf_KIDS"
8036           will be set automatically, and, shifted up eight bits, the eight
8037           bits of "op_private", except that the bit with value 1 or 2 is
8038           automatically set as required.  "listval" and "subscript" supply
8039           the parameters of the slice; they are consumed by this function and
8040           become part of the constructed op tree.
8041
8042            OP*  newSLICEOP(I32 flags, OP* subscript, OP* listop)
8043
8044       "newSTATEOP"
8045           Constructs a state op (COP).  The state op is normally a
8046           "nextstate" op, but will be a "dbstate" op if debugging is enabled
8047           for currently-compiled code.  The state op is populated from
8048           "PL_curcop" (or "PL_compiling").  If "label" is non-null, it
8049           supplies the name of a label to attach to the state op; this
8050           function takes ownership of the memory pointed at by "label", and
8051           will free it.  "flags" gives the eight bits of "op_flags" for the
8052           state op.
8053
8054           If "o" is null, the state op is returned.  Otherwise the state op
8055           is combined with "o" into a "lineseq" list op, which is returned.
8056           "o" is consumed by this function and becomes part of the returned
8057           op tree.
8058
8059            OP*  newSTATEOP(I32 flags, char* label, OP* o)
8060
8061       "newSVOP"
8062           Constructs, checks, and returns an op of any type that involves an
8063           embedded SV.  "type" is the opcode.  "flags" gives the eight bits
8064           of "op_flags".  "sv" gives the SV to embed in the op; this function
8065           takes ownership of one reference to it.
8066
8067            OP*  newSVOP(I32 type, I32 flags, SV* sv)
8068
8069       "newTRYCATCHOP"
8070           NOTE: "newTRYCATCHOP" is experimental and may change or be removed
8071           without notice.
8072
8073           Constructs and returns a conditional execution statement that
8074           implements the "try"/"catch" semantics.  First the op tree in
8075           "tryblock" is executed, inside a context that traps exceptions.  If
8076           an exception occurs then the optree in "catchblock" is executed,
8077           with the trapped exception set into the lexical variable given by
8078           "catchvar" (which must be an op of type "OP_PADSV").  All the
8079           optrees are consumed by this function and become part of the
8080           returned op tree.
8081
8082           The "flags" argument is currently ignored.
8083
8084            OP*  newTRYCATCHOP(I32 flags, OP* tryblock, OP *catchvar,
8085                               OP* catchblock)
8086
8087       "newUNOP"
8088           Constructs, checks, and returns an op of any unary type.  "type" is
8089           the opcode.  "flags" gives the eight bits of "op_flags", except
8090           that "OPf_KIDS" will be set automatically if required, and, shifted
8091           up eight bits, the eight bits of "op_private", except that the bit
8092           with value 1 is automatically set.  "first" supplies an optional op
8093           to be the direct child of the unary op; it is consumed by this
8094           function and become part of the constructed op tree.
8095
8096            OP*  newUNOP(I32 type, I32 flags, OP* first)
8097
8098       "newUNOP_AUX"
8099           Similar to "newUNOP", but creates an "UNOP_AUX" struct instead,
8100           with "op_aux" initialised to "aux"
8101
8102            OP*  newUNOP_AUX(I32 type, I32 flags, OP* first,
8103                             UNOP_AUX_item *aux)
8104
8105       "newWHENOP"
8106           Constructs, checks, and returns an op tree expressing a "when"
8107           block.  "cond" supplies the test expression, and "block" supplies
8108           the block that will be executed if the test evaluates to true; they
8109           are consumed by this function and become part of the constructed op
8110           tree.  "cond" will be interpreted DWIMically, often as a comparison
8111           against $_, and may be null to generate a "default" block.
8112
8113            OP*  newWHENOP(OP* cond, OP* block)
8114
8115       "newWHILEOP"
8116           Constructs, checks, and returns an op tree expressing a "while"
8117           loop.  This is a heavyweight loop, with structure that allows
8118           exiting the loop by "last" and suchlike.
8119
8120           "loop" is an optional preconstructed "enterloop" op to use in the
8121           loop; if it is null then a suitable op will be constructed
8122           automatically.  "expr" supplies the loop's controlling expression.
8123           "block" supplies the main body of the loop, and "cont" optionally
8124           supplies a "continue" block that operates as a second half of the
8125           body.  All of these optree inputs are consumed by this function and
8126           become part of the constructed op tree.
8127
8128           "flags" gives the eight bits of "op_flags" for the "leaveloop" op
8129           and, shifted up eight bits, the eight bits of "op_private" for the
8130           "leaveloop" op, except that (in both cases) some bits will be set
8131           automatically.  "debuggable" is currently unused and should always
8132           be 1.  "has_my" can be supplied as true to force the loop body to
8133           be enclosed in its own scope.
8134
8135            OP*  newWHILEOP(I32 flags, I32 debuggable, LOOP* loop, OP* expr,
8136                            OP* block, OP* cont, I32 has_my)
8137
8138       "PL_opfreehook"
8139           When non-"NULL", the function pointed by this variable will be
8140           called each time an OP is freed with the corresponding OP as the
8141           argument.  This allows extensions to free any extra attribute they
8142           have locally attached to an OP.  It is also assured to first fire
8143           for the parent OP and then for its kids.
8144
8145           When you replace this variable, it is considered a good practice to
8146           store the possibly previously installed hook and that you recall it
8147           inside your own.
8148
8149           On threaded perls, each thread has an independent copy of this
8150           variable; each initialized at creation time with the current value
8151           of the creating thread's copy.
8152
8153            Perl_ophook_t  PL_opfreehook
8154
8155       "PL_peepp"
8156           Pointer to the per-subroutine peephole optimiser.  This is a
8157           function that gets called at the end of compilation of a Perl
8158           subroutine (or equivalently independent piece of Perl code) to
8159           perform fixups of some ops and to perform small-scale
8160           optimisations.  The function is called once for each subroutine
8161           that is compiled, and is passed, as sole parameter, a pointer to
8162           the op that is the entry point to the subroutine.  It modifies the
8163           op tree in place.
8164
8165           The peephole optimiser should never be completely replaced.
8166           Rather, add code to it by wrapping the existing optimiser.  The
8167           basic way to do this can be seen in "Compile pass 3: peephole
8168           optimization" in perlguts.  If the new code wishes to operate on
8169           ops throughout the subroutine's structure, rather than just at the
8170           top level, it is likely to be more convenient to wrap the
8171           "PL_rpeepp" hook.
8172
8173           On threaded perls, each thread has an independent copy of this
8174           variable; each initialized at creation time with the current value
8175           of the creating thread's copy.
8176
8177            peep_t  PL_peepp
8178
8179       "PL_rpeepp"
8180           Pointer to the recursive peephole optimiser.  This is a function
8181           that gets called at the end of compilation of a Perl subroutine (or
8182           equivalently independent piece of Perl code) to perform fixups of
8183           some ops and to perform small-scale optimisations.  The function is
8184           called once for each chain of ops linked through their "op_next"
8185           fields; it is recursively called to handle each side chain.  It is
8186           passed, as sole parameter, a pointer to the op that is at the head
8187           of the chain.  It modifies the op tree in place.
8188
8189           The peephole optimiser should never be completely replaced.
8190           Rather, add code to it by wrapping the existing optimiser.  The
8191           basic way to do this can be seen in "Compile pass 3: peephole
8192           optimization" in perlguts.  If the new code wishes to operate only
8193           on ops at a subroutine's top level, rather than throughout the
8194           structure, it is likely to be more convenient to wrap the
8195           "PL_peepp" hook.
8196
8197           On threaded perls, each thread has an independent copy of this
8198           variable; each initialized at creation time with the current value
8199           of the creating thread's copy.
8200
8201            peep_t  PL_rpeepp
8202

Optree Manipulation Functions

8204       "alloccopstash"
8205           NOTE: "alloccopstash" is experimental and may change or be removed
8206           without notice.
8207
8208           Available only under threaded builds, this function allocates an
8209           entry in "PL_stashpad" for the stash passed to it.
8210
8211            PADOFFSET  alloccopstash(HV *hv)
8212
8213       "block_end"
8214           Handles compile-time scope exit.  "floor" is the savestack index
8215           returned by "block_start", and "seq" is the body of the block.
8216           Returns the block, possibly modified.
8217
8218            OP*  block_end(I32 floor, OP* seq)
8219
8220       "block_start"
8221           Handles compile-time scope entry.  Arranges for hints to be
8222           restored on block exit and also handles pad sequence numbers to
8223           make lexical variables scope right.  Returns a savestack index for
8224           use with "block_end".
8225
8226            int  block_start(int full)
8227
8228       "ck_entersub_args_list"
8229           Performs the default fixup of the arguments part of an "entersub"
8230           op tree.  This consists of applying list context to each of the
8231           argument ops.  This is the standard treatment used on a call marked
8232           with "&", or a method call, or a call through a subroutine
8233           reference, or any other call where the callee can't be identified
8234           at compile time, or a call where the callee has no prototype.
8235
8236            OP*  ck_entersub_args_list(OP *entersubop)
8237
8238       "ck_entersub_args_proto"
8239           Performs the fixup of the arguments part of an "entersub" op tree
8240           based on a subroutine prototype.  This makes various modifications
8241           to the argument ops, from applying context up to inserting "refgen"
8242           ops, and checking the number and syntactic types of arguments, as
8243           directed by the prototype.  This is the standard treatment used on
8244           a subroutine call, not marked with "&", where the callee can be
8245           identified at compile time and has a prototype.
8246
8247           "protosv" supplies the subroutine prototype to be applied to the
8248           call.  It may be a normal defined scalar, of which the string value
8249           will be used.  Alternatively, for convenience, it may be a
8250           subroutine object (a "CV*" that has been cast to "SV*") which has a
8251           prototype.  The prototype supplied, in whichever form, does not
8252           need to match the actual callee referenced by the op tree.
8253
8254           If the argument ops disagree with the prototype, for example by
8255           having an unacceptable number of arguments, a valid op tree is
8256           returned anyway.  The error is reflected in the parser state,
8257           normally resulting in a single exception at the top level of
8258           parsing which covers all the compilation errors that occurred.  In
8259           the error message, the callee is referred to by the name defined by
8260           the "namegv" parameter.
8261
8262            OP*  ck_entersub_args_proto(OP *entersubop, GV *namegv,
8263                                        SV *protosv)
8264
8265       "ck_entersub_args_proto_or_list"
8266           Performs the fixup of the arguments part of an "entersub" op tree
8267           either based on a subroutine prototype or using default list-
8268           context processing.  This is the standard treatment used on a
8269           subroutine call, not marked with "&", where the callee can be
8270           identified at compile time.
8271
8272           "protosv" supplies the subroutine prototype to be applied to the
8273           call, or indicates that there is no prototype.  It may be a normal
8274           scalar, in which case if it is defined then the string value will
8275           be used as a prototype, and if it is undefined then there is no
8276           prototype.  Alternatively, for convenience, it may be a subroutine
8277           object (a "CV*" that has been cast to "SV*"), of which the
8278           prototype will be used if it has one.  The prototype (or lack
8279           thereof) supplied, in whichever form, does not need to match the
8280           actual callee referenced by the op tree.
8281
8282           If the argument ops disagree with the prototype, for example by
8283           having an unacceptable number of arguments, a valid op tree is
8284           returned anyway.  The error is reflected in the parser state,
8285           normally resulting in a single exception at the top level of
8286           parsing which covers all the compilation errors that occurred.  In
8287           the error message, the callee is referred to by the name defined by
8288           the "namegv" parameter.
8289
8290            OP*  ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
8291                                                SV *protosv)
8292
8293       "cv_const_sv"
8294           If "cv" is a constant sub eligible for inlining, returns the
8295           constant value returned by the sub.  Otherwise, returns "NULL".
8296
8297           Constant subs can be created with "newCONSTSUB" or as described in
8298           "Constant Functions" in perlsub.
8299
8300            SV*  cv_const_sv(const CV *const cv)
8301
8302       "cv_get_call_checker"
8303           The original form of "cv_get_call_checker_flags", which does not
8304           return checker flags.  When using a checker function returned by
8305           this function, it is only safe to call it with a genuine GV as its
8306           "namegv" argument.
8307
8308            void  cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
8309                                      SV **ckobj_p)
8310
8311       "cv_get_call_checker_flags"
8312           Retrieves the function that will be used to fix up a call to "cv".
8313           Specifically, the function is applied to an "entersub" op tree for
8314           a subroutine call, not marked with "&", where the callee can be
8315           identified at compile time as "cv".
8316
8317           The C-level function pointer is returned in *ckfun_p, an SV
8318           argument for it is returned in *ckobj_p, and control flags are
8319           returned in *ckflags_p.  The function is intended to be called in
8320           this manner:
8321
8322            entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
8323
8324           In this call, "entersubop" is a pointer to the "entersub" op, which
8325           may be replaced by the check function, and "namegv" supplies the
8326           name that should be used by the check function to refer to the
8327           callee of the "entersub" op if it needs to emit any diagnostics.
8328           It is permitted to apply the check function in non-standard
8329           situations, such as to a call to a different subroutine or to a
8330           method call.
8331
8332           "namegv" may not actually be a GV.  If the
8333           "CALL_CHECKER_REQUIRE_GV" bit is clear in *ckflags_p, it is
8334           permitted to pass a CV or other SV instead, anything that can be
8335           used as the first argument to "cv_name".  If the
8336           "CALL_CHECKER_REQUIRE_GV" bit is set in *ckflags_p then the check
8337           function requires "namegv" to be a genuine GV.
8338
8339           By default, the check function is
8340           Perl_ck_entersub_args_proto_or_list, the SV parameter is "cv"
8341           itself, and the "CALL_CHECKER_REQUIRE_GV" flag is clear.  This
8342           implements standard prototype processing.  It can be changed, for a
8343           particular subroutine, by "cv_set_call_checker_flags".
8344
8345           If the "CALL_CHECKER_REQUIRE_GV" bit is set in "gflags" then it
8346           indicates that the caller only knows about the genuine GV version
8347           of "namegv", and accordingly the corresponding bit will always be
8348           set in *ckflags_p, regardless of the check function's recorded
8349           requirements.  If the "CALL_CHECKER_REQUIRE_GV" bit is clear in
8350           "gflags" then it indicates the caller knows about the possibility
8351           of passing something other than a GV as "namegv", and accordingly
8352           the corresponding bit may be either set or clear in *ckflags_p,
8353           indicating the check function's recorded requirements.
8354
8355           "gflags" is a bitset passed into "cv_get_call_checker_flags", in
8356           which only the "CALL_CHECKER_REQUIRE_GV" bit currently has a
8357           defined meaning (for which see above).  All other bits should be
8358           clear.
8359
8360            void  cv_get_call_checker_flags(CV *cv, U32 gflags,
8361                                            Perl_call_checker *ckfun_p,
8362                                            SV **ckobj_p, U32 *ckflags_p)
8363
8364       "cv_set_call_checker"
8365           The original form of "cv_set_call_checker_flags", which passes it
8366           the "CALL_CHECKER_REQUIRE_GV" flag for backward-compatibility.  The
8367           effect of that flag setting is that the check function is
8368           guaranteed to get a genuine GV as its "namegv" argument.
8369
8370            void  cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
8371                                      SV *ckobj)
8372
8373       "cv_set_call_checker_flags"
8374           Sets the function that will be used to fix up a call to "cv".
8375           Specifically, the function is applied to an "entersub" op tree for
8376           a subroutine call, not marked with "&", where the callee can be
8377           identified at compile time as "cv".
8378
8379           The C-level function pointer is supplied in "ckfun", an SV argument
8380           for it is supplied in "ckobj", and control flags are supplied in
8381           "ckflags".  The function should be defined like this:
8382
8383               STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
8384
8385           It is intended to be called in this manner:
8386
8387               entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
8388
8389           In this call, "entersubop" is a pointer to the "entersub" op, which
8390           may be replaced by the check function, and "namegv" supplies the
8391           name that should be used by the check function to refer to the
8392           callee of the "entersub" op if it needs to emit any diagnostics.
8393           It is permitted to apply the check function in non-standard
8394           situations, such as to a call to a different subroutine or to a
8395           method call.
8396
8397           "namegv" may not actually be a GV.  For efficiency, perl may pass a
8398           CV or other SV instead.  Whatever is passed can be used as the
8399           first argument to "cv_name".  You can force perl to pass a GV by
8400           including "CALL_CHECKER_REQUIRE_GV" in the "ckflags".
8401
8402           "ckflags" is a bitset, in which only the "CALL_CHECKER_REQUIRE_GV"
8403           bit currently has a defined meaning (for which see above).  All
8404           other bits should be clear.
8405
8406           The current setting for a particular CV can be retrieved by
8407           "cv_get_call_checker_flags".
8408
8409            void  cv_set_call_checker_flags(CV *cv, Perl_call_checker ckfun,
8410                                            SV *ckobj, U32 ckflags)
8411
8412       "LINKLIST"
8413           Given the root of an optree, link the tree in execution order using
8414           the "op_next" pointers and return the first op executed.  If this
8415           has already been done, it will not be redone, and "o->op_next" will
8416           be returned.  If "o->op_next" is not already set, "o" should be at
8417           least an "UNOP".
8418
8419            OP*  LINKLIST(OP *o)
8420
8421       "newATTRSUB"
8422           Construct a Perl subroutine, also performing some surrounding jobs.
8423
8424           This is the same as ""newATTRSUB_x"" in perlintern with its
8425           "o_is_gv" parameter set to FALSE.  This means that if "o" is null,
8426           the new sub will be anonymous; otherwise the name will be derived
8427           from "o" in the way described (as with all other details) in
8428           ""newATTRSUB_x"" in perlintern.
8429
8430            CV*  newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs, OP *block)
8431
8432       "newCONSTSUB"
8433           Behaves like "newCONSTSUB_flags", except that "name" is nul-
8434           terminated rather than of counted length, and no flags are set.
8435           (This means that "name" is always interpreted as Latin-1.)
8436
8437            CV*  newCONSTSUB(HV* stash, const char* name, SV* sv)
8438
8439       "newCONSTSUB_flags"
8440           Construct a constant subroutine, also performing some surrounding
8441           jobs.  A scalar constant-valued subroutine is eligible for inlining
8442           at compile-time, and in Perl code can be created by
8443           "sub FOO () { 123 }".  Other kinds of constant subroutine have
8444           other treatment.
8445
8446           The subroutine will have an empty prototype and will ignore any
8447           arguments when called.  Its constant behaviour is determined by
8448           "sv".  If "sv" is null, the subroutine will yield an empty list.
8449           If "sv" points to a scalar, the subroutine will always yield that
8450           scalar.  If "sv" points to an array, the subroutine will always
8451           yield a list of the elements of that array in list context, or the
8452           number of elements in the array in scalar context.  This function
8453           takes ownership of one counted reference to the scalar or array,
8454           and will arrange for the object to live as long as the subroutine
8455           does.  If "sv" points to a scalar then the inlining assumes that
8456           the value of the scalar will never change, so the caller must
8457           ensure that the scalar is not subsequently written to.  If "sv"
8458           points to an array then no such assumption is made, so it is
8459           ostensibly safe to mutate the array or its elements, but whether
8460           this is really supported has not been determined.
8461
8462           The subroutine will have "CvFILE" set according to "PL_curcop".
8463           Other aspects of the subroutine will be left in their default
8464           state.  The caller is free to mutate the subroutine beyond its
8465           initial state after this function has returned.
8466
8467           If "name" is null then the subroutine will be anonymous, with its
8468           "CvGV" referring to an "__ANON__" glob.  If "name" is non-null then
8469           the subroutine will be named accordingly, referenced by the
8470           appropriate glob.  "name" is a string of length "len" bytes giving
8471           a sigilless symbol name, in UTF-8 if "flags" has the "SVf_UTF8" bit
8472           set and in Latin-1 otherwise.  The name may be either qualified or
8473           unqualified.  If the name is unqualified then it defaults to being
8474           in the stash specified by "stash" if that is non-null, or to
8475           "PL_curstash" if "stash" is null.  The symbol is always added to
8476           the stash if necessary, with "GV_ADDMULTI" semantics.
8477
8478           "flags" should not have bits set other than "SVf_UTF8".
8479
8480           If there is already a subroutine of the specified name, then the
8481           new sub will replace the existing one in the glob.  A warning may
8482           be generated about the redefinition.
8483
8484           If the subroutine has one of a few special names, such as "BEGIN"
8485           or "END", then it will be claimed by the appropriate queue for
8486           automatic running of phase-related subroutines.  In this case the
8487           relevant glob will be left not containing any subroutine, even if
8488           it did contain one before.  Execution of the subroutine will likely
8489           be a no-op, unless "sv" was a tied array or the caller modified the
8490           subroutine in some interesting way before it was executed.  In the
8491           case of "BEGIN", the treatment is buggy: the sub will be executed
8492           when only half built, and may be deleted prematurely, possibly
8493           causing a crash.
8494
8495           The function returns a pointer to the constructed subroutine.  If
8496           the sub is anonymous then ownership of one counted reference to the
8497           subroutine is transferred to the caller.  If the sub is named then
8498           the caller does not get ownership of a reference.  In most such
8499           cases, where the sub has a non-phase name, the sub will be alive at
8500           the point it is returned by virtue of being contained in the glob
8501           that names it.  A phase-named subroutine will usually be alive by
8502           virtue of the reference owned by the phase's automatic run queue.
8503           A "BEGIN" subroutine may have been destroyed already by the time
8504           this function returns, but currently bugs occur in that case before
8505           the caller gets control.  It is the caller's responsibility to
8506           ensure that it knows which of these situations applies.
8507
8508            CV*  newCONSTSUB_flags(HV* stash, const char* name, STRLEN len,
8509                                   U32 flags, SV* sv)
8510
8511       "newSUB"
8512           Like "newATTRSUB", but without attributes.
8513
8514            CV*  newSUB(I32 floor, OP* o, OP* proto, OP* block)
8515
8516       "newXS"
8517           Used by "xsubpp" to hook up XSUBs as Perl subs.  "filename" needs
8518           to be static storage, as it is used directly as CvFILE(), without a
8519           copy being made.
8520
8521       "op_append_elem"
8522           Append an item to the list of ops contained directly within a list-
8523           type op, returning the lengthened list.  "first" is the list-type
8524           op, and "last" is the op to append to the list.  "optype" specifies
8525           the intended opcode for the list.  If "first" is not already a list
8526           of the right type, it will be upgraded into one.  If either "first"
8527           or "last" is null, the other is returned unchanged.
8528
8529            OP*  op_append_elem(I32 optype, OP* first, OP* last)
8530
8531       "op_append_list"
8532           Concatenate the lists of ops contained directly within two list-
8533           type ops, returning the combined list.  "first" and "last" are the
8534           list-type ops to concatenate.  "optype" specifies the intended
8535           opcode for the list.  If either "first" or "last" is not already a
8536           list of the right type, it will be upgraded into one.  If either
8537           "first" or "last" is null, the other is returned unchanged.
8538
8539            OP*  op_append_list(I32 optype, OP* first, OP* last)
8540
8541       "OP_CLASS"
8542           Return the class of the provided OP: that is, which of the *OP
8543           structures it uses.  For core ops this currently gets the
8544           information out of "PL_opargs", which does not always accurately
8545           reflect the type used; in v5.26 onwards, see also the function
8546           "op_class" which can do a better job of determining the used type.
8547
8548           For custom ops the type is returned from the registration, and it
8549           is up to the registree to ensure it is accurate.  The value
8550           returned will be one of the "OA_"* constants from op.h.
8551
8552            U32  OP_CLASS(OP *o)
8553
8554       "op_contextualize"
8555           Applies a syntactic context to an op tree representing an
8556           expression.  "o" is the op tree, and "context" must be "G_SCALAR",
8557           "G_ARRAY", or "G_VOID" to specify the context to apply.  The
8558           modified op tree is returned.
8559
8560            OP*  op_contextualize(OP* o, I32 context)
8561
8562       "op_convert_list"
8563           Converts "o" into a list op if it is not one already, and then
8564           converts it into the specified "type", calling its check function,
8565           allocating a target if it needs one, and folding constants.
8566
8567           A list-type op is usually constructed one kid at a time via
8568           "newLISTOP", "op_prepend_elem" and "op_append_elem".  Then finally
8569           it is passed to "op_convert_list" to make it the right type.
8570
8571            OP*  op_convert_list(I32 optype, I32 flags, OP* o)
8572
8573       "OP_DESC"
8574           Return a short description of the provided OP.
8575
8576            const char *  OP_DESC(OP *o)
8577
8578       "op_free"
8579           Free an op and its children. Only use this when an op is no longer
8580           linked to from any optree.
8581
8582            void  op_free(OP* arg)
8583
8584       "OpHAS_SIBLING"
8585           Returns true if "o" has a sibling
8586
8587            bool  OpHAS_SIBLING(OP *o)
8588
8589       "OpLASTSIB_set"
8590           Marks "o" as having no further siblings and marks o as having the
8591           specified parent. See also "OpMORESIB_set" and "OpMAYBESIB_set".
8592           For a higher-level interface, see "op_sibling_splice".
8593
8594            void  OpLASTSIB_set(OP *o, OP *parent)
8595
8596       "op_linklist"
8597           This function is the implementation of the "LINKLIST" macro.  It
8598           should not be called directly.
8599
8600            OP*  op_linklist(OP *o)
8601
8602       "op_lvalue"
8603           NOTE: "op_lvalue" is experimental and may change or be removed
8604           without notice.
8605
8606           Propagate lvalue ("modifiable") context to an op and its children.
8607           "type" represents the context type, roughly based on the type of op
8608           that would do the modifying, although "local()" is represented by
8609           "OP_NULL", because it has no op type of its own (it is signalled by
8610           a flag on the lvalue op).
8611
8612           This function detects things that can't be modified, such as
8613           "$x+1", and generates errors for them.  For example, "$x+1 = 2"
8614           would cause it to be called with an op of type "OP_ADD" and a
8615           "type" argument of "OP_SASSIGN".
8616
8617           It also flags things that need to behave specially in an lvalue
8618           context, such as "$$x = 5" which might have to vivify a reference
8619           in $x.
8620
8621            OP*  op_lvalue(OP* o, I32 type)
8622
8623       "OpMAYBESIB_set"
8624           Conditionally does "OpMORESIB_set" or "OpLASTSIB_set" depending on
8625           whether "sib" is non-null. For a higher-level interface, see
8626           "op_sibling_splice".
8627
8628            void  OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
8629
8630       "OpMORESIB_set"
8631           Sets the sibling of "o" to the non-zero value "sib". See also
8632           "OpLASTSIB_set" and "OpMAYBESIB_set". For a higher-level interface,
8633           see "op_sibling_splice".
8634
8635            void  OpMORESIB_set(OP *o, OP *sib)
8636
8637       "OP_NAME"
8638           Return the name of the provided OP.  For core ops this looks up the
8639           name from the op_type; for custom ops from the op_ppaddr.
8640
8641            const char *  OP_NAME(OP *o)
8642
8643       "op_null"
8644           Neutralizes an op when it is no longer needed, but is still linked
8645           to from other ops.
8646
8647            void  op_null(OP* o)
8648
8649       "op_parent"
8650           Returns the parent OP of "o", if it has a parent. Returns "NULL"
8651           otherwise.
8652
8653            OP*  op_parent(OP *o)
8654
8655       "op_prepend_elem"
8656           Prepend an item to the list of ops contained directly within a
8657           list-type op, returning the lengthened list.  "first" is the op to
8658           prepend to the list, and "last" is the list-type op.  "optype"
8659           specifies the intended opcode for the list.  If "last" is not
8660           already a list of the right type, it will be upgraded into one.  If
8661           either "first" or "last" is null, the other is returned unchanged.
8662
8663            OP*  op_prepend_elem(I32 optype, OP* first, OP* last)
8664
8665       "op_scope"
8666           NOTE: "op_scope" is experimental and may change or be removed
8667           without notice.
8668
8669           Wraps up an op tree with some additional ops so that at runtime a
8670           dynamic scope will be created.  The original ops run in the new
8671           dynamic scope, and then, provided that they exit normally, the
8672           scope will be unwound.  The additional ops used to create and
8673           unwind the dynamic scope will normally be an "enter"/"leave" pair,
8674           but a "scope" op may be used instead if the ops are simple enough
8675           to not need the full dynamic scope structure.
8676
8677            OP*  op_scope(OP* o)
8678
8679       "OpSIBLING"
8680           Returns the sibling of "o", or "NULL" if there is no sibling
8681
8682            OP*  OpSIBLING(OP *o)
8683
8684       "op_sibling_splice"
8685           A general function for editing the structure of an existing chain
8686           of op_sibling nodes.  By analogy with the perl-level "splice()"
8687           function, allows you to delete zero or more sequential nodes,
8688           replacing them with zero or more different nodes.  Performs the
8689           necessary op_first/op_last housekeeping on the parent node and
8690           op_sibling manipulation on the children.  The last deleted node
8691           will be marked as the last node by updating the
8692           op_sibling/op_sibparent or op_moresib field as appropriate.
8693
8694           Note that op_next is not manipulated, and nodes are not freed; that
8695           is the responsibility of the caller.  It also won't create a new
8696           list op for an empty list etc; use higher-level functions like
8697           op_append_elem() for that.
8698
8699           "parent" is the parent node of the sibling chain. It may passed as
8700           "NULL" if the splicing doesn't affect the first or last op in the
8701           chain.
8702
8703           "start" is the node preceding the first node to be spliced.
8704           Node(s) following it will be deleted, and ops will be inserted
8705           after it.  If it is "NULL", the first node onwards is deleted, and
8706           nodes are inserted at the beginning.
8707
8708           "del_count" is the number of nodes to delete.  If zero, no nodes
8709           are deleted.  If -1 or greater than or equal to the number of
8710           remaining kids, all remaining kids are deleted.
8711
8712           "insert" is the first of a chain of nodes to be inserted in place
8713           of the nodes.  If "NULL", no nodes are inserted.
8714
8715           The head of the chain of deleted ops is returned, or "NULL" if no
8716           ops were deleted.
8717
8718           For example:
8719
8720               action                    before      after         returns
8721               ------                    -----       -----         -------
8722
8723                                         P           P
8724               splice(P, A, 2, X-Y-Z)    |           |             B-C
8725                                         A-B-C-D     A-X-Y-Z-D
8726
8727                                         P           P
8728               splice(P, NULL, 1, X-Y)   |           |             A
8729                                         A-B-C-D     X-Y-B-C-D
8730
8731                                         P           P
8732               splice(P, NULL, 3, NULL)  |           |             A-B-C
8733                                         A-B-C-D     D
8734
8735                                         P           P
8736               splice(P, B, 0, X-Y)      |           |             NULL
8737                                         A-B-C-D     A-B-X-Y-C-D
8738
8739           For lower-level direct manipulation of "op_sibparent" and
8740           "op_moresib", see "OpMORESIB_set", "OpLASTSIB_set",
8741           "OpMAYBESIB_set".
8742
8743            OP*  op_sibling_splice(OP *parent, OP *start, int del_count,
8744                                   OP* insert)
8745
8746       "OP_TYPE_IS"
8747           Returns true if the given OP is not a "NULL" pointer and if it is
8748           of the given type.
8749
8750           The negation of this macro, "OP_TYPE_ISNT" is also available as
8751           well as "OP_TYPE_IS_NN" and "OP_TYPE_ISNT_NN" which elide the NULL
8752           pointer check.
8753
8754            bool  OP_TYPE_IS(OP *o, Optype type)
8755
8756       "OP_TYPE_IS_OR_WAS"
8757           Returns true if the given OP is not a NULL pointer and if it is of
8758           the given type or used to be before being replaced by an OP of type
8759           OP_NULL.
8760
8761           The negation of this macro, "OP_TYPE_ISNT_AND_WASNT" is also
8762           available as well as "OP_TYPE_IS_OR_WAS_NN" and
8763           "OP_TYPE_ISNT_AND_WASNT_NN" which elide the "NULL" pointer check.
8764
8765            bool  OP_TYPE_IS_OR_WAS(OP *o, Optype type)
8766
8767       "rv2cv_op_cv"
8768           Examines an op, which is expected to identify a subroutine at
8769           runtime, and attempts to determine at compile time which subroutine
8770           it identifies.  This is normally used during Perl compilation to
8771           determine whether a prototype can be applied to a function call.
8772           "cvop" is the op being considered, normally an "rv2cv" op.  A
8773           pointer to the identified subroutine is returned, if it could be
8774           determined statically, and a null pointer is returned if it was not
8775           possible to determine statically.
8776
8777           Currently, the subroutine can be identified statically if the RV
8778           that the "rv2cv" is to operate on is provided by a suitable "gv" or
8779           "const" op.  A "gv" op is suitable if the GV's CV slot is
8780           populated.  A "const" op is suitable if the constant value must be
8781           an RV pointing to a CV.  Details of this process may change in
8782           future versions of Perl.  If the "rv2cv" op has the
8783           "OPpENTERSUB_AMPER" flag set then no attempt is made to identify
8784           the subroutine statically: this flag is used to suppress compile-
8785           time magic on a subroutine call, forcing it to use default runtime
8786           behaviour.
8787
8788           If "flags" has the bit "RV2CVOPCV_MARK_EARLY" set, then the
8789           handling of a GV reference is modified.  If a GV was examined and
8790           its CV slot was found to be empty, then the "gv" op has the
8791           "OPpEARLY_CV" flag set.  If the op is not optimised away, and the
8792           CV slot is later populated with a subroutine having a prototype,
8793           that flag eventually triggers the warning "called too early to
8794           check prototype".
8795
8796           If "flags" has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then instead
8797           of returning a pointer to the subroutine it returns a pointer to
8798           the GV giving the most appropriate name for the subroutine in this
8799           context.  Normally this is just the "CvGV" of the subroutine, but
8800           for an anonymous ("CvANON") subroutine that is referenced through a
8801           GV it will be the referencing GV.  The resulting "GV*" is cast to
8802           "CV*" to be returned.  A null pointer is returned as usual if there
8803           is no statically-determinable subroutine.
8804
8805            CV*  rv2cv_op_cv(OP *cvop, U32 flags)
8806

Pack and Unpack

8808       "pack_cat"
8809           "DEPRECATED!"  It is planned to remove "pack_cat" from a future
8810           release of Perl.  Do not use it for new code; remove it from
8811           existing code.
8812
8813           The engine implementing "pack()" Perl function.  Note: parameters
8814           "next_in_list" and "flags" are not used.  This call should not be
8815           used; use "packlist" instead.
8816
8817            void  pack_cat(SV *cat, const char *pat, const char *patend,
8818                           SV **beglist, SV **endlist, SV ***next_in_list,
8819                           U32 flags)
8820
8821       "packlist"
8822           The engine implementing "pack()" Perl function.
8823
8824            void  packlist(SV *cat, const char *pat, const char *patend,
8825                           SV **beglist, SV **endlist)
8826
8827       "unpack_str"
8828           "DEPRECATED!"  It is planned to remove "unpack_str" from a future
8829           release of Perl.  Do not use it for new code; remove it from
8830           existing code.
8831
8832           The engine implementing "unpack()" Perl function.  Note: parameters
8833           "strbeg", "new_s" and "ocnt" are not used.  This call should not be
8834           used, use "unpackstring" instead.
8835
8836            SSize_t  unpack_str(const char *pat, const char *patend,
8837                                const char *s, const char *strbeg,
8838                                const char *strend, char **new_s, I32 ocnt,
8839                                U32 flags)
8840
8841       "unpackstring"
8842           The engine implementing the "unpack()" Perl function.
8843
8844           Using the template "pat..patend", this function unpacks the string
8845           "s..strend" into a number of mortal SVs, which it pushes onto the
8846           perl argument (@_) stack (so you will need to issue a "PUTBACK"
8847           before and "SPAGAIN" after the call to this function).  It returns
8848           the number of pushed elements.
8849
8850           The "strend" and "patend" pointers should point to the byte
8851           following the last character of each string.
8852
8853           Although this function returns its values on the perl argument
8854           stack, it doesn't take any parameters from that stack (and thus in
8855           particular there's no need to do a "PUSHMARK" before calling it,
8856           unlike "call_pv" for example).
8857
8858            SSize_t  unpackstring(const char *pat, const char *patend,
8859                                  const char *s, const char *strend,
8860                                  U32 flags)
8861

Pad Data Structures

8863       "CvPADLIST"
8864           NOTE: "CvPADLIST" is experimental and may change or be removed
8865           without notice.
8866
8867           CV's can have CvPADLIST(cv) set to point to a PADLIST.  This is the
8868           CV's scratchpad, which stores lexical variables and opcode
8869           temporary and per-thread values.
8870
8871           For these purposes "formats" are a kind-of CV; eval""s are too
8872           (except they're not callable at will and are always thrown away
8873           after the eval"" is done executing).  Require'd files are simply
8874           evals without any outer lexical scope.
8875
8876           XSUBs do not have a "CvPADLIST".  "dXSTARG" fetches values from
8877           "PL_curpad", but that is really the callers pad (a slot of which is
8878           allocated by every entersub). Do not get or set "CvPADLIST" if a CV
8879           is an XSUB (as determined by "CvISXSUB()"), "CvPADLIST" slot is
8880           reused for a different internal purpose in XSUBs.
8881
8882           The PADLIST has a C array where pads are stored.
8883
8884           The 0th entry of the PADLIST is a PADNAMELIST which represents the
8885           "names" or rather the "static type information" for lexicals.  The
8886           individual elements of a PADNAMELIST are PADNAMEs.  Future
8887           refactorings might stop the PADNAMELIST from being stored in the
8888           PADLIST's array, so don't rely on it.  See "PadlistNAMES".
8889
8890           The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the
8891           stack frame at that depth of recursion into the CV.  The 0th slot
8892           of a frame AV is an AV which is @_.  Other entries are storage for
8893           variables and op targets.
8894
8895           Iterating over the PADNAMELIST iterates over all possible pad
8896           items.  Pad slots for targets ("SVs_PADTMP") and GVs end up having
8897           &PL_padname_undef "names", while slots for constants have
8898           &PL_padname_const "names" (see "pad_alloc").  That
8899           &PL_padname_undef and &PL_padname_const are used is an
8900           implementation detail subject to change.  To test for them, use
8901           "!PadnamePV(name)" and "PadnamePV(name) && !PadnameLEN(name)",
8902           respectively.
8903
8904           Only "my"/"our" variable slots get valid names.  The rest are op
8905           targets/GVs/constants which are statically allocated or resolved at
8906           compile time.  These don't have names by which they can be looked
8907           up from Perl code at run time through eval"" the way "my"/"our"
8908           variables can be.  Since they can't be looked up by "name" but only
8909           by their index allocated at compile time (which is usually in
8910           "PL_op->op_targ"), wasting a name SV for them doesn't make sense.
8911
8912           The pad names in the PADNAMELIST have their PV holding the name of
8913           the variable.  The "COP_SEQ_RANGE_LOW" and "_HIGH" fields form a
8914           range (low+1..high inclusive) of cop_seq numbers for which the name
8915           is valid.  During compilation, these fields may hold the special
8916           value PERL_PADSEQ_INTRO to indicate various stages:
8917
8918            COP_SEQ_RANGE_LOW        _HIGH
8919            -----------------        -----
8920            PERL_PADSEQ_INTRO            0   variable not yet introduced:
8921                                             { my ($x
8922            valid-seq#   PERL_PADSEQ_INTRO   variable in scope:
8923                                             { my ($x);
8924            valid-seq#          valid-seq#   compilation of scope complete:
8925                                             { my ($x); .... }
8926
8927           When a lexical var hasn't yet been introduced, it already exists
8928           from the perspective of duplicate declarations, but not for
8929           variable lookups, e.g.
8930
8931               my ($x, $x); # '"my" variable $x masks earlier declaration'
8932               my $x = $x;  # equal to my $x = $::x;
8933
8934           For typed lexicals "PadnameTYPE" points at the type stash.  For
8935           "our" lexicals, "PadnameOURSTASH" points at the stash of the
8936           associated global (so that duplicate "our" declarations in the same
8937           package can be detected).  "PadnameGEN" is sometimes used to store
8938           the generation number during compilation.
8939
8940           If "PadnameOUTER" is set on the pad name, then that slot in the
8941           frame AV is a REFCNT'ed reference to a lexical from "outside".
8942           Such entries are sometimes referred to as 'fake'.  In this case,
8943           the name does not use 'low' and 'high' to store a cop_seq range,
8944           since it is in scope throughout.  Instead 'high' stores some flags
8945           containing info about the real lexical (is it declared in an anon,
8946           and is it capable of being instantiated multiple times?), and for
8947           fake ANONs, 'low' contains the index within the parent's pad where
8948           the lexical's value is stored, to make cloning quicker.
8949
8950           If the 'name' is "&" the corresponding entry in the PAD is a CV
8951           representing a possible closure.
8952
8953           Note that formats are treated as anon subs, and are cloned each
8954           time write is called (if necessary).
8955
8956           The flag "SVs_PADSTALE" is cleared on lexicals each time the "my()"
8957           is executed, and set on scope exit.  This allows the "Variable $x
8958           is not available" warning to be generated in evals, such as
8959
8960               { my $x = 1; sub f { eval '$x'} } f();
8961
8962           For state vars, "SVs_PADSTALE" is overloaded to mean 'not yet
8963           initialised', but this internal state is stored in a separate pad
8964           entry.
8965
8966            PADLIST *  CvPADLIST(CV *cv)
8967
8968       "pad_add_name_pvs"
8969           Exactly like "pad_add_name_pvn", but takes a literal string instead
8970           of a string/length pair.
8971
8972            PADOFFSET  pad_add_name_pvs("name", U32 flags, HV *typestash,
8973                                        HV *ourstash)
8974
8975       "PadARRAY"
8976           NOTE: "PadARRAY" is experimental and may change or be removed
8977           without notice.
8978
8979           The C array of pad entries.
8980
8981            SV **  PadARRAY(PAD * pad)
8982
8983       "pad_findmy_pvs"
8984           Exactly like "pad_findmy_pvn", but takes a literal string instead
8985           of a string/length pair.
8986
8987            PADOFFSET  pad_findmy_pvs("name", U32 flags)
8988
8989       "PadlistARRAY"
8990           NOTE: "PadlistARRAY" is experimental and may change or be removed
8991           without notice.
8992
8993           The C array of a padlist, containing the pads.  Only subscript it
8994           with numbers >= 1, as the 0th entry is not guaranteed to remain
8995           usable.
8996
8997            PAD **  PadlistARRAY(PADLIST * padlist)
8998
8999       "PadlistMAX"
9000           NOTE: "PadlistMAX" is experimental and may change or be removed
9001           without notice.
9002
9003           The index of the last allocated space in the padlist.  Note that
9004           the last pad may be in an earlier slot.  Any entries following it
9005           will be "NULL" in that case.
9006
9007            SSize_t  PadlistMAX(PADLIST * padlist)
9008
9009       "PadlistNAMES"
9010           NOTE: "PadlistNAMES" is experimental and may change or be removed
9011           without notice.
9012
9013           The names associated with pad entries.
9014
9015            PADNAMELIST *  PadlistNAMES(PADLIST * padlist)
9016
9017       "PadlistNAMESARRAY"
9018           NOTE: "PadlistNAMESARRAY" is experimental and may change or be
9019           removed without notice.
9020
9021           The C array of pad names.
9022
9023            PADNAME **  PadlistNAMESARRAY(PADLIST * padlist)
9024
9025       "PadlistNAMESMAX"
9026           NOTE: "PadlistNAMESMAX" is experimental and may change or be
9027           removed without notice.
9028
9029           The index of the last pad name.
9030
9031            SSize_t  PadlistNAMESMAX(PADLIST * padlist)
9032
9033       "PadlistREFCNT"
9034           NOTE: "PadlistREFCNT" is experimental and may change or be removed
9035           without notice.
9036
9037           The reference count of the padlist.  Currently this is always 1.
9038
9039            U32  PadlistREFCNT(PADLIST * padlist)
9040
9041       "PadMAX"
9042           NOTE: "PadMAX" is experimental and may change or be removed without
9043           notice.
9044
9045           The index of the last pad entry.
9046
9047            SSize_t  PadMAX(PAD * pad)
9048
9049       "PadnameLEN"
9050           NOTE: "PadnameLEN" is experimental and may change or be removed
9051           without notice.
9052
9053           The length of the name.
9054
9055            STRLEN  PadnameLEN(PADNAME * pn)
9056
9057       "PadnamelistARRAY"
9058           NOTE: "PadnamelistARRAY" is experimental and may change or be
9059           removed without notice.
9060
9061           The C array of pad names.
9062
9063            PADNAME **  PadnamelistARRAY(PADNAMELIST * pnl)
9064
9065       "PadnamelistMAX"
9066           NOTE: "PadnamelistMAX" is experimental and may change or be removed
9067           without notice.
9068
9069           The index of the last pad name.
9070
9071            SSize_t  PadnamelistMAX(PADNAMELIST * pnl)
9072
9073       "PadnamelistREFCNT"
9074           NOTE: "PadnamelistREFCNT" is experimental and may change or be
9075           removed without notice.
9076
9077           The reference count of the pad name list.
9078
9079            SSize_t  PadnamelistREFCNT(PADNAMELIST * pnl)
9080
9081       "PadnamelistREFCNT_dec"
9082           NOTE: "PadnamelistREFCNT_dec" is experimental and may change or be
9083           removed without notice.
9084
9085           Lowers the reference count of the pad name list.
9086
9087            void  PadnamelistREFCNT_dec(PADNAMELIST * pnl)
9088
9089       "PadnamePV"
9090           NOTE: "PadnamePV" is experimental and may change or be removed
9091           without notice.
9092
9093           The name stored in the pad name struct.  This returns "NULL" for a
9094           target slot.
9095
9096            char *  PadnamePV(PADNAME * pn)
9097
9098       "PadnameREFCNT"
9099           NOTE: "PadnameREFCNT" is experimental and may change or be removed
9100           without notice.
9101
9102           The reference count of the pad name.
9103
9104            SSize_t  PadnameREFCNT(PADNAME * pn)
9105
9106       "PadnameREFCNT_dec"
9107           NOTE: "PadnameREFCNT_dec" is experimental and may change or be
9108           removed without notice.
9109
9110           Lowers the reference count of the pad name.
9111
9112            void  PadnameREFCNT_dec(PADNAME * pn)
9113
9114       "PadnameSV"
9115           NOTE: "PadnameSV" is experimental and may change or be removed
9116           without notice.
9117
9118           Returns the pad name as a mortal SV.
9119
9120            SV *  PadnameSV(PADNAME * pn)
9121
9122       "PadnameUTF8"
9123           NOTE: "PadnameUTF8" is experimental and may change or be removed
9124           without notice.
9125
9126           Whether PadnamePV is in UTF-8.  Currently, this is always true.
9127
9128            bool  PadnameUTF8(PADNAME * pn)
9129
9130       "pad_new"
9131           Create a new padlist, updating the global variables for the
9132           currently-compiling padlist to point to the new padlist.  The
9133           following flags can be OR'ed together:
9134
9135               padnew_CLONE        this pad is for a cloned CV
9136               padnew_SAVE         save old globals on the save stack
9137               padnew_SAVESUB      also save extra stuff for start of sub
9138
9139            PADLIST*  pad_new(int flags)
9140
9141       "PL_comppad"
9142           NOTE: "PL_comppad" is experimental and may change or be removed
9143           without notice.
9144
9145           During compilation, this points to the array containing the values
9146           part of the pad for the currently-compiling code.  (At runtime a CV
9147           may have many such value arrays; at compile time just one is
9148           constructed.)  At runtime, this points to the array containing the
9149           currently-relevant values for the pad for the currently-executing
9150           code.
9151
9152       "PL_comppad_name"
9153           NOTE: "PL_comppad_name" is experimental and may change or be
9154           removed without notice.
9155
9156           During compilation, this points to the array containing the names
9157           part of the pad for the currently-compiling code.
9158
9159       "PL_curpad"
9160           NOTE: "PL_curpad" is experimental and may change or be removed
9161           without notice.
9162
9163           Points directly to the body of the "PL_comppad" array.  (I.e., this
9164           is "PadARRAY(PL_comppad)".)
9165

Password and Group access

9167       "GRPASSWD"
9168           This symbol, if defined, indicates to the C program that "struct
9169           group" in grp.h contains "gr_passwd".
9170
9171       "HAS_ENDGRENT"
9172           This symbol, if defined, indicates that the getgrent routine is
9173           available for finalizing sequential access of the group database.
9174
9175       "HAS_ENDGRENT_R"
9176           This symbol, if defined, indicates that the "endgrent_r" routine is
9177           available to endgrent re-entrantly.
9178
9179       "HAS_ENDPWENT"
9180           This symbol, if defined, indicates that the getgrent routine is
9181           available for finalizing sequential access of the passwd database.
9182
9183       "HAS_ENDPWENT_R"
9184           This symbol, if defined, indicates that the "endpwent_r" routine is
9185           available to endpwent re-entrantly.
9186
9187       "HAS_GETGRENT"
9188           This symbol, if defined, indicates that the "getgrent" routine is
9189           available for sequential access of the group database.
9190
9191       "HAS_GETGRENT_R"
9192           This symbol, if defined, indicates that the "getgrent_r" routine is
9193           available to getgrent re-entrantly.
9194
9195       "HAS_GETPWENT"
9196           This symbol, if defined, indicates that the "getpwent" routine is
9197           available for sequential access of the passwd database.  If this is
9198           not available, the older "getpw()" function may be available.
9199
9200       "HAS_GETPWENT_R"
9201           This symbol, if defined, indicates that the "getpwent_r" routine is
9202           available to getpwent re-entrantly.
9203
9204       "HAS_SETGRENT"
9205           This symbol, if defined, indicates that the "setgrent" routine is
9206           available for initializing sequential access of the group database.
9207
9208       "HAS_SETGRENT_R"
9209           This symbol, if defined, indicates that the "setgrent_r" routine is
9210           available to setgrent re-entrantly.
9211
9212       "HAS_SETPWENT"
9213           This symbol, if defined, indicates that the "setpwent" routine is
9214           available for initializing sequential access of the passwd
9215           database.
9216
9217       "HAS_SETPWENT_R"
9218           This symbol, if defined, indicates that the "setpwent_r" routine is
9219           available to setpwent re-entrantly.
9220
9221       "PWAGE"
9222           This symbol, if defined, indicates to the C program that "struct
9223           passwd" contains "pw_age".
9224
9225       "PWCHANGE"
9226           This symbol, if defined, indicates to the C program that "struct
9227           passwd" contains "pw_change".
9228
9229       "PWCLASS"
9230           This symbol, if defined, indicates to the C program that "struct
9231           passwd" contains "pw_class".
9232
9233       "PWCOMMENT"
9234           This symbol, if defined, indicates to the C program that "struct
9235           passwd" contains "pw_comment".
9236
9237       "PWEXPIRE"
9238           This symbol, if defined, indicates to the C program that "struct
9239           passwd" contains "pw_expire".
9240
9241       "PWGECOS"
9242           This symbol, if defined, indicates to the C program that "struct
9243           passwd" contains "pw_gecos".
9244
9245       "PWPASSWD"
9246           This symbol, if defined, indicates to the C program that "struct
9247           passwd" contains "pw_passwd".
9248
9249       "PWQUOTA"
9250           This symbol, if defined, indicates to the C program that "struct
9251           passwd" contains "pw_quota".
9252

Paths to system commands

9254       "CSH"
9255           This symbol, if defined, contains the full pathname of csh.
9256
9257       "LOC_SED"
9258           This symbol holds the complete pathname to the sed program.
9259
9260       "SH_PATH"
9261           This symbol contains the full pathname to the shell used on this on
9262           this system to execute Bourne shell scripts.  Usually, this will be
9263           /bin/sh, though it's possible that some systems will have /bin/ksh,
9264           /bin/pdksh, /bin/ash, /bin/bash, or even something such as
9265           D:/bin/sh.exe.
9266

Prototype information

9268       "CRYPT_R_PROTO"
9269           This symbol encodes the prototype of "crypt_r".  It is zero if
9270           "d_crypt_r" is undef, and one of the "REENTRANT_PROTO_T_ABC" macros
9271           of reentr.h if "d_crypt_r" is defined.
9272
9273       "CTERMID_R_PROTO"
9274           This symbol encodes the prototype of "ctermid_r".  It is zero if
9275           "d_ctermid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9276           macros of reentr.h if "d_ctermid_r" is defined.
9277
9278       "DRAND48_R_PROTO"
9279           This symbol encodes the prototype of "drand48_r".  It is zero if
9280           "d_drand48_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9281           macros of reentr.h if "d_drand48_r" is defined.
9282
9283       "ENDGRENT_R_PROTO"
9284           This symbol encodes the prototype of "endgrent_r".  It is zero if
9285           "d_endgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9286           macros of reentr.h if "d_endgrent_r" is defined.
9287
9288       "ENDHOSTENT_R_PROTO"
9289           This symbol encodes the prototype of "endhostent_r".  It is zero if
9290           "d_endhostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9291           macros of reentr.h if "d_endhostent_r" is defined.
9292
9293       "ENDNETENT_R_PROTO"
9294           This symbol encodes the prototype of "endnetent_r".  It is zero if
9295           "d_endnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9296           macros of reentr.h if "d_endnetent_r" is defined.
9297
9298       "ENDPROTOENT_R_PROTO"
9299           This symbol encodes the prototype of "endprotoent_r".  It is zero
9300           if "d_endprotoent_r" is undef, and one of the
9301           "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_endprotoent_r" is
9302           defined.
9303
9304       "ENDPWENT_R_PROTO"
9305           This symbol encodes the prototype of "endpwent_r".  It is zero if
9306           "d_endpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9307           macros of reentr.h if "d_endpwent_r" is defined.
9308
9309       "ENDSERVENT_R_PROTO"
9310           This symbol encodes the prototype of "endservent_r".  It is zero if
9311           "d_endservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9312           macros of reentr.h if "d_endservent_r" is defined.
9313
9314       "GDBMNDBM_H_USES_PROTOTYPES"
9315           This symbol, if defined, indicates that gdbm/ndbm.h uses real
9316           "ANSI" C prototypes instead of K&R style function declarations
9317           without any parameter information. While "ANSI" C prototypes are
9318           supported in C++, K&R style function declarations will yield
9319           errors.
9320
9321       "GDBM_NDBM_H_USES_PROTOTYPES"
9322           This symbol, if defined, indicates that <gdbm-ndbm.h> uses real
9323           "ANSI" C prototypes instead of K&R style function declarations
9324           without any parameter information. While "ANSI" C prototypes are
9325           supported in C++, K&R style function declarations will yield
9326           errors.
9327
9328       "GETGRENT_R_PROTO"
9329           This symbol encodes the prototype of "getgrent_r".  It is zero if
9330           "d_getgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9331           macros of reentr.h if "d_getgrent_r" is defined.
9332
9333       "GETGRGID_R_PROTO"
9334           This symbol encodes the prototype of "getgrgid_r".  It is zero if
9335           "d_getgrgid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9336           macros of reentr.h if "d_getgrgid_r" is defined.
9337
9338       "GETGRNAM_R_PROTO"
9339           This symbol encodes the prototype of "getgrnam_r".  It is zero if
9340           "d_getgrnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9341           macros of reentr.h if "d_getgrnam_r" is defined.
9342
9343       "GETHOSTBYADDR_R_PROTO"
9344           This symbol encodes the prototype of "gethostbyaddr_r".  It is zero
9345           if "d_gethostbyaddr_r" is undef, and one of the
9346           "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_gethostbyaddr_r"
9347           is defined.
9348
9349       "GETHOSTBYNAME_R_PROTO"
9350           This symbol encodes the prototype of "gethostbyname_r".  It is zero
9351           if "d_gethostbyname_r" is undef, and one of the
9352           "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_gethostbyname_r"
9353           is defined.
9354
9355       "GETHOSTENT_R_PROTO"
9356           This symbol encodes the prototype of "gethostent_r".  It is zero if
9357           "d_gethostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9358           macros of reentr.h if "d_gethostent_r" is defined.
9359
9360       "GETLOGIN_R_PROTO"
9361           This symbol encodes the prototype of "getlogin_r".  It is zero if
9362           "d_getlogin_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9363           macros of reentr.h if "d_getlogin_r" is defined.
9364
9365       "GETNETBYADDR_R_PROTO"
9366           This symbol encodes the prototype of "getnetbyaddr_r".  It is zero
9367           if "d_getnetbyaddr_r" is undef, and one of the
9368           "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getnetbyaddr_r" is
9369           defined.
9370
9371       "GETNETBYNAME_R_PROTO"
9372           This symbol encodes the prototype of "getnetbyname_r".  It is zero
9373           if "d_getnetbyname_r" is undef, and one of the
9374           "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getnetbyname_r" is
9375           defined.
9376
9377       "GETNETENT_R_PROTO"
9378           This symbol encodes the prototype of "getnetent_r".  It is zero if
9379           "d_getnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9380           macros of reentr.h if "d_getnetent_r" is defined.
9381
9382       "GETPROTOBYNAME_R_PROTO"
9383           This symbol encodes the prototype of "getprotobyname_r".  It is
9384           zero if "d_getprotobyname_r" is undef, and one of the
9385           "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getprotobyname_r"
9386           is defined.
9387
9388       "GETPROTOBYNUMBER_R_PROTO"
9389           This symbol encodes the prototype of "getprotobynumber_r".  It is
9390           zero if "d_getprotobynumber_r" is undef, and one of the
9391           "REENTRANT_PROTO_T_ABC" macros of reentr.h if
9392           "d_getprotobynumber_r" is defined.
9393
9394       "GETPROTOENT_R_PROTO"
9395           This symbol encodes the prototype of "getprotoent_r".  It is zero
9396           if "d_getprotoent_r" is undef, and one of the
9397           "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getprotoent_r" is
9398           defined.
9399
9400       "GETPWENT_R_PROTO"
9401           This symbol encodes the prototype of "getpwent_r".  It is zero if
9402           "d_getpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9403           macros of reentr.h if "d_getpwent_r" is defined.
9404
9405       "GETPWNAM_R_PROTO"
9406           This symbol encodes the prototype of "getpwnam_r".  It is zero if
9407           "d_getpwnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9408           macros of reentr.h if "d_getpwnam_r" is defined.
9409
9410       "GETPWUID_R_PROTO"
9411           This symbol encodes the prototype of "getpwuid_r".  It is zero if
9412           "d_getpwuid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9413           macros of reentr.h if "d_getpwuid_r" is defined.
9414
9415       "GETSERVBYNAME_R_PROTO"
9416           This symbol encodes the prototype of "getservbyname_r".  It is zero
9417           if "d_getservbyname_r" is undef, and one of the
9418           "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getservbyname_r"
9419           is defined.
9420
9421       "GETSERVBYPORT_R_PROTO"
9422           This symbol encodes the prototype of "getservbyport_r".  It is zero
9423           if "d_getservbyport_r" is undef, and one of the
9424           "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getservbyport_r"
9425           is defined.
9426
9427       "GETSERVENT_R_PROTO"
9428           This symbol encodes the prototype of "getservent_r".  It is zero if
9429           "d_getservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9430           macros of reentr.h if "d_getservent_r" is defined.
9431
9432       "GETSPNAM_R_PROTO"
9433           This symbol encodes the prototype of "getspnam_r".  It is zero if
9434           "d_getspnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9435           macros of reentr.h if "d_getspnam_r" is defined.
9436
9437       "HAS_DBMINIT_PROTO"
9438           This symbol, if defined, indicates that the system provides a
9439           prototype for the "dbminit()" function.  Otherwise, it is up to the
9440           program to supply one.  A good guess is
9441
9442            extern int dbminit(char *);
9443
9444       "HAS_DRAND48_PROTO"
9445           This symbol, if defined, indicates that the system provides a
9446           prototype for the "drand48()" function.  Otherwise, it is up to the
9447           program to supply one.  A good guess is
9448
9449            extern double drand48(void);
9450
9451       "HAS_FLOCK_PROTO"
9452           This symbol, if defined, indicates that the system provides a
9453           prototype for the "flock()" function.  Otherwise, it is up to the
9454           program to supply one.  A good guess is
9455
9456            extern int flock(int, int);
9457
9458       "HAS_GETHOST_PROTOS"
9459           This symbol, if defined, indicates that netdb.h includes prototypes
9460           for "gethostent()", "gethostbyname()", and "gethostbyaddr()".
9461           Otherwise, it is up to the program to guess them.  See netdbtype.U
9462           (part of metaconfig) for probing for various "Netdb_xxx_t" types.
9463
9464       "HAS_GETNET_PROTOS"
9465           This symbol, if defined, indicates that netdb.h includes prototypes
9466           for "getnetent()", "getnetbyname()", and "getnetbyaddr()".
9467           Otherwise, it is up to the program to guess them.  See netdbtype.U
9468           (part of metaconfig) for probing for various "Netdb_xxx_t" types.
9469
9470       "HAS_GETPROTO_PROTOS"
9471           This symbol, if defined, indicates that netdb.h includes prototypes
9472           for "getprotoent()", "getprotobyname()", and "getprotobyaddr()".
9473           Otherwise, it is up to the program to guess them.  See netdbtype.U
9474           (part of metaconfig) for probing for various "Netdb_xxx_t" types.
9475
9476       "HAS_GETSERV_PROTOS"
9477           This symbol, if defined, indicates that netdb.h includes prototypes
9478           for "getservent()", "getservbyname()", and "getservbyaddr()".
9479           Otherwise, it is up to the program to guess them.  See netdbtype.U
9480           (part of metaconfig) for probing for various "Netdb_xxx_t" types.
9481
9482       "HAS_MODFL_PROTO"
9483           This symbol, if defined, indicates that the system provides a
9484           prototype for the "modfl()" function.  Otherwise, it is up to the
9485           program to supply one.
9486
9487       "HAS_SBRK_PROTO"
9488           This symbol, if defined, indicates that the system provides a
9489           prototype for the "sbrk()" function.  Otherwise, it is up to the
9490           program to supply one.  Good guesses are
9491
9492            extern void* sbrk(int);
9493            extern void* sbrk(size_t);
9494
9495       "HAS_SETRESGID_PROTO"
9496           This symbol, if defined, indicates that the system provides a
9497           prototype for the "setresgid()" function.  Otherwise, it is up to
9498           the program to supply one.  Good guesses are
9499
9500            extern int setresgid(uid_t ruid, uid_t euid, uid_t suid);
9501
9502       "HAS_SETRESUID_PROTO"
9503           This symbol, if defined, indicates that the system provides a
9504           prototype for the "setresuid()" function.  Otherwise, it is up to
9505           the program to supply one.  Good guesses are
9506
9507            extern int setresuid(uid_t ruid, uid_t euid, uid_t suid);
9508
9509       "HAS_SHMAT_PROTOTYPE"
9510           This symbol, if defined, indicates that the sys/shm.h includes a
9511           prototype for "shmat()".  Otherwise, it is up to the program to
9512           guess one.  "Shmat_t" "shmat(int, Shmat_t, int)" is a good guess,
9513           but not always right so it should be emitted by the program only
9514           when "HAS_SHMAT_PROTOTYPE" is not defined to avoid conflicting
9515           defs.
9516
9517       "HAS_SOCKATMARK_PROTO"
9518           This symbol, if defined, indicates that the system provides a
9519           prototype for the "sockatmark()" function.  Otherwise, it is up to
9520           the program to supply one.  A good guess is
9521
9522            extern int sockatmark(int);
9523
9524       "HAS_SYSCALL_PROTO"
9525           This symbol, if defined, indicates that the system provides a
9526           prototype for the "syscall()" function.  Otherwise, it is up to the
9527           program to supply one.  Good guesses are
9528
9529            extern int syscall(int,  ...);
9530            extern int syscall(long, ...);
9531
9532       "HAS_TELLDIR_PROTO"
9533           This symbol, if defined, indicates that the system provides a
9534           prototype for the "telldir()" function.  Otherwise, it is up to the
9535           program to supply one.  A good guess is
9536
9537            extern long telldir(DIR*);
9538
9539       "NDBM_H_USES_PROTOTYPES"
9540           This symbol, if defined, indicates that ndbm.h uses real "ANSI" C
9541           prototypes instead of K&R style function declarations without any
9542           parameter information. While "ANSI" C prototypes are supported in
9543           C++, K&R style function declarations will yield errors.
9544
9545       "RANDOM_R_PROTO"
9546           This symbol encodes the prototype of "random_r".  It is zero if
9547           "d_random_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9548           macros of reentr.h if "d_random_r" is defined.
9549
9550       "READDIR_R_PROTO"
9551           This symbol encodes the prototype of "readdir_r".  It is zero if
9552           "d_readdir_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9553           macros of reentr.h if "d_readdir_r" is defined.
9554
9555       "SETGRENT_R_PROTO"
9556           This symbol encodes the prototype of "setgrent_r".  It is zero if
9557           "d_setgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9558           macros of reentr.h if "d_setgrent_r" is defined.
9559
9560       "SETHOSTENT_R_PROTO"
9561           This symbol encodes the prototype of "sethostent_r".  It is zero if
9562           "d_sethostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9563           macros of reentr.h if "d_sethostent_r" is defined.
9564
9565       "SETLOCALE_R_PROTO"
9566           This symbol encodes the prototype of "setlocale_r".  It is zero if
9567           "d_setlocale_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9568           macros of reentr.h if "d_setlocale_r" is defined.
9569
9570       "SETNETENT_R_PROTO"
9571           This symbol encodes the prototype of "setnetent_r".  It is zero if
9572           "d_setnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9573           macros of reentr.h if "d_setnetent_r" is defined.
9574
9575       "SETPROTOENT_R_PROTO"
9576           This symbol encodes the prototype of "setprotoent_r".  It is zero
9577           if "d_setprotoent_r" is undef, and one of the
9578           "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_setprotoent_r" is
9579           defined.
9580
9581       "SETPWENT_R_PROTO"
9582           This symbol encodes the prototype of "setpwent_r".  It is zero if
9583           "d_setpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9584           macros of reentr.h if "d_setpwent_r" is defined.
9585
9586       "SETSERVENT_R_PROTO"
9587           This symbol encodes the prototype of "setservent_r".  It is zero if
9588           "d_setservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9589           macros of reentr.h if "d_setservent_r" is defined.
9590
9591       "SRAND48_R_PROTO"
9592           This symbol encodes the prototype of "srand48_r".  It is zero if
9593           "d_srand48_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9594           macros of reentr.h if "d_srand48_r" is defined.
9595
9596       "SRANDOM_R_PROTO"
9597           This symbol encodes the prototype of "srandom_r".  It is zero if
9598           "d_srandom_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9599           macros of reentr.h if "d_srandom_r" is defined.
9600
9601       "STRERROR_R_PROTO"
9602           This symbol encodes the prototype of "strerror_r".  It is zero if
9603           "d_strerror_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9604           macros of reentr.h if "d_strerror_r" is defined.
9605
9606       "TMPNAM_R_PROTO"
9607           This symbol encodes the prototype of "tmpnam_r".  It is zero if
9608           "d_tmpnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9609           macros of reentr.h if "d_tmpnam_r" is defined.
9610
9611       "TTYNAME_R_PROTO"
9612           This symbol encodes the prototype of "ttyname_r".  It is zero if
9613           "d_ttyname_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9614           macros of reentr.h if "d_ttyname_r" is defined.
9615

REGEXP Functions

9617       "pregcomp"
9618           Described in perlreguts.
9619
9620            REGEXP*  pregcomp(SV * const pattern, const U32 flags)
9621
9622       "pregexec"
9623           Described in perlreguts.
9624
9625            I32  pregexec(REGEXP * const prog, char* stringarg, char* strend,
9626                          char* strbeg, SSize_t minend, SV* screamer,
9627                          U32 nosave)
9628
9629       "re_dup_guts"
9630           Duplicate a regexp.
9631
9632           This routine is expected to clone a given regexp structure. It is
9633           only compiled under USE_ITHREADS.
9634
9635           After all of the core data stored in struct regexp is duplicated
9636           the "regexp_engine.dupe" method is used to copy any private data
9637           stored in the *pprivate pointer. This allows extensions to handle
9638           any duplication they need to do.
9639
9640            void  re_dup_guts(const REGEXP *sstr, REGEXP *dstr,
9641                              CLONE_PARAMS* param)
9642
9643       "regmatch_info"
9644           Some basic information about the current match that is created by
9645           Perl_regexec_flags and then passed to regtry(), regmatch() etc.  It
9646           is allocated as a local var on the stack, so nothing should be
9647           stored in it that needs preserving or clearing up on croak().  For
9648           that, see the aux_info and aux_info_eval members of the
9649           regmatch_state union.
9650
9651       "SvRX"
9652           Convenience macro to get the REGEXP from a SV.  This is
9653           approximately equivalent to the following snippet:
9654
9655               if (SvMAGICAL(sv))
9656                   mg_get(sv);
9657               if (SvROK(sv))
9658                   sv = MUTABLE_SV(SvRV(sv));
9659               if (SvTYPE(sv) == SVt_REGEXP)
9660                   return (REGEXP*) sv;
9661
9662           "NULL" will be returned if a REGEXP* is not found.
9663
9664            REGEXP *  SvRX(SV *sv)
9665
9666       "SvRXOK"
9667           Returns a boolean indicating whether the SV (or the one it
9668           references) is a REGEXP.
9669
9670           If you want to do something with the REGEXP* later use SvRX instead
9671           and check for NULL.
9672
9673            bool  SvRXOK(SV* sv)
9674

Signals

9676       "HAS_SIGINFO_SI_ADDR"
9677           This symbol, if defined, indicates that "siginfo_t" has the
9678           "si_addr" member
9679
9680       "HAS_SIGINFO_SI_BAND"
9681           This symbol, if defined, indicates that "siginfo_t" has the
9682           "si_band" member
9683
9684       "HAS_SIGINFO_SI_ERRNO"
9685           This symbol, if defined, indicates that "siginfo_t" has the
9686           "si_errno" member
9687
9688       "HAS_SIGINFO_SI_PID"
9689           This symbol, if defined, indicates that "siginfo_t" has the
9690           "si_pid" member
9691
9692       "HAS_SIGINFO_SI_STATUS"
9693           This symbol, if defined, indicates that "siginfo_t" has the
9694           "si_status" member
9695
9696       "HAS_SIGINFO_SI_UID"
9697           This symbol, if defined, indicates that "siginfo_t" has the
9698           "si_uid" member
9699
9700       "HAS_SIGINFO_SI_VALUE"
9701           This symbol, if defined, indicates that "siginfo_t" has the
9702           "si_value" member
9703
9704       "PERL_SIGNALS_UNSAFE_FLAG"
9705           If this bit in "PL_signals" is set, the system is uing the pre-Perl
9706           5.8 unsafe signals.  See "PERL_SIGNALS" in perlrun and "Deferred
9707           Signals (Safe Signals)" in perlipc.
9708
9709            U32  PERL_SIGNALS_UNSAFE_FLAG
9710
9711       "rsignal"
9712           A wrapper for the C library signal(2).  Don't use the latter, as
9713           the Perl version knows things that interact with the rest of the
9714           perl interpreter.
9715
9716            Sighandler_t  rsignal(int i, Sighandler_t t)
9717
9718       "Sigjmp_buf"
9719           This is the buffer type to be used with Sigsetjmp and Siglongjmp.
9720
9721       "Siglongjmp"
9722           This macro is used in the same way as "siglongjmp()", but will
9723           invoke traditional "longjmp()" if siglongjmp isn't available.  See
9724           "HAS_SIGSETJMP".
9725
9726            void  Siglongjmp(jmp_buf env, int val)
9727
9728       "SIG_NAME"
9729           This symbol contains a list of signal names in order of signal
9730           number. This is intended to be used as a static array
9731           initialization, like this:
9732
9733            char *sig_name[] = { SIG_NAME };
9734
9735           The signals in the list are separated with commas, and each signal
9736           is surrounded by double quotes. There is no leading "SIG" in the
9737           signal name, i.e. "SIGQUIT" is known as ""QUIT"".  Gaps in the
9738           signal numbers (up to "NSIG") are filled in with "NUMnn", etc.,
9739           where nn is the actual signal number (e.g. "NUM37").  The signal
9740           number for "sig_name[i]" is stored in "sig_num[i]".  The last
9741           element is 0 to terminate the list with a "NULL".  This corresponds
9742           to the 0 at the end of the "sig_name_init" list.  Note that this
9743           variable is initialized from the "sig_name_init", not from
9744           "sig_name" (which is unused).
9745
9746       "SIG_NUM"
9747           This symbol contains a list of signal numbers, in the same order as
9748           the "SIG_NAME" list. It is suitable for static array
9749           initialization, as in:
9750
9751            int sig_num[] = { SIG_NUM };
9752
9753           The signals in the list are separated with commas, and the indices
9754           within that list and the "SIG_NAME" list match, so it's easy to
9755           compute the signal name from a number or vice versa at the price of
9756           a small dynamic linear lookup.  Duplicates are allowed, but are
9757           moved to the end of the list.  The signal number corresponding to
9758           "sig_name[i]" is "sig_number[i]".  if (i < "NSIG") then
9759           "sig_number[i]" == i.  The last element is 0, corresponding to the
9760           0 at the end of the "sig_name_init" list.  Note that this variable
9761           is initialized from the "sig_num_init", not from "sig_num" (which
9762           is unused).
9763
9764       "Sigsetjmp"
9765           This macro is used in the same way as "sigsetjmp()", but will
9766           invoke traditional "setjmp()" if sigsetjmp isn't available.  See
9767           "HAS_SIGSETJMP".
9768
9769            int  Sigsetjmp(jmp_buf env, int savesigs)
9770
9771       "SIG_SIZE"
9772           This variable contains the number of elements of the "SIG_NAME" and
9773           "SIG_NUM" arrays, excluding the final "NULL" entry.
9774
9775       "whichsig"
9776       "whichsig_pv"
9777       "whichsig_pvn"
9778       "whichsig_sv"
9779           These all convert a signal name into its corresponding signal
9780           number; returning -1 if no corresponding number was found.
9781
9782           They differ only in the source of the signal name:
9783
9784           "whichsig_pv" takes the name from the "NUL"-terminated string
9785           starting at "sig".
9786
9787           "whichsig" is merely a different spelling, a synonym, of
9788           "whichsig_pv".
9789
9790           "whichsig_pvn" takes the name from the string starting at "sig",
9791           with length "len" bytes.
9792
9793           "whichsig_sv" takes the name from the PV stored in the SV "sigsv".
9794
9795            I32  whichsig    (const char* sig)
9796            I32  whichsig_pv (const char* sig)
9797            I32  whichsig_pvn(const char* sig, STRLEN len)
9798            I32  whichsig_sv (SV* sigsv)
9799

Site configuration

9801       These variables give details as to where various libraries,
9802       installation destinations, etc., go, as well as what various
9803       installation options were selected
9804
9805       "ARCHLIB"
9806           This variable, if defined, holds the name of the directory in which
9807           the user wants to put architecture-dependent public library files
9808           for perl5.  It is most often a local directory such as
9809           /usr/local/lib.  Programs using this variable must be prepared to
9810           deal with filename expansion.  If "ARCHLIB" is the same as
9811           "PRIVLIB", it is not defined, since presumably the program already
9812           searches "PRIVLIB".
9813
9814       "ARCHLIB_EXP"
9815           This symbol contains the ~name expanded version of "ARCHLIB", to be
9816           used in programs that are not prepared to deal with ~ expansion at
9817           run-time.
9818
9819       "ARCHNAME"
9820           This symbol holds a string representing the architecture name.  It
9821           may be used to construct an architecture-dependant pathname where
9822           library files may be held under a private library, for instance.
9823
9824       "BIN"
9825           This symbol holds the path of the bin directory where the package
9826           will be installed. Program must be prepared to deal with ~name
9827           substitution.
9828
9829       "BIN_EXP"
9830           This symbol is the filename expanded version of the "BIN" symbol,
9831           for programs that do not want to deal with that at run-time.
9832
9833       "INSTALL_USR_BIN_PERL"
9834           This symbol, if defined, indicates that Perl is to be installed
9835           also as /usr/bin/perl.
9836
9837       "MULTIARCH"
9838           This symbol, if defined, signifies that the build process will
9839           produce some binary files that are going to be used in a cross-
9840           platform environment.  This is the case for example with the NeXT
9841           "fat" binaries that contain executables for several "CPUs".
9842
9843       "PERL_INC_VERSION_LIST"
9844           This variable specifies the list of subdirectories in over which
9845           perl.c:"incpush()" and lib/lib.pm will automatically search when
9846           adding directories to @"INC", in a format suitable for a C
9847           initialization string.  See the "inc_version_list" entry in
9848           Porting/Glossary for more details.
9849
9850       "PERL_OTHERLIBDIRS"
9851           This variable contains a colon-separated set of paths for the perl
9852           binary to search for additional library files or modules.  These
9853           directories will be tacked to the end of @"INC".  Perl will
9854           automatically search below each path for version- and architecture-
9855           specific directories.  See "PERL_INC_VERSION_LIST" for more
9856           details.
9857
9858       "PERL_RELOCATABLE_INC"
9859           This symbol, if defined, indicates that we'd like to relocate
9860           entries in @"INC" at run time based on the location of the perl
9861           binary.
9862
9863       "PERL_TARGETARCH"
9864           This symbol, if defined, indicates the target architecture Perl has
9865           been cross-compiled to.  Undefined if not a cross-compile.
9866
9867       "PERL_USE_DEVEL"
9868           This symbol, if defined, indicates that Perl was configured with
9869           "-Dusedevel", to enable development features.  This should not be
9870           done for production builds.
9871
9872       "PERL_VENDORARCH"
9873           If defined, this symbol contains the name of a private library.
9874           The library is private in the sense that it needn't be in anyone's
9875           execution path, but it should be accessible by the world.  It may
9876           have a ~ on the front.  The standard distribution will put nothing
9877           in this directory.  Vendors who distribute perl may wish to place
9878           their own architecture-dependent modules and extensions in this
9879           directory with
9880
9881            MakeMaker Makefile.PL INSTALLDIRS=vendor
9882
9883           or equivalent.  See "INSTALL" for details.
9884
9885       "PERL_VENDORARCH_EXP"
9886           This symbol contains the ~name expanded version of
9887           "PERL_VENDORARCH", to be used in programs that are not prepared to
9888           deal with ~ expansion at run-time.
9889
9890       "PERL_VENDORLIB_EXP"
9891           This symbol contains the ~name expanded version of "VENDORLIB", to
9892           be used in programs that are not prepared to deal with ~ expansion
9893           at run-time.
9894
9895       "PERL_VENDORLIB_STEM"
9896           This define is "PERL_VENDORLIB_EXP" with any trailing version-
9897           specific component removed.  The elements in "inc_version_list"
9898           ("inc_version_list".U (part of metaconfig)) can be tacked onto this
9899           variable to generate a list of directories to search.
9900
9901       "PRIVLIB"
9902           This symbol contains the name of the private library for this
9903           package.  The library is private in the sense that it needn't be in
9904           anyone's execution path, but it should be accessible by the world.
9905           The program should be prepared to do ~ expansion.
9906
9907       "PRIVLIB_EXP"
9908           This symbol contains the ~name expanded version of "PRIVLIB", to be
9909           used in programs that are not prepared to deal with ~ expansion at
9910           run-time.
9911
9912       "SITEARCH"
9913           This symbol contains the name of the private library for this
9914           package.  The library is private in the sense that it needn't be in
9915           anyone's execution path, but it should be accessible by the world.
9916           The program should be prepared to do ~ expansion.  The standard
9917           distribution will put nothing in this directory.  After perl has
9918           been installed, users may install their own local architecture-
9919           dependent modules in this directory with
9920
9921            MakeMaker Makefile.PL
9922
9923           or equivalent.  See "INSTALL" for details.
9924
9925       "SITEARCH_EXP"
9926           This symbol contains the ~name expanded version of "SITEARCH", to
9927           be used in programs that are not prepared to deal with ~ expansion
9928           at run-time.
9929
9930       "SITELIB"
9931           This symbol contains the name of the private library for this
9932           package.  The library is private in the sense that it needn't be in
9933           anyone's execution path, but it should be accessible by the world.
9934           The program should be prepared to do ~ expansion.  The standard
9935           distribution will put nothing in this directory.  After perl has
9936           been installed, users may install their own local architecture-
9937           independent modules in this directory with
9938
9939            MakeMaker Makefile.PL
9940
9941           or equivalent.  See "INSTALL" for details.
9942
9943       "SITELIB_EXP"
9944           This symbol contains the ~name expanded version of "SITELIB", to be
9945           used in programs that are not prepared to deal with ~ expansion at
9946           run-time.
9947
9948       "SITELIB_STEM"
9949           This define is "SITELIB_EXP" with any trailing version-specific
9950           component removed.  The elements in "inc_version_list"
9951           ("inc_version_list".U (part of metaconfig)) can be tacked onto this
9952           variable to generate a list of directories to search.
9953
9954       "STARTPERL"
9955           This variable contains the string to put in front of a perl script
9956           to make sure (one hopes) that it runs with perl and not some shell.
9957
9958       "USE_64_BIT_ALL"
9959           This symbol, if defined, indicates that 64-bit integers should be
9960           used when available.  If not defined, the native integers will be
9961           used (be they 32 or 64 bits).  The maximal possible 64-bitness is
9962           employed: LP64 or "ILP64", meaning that you will be able to use
9963           more than 2 gigabytes of memory.  This mode is even more binary
9964           incompatible than "USE_64_BIT_INT". You may not be able to run the
9965           resulting executable in a 32-bit "CPU" at all or you may need at
9966           least to reboot your OS to 64-bit mode.
9967
9968       "USE_64_BIT_INT"
9969           This symbol, if defined, indicates that 64-bit integers should be
9970           used when available.  If not defined, the native integers will be
9971           employed (be they 32 or 64 bits).  The minimal possible 64-bitness
9972           is used, just enough to get 64-bit integers into Perl.  This may
9973           mean using for example "long longs", while your memory may still be
9974           limited to 2 gigabytes.
9975
9976       "USE_BSD_GETPGRP"
9977           This symbol, if defined, indicates that getpgrp needs one arguments
9978           whereas "USG" one needs none.
9979
9980       "USE_BSD_SETPGRP"
9981           This symbol, if defined, indicates that setpgrp needs two arguments
9982           whereas "USG" one needs none.  See also "HAS_SETPGID" for a "POSIX"
9983           interface.
9984
9985       "USE_CPLUSPLUS"
9986           This symbol, if defined, indicates that a C++ compiler was used to
9987           compiled Perl and will be used to compile extensions.
9988
9989       "USE_CROSS_COMPILE"
9990           This symbol, if defined, indicates that Perl is being cross-
9991           compiled.
9992
9993       "USE_C_BACKTRACE"
9994           This symbol, if defined, indicates that Perl should be built with
9995           support for backtrace.
9996
9997       "USE_DTRACE"
9998           This symbol, if defined, indicates that Perl should be built with
9999           support for DTrace.
10000
10001       "USE_DYNAMIC_LOADING"
10002           This symbol, if defined, indicates that dynamic loading of some
10003           sort is available.
10004
10005       "USE_FAST_STDIO"
10006           This symbol, if defined, indicates that Perl should be built to use
10007           'fast stdio'.  Defaults to define in Perls 5.8 and earlier, to
10008           undef later.
10009
10010       "USE_ITHREADS"
10011           This symbol, if defined, indicates that Perl should be built to use
10012           the interpreter-based threading implementation.
10013
10014       "USE_KERN_PROC_PATHNAME"
10015           This symbol, if defined, indicates that we can use sysctl with
10016           "KERN_PROC_PATHNAME" to get a full path for the executable, and
10017           hence convert $^X to an absolute path.
10018
10019       "USE_LARGE_FILES"
10020           This symbol, if defined, indicates that large file support should
10021           be used when available.
10022
10023       "USE_LONG_DOUBLE"
10024           This symbol, if defined, indicates that long doubles should be used
10025           when available.
10026
10027       "USE_MORE_BITS"
10028           This symbol, if defined, indicates that 64-bit interfaces and long
10029           doubles should be used when available.
10030
10031       "USE_NSGETEXECUTABLEPATH"
10032           This symbol, if defined, indicates that we can use
10033           "_NSGetExecutablePath" and realpath to get a full path for the
10034           executable, and hence convert $^X to an absolute path.
10035
10036       "USE_PERLIO"
10037           This symbol, if defined, indicates that the PerlIO abstraction
10038           should be used throughout.  If not defined, stdio should be used in
10039           a fully backward compatible manner.
10040
10041       "USE_QUADMATH"
10042           This symbol, if defined, indicates that the quadmath library should
10043           be used when available.
10044
10045       "USE_REENTRANT_API"
10046           This symbol, if defined, indicates that Perl should try to use the
10047           various "_r" versions of library functions.  This is extremely
10048           experimental.
10049
10050       "USE_SEMCTL_SEMID_DS"
10051           This symbol, if defined, indicates that "struct semid_ds" * is used
10052           for semctl "IPC_STAT".
10053
10054       "USE_SEMCTL_SEMUN"
10055           This symbol, if defined, indicates that "union semun" is used for
10056           semctl "IPC_STAT".
10057
10058       "USE_SITECUSTOMIZE"
10059           This symbol, if defined, indicates that sitecustomize should be
10060           used.
10061
10062       "USE_SOCKS"
10063           This symbol, if defined, indicates that Perl should be built to use
10064           socks.
10065
10066       "USE_STAT_BLOCKS"
10067           This symbol is defined if this system has a stat structure
10068           declaring "st_blksize" and "st_blocks".
10069
10070       "USE_STDIO_BASE"
10071           This symbol is defined if the "_base" field (or similar) of the
10072           stdio "FILE" structure can be used to access the stdio buffer for a
10073           file handle.  If this is defined, then the "FILE_base(fp)" macro
10074           will also be defined and should be used to access this field.
10075           Also, the "FILE_bufsiz(fp)" macro will be defined and should be
10076           used to determine the number of bytes in the buffer.
10077           "USE_STDIO_BASE" will never be defined unless "USE_STDIO_PTR" is.
10078
10079       "USE_STDIO_PTR"
10080           This symbol is defined if the "_ptr" and "_cnt" fields (or similar)
10081           of the stdio "FILE" structure can be used to access the stdio
10082           buffer for a file handle.  If this is defined, then the
10083           "FILE_ptr(fp)" and "FILE_cnt(fp)" macros will also be defined and
10084           should be used to access these fields.
10085
10086       "USE_STRICT_BY_DEFAULT"
10087           This symbol, if defined, enables additional defaults.  At this time
10088           it only enables implicit strict by default.
10089
10090       "USE_THREADS"
10091           This symbol, if defined, indicates that Perl should be built to use
10092           threads.  At present, it is a synonym for and "USE_ITHREADS", but
10093           eventually the source ought to be changed to use this to mean
10094           "_any_" threading implementation.
10095

Sockets configuration values

10097       "HAS_SOCKADDR_IN6"
10098           This symbol, if defined, indicates the availability of "struct
10099           sockaddr_in6";
10100
10101       "HAS_SOCKADDR_SA_LEN"
10102           This symbol, if defined, indicates that the "struct sockaddr"
10103           structure has a member called "sa_len", indicating the length of
10104           the structure.
10105
10106       "HAS_SOCKADDR_STORAGE"
10107           This symbol, if defined, indicates the availability of "struct
10108           sockaddr_storage";
10109
10110       "HAS_SOCKATMARK"
10111           This symbol, if defined, indicates that the "sockatmark" routine is
10112           available to test whether a socket is at the out-of-band mark.
10113
10114       "HAS_SOCKET"
10115           This symbol, if defined, indicates that the "BSD" "socket"
10116           interface is supported.
10117
10118       "HAS_SOCKETPAIR"
10119           This symbol, if defined, indicates that the "BSD" "socketpair()"
10120           call is supported.
10121
10122       "HAS_SOCKS5_INIT"
10123           This symbol, if defined, indicates that the "socks5_init" routine
10124           is available to initialize "SOCKS" 5.
10125
10126       "I_SOCKS"
10127           This symbol, if defined, indicates that socks.h exists and should
10128           be included.
10129
10130            #ifdef I_SOCKS
10131                #include <socks.h>
10132            #endif
10133
10134       "I_SYS_SOCKIO"
10135           This symbol, if defined, indicates the sys/sockio.h should be
10136           included to get socket ioctl options, like "SIOCATMARK".
10137
10138            #ifdef I_SYS_SOCKIO
10139                #include <sys_sockio.h>
10140            #endif
10141

Source Filters

10143       "filter_add"
10144           Described in perlfilter.
10145
10146            SV*  filter_add(filter_t funcp, SV* datasv)
10147
10148       "filter_read"
10149           Described in perlfilter.
10150
10151            I32  filter_read(int idx, SV *buf_sv, int maxlen)
10152

Stack Manipulation Macros

10154       "BHK"
10155           Described in perlguts.
10156
10157       "BINOP"
10158           Described in perlguts.
10159
10160       "DESTRUCTORFUNC_NOCONTEXT_t"
10161           Described in perlguts.
10162
10163       "DESTRUCTORFUNC_t"
10164           Described in perlguts.
10165
10166       "dMARK"
10167           Declare a stack marker variable, "mark", for the XSUB.  See "MARK"
10168           and "dORIGMARK".
10169
10170              dMARK;
10171
10172       "dORIGMARK"
10173           Saves the original stack mark for the XSUB.  See "ORIGMARK".
10174
10175              dORIGMARK;
10176
10177       "dSP"
10178           Declares a local copy of perl's stack pointer for the XSUB,
10179           available via the "SP" macro.  See "SP".
10180
10181              dSP;
10182
10183       "dTARGET"
10184           Declare that this function uses "TARG"
10185
10186              dTARGET;
10187
10188       "EXTEND"
10189           Used to extend the argument stack for an XSUB's return values.
10190           Once used, guarantees that there is room for at least "nitems" to
10191           be pushed onto the stack.
10192
10193            void  EXTEND(SP, SSize_t nitems)
10194
10195       "LISTOP"
10196           Described in perlguts.
10197
10198       "LOGOP"
10199           Described in perlguts.
10200
10201       "LOOP"
10202           Described in perlguts.
10203
10204       "MARK"
10205           Stack marker variable for the XSUB.  See "dMARK".
10206
10207       "mPUSHi"
10208           Push an integer onto the stack.  The stack must have room for this
10209           element.  Does not use "TARG".  See also "PUSHi", "mXPUSHi" and
10210           "XPUSHi".
10211
10212            void  mPUSHi(IV iv)
10213
10214       "mPUSHn"
10215           Push a double onto the stack.  The stack must have room for this
10216           element.  Does not use "TARG".  See also "PUSHn", "mXPUSHn" and
10217           "XPUSHn".
10218
10219            void  mPUSHn(NV nv)
10220
10221       "mPUSHp"
10222           Push a string onto the stack.  The stack must have room for this
10223           element.  The "len" indicates the length of the string.  Does not
10224           use "TARG".  See also "PUSHp", "mXPUSHp" and "XPUSHp".
10225
10226            void  mPUSHp(char* str, STRLEN len)
10227
10228       "mPUSHs"
10229           Push an SV onto the stack and mortalizes the SV.  The stack must
10230           have room for this element.  Does not use "TARG".  See also "PUSHs"
10231           and "mXPUSHs".
10232
10233            void  mPUSHs(SV* sv)
10234
10235       "mPUSHu"
10236           Push an unsigned integer onto the stack.  The stack must have room
10237           for this element.  Does not use "TARG".  See also "PUSHu",
10238           "mXPUSHu" and "XPUSHu".
10239
10240            void  mPUSHu(UV uv)
10241
10242       "mXPUSHi"
10243           Push an integer onto the stack, extending the stack if necessary.
10244           Does not use "TARG".  See also "XPUSHi", "mPUSHi" and "PUSHi".
10245
10246            void  mXPUSHi(IV iv)
10247
10248       "mXPUSHn"
10249           Push a double onto the stack, extending the stack if necessary.
10250           Does not use "TARG".  See also "XPUSHn", "mPUSHn" and "PUSHn".
10251
10252            void  mXPUSHn(NV nv)
10253
10254       "mXPUSHp"
10255           Push a string onto the stack, extending the stack if necessary.
10256           The "len" indicates the length of the string.  Does not use "TARG".
10257           See also "XPUSHp", "mPUSHp" and "PUSHp".
10258
10259            void  mXPUSHp(char* str, STRLEN len)
10260
10261       "mXPUSHs"
10262           Push an SV onto the stack, extending the stack if necessary and
10263           mortalizes the SV.  Does not use "TARG".  See also "XPUSHs" and
10264           "mPUSHs".
10265
10266            void  mXPUSHs(SV* sv)
10267
10268       "mXPUSHu"
10269           Push an unsigned integer onto the stack, extending the stack if
10270           necessary.  Does not use "TARG".  See also "XPUSHu", "mPUSHu" and
10271           "PUSHu".
10272
10273            void  mXPUSHu(UV uv)
10274
10275       "newXSproto"
10276           Used by "xsubpp" to hook up XSUBs as Perl subs.  Adds Perl
10277           prototypes to the subs.
10278
10279       "OP"
10280           Described in perlguts.
10281
10282       "ORIGMARK"
10283           The original stack mark for the XSUB.  See "dORIGMARK".
10284
10285       "peep_t"
10286           Described in perlguts.
10287
10288       "PL_runops"
10289           Described in perlguts.
10290
10291       "PMOP"
10292           Described in perlguts.
10293
10294       "POPi"
10295           Pops an integer off the stack.
10296
10297            IV  POPi
10298
10299       "POPl"
10300           Pops a long off the stack.
10301
10302            long  POPl
10303
10304       "POPn"
10305           Pops a double off the stack.
10306
10307            NV  POPn
10308
10309       "POPp"
10310           Pops a string off the stack.
10311
10312            char*  POPp
10313
10314       "POPpbytex"
10315           Pops a string off the stack which must consist of bytes i.e.
10316           characters < 256.
10317
10318            char*  POPpbytex
10319
10320       "POPpx"
10321           Pops a string off the stack.  Identical to POPp.  There are two
10322           names for historical reasons.
10323
10324            char*  POPpx
10325
10326       "POPs"
10327           Pops an SV off the stack.
10328
10329            SV*  POPs
10330
10331       "POPu"
10332           Pops an unsigned integer off the stack.
10333
10334            UV  POPu
10335
10336       "POPul"
10337           Pops an unsigned long off the stack.
10338
10339            long  POPul
10340
10341       "PUSHi"
10342           Push an integer onto the stack.  The stack must have room for this
10343           element.  Handles 'set' magic.  Uses "TARG", so "dTARGET" or
10344           "dXSTARG" should be called to declare it.  Do not call multiple
10345           "TARG"-oriented macros to return lists from XSUB's - see "mPUSHi"
10346           instead.  See also "XPUSHi" and "mXPUSHi".
10347
10348            void  PUSHi(IV iv)
10349
10350       "PUSHMARK"
10351           Opening bracket for arguments on a callback.  See "PUTBACK" and
10352           perlcall.
10353
10354            void  PUSHMARK(SP)
10355
10356       "PUSHmortal"
10357           Push a new mortal SV onto the stack.  The stack must have room for
10358           this element.  Does not use "TARG".  See also "PUSHs",
10359           "XPUSHmortal" and "XPUSHs".
10360
10361            void  PUSHmortal
10362
10363       "PUSHn"
10364           Push a double onto the stack.  The stack must have room for this
10365           element.  Handles 'set' magic.  Uses "TARG", so "dTARGET" or
10366           "dXSTARG" should be called to declare it.  Do not call multiple
10367           "TARG"-oriented macros to return lists from XSUB's - see "mPUSHn"
10368           instead.  See also "XPUSHn" and "mXPUSHn".
10369
10370            void  PUSHn(NV nv)
10371
10372       "PUSHp"
10373           Push a string onto the stack.  The stack must have room for this
10374           element.  The "len" indicates the length of the string.  Handles
10375           'set' magic.  Uses "TARG", so "dTARGET" or "dXSTARG" should be
10376           called to declare it.  Do not call multiple "TARG"-oriented macros
10377           to return lists from XSUB's - see "mPUSHp" instead.  See also
10378           "XPUSHp" and "mXPUSHp".
10379
10380            void  PUSHp(char* str, STRLEN len)
10381
10382       "PUSHs"
10383           Push an SV onto the stack.  The stack must have room for this
10384           element.  Does not handle 'set' magic.  Does not use "TARG".  See
10385           also "PUSHmortal", "XPUSHs", and "XPUSHmortal".
10386
10387            void  PUSHs(SV* sv)
10388
10389       "PUSHu"
10390           Push an unsigned integer onto the stack.  The stack must have room
10391           for this element.  Handles 'set' magic.  Uses "TARG", so "dTARGET"
10392           or "dXSTARG" should be called to declare it.  Do not call multiple
10393           "TARG"-oriented macros to return lists from XSUB's - see "mPUSHu"
10394           instead.  See also "XPUSHu" and "mXPUSHu".
10395
10396            void  PUSHu(UV uv)
10397
10398       "PUTBACK"
10399           Closing bracket for XSUB arguments.  This is usually handled by
10400           "xsubpp".  See "PUSHMARK" and perlcall for other uses.
10401
10402              PUTBACK;
10403
10404       "save_aptr"
10405           Described in perlguts.
10406
10407            void  save_aptr(AV** aptr)
10408
10409       "save_ary"
10410           Described in perlguts.
10411
10412            AV*  save_ary(GV* gv)
10413
10414       "SAVEBOOL"
10415           Described in perlguts.
10416
10417              SAVEBOOL(bool i)
10418
10419       "SAVEDELETE"
10420           Described in perlguts.
10421
10422              SAVEDELETE(HV * hv, char * key, I32 length)
10423
10424       "SAVEDESTRUCTOR"
10425           Described in perlguts.
10426
10427              SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)
10428
10429       "SAVEDESTRUCTOR_X"
10430           Described in perlguts.
10431
10432              SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)
10433
10434       "SAVEFREEOP"
10435           Described in perlguts.
10436
10437              SAVEFREEOP(OP *op)
10438
10439       "SAVEFREEPV"
10440           Described in perlguts.
10441
10442              SAVEFREEPV(void * p)
10443
10444       "SAVEFREESV"
10445           Described in perlguts.
10446
10447              SAVEFREESV(SV* sv)
10448
10449       "save_hash"
10450           Described in perlguts.
10451
10452            HV*  save_hash(GV* gv)
10453
10454       "save_hptr"
10455           Described in perlguts.
10456
10457            void  save_hptr(HV** hptr)
10458
10459       "SAVEI8"
10460           Described in perlguts.
10461
10462              SAVEI8(I8 i)
10463
10464       "SAVEI32"
10465           Described in perlguts.
10466
10467              SAVEI32(I32 i)
10468
10469       "SAVEI16"
10470           Described in perlguts.
10471
10472              SAVEI16(I16 i)
10473
10474       "SAVEINT"
10475           Described in perlguts.
10476
10477              SAVEINT(int i)
10478
10479       "save_item"
10480           Described in perlguts.
10481
10482            void  save_item(SV* item)
10483
10484       "SAVEIV"
10485           Described in perlguts.
10486
10487              SAVEIV(IV i)
10488
10489       "save_list"
10490           "DEPRECATED!"  It is planned to remove "save_list" from a future
10491           release of Perl.  Do not use it for new code; remove it from
10492           existing code.
10493
10494           Described in perlguts.
10495
10496            void  save_list(SV** sarg, I32 maxsarg)
10497
10498       "SAVELONG"
10499           Described in perlguts.
10500
10501              SAVELONG(long i)
10502
10503       "SAVEMORTALIZESV"
10504           Described in perlguts.
10505
10506              SAVEMORTALIZESV(SV* sv)
10507
10508       "SAVEPPTR"
10509           Described in perlguts.
10510
10511              SAVEPPTR(char * p)
10512
10513       "save_scalar"
10514           Described in perlguts.
10515
10516            SV*  save_scalar(GV* gv)
10517
10518       "SAVESPTR"
10519           Described in perlguts.
10520
10521              SAVESPTR(SV * s)
10522
10523       "SAVESTACK_POS"
10524           Described in perlguts.
10525
10526              SAVESTACK_POS()
10527
10528       "save_svref"
10529           Described in perlguts.
10530
10531            SV*  save_svref(SV** sptr)
10532
10533       "SP"
10534           Stack pointer.  This is usually handled by "xsubpp".  See "dSP" and
10535           "SPAGAIN".
10536
10537       "SPAGAIN"
10538           Refetch the stack pointer.  Used after a callback.  See perlcall.
10539
10540              SPAGAIN;
10541
10542       "TARG"
10543           "TARG" is short for "target".  It is an entry in the pad that an
10544           OPs "op_targ" refers to.  It is scratchpad space, often used as a
10545           return value for the OP, but some use it for other purposes.
10546
10547              TARG;
10548
10549       "UNOP"
10550           Described in perlguts.
10551
10552       "XPUSHi"
10553           Push an integer onto the stack, extending the stack if necessary.
10554           Handles 'set' magic.  Uses "TARG", so "dTARGET" or "dXSTARG" should
10555           be called to declare it.  Do not call multiple "TARG"-oriented
10556           macros to return lists from XSUB's - see "mXPUSHi" instead.  See
10557           also "PUSHi" and "mPUSHi".
10558
10559            void  XPUSHi(IV iv)
10560
10561       "XPUSHmortal"
10562           Push a new mortal SV onto the stack, extending the stack if
10563           necessary.  Does not use "TARG".  See also "XPUSHs", "PUSHmortal"
10564           and "PUSHs".
10565
10566            void  XPUSHmortal
10567
10568       "XPUSHn"
10569           Push a double onto the stack, extending the stack if necessary.
10570           Handles 'set' magic.  Uses "TARG", so "dTARGET" or "dXSTARG" should
10571           be called to declare it.  Do not call multiple "TARG"-oriented
10572           macros to return lists from XSUB's - see "mXPUSHn" instead.  See
10573           also "PUSHn" and "mPUSHn".
10574
10575            void  XPUSHn(NV nv)
10576
10577       "XPUSHp"
10578           Push a string onto the stack, extending the stack if necessary.
10579           The "len" indicates the length of the string.  Handles 'set' magic.
10580           Uses "TARG", so "dTARGET" or "dXSTARG" should be called to declare
10581           it.  Do not call multiple "TARG"-oriented macros to return lists
10582           from XSUB's - see "mXPUSHp" instead.  See also "PUSHp" and
10583           "mPUSHp".
10584
10585            void  XPUSHp(char* str, STRLEN len)
10586
10587       "XPUSHs"
10588           Push an SV onto the stack, extending the stack if necessary.  Does
10589           not handle 'set' magic.  Does not use "TARG".  See also
10590           "XPUSHmortal", "PUSHs" and "PUSHmortal".
10591
10592            void  XPUSHs(SV* sv)
10593
10594       "XPUSHu"
10595           Push an unsigned integer onto the stack, extending the stack if
10596           necessary.  Handles 'set' magic.  Uses "TARG", so "dTARGET" or
10597           "dXSTARG" should be called to declare it.  Do not call multiple
10598           "TARG"-oriented macros to return lists from XSUB's - see "mXPUSHu"
10599           instead.  See also "PUSHu" and "mPUSHu".
10600
10601            void  XPUSHu(UV uv)
10602
10603       "XS_APIVERSION_BOOTCHECK"
10604           Macro to verify that the perl api version an XS module has been
10605           compiled against matches the api version of the perl interpreter
10606           it's being loaded into.
10607
10608              XS_APIVERSION_BOOTCHECK;
10609
10610       "XSRETURN"
10611           Return from XSUB, indicating number of items on the stack.  This is
10612           usually handled by "xsubpp".
10613
10614            void  XSRETURN(int nitems)
10615
10616       "XSRETURN_EMPTY"
10617           Return an empty list from an XSUB immediately.
10618
10619              XSRETURN_EMPTY;
10620
10621       "XSRETURN_IV"
10622           Return an integer from an XSUB immediately.  Uses "XST_mIV".
10623
10624            void  XSRETURN_IV(IV iv)
10625
10626       "XSRETURN_NO"
10627           Return &PL_sv_no from an XSUB immediately.  Uses "XST_mNO".
10628
10629              XSRETURN_NO;
10630
10631       "XSRETURN_NV"
10632           Return a double from an XSUB immediately.  Uses "XST_mNV".
10633
10634            void  XSRETURN_NV(NV nv)
10635
10636       "XSRETURN_PV"
10637           Return a copy of a string from an XSUB immediately.  Uses
10638           "XST_mPV".
10639
10640            void  XSRETURN_PV(char* str)
10641
10642       "XSRETURN_UNDEF"
10643           Return &PL_sv_undef from an XSUB immediately.  Uses "XST_mUNDEF".
10644
10645              XSRETURN_UNDEF;
10646
10647       "XSRETURN_UV"
10648           Return an integer from an XSUB immediately.  Uses "XST_mUV".
10649
10650            void  XSRETURN_UV(IV uv)
10651
10652       "XSRETURN_YES"
10653           Return &PL_sv_yes from an XSUB immediately.  Uses "XST_mYES".
10654
10655              XSRETURN_YES;
10656
10657       "XST_mIV"
10658           Place an integer into the specified position "pos" on the stack.
10659           The value is stored in a new mortal SV.
10660
10661            void  XST_mIV(int pos, IV iv)
10662
10663       "XST_mNO"
10664           Place &PL_sv_no into the specified position "pos" on the stack.
10665
10666            void  XST_mNO(int pos)
10667
10668       "XST_mNV"
10669           Place a double into the specified position "pos" on the stack.  The
10670           value is stored in a new mortal SV.
10671
10672            void  XST_mNV(int pos, NV nv)
10673
10674       "XST_mPV"
10675           Place a copy of a string into the specified position "pos" on the
10676           stack.  The value is stored in a new mortal SV.
10677
10678            void  XST_mPV(int pos, char* str)
10679
10680       "XST_mUNDEF"
10681           Place &PL_sv_undef into the specified position "pos" on the stack.
10682
10683            void  XST_mUNDEF(int pos)
10684
10685       "XST_mUV"
10686           Place an unsigned integer into the specified position "pos" on the
10687           stack.  The value is stored in a new mortal SV.
10688
10689            void  XST_mUV(int pos, UV uv)
10690
10691       "XST_mYES"
10692           Place &PL_sv_yes into the specified position "pos" on the stack.
10693
10694            void  XST_mYES(int pos)
10695
10696       "XS_VERSION"
10697           The version identifier for an XS module.  This is usually handled
10698           automatically by "ExtUtils::MakeMaker".  See
10699           "XS_VERSION_BOOTCHECK".
10700
10701       "XS_VERSION_BOOTCHECK"
10702           Macro to verify that a PM module's $VERSION variable matches the XS
10703           module's "XS_VERSION" variable.  This is usually handled
10704           automatically by "xsubpp".  See "The VERSIONCHECK: Keyword" in
10705           perlxs.
10706
10707              XS_VERSION_BOOTCHECK;
10708

String Handling

10710       See also "Unicode Support".
10711
10712       "CAT2"
10713           This macro concatenates 2 tokens together.
10714
10715            token  CAT2(token x, token y)
10716
10717       "Copy"
10718           The XSUB-writer's interface to the C "memcpy" function.  The "src"
10719           is the source, "dest" is the destination, "nitems" is the number of
10720           items, and "type" is the type.  May fail on overlapping copies.
10721           See also "Move".
10722
10723            void  Copy(void* src, void* dest, int nitems, type)
10724
10725       "CopyD"
10726           Like "Copy" but returns "dest".  Useful for encouraging compilers
10727           to tail-call optimise.
10728
10729            void *  CopyD(void* src, void* dest, int nitems, type)
10730
10731       "delimcpy"
10732           Copy a source buffer to a destination buffer, stopping at (but not
10733           including) the first occurrence in the source of an unescaped
10734           (defined below) delimiter byte, "delim".  The source is the bytes
10735           between "from" and "from_end" - 1.  Similarly, the dest is "to" up
10736           to "to_end".
10737
10738           The number of bytes copied is written to *retlen.
10739
10740           Returns the position of the first uncopied "delim" in the "from"
10741           buffer, but if there is no such occurrence before "from_end", then
10742           "from_end" is returned, and the entire buffer
10743           "from" .. "from_end" - 1 is copied.
10744
10745           If there is room in the destination available after the copy, an
10746           extra terminating safety "NUL" byte is appended (not included in
10747           the returned length).
10748
10749           The error case is if the destination buffer is not large enough to
10750           accommodate everything that should be copied.  In this situation, a
10751           value larger than "to_end" - "to" is written to *retlen, and as
10752           much of the source as fits will be written to the destination.  Not
10753           having room for the safety "NUL" is not considered an error.
10754
10755           In the following examples, let "x" be the delimiter, and 0
10756           represent a "NUL" byte (NOT the digit 0).  Then we would have
10757
10758             Source     Destination
10759            abcxdef        abc0
10760
10761           provided the destination buffer is at least 4 bytes long.
10762
10763           An escaped delimiter is one which is immediately preceded by a
10764           single backslash.  Escaped delimiters are copied, and the copy
10765           continues past the delimiter; the backslash is not copied:
10766
10767             Source       Destination
10768            abc\xdef       abcxdef0
10769
10770           (provided the destination buffer is at least 8 bytes long).
10771
10772           It's actually somewhat more complicated than that. A sequence of
10773           any odd number of backslashes escapes the following delimiter, and
10774           the copy continues with exactly one of the backslashes stripped.
10775
10776                Source         Destination
10777                abc\xdef          abcxdef0
10778              abc\\\xdef        abc\\xdef0
10779            abc\\\\\xdef      abc\\\\xdef0
10780
10781           (as always, if the destination is large enough)
10782
10783           An even number of preceding backslashes does not escape the
10784           delimiter, so that the copy stops just before it, and includes all
10785           the backslashes (no stripping; zero is considered even):
10786
10787                 Source         Destination
10788                 abcxdef          abc0
10789               abc\\xdef          abc\\0
10790             abc\\\\xdef          abc\\\\0
10791
10792            char*  delimcpy(char* to, const char* to_end, const char* from,
10793                            const char* from_end, const int delim,
10794                            I32* retlen)
10795
10796       "fbm_compile"
10797           Analyzes the string in order to make fast searches on it using
10798           "fbm_instr()" -- the Boyer-Moore algorithm.
10799
10800            void  fbm_compile(SV* sv, U32 flags)
10801
10802       "fbm_instr"
10803           Returns the location of the SV in the string delimited by "big" and
10804           "bigend" ("bigend") is the char following the last char).  It
10805           returns "NULL" if the string can't be found.  The "sv" does not
10806           have to be "fbm_compiled", but the search will not be as fast then.
10807
10808            char*  fbm_instr(unsigned char* big, unsigned char* bigend,
10809                             SV* littlestr, U32 flags)
10810
10811       "foldEQ"
10812           Returns true if the leading "len" bytes of the strings "s1" and
10813           "s2" are the same case-insensitively; false otherwise.  Uppercase
10814           and lowercase ASCII range bytes match themselves and their opposite
10815           case counterparts.  Non-cased and non-ASCII range bytes match only
10816           themselves.
10817
10818            I32  foldEQ(const char* a, const char* b, I32 len)
10819
10820       "ibcmp"
10821           This is a synonym for "(! foldEQ())"
10822
10823            I32  ibcmp(const char* a, const char* b, I32 len)
10824
10825       "ibcmp_locale"
10826           This is a synonym for "(! foldEQ_locale())"
10827
10828            I32  ibcmp_locale(const char* a, const char* b, I32 len)
10829
10830       "ibcmp_utf8"
10831           This is a synonym for "(! foldEQ_utf8())"
10832
10833            I32  ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1,
10834                            const char *s2, char **pe2, UV l2, bool u2)
10835
10836       "instr"
10837           Same as strstr(3), which finds and returns a pointer to the first
10838           occurrence of the NUL-terminated substring "little" in the NUL-
10839           terminated string "big", returning NULL if not found.  The
10840           terminating NUL bytes are not compared.
10841
10842            char*  instr(const char* big, const char* little)
10843
10844       "memCHRs"
10845           Returns the position of the first occurence of the byte "c" in the
10846           literal string "list", or NULL if "c" doesn't appear in "list".
10847           All bytes are treated as unsigned char.  Thus this macro can be
10848           used to determine if "c" is in a set of particular characters.
10849           Unlike strchr(3), it works even if "c" is "NUL" (and the set
10850           doesn't include "NUL").
10851
10852            bool  memCHRs("list", char c)
10853
10854       "memEQ"
10855           Test two buffers (which may contain embedded "NUL" characters, to
10856           see if they are equal.  The "len" parameter indicates the number of
10857           bytes to compare.  Returns true or false.  It is undefined behavior
10858           if either of the buffers doesn't contain at least "len" bytes.
10859
10860            bool  memEQ(char* s1, char* s2, STRLEN len)
10861
10862       "memEQs"
10863           Like "memEQ", but the second string is a literal enclosed in double
10864           quotes, "l1" gives the number of bytes in "s1".  Returns true or
10865           false.
10866
10867            bool  memEQs(char* s1, STRLEN l1, "s2")
10868
10869       "memNE"
10870           Test two buffers (which may contain embedded "NUL" characters, to
10871           see if they are not equal.  The "len" parameter indicates the
10872           number of bytes to compare.  Returns true or false.  It is
10873           undefined behavior if either of the buffers doesn't contain at
10874           least "len" bytes.
10875
10876            bool  memNE(char* s1, char* s2, STRLEN len)
10877
10878       "memNEs"
10879           Like "memNE", but the second string is a literal enclosed in double
10880           quotes, "l1" gives the number of bytes in "s1".  Returns true or
10881           false.
10882
10883            bool  memNEs(char* s1, STRLEN l1, "s2")
10884
10885       "Move"
10886           The XSUB-writer's interface to the C "memmove" function.  The "src"
10887           is the source, "dest" is the destination, "nitems" is the number of
10888           items, and "type" is the type.  Can do overlapping moves.  See also
10889           "Copy".
10890
10891            void  Move(void* src, void* dest, int nitems, type)
10892
10893       "MoveD"
10894           Like "Move" but returns "dest".  Useful for encouraging compilers
10895           to tail-call optimise.
10896
10897            void *  MoveD(void* src, void* dest, int nitems, type)
10898
10899       "my_snprintf"
10900           The C library "snprintf" functionality, if available and standards-
10901           compliant (uses "vsnprintf", actually).  However, if the
10902           "vsnprintf" is not available, will unfortunately use the unsafe
10903           "vsprintf" which can overrun the buffer (there is an overrun check,
10904           but that may be too late).  Consider using "sv_vcatpvf" instead, or
10905           getting "vsnprintf".
10906
10907            int  my_snprintf(char *buffer, const Size_t len,
10908                             const char *format, ...)
10909
10910       "my_sprintf"
10911           "DEPRECATED!"  It is planned to remove "my_sprintf" from a future
10912           release of Perl.  Do not use it for new code; remove it from
10913           existing code.
10914
10915           Do NOT use this due to the possibility of overflowing "buffer".
10916           Instead use my_snprintf()
10917
10918            int  my_sprintf(NN char *buffer, NN const char *pat, ...)
10919
10920       "my_strlcat"
10921           The C library "strlcat" if available, or a Perl implementation of
10922           it.  This operates on C "NUL"-terminated strings.
10923
10924           "my_strlcat()" appends string "src" to the end of "dst".  It will
10925           append at most "size - strlen(dst) - 1" characters.  It will then
10926           "NUL"-terminate, unless "size" is 0 or the original "dst" string
10927           was longer than "size" (in practice this should not happen as it
10928           means that either "size" is incorrect or that "dst" is not a proper
10929           "NUL"-terminated string).
10930
10931           Note that "size" is the full size of the destination buffer and the
10932           result is guaranteed to be "NUL"-terminated if there is room.  Note
10933           that room for the "NUL" should be included in "size".
10934
10935           The return value is the total length that "dst" would have if
10936           "size" is sufficiently large.  Thus it is the initial length of
10937           "dst" plus the length of "src".  If "size" is smaller than the
10938           return, the excess was not appended.
10939
10940            Size_t  my_strlcat(char *dst, const char *src, Size_t size)
10941
10942       "my_strlcpy"
10943           The C library "strlcpy" if available, or a Perl implementation of
10944           it.  This operates on C "NUL"-terminated strings.
10945
10946           "my_strlcpy()" copies up to "size - 1" characters from the string
10947           "src" to "dst", "NUL"-terminating the result if "size" is not 0.
10948
10949           The return value is the total length "src" would be if the copy
10950           completely succeeded.  If it is larger than "size", the excess was
10951           not copied.
10952
10953            Size_t  my_strlcpy(char *dst, const char *src, Size_t size)
10954
10955       "my_strnlen"
10956           The C library "strnlen" if available, or a Perl implementation of
10957           it.
10958
10959           "my_strnlen()" computes the length of the string, up to "maxlen"
10960           characters.  It will never attempt to address more than "maxlen"
10961           characters, making it suitable for use with strings that are not
10962           guaranteed to be NUL-terminated.
10963
10964            Size_t  my_strnlen(const char *str, Size_t maxlen)
10965
10966       "my_vsnprintf"
10967           The C library "vsnprintf" if available and standards-compliant.
10968           However, if the "vsnprintf" is not available, will unfortunately
10969           use the unsafe "vsprintf" which can overrun the buffer (there is an
10970           overrun check, but that may be too late).  Consider using
10971           "sv_vcatpvf" instead, or getting "vsnprintf".
10972
10973            int  my_vsnprintf(char *buffer, const Size_t len,
10974                              const char *format, va_list ap)
10975
10976       "ninstr"
10977           Find the first (leftmost) occurrence of a sequence of bytes within
10978           another sequence.  This is the Perl version of "strstr()", extended
10979           to handle arbitrary sequences, potentially containing embedded
10980           "NUL" characters ("NUL" is what the initial "n" in the function
10981           name stands for; some systems have an equivalent, "memmem()", but
10982           with a somewhat different API).
10983
10984           Another way of thinking about this function is finding a needle in
10985           a haystack.  "big" points to the first byte in the haystack.
10986           "big_end" points to one byte beyond the final byte in the haystack.
10987           "little" points to the first byte in the needle.  "little_end"
10988           points to one byte beyond the final byte in the needle.  All the
10989           parameters must be non-"NULL".
10990
10991           The function returns "NULL" if there is no occurrence of "little"
10992           within "big".  If "little" is the empty string, "big" is returned.
10993
10994           Because this function operates at the byte level, and because of
10995           the inherent characteristics of UTF-8 (or UTF-EBCDIC), it will work
10996           properly if both the needle and the haystack are strings with the
10997           same UTF-8ness, but not if the UTF-8ness differs.
10998
10999            char*  ninstr(const char* big, const char* bigend,
11000                          const char* little, const char* lend)
11001
11002       "Nullch"
11003           Null character pointer.  (No longer available when "PERL_CORE" is
11004           defined.)
11005
11006       "rninstr"
11007           Like "ninstr", but instead finds the final (rightmost) occurrence
11008           of a sequence of bytes within another sequence, returning "NULL" if
11009           there is no such occurrence.
11010
11011            char*  rninstr(const char* big, const char* bigend,
11012                           const char* little, const char* lend)
11013
11014       "savepv"
11015           Perl's version of "strdup()".  Returns a pointer to a newly
11016           allocated string which is a duplicate of "pv".  The size of the
11017           string is determined by "strlen()", which means it may not contain
11018           embedded "NUL" characters and must have a trailing "NUL".  To
11019           prevent memory leaks, the memory allocated for the new string needs
11020           to be freed when no longer needed.  This can be done with the
11021           "Safefree" function, or "SAVEFREEPV".
11022
11023           On some platforms, Windows for example, all allocated memory owned
11024           by a thread is deallocated when that thread ends.  So if you need
11025           that not to happen, you need to use the shared memory functions,
11026           such as "savesharedpv".
11027
11028            char*  savepv(const char* pv)
11029
11030       "savepvn"
11031           Perl's version of what "strndup()" would be if it existed.  Returns
11032           a pointer to a newly allocated string which is a duplicate of the
11033           first "len" bytes from "pv", plus a trailing "NUL" byte.  The
11034           memory allocated for the new string can be freed with the
11035           "Safefree()" function.
11036
11037           On some platforms, Windows for example, all allocated memory owned
11038           by a thread is deallocated when that thread ends.  So if you need
11039           that not to happen, you need to use the shared memory functions,
11040           such as "savesharedpvn".
11041
11042            char*  savepvn(const char* pv, Size_t len)
11043
11044       "savepvs"
11045           Like "savepvn", but takes a literal string instead of a
11046           string/length pair.
11047
11048            char*  savepvs("literal string")
11049
11050       "savesharedpv"
11051           A version of "savepv()" which allocates the duplicate string in
11052           memory which is shared between threads.
11053
11054            char*  savesharedpv(const char* pv)
11055
11056       "savesharedpvn"
11057           A version of "savepvn()" which allocates the duplicate string in
11058           memory which is shared between threads.  (With the specific
11059           difference that a "NULL" pointer is not acceptable)
11060
11061            char*  savesharedpvn(const char *const pv, const STRLEN len)
11062
11063       "savesharedpvs"
11064           A version of "savepvs()" which allocates the duplicate string in
11065           memory which is shared between threads.
11066
11067            char*  savesharedpvs("literal string")
11068
11069       "savesharedsvpv"
11070           A version of "savesharedpv()" which allocates the duplicate string
11071           in memory which is shared between threads.
11072
11073            char*  savesharedsvpv(SV *sv)
11074
11075       "savesvpv"
11076           A version of "savepv()"/"savepvn()" which gets the string to
11077           duplicate from the passed in SV using "SvPV()"
11078
11079           On some platforms, Windows for example, all allocated memory owned
11080           by a thread is deallocated when that thread ends.  So if you need
11081           that not to happen, you need to use the shared memory functions,
11082           such as "savesharedsvpv".
11083
11084            char*  savesvpv(SV* sv)
11085
11086       "strEQ"
11087           Test two "NUL"-terminated strings to see if they are equal.
11088           Returns true or false.
11089
11090            bool  strEQ(char* s1, char* s2)
11091
11092       "strGE"
11093           Test two "NUL"-terminated strings to see if the first, "s1", is
11094           greater than or equal to the second, "s2".  Returns true or false.
11095
11096            bool  strGE(char* s1, char* s2)
11097
11098       "strGT"
11099           Test two "NUL"-terminated strings to see if the first, "s1", is
11100           greater than the second, "s2".  Returns true or false.
11101
11102            bool  strGT(char* s1, char* s2)
11103
11104       "STRINGIFY"
11105           This macro surrounds its token with double quotes.
11106
11107            string  STRINGIFY(token x)
11108
11109       "strLE"
11110           Test two "NUL"-terminated strings to see if the first, "s1", is
11111           less than or equal to the second, "s2".  Returns true or false.
11112
11113            bool  strLE(char* s1, char* s2)
11114
11115       "strLT"
11116           Test two "NUL"-terminated strings to see if the first, "s1", is
11117           less than the second, "s2".  Returns true or false.
11118
11119            bool  strLT(char* s1, char* s2)
11120
11121       "strNE"
11122           Test two "NUL"-terminated strings to see if they are different.
11123           Returns true or false.
11124
11125            bool  strNE(char* s1, char* s2)
11126
11127       "strnEQ"
11128           Test two "NUL"-terminated strings to see if they are equal.  The
11129           "len" parameter indicates the number of bytes to compare.  Returns
11130           true or false.  (A wrapper for "strncmp").
11131
11132            bool  strnEQ(char* s1, char* s2, STRLEN len)
11133
11134       "strnNE"
11135           Test two "NUL"-terminated strings to see if they are different.
11136           The "len" parameter indicates the number of bytes to compare.
11137           Returns true or false.  (A wrapper for "strncmp").
11138
11139            bool  strnNE(char* s1, char* s2, STRLEN len)
11140
11141       "STR_WITH_LEN"
11142           Returns two comma separated tokens of the input literal string, and
11143           its length.  This is convenience macro which helps out in some API
11144           calls.  Note that it can't be used as an argument to macros or
11145           functions that under some configurations might be macros, which
11146           means that it requires the full Perl_xxx(aTHX_ ...) form for any
11147           API calls where it's used.
11148
11149            pair  STR_WITH_LEN("literal string")
11150
11151       "Zero"
11152           The XSUB-writer's interface to the C "memzero" function.  The
11153           "dest" is the destination, "nitems" is the number of items, and
11154           "type" is the type.
11155
11156            void  Zero(void* dest, int nitems, type)
11157
11158       "ZeroD"
11159           Like "Zero" but returns dest.  Useful for encouraging compilers to
11160           tail-call optimise.
11161
11162            void *  ZeroD(void* dest, int nitems, type)
11163

SV Flags

11165       "SVt_IV"
11166           Type flag for scalars.  See "svtype".
11167
11168       "SVt_NULL"
11169           Type flag for scalars.  See "svtype".
11170
11171       "SVt_NV"
11172           Type flag for scalars.  See "svtype".
11173
11174       "SVt_PV"
11175           Type flag for scalars.  See "svtype".
11176
11177       "SVt_PVAV"
11178           Type flag for arrays.  See "svtype".
11179
11180       "SVt_PVCV"
11181           Type flag for subroutines.  See "svtype".
11182
11183       "SVt_PVFM"
11184           Type flag for formats.  See "svtype".
11185
11186       "SVt_PVGV"
11187           Type flag for typeglobs.  See "svtype".
11188
11189       "SVt_PVHV"
11190           Type flag for hashes.  See "svtype".
11191
11192       "SVt_PVIO"
11193           Type flag for I/O objects.  See "svtype".
11194
11195       "SVt_PVIV"
11196           Type flag for scalars.  See "svtype".
11197
11198       "SVt_PVLV"
11199           Type flag for scalars.  See "svtype".
11200
11201       "SVt_PVMG"
11202           Type flag for scalars.  See "svtype".
11203
11204       "SVt_PVNV"
11205           Type flag for scalars.  See "svtype".
11206
11207       "SVt_REGEXP"
11208           Type flag for regular expressions.  See "svtype".
11209
11210       "svtype"
11211           An enum of flags for Perl types.  These are found in the file sv.h
11212           in the "svtype" enum.  Test these flags with the "SvTYPE" macro.
11213
11214           The types are:
11215
11216               SVt_NULL
11217               SVt_IV
11218               SVt_NV
11219               SVt_RV
11220               SVt_PV
11221               SVt_PVIV
11222               SVt_PVNV
11223               SVt_PVMG
11224               SVt_INVLIST
11225               SVt_REGEXP
11226               SVt_PVGV
11227               SVt_PVLV
11228               SVt_PVAV
11229               SVt_PVHV
11230               SVt_PVCV
11231               SVt_PVFM
11232               SVt_PVIO
11233
11234           These are most easily explained from the bottom up.
11235
11236           "SVt_PVIO" is for I/O objects, "SVt_PVFM" for formats, "SVt_PVCV"
11237           for subroutines, "SVt_PVHV" for hashes and "SVt_PVAV" for arrays.
11238
11239           All the others are scalar types, that is, things that can be bound
11240           to a "$" variable.  For these, the internal types are mostly
11241           orthogonal to types in the Perl language.
11242
11243           Hence, checking "SvTYPE(sv) < SVt_PVAV" is the best way to see
11244           whether something is a scalar.
11245
11246           "SVt_PVGV" represents a typeglob.  If "!SvFAKE(sv)", then it is a
11247           real, incoercible typeglob.  If "SvFAKE(sv)", then it is a scalar
11248           to which a typeglob has been assigned.  Assigning to it again will
11249           stop it from being a typeglob.  "SVt_PVLV" represents a scalar that
11250           delegates to another scalar behind the scenes.  It is used, e.g.,
11251           for the return value of "substr" and for tied hash and array
11252           elements.  It can hold any scalar value, including a typeglob.
11253           "SVt_REGEXP" is for regular expressions.  "SVt_INVLIST" is for Perl
11254           core internal use only.
11255
11256           "SVt_PVMG" represents a "normal" scalar (not a typeglob, regular
11257           expression, or delegate).  Since most scalars do not need all the
11258           internal fields of a PVMG, we save memory by allocating smaller
11259           structs when possible.  All the other types are just simpler forms
11260           of "SVt_PVMG", with fewer internal fields.  "SVt_NULL" can only
11261           hold undef.  "SVt_IV" can hold undef, an integer, or a reference.
11262           ("SVt_RV" is an alias for "SVt_IV", which exists for backward
11263           compatibility.)  "SVt_NV" can hold any of those or a double.
11264           "SVt_PV" can only hold "undef" or a string.  "SVt_PVIV" is a
11265           superset of "SVt_PV" and "SVt_IV".  "SVt_PVNV" is similar.
11266           "SVt_PVMG" can hold anything "SVt_PVNV" can hold, but it can, but
11267           does not have to, be blessed or magical.
11268

SV Handling

11270       An SV (or AV, HV, etc.) is allocated in two parts: the head (struct sv,
11271       av, hv...) contains type and reference count information, and for many
11272       types, a pointer to the body (struct xrv, xpv, xpviv...), which
11273       contains fields specific to each type.  Some types store all they need
11274       in the head, so don't have a body.
11275
11276       In all but the most memory-paranoid configurations (ex: PURIFY), heads
11277       and bodies are allocated out of arenas, which by default are
11278       approximately 4K chunks of memory parcelled up into N heads or bodies.
11279       Sv-bodies are allocated by their sv-type, guaranteeing size consistency
11280       needed to allocate safely from arrays.
11281
11282       For SV-heads, the first slot in each arena is reserved, and holds a
11283       link to the next arena, some flags, and a note of the number of slots.
11284       Snaked through each arena chain is a linked list of free items; when
11285       this becomes empty, an extra arena is allocated and divided up into N
11286       items which are threaded into the free list.
11287
11288       SV-bodies are similar, but they use arena-sets by default, which
11289       separate the link and info from the arena itself, and reclaim the 1st
11290       slot in the arena.  SV-bodies are further described later.
11291
11292       The following global variables are associated with arenas:
11293
11294        PL_sv_arenaroot     pointer to list of SV arenas
11295        PL_sv_root          pointer to list of free SV structures
11296
11297        PL_body_arenas      head of linked-list of body arenas
11298        PL_body_roots[]     array of pointers to list of free bodies of svtype
11299                            arrays are indexed by the svtype needed
11300
11301       A few special SV heads are not allocated from an arena, but are instead
11302       directly created in the interpreter structure, eg PL_sv_undef.  The
11303       size of arenas can be changed from the default by setting
11304       PERL_ARENA_SIZE appropriately at compile time.
11305
11306       The SV arena serves the secondary purpose of allowing still-live SVs to
11307       be located and destroyed during final cleanup.
11308
11309       At the lowest level, the macros new_SV() and del_SV() grab and free an
11310       SV head.  (If debugging with -DD, del_SV() calls the function
11311       S_del_sv() to return the SV to the free list with error checking.)
11312       new_SV() calls more_sv() / sv_add_arena() to add an extra arena if the
11313       free list is empty.  SVs in the free list have their SvTYPE field set
11314       to all ones.
11315
11316       At the time of very final cleanup, sv_free_arenas() is called from
11317       perl_destruct() to physically free all the arenas allocated since the
11318       start of the interpreter.
11319
11320       The internal function visit() scans the SV arenas list, and calls a
11321       specified function for each SV it finds which is still live, i.e. which
11322       has an SvTYPE other than all 1's, and a non-zero SvREFCNT. visit() is
11323       used by the following functions (specified as [function that calls
11324       visit()] / [function called by visit() for each SV]):
11325
11326           sv_report_used() / do_report_used()
11327                               dump all remaining SVs (debugging aid)
11328
11329           sv_clean_objs() / do_clean_objs(),do_clean_named_objs(),
11330                             do_clean_named_io_objs(),do_curse()
11331                               Attempt to free all objects pointed to by RVs,
11332                               try to do the same for all objects indir-
11333                               ectly referenced by typeglobs too, and
11334                               then do a final sweep, cursing any
11335                               objects that remain.  Called once from
11336                               perl_destruct(), prior to calling sv_clean_all()
11337                               below.
11338
11339           sv_clean_all() / do_clean_all()
11340                               SvREFCNT_dec(sv) each remaining SV, possibly
11341                               triggering an sv_free(). It also sets the
11342                               SVf_BREAK flag on the SV to indicate that the
11343                               refcnt has been artificially lowered, and thus
11344                               stopping sv_free() from giving spurious warnings
11345                               about SVs which unexpectedly have a refcnt
11346                               of zero.  called repeatedly from perl_destruct()
11347                               until there are no SVs left.
11348
11349   Arena allocator API Summary
11350       Private API to rest of sv.c
11351
11352           new_SV(),  del_SV(),
11353
11354           new_XPVNV(), del_XPVGV(),
11355           etc
11356
11357       Public API:
11358
11359           sv_report_used(), sv_clean_objs(), sv_clean_all(), sv_free_arenas()
11360
11361       "boolSV"
11362           Returns a true SV if "b" is a true value, or a false SV if "b" is
11363           0.
11364
11365           See also "PL_sv_yes" and "PL_sv_no".
11366
11367            SV *  boolSV(bool b)
11368
11369       "croak_xs_usage"
11370           A specialised variant of "croak()" for emitting the usage message
11371           for xsubs
11372
11373               croak_xs_usage(cv, "eee_yow");
11374
11375           works out the package name and subroutine name from "cv", and then
11376           calls "croak()".  Hence if "cv" is &ouch::awk, it would call
11377           "croak" as:
11378
11379            Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
11380                                                                "eee_yow");
11381
11382            void  croak_xs_usage(const CV *const cv, const char *const params)
11383
11384       "DEFSV"
11385           Returns the SV associated with $_
11386
11387            SV *  DEFSV
11388
11389       "DEFSV_set"
11390           Associate "sv" with $_
11391
11392            void  DEFSV_set(SV * sv)
11393
11394       "get_sv"
11395           Returns the SV of the specified Perl scalar.  "flags" are passed to
11396           "gv_fetchpv".  If "GV_ADD" is set and the Perl variable does not
11397           exist then it will be created.  If "flags" is zero and the variable
11398           does not exist then NULL is returned.
11399
11400           NOTE: the "perl_get_sv()" form is deprecated.
11401
11402            SV*  get_sv(const char *name, I32 flags)
11403
11404       "isGV_with_GP"
11405           Returns a boolean as to whether or not "sv" is a GV with a pointer
11406           to a GP (glob pointer).
11407
11408            bool  isGV_with_GP(SV * sv)
11409
11410       "looks_like_number"
11411           Test if the content of an SV looks like a number (or is a number).
11412           "Inf" and "Infinity" are treated as numbers (so will not issue a
11413           non-numeric warning), even if your "atof()" doesn't grok them.
11414           Get-magic is ignored.
11415
11416            I32  looks_like_number(SV *const sv)
11417
11418       "MUTABLE_PTR"
11419       "MUTABLE_AV"
11420       "MUTABLE_CV"
11421       "MUTABLE_GV"
11422       "MUTABLE_HV"
11423       "MUTABLE_IO"
11424       "MUTABLE_SV"
11425           The "MUTABLE_*"() macros cast pointers to the types shown, in such
11426           a way (compiler permitting) that casting away const-ness will give
11427           a warning; e.g.:
11428
11429            const SV *sv = ...;
11430            AV *av1 = (AV*)sv;        <== BAD:  the const has been silently
11431                                                cast away
11432            AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
11433
11434           "MUTABLE_PTR" is the base macro used to derive new casts.  The
11435           other already-built-in ones return pointers to what their names
11436           indicate.
11437
11438            void *  MUTABLE_PTR(void * p)
11439            AV *    MUTABLE_AV (AV * p)
11440            CV *    MUTABLE_CV (CV * p)
11441            GV *    MUTABLE_GV (GV * p)
11442            HV *    MUTABLE_HV (HV * p)
11443            IO *    MUTABLE_IO (IO * p)
11444            SV *    MUTABLE_SV (SV * p)
11445
11446       "newRV"
11447       "newRV_inc"
11448           These are identical.  They create an RV wrapper for an SV.  The
11449           reference count for the original SV is incremented.
11450
11451            SV*  newRV(SV *const sv)
11452
11453       "newRV_noinc"
11454           Creates an RV wrapper for an SV.  The reference count for the
11455           original SV is not incremented.
11456
11457            SV*  newRV_noinc(SV *const tmpRef)
11458
11459       "newSV"
11460           Creates a new SV.  A non-zero "len" parameter indicates the number
11461           of bytes of preallocated string space the SV should have.  An extra
11462           byte for a trailing "NUL" is also reserved.  ("SvPOK" is not set
11463           for the SV even if string space is allocated.)  The reference count
11464           for the new SV is set to 1.
11465
11466           In 5.9.3, "newSV()" replaces the older "NEWSV()" API, and drops the
11467           first parameter, x, a debug aid which allowed callers to identify
11468           themselves.  This aid has been superseded by a new build option,
11469           "PERL_MEM_LOG" (see "PERL_MEM_LOG" in perlhacktips).  The older API
11470           is still there for use in XS modules supporting older perls.
11471
11472            SV*  newSV(const STRLEN len)
11473
11474       "newSVhek"
11475           Creates a new SV from the hash key structure.  It will generate
11476           scalars that point to the shared string table where possible.
11477           Returns a new (undefined) SV if "hek" is NULL.
11478
11479            SV*  newSVhek(const HEK *const hek)
11480
11481       "newSViv"
11482           Creates a new SV and copies an integer into it.  The reference
11483           count for the SV is set to 1.
11484
11485            SV*  newSViv(const IV i)
11486
11487       "newSVnv"
11488           Creates a new SV and copies a floating point value into it.  The
11489           reference count for the SV is set to 1.
11490
11491            SV*  newSVnv(const NV n)
11492
11493       "newSVpadname"
11494           NOTE: "newSVpadname" is experimental and may change or be removed
11495           without notice.
11496
11497           Creates a new SV containing the pad name.
11498
11499            SV*  newSVpadname(PADNAME *pn)
11500
11501       "newSVpv"
11502           Creates a new SV and copies a string (which may contain "NUL"
11503           ("\0") characters) into it.  The reference count for the SV is set
11504           to 1.  If "len" is zero, Perl will compute the length using
11505           "strlen()", (which means if you use this option, that "s" can't
11506           have embedded "NUL" characters and has to have a terminating "NUL"
11507           byte).
11508
11509           This function can cause reliability issues if you are likely to
11510           pass in empty strings that are not null terminated, because it will
11511           run strlen on the string and potentially run past valid memory.
11512
11513           Using "newSVpvn" is a safer alternative for non "NUL" terminated
11514           strings.  For string literals use "newSVpvs" instead.  This
11515           function will work fine for "NUL" terminated strings, but if you
11516           want to avoid the if statement on whether to call "strlen" use
11517           "newSVpvn" instead (calling "strlen" yourself).
11518
11519            SV*  newSVpv(const char *const s, const STRLEN len)
11520
11521       "newSVpvf"
11522           Creates a new SV and initializes it with the string formatted like
11523           "sv_catpvf".
11524
11525           NOTE: "newSVpvf" must be explicitly called as "Perl_newSVpvf" with
11526           an "aTHX_" parameter.
11527
11528            SV*  Perl_newSVpvf(pTHX_ const char *const pat, ...)
11529
11530       "newSVpvf_nocontext"
11531           Like "newSVpvf" but does not take a thread context ("aTHX")
11532           parameter, so is used in situations where the caller doesn't
11533           already have the thread context.
11534
11535            SV*  newSVpvf_nocontext(const char *const pat, ...)
11536
11537       "newSVpvn"
11538           Creates a new SV and copies a string into it, which may contain
11539           "NUL" characters ("\0") and other binary data.  The reference count
11540           for the SV is set to 1.  Note that if "len" is zero, Perl will
11541           create a zero length (Perl) string.  You are responsible for
11542           ensuring that the source buffer is at least "len" bytes long.  If
11543           the "buffer" argument is NULL the new SV will be undefined.
11544
11545            SV*  newSVpvn(const char *const buffer, const STRLEN len)
11546
11547       "newSVpvn_flags"
11548           Creates a new SV and copies a string (which may contain "NUL"
11549           ("\0") characters) into it.  The reference count for the SV is set
11550           to 1.  Note that if "len" is zero, Perl will create a zero length
11551           string.  You are responsible for ensuring that the source string is
11552           at least "len" bytes long.  If the "s" argument is NULL the new SV
11553           will be undefined.  Currently the only flag bits accepted are
11554           "SVf_UTF8" and "SVs_TEMP".  If "SVs_TEMP" is set, then
11555           "sv_2mortal()" is called on the result before returning.  If
11556           "SVf_UTF8" is set, "s" is considered to be in UTF-8 and the
11557           "SVf_UTF8" flag will be set on the new SV.  "newSVpvn_utf8()" is a
11558           convenience wrapper for this function, defined as
11559
11560               #define newSVpvn_utf8(s, len, u)                    \
11561                   newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
11562
11563            SV*  newSVpvn_flags(const char *const s, const STRLEN len,
11564                                const U32 flags)
11565
11566       "newSVpvn_share"
11567           Creates a new SV with its "SvPVX_const" pointing to a shared string
11568           in the string table.  If the string does not already exist in the
11569           table, it is created first.  Turns on the "SvIsCOW" flag (or
11570           "READONLY" and "FAKE" in 5.16 and earlier).  If the "hash"
11571           parameter is non-zero, that value is used; otherwise the hash is
11572           computed.  The string's hash can later be retrieved from the SV
11573           with the "SvSHARED_HASH" macro.  The idea here is that as the
11574           string table is used for shared hash keys these strings will have
11575           "SvPVX_const == HeKEY" and hash lookup will avoid string compare.
11576
11577            SV*  newSVpvn_share(const char* s, I32 len, U32 hash)
11578
11579       "newSVpvn_utf8"
11580           Creates a new SV and copies a string (which may contain "NUL"
11581           ("\0") characters) into it.  If "utf8" is true, calls "SvUTF8_on"
11582           on the new SV.  Implemented as a wrapper around "newSVpvn_flags".
11583
11584            SV*  newSVpvn_utf8(const char* s, STRLEN len, U32 utf8)
11585
11586       "newSVpvs"
11587           Like "newSVpvn", but takes a literal string instead of a
11588           string/length pair.
11589
11590            SV*  newSVpvs("literal string")
11591
11592       "newSVpvs_flags"
11593           Like "newSVpvn_flags", but takes a literal string instead of a
11594           string/length pair.
11595
11596            SV*  newSVpvs_flags("literal string", U32 flags)
11597
11598       "newSVpv_share"
11599           Like "newSVpvn_share", but takes a "NUL"-terminated string instead
11600           of a string/length pair.
11601
11602            SV*  newSVpv_share(const char* s, U32 hash)
11603
11604       "newSVpvs_share"
11605           Like "newSVpvn_share", but takes a literal string instead of a
11606           string/length pair and omits the hash parameter.
11607
11608            SV*  newSVpvs_share("literal string")
11609
11610       "newSVrv"
11611           Creates a new SV for the existing RV, "rv", to point to.  If "rv"
11612           is not an RV then it will be upgraded to one.  If "classname" is
11613           non-null then the new SV will be blessed in the specified package.
11614           The new SV is returned and its reference count is 1.  The reference
11615           count 1 is owned by "rv". See also newRV_inc() and newRV_noinc()
11616           for creating a new RV properly.
11617
11618            SV*  newSVrv(SV *const rv, const char *const classname)
11619
11620       "newSVsv"
11621       "newSVsv_nomg"
11622       "newSVsv_flags"
11623           These create a new SV which is an exact duplicate of the original
11624           SV (using "sv_setsv".)
11625
11626           They differ only in that "newSVsv" performs 'get' magic;
11627           "newSVsv_nomg" skips any magic; and "newSVsv_flags" allows you to
11628           explicitly set a "flags" parameter.
11629
11630            SV*  newSVsv      (SV *const old)
11631            SV*  newSVsv_nomg (SV *const old)
11632            SV*  newSVsv_flags(SV *const old, I32 flags)
11633
11634       "newSV_type"
11635           Creates a new SV, of the type specified.  The reference count for
11636           the new SV is set to 1.
11637
11638            SV*  newSV_type(const svtype type)
11639
11640       "newSVuv"
11641           Creates a new SV and copies an unsigned integer into it.  The
11642           reference count for the SV is set to 1.
11643
11644            SV*  newSVuv(const UV u)
11645
11646       "Nullsv"
11647           Null SV pointer.  (No longer available when "PERL_CORE" is
11648           defined.)
11649
11650       "PL_na"
11651           A convenience variable which is typically used with "SvPV" when one
11652           doesn't care about the length of the string.  It is usually more
11653           efficient to either declare a local variable and use that instead
11654           or to use the "SvPV_nolen" macro.
11655
11656            STRLEN  PL_na
11657
11658       "PL_sv_no"
11659           This is the "false" SV.  It is readonly.  See "PL_sv_yes".  Always
11660           refer to this as &PL_sv_no.
11661
11662            SV  PL_sv_no
11663
11664       "PL_sv_undef"
11665           This is the "undef" SV.  It is readonly.  Always refer to this as
11666           &PL_sv_undef.
11667
11668            SV  PL_sv_undef
11669
11670       "PL_sv_yes"
11671           This is the "true" SV.  It is readonly.  See "PL_sv_no".  Always
11672           refer to this as &PL_sv_yes.
11673
11674            SV  PL_sv_yes
11675
11676       "PL_sv_zero"
11677           This readonly SV has a zero numeric value and a "0" string value.
11678           It's similar to "PL_sv_no" except for its string value. Can be used
11679           as a cheap alternative to mXPUSHi(0) for example.  Always refer to
11680           this as &PL_sv_zero. Introduced in 5.28.
11681
11682            SV  PL_sv_zero
11683
11684       "SAVE_DEFSV"
11685           Localize $_.  See "Localizing changes" in perlguts.
11686
11687            void  SAVE_DEFSV
11688
11689       "sortsv"
11690           In-place sort an array of SV pointers with the given comparison
11691           routine.
11692
11693           Currently this always uses mergesort.  See "sortsv_flags" for a
11694           more flexible routine.
11695
11696            void  sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
11697
11698       "sortsv_flags"
11699           In-place sort an array of SV pointers with the given comparison
11700           routine, with various SORTf_* flag options.
11701
11702            void  sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp,
11703                               U32 flags)
11704
11705       "SV"
11706           Described in perlguts.
11707
11708       "sv_2cv"
11709           Using various gambits, try to get a CV from an SV; in addition, try
11710           if possible to set *st and *gvp to the stash and GV associated with
11711           it.  The flags in "lref" are passed to "gv_fetchsv".
11712
11713            CV*  sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)
11714
11715       "sv_2io"
11716           Using various gambits, try to get an IO from an SV: the IO slot if
11717           its a GV; or the recursive result if we're an RV; or the IO slot of
11718           the symbol named after the PV if we're a string.
11719
11720           'Get' magic is ignored on the "sv" passed in, but will be called on
11721           "SvRV(sv)" if "sv" is an RV.
11722
11723            IO*  sv_2io(SV *const sv)
11724
11725       "sv_2iv_flags"
11726           Return the integer value of an SV, doing any necessary string
11727           conversion.  If "flags" has the "SV_GMAGIC" bit set, does an
11728           "mg_get()" first.  Normally used via the "SvIV(sv)" and "SvIVx(sv)"
11729           macros.
11730
11731            IV  sv_2iv_flags(SV *const sv, const I32 flags)
11732
11733       "sv_2mortal"
11734           Marks an existing SV as mortal.  The SV will be destroyed "soon",
11735           either by an explicit call to "FREETMPS", or by an implicit call at
11736           places such as statement boundaries.  "SvTEMP()" is turned on which
11737           means that the SV's string buffer can be "stolen" if this SV is
11738           copied.  See also "sv_newmortal" and "sv_mortalcopy".
11739
11740            SV*  sv_2mortal(SV *const sv)
11741
11742       "sv_2nv_flags"
11743           Return the num value of an SV, doing any necessary string or
11744           integer conversion.  If "flags" has the "SV_GMAGIC" bit set, does
11745           an "mg_get()" first.  Normally used via the "SvNV(sv)" and
11746           "SvNVx(sv)" macros.
11747
11748            NV  sv_2nv_flags(SV *const sv, const I32 flags)
11749
11750       "sv_2pvbyte"
11751           Returns a pointer to the byte-encoded representation of the SV, and
11752           set *lp to its length.  If the SV is marked as being encoded as
11753           UTF-8, it will downgrade it to a byte string as a side-effect, if
11754           possible.  If the SV cannot be downgraded, this croaks.
11755
11756           Processes 'get' magic.
11757
11758           Usually accessed via the "SvPVbyte" macro.
11759
11760            char*  sv_2pvbyte(SV *sv, STRLEN *const lp)
11761
11762       "sv_2pvutf8"
11763           Return a pointer to the UTF-8-encoded representation of the SV, and
11764           set *lp to its length.  May cause the SV to be upgraded to UTF-8 as
11765           a side-effect.
11766
11767           Usually accessed via the "SvPVutf8" macro.
11768
11769            char*  sv_2pvutf8(SV *sv, STRLEN *const lp)
11770
11771       "sv_2uv_flags"
11772           Return the unsigned integer value of an SV, doing any necessary
11773           string conversion.  If "flags" has the "SV_GMAGIC" bit set, does an
11774           "mg_get()" first.  Normally used via the "SvUV(sv)" and "SvUVx(sv)"
11775           macros.
11776
11777            UV  sv_2uv_flags(SV *const sv, const I32 flags)
11778
11779       "sv_backoff"
11780           Remove any string offset.  You should normally use the "SvOOK_off"
11781           macro wrapper instead.
11782
11783            void  sv_backoff(SV *const sv)
11784
11785       "sv_bless"
11786           Blesses an SV into a specified package.  The SV must be an RV.  The
11787           package must be designated by its stash (see "gv_stashpv").  The
11788           reference count of the SV is unaffected.
11789
11790            SV*  sv_bless(SV *const sv, HV *const stash)
11791
11792       "sv_catpv"
11793       "sv_catpv_flags"
11794       "sv_catpv_mg"
11795       "sv_catpv_nomg"
11796           These concatenate the "NUL"-terminated string "sstr" onto the end
11797           of the string which is in the SV.  If the SV has the UTF-8 status
11798           set, then the bytes appended should be valid UTF-8.
11799
11800           They differ only in how they handle magic:
11801
11802           "sv_catpv_mg" performs both 'get' and 'set' magic.
11803
11804           "sv_catpv" performs only 'get' magic.
11805
11806           "sv_catpv_nomg" skips all magic.
11807
11808           "sv_catpv_flags" has an extra "flags" parameter which allows you to
11809           specify any combination of magic handling (using "SV_GMAGIC" and/or
11810           "SV_SMAGIC"), and to also override the UTF-8 handling.  By
11811           supplying the "SV_CATUTF8" flag, the appended string is forced to
11812           be interpreted as UTF-8; by supplying instead the "SV_CATBYTES"
11813           flag, it will be interpreted as just bytes.  Either the SV or the
11814           string appended will be upgraded to UTF-8 if necessary.
11815
11816            void  sv_catpv      (SV *const dsv, const char* sstr)
11817            void  sv_catpv_flags(SV *dsv, const char *sstr, const I32 flags)
11818            void  sv_catpv_mg   (SV *const dsv, const char *const sstr)
11819            void  sv_catpv_nomg (SV *const dsv, const char* sstr)
11820
11821       "sv_catpvf"
11822       "sv_catpvf_nocontext"
11823       "sv_catpvf_mg"
11824       "sv_catpvf_mg_nocontext"
11825           These process their arguments like "sprintf", and append the
11826           formatted output to an SV.  As with "sv_vcatpvfn", argument
11827           reordering is not supporte when called with a non-null C-style
11828           variable argument list.
11829
11830           If the appended data contains "wide" characters (including, but not
11831           limited to, SVs with a UTF-8 PV formatted with %s, and characters
11832           >255 formatted with %c), the original SV might get upgraded to
11833           UTF-8.
11834
11835           If the original SV was UTF-8, the pattern should be valid UTF-8; if
11836           the original SV was bytes, the pattern should be too.
11837
11838           All perform 'get' magic, but only "sv_catpvf_mg" and
11839           "sv_catpvf_mg_nocontext" perform 'set' magic.
11840
11841           "sv_catpvf_nocontext" and "sv_catpvf_mg_nocontext" do not take a
11842           thread context ("aTHX") parameter, so are used in situations where
11843           the caller doesn't already have the thread context.
11844
11845           NOTE: "sv_catpvf" must be explicitly called as "Perl_sv_catpvf"
11846           with an "aTHX_" parameter.
11847
11848           NOTE: "sv_catpvf_mg" must be explicitly called as
11849           "Perl_sv_catpvf_mg" with an "aTHX_" parameter.
11850
11851            void  Perl_sv_catpvf        (pTHX_ SV *const sv,
11852                                         const char *const pat, ...)
11853            void  sv_catpvf_nocontext   (SV *const sv, const char *const pat,
11854                                         ...)
11855            void  Perl_sv_catpvf_mg     (pTHX_ SV *const sv,
11856                                         const char *const pat, ...)
11857            void  sv_catpvf_mg_nocontext(SV *const sv, const char *const pat,
11858                                         ...)
11859
11860       "sv_catpvn"
11861       "sv_catpvn_flags"
11862       "sv_catpvn_mg"
11863       "sv_catpvn_nomg"
11864           These concatenate the "len" bytes of the string beginning at "ptr"
11865           onto the end of the string which is in "dsv".  The caller must make
11866           sure "ptr" contains at least "len" bytes.
11867
11868           For all but "sv_catpvn_flags", the string appended is assumed to be
11869           valid UTF-8 if the SV has the UTF-8 status set, and a string of
11870           bytes otherwise.
11871
11872           They differ in that:
11873
11874           "sv_catpvn_mg" performs both 'get' and 'set' magic on "dsv".
11875
11876           "sv_catpvn" performs only 'get' magic.
11877
11878           "sv_catpvn_nomg" skips all magic.
11879
11880           "sv_catpvn_flags" has an extra "flags" parameter which allows you
11881           to specify any combination of magic handling (using "SV_GMAGIC"
11882           and/or "SV_SMAGIC") and to also override the UTF-8 handling.  By
11883           supplying the "SV_CATBYTES" flag, the appended string is
11884           interpreted as plain bytes; by supplying instead the "SV_CATUTF8"
11885           flag, it will be interpreted as UTF-8, and the "dsv" will be
11886           upgraded to UTF-8 if necessary.
11887
11888           "sv_catpvn", "sv_catpvn_mg", and "sv_catpvn_nomg" are implemented
11889           in terms of "sv_catpvn_flags".
11890
11891            void  sv_catpvn      (SV *dsv, const char *sstr, STRLEN len)
11892            void  sv_catpvn_flags(SV *const dsv, const char *sstr,
11893                                  const STRLEN len, const I32 flags)
11894            void  sv_catpvn_mg   (SV *dsv, const char *sstr, STRLEN len)
11895            void  sv_catpvn_nomg (SV *dsv, const char *sstr, STRLEN len)
11896
11897       "sv_catpvs"
11898           Like "sv_catpvn", but takes a literal string instead of a
11899           string/length pair.
11900
11901            void  sv_catpvs(SV* sv, "literal string")
11902
11903       "sv_catpvs_flags"
11904           Like "sv_catpvn_flags", but takes a literal string instead of a
11905           string/length pair.
11906
11907            void  sv_catpvs_flags(SV* sv, "literal string", I32 flags)
11908
11909       "sv_catpvs_mg"
11910           Like "sv_catpvn_mg", but takes a literal string instead of a
11911           string/length pair.
11912
11913            void  sv_catpvs_mg(SV* sv, "literal string")
11914
11915       "sv_catpvs_nomg"
11916           Like "sv_catpvn_nomg", but takes a literal string instead of a
11917           string/length pair.
11918
11919            void  sv_catpvs_nomg(SV* sv, "literal string")
11920
11921       "sv_catsv"
11922       "sv_catsv_flags"
11923       "sv_catsv_mg"
11924       "sv_catsv_nomg"
11925           These concatenate the string from SV "sstr" onto the end of the
11926           string in SV "dsv".  If "sstr" is null, these are no-ops; otherwise
11927           only "dsv" is modified.
11928
11929           They differ only in what magic they perform:
11930
11931           "sv_catsv_mg" performs 'get' magic on both SVs before the copy, and
11932           'set' magic on "dsv" afterwards.
11933
11934           "sv_catsv" performs just 'get' magic, on both SVs.
11935
11936           "sv_catsv_nomg" skips all magic.
11937
11938           "sv_catsv_flags" has an extra "flags" parameter which allows you to
11939           use "SV_GMAGIC" and/or "SV_SMAGIC" to specify any combination of
11940           magic handling (although either both or neither SV will have 'get'
11941           magic applied to it.)
11942
11943           "sv_catsv", "sv_catsv_mg", and "sv_catsv_nomg" are implemented in
11944           terms of "sv_catsv_flags".
11945
11946            void  sv_catsv      (SV *dsv, SV *sstr)
11947            void  sv_catsv_flags(SV *const dsv, SV *const sstr,
11948                                 const I32 flags)
11949            void  sv_catsv_mg   (SV *dsv, SV *sstr)
11950            void  sv_catsv_nomg (SV *dsv, SV *sstr)
11951
11952       "sv_chop"
11953           Efficient removal of characters from the beginning of the string
11954           buffer.  "SvPOK(sv)", or at least "SvPOKp(sv)", must be true and
11955           "ptr" must be a pointer to somewhere inside the string buffer.
11956           "ptr" becomes the first character of the adjusted string.  Uses the
11957           "OOK" hack.  On return, only "SvPOK(sv)" and "SvPOKp(sv)" among the
11958           "OK" flags will be true.
11959
11960           Beware: after this function returns, "ptr" and SvPVX_const(sv) may
11961           no longer refer to the same chunk of data.
11962
11963           The unfortunate similarity of this function's name to that of
11964           Perl's "chop" operator is strictly coincidental.  This function
11965           works from the left; "chop" works from the right.
11966
11967            void  sv_chop(SV *const sv, const char *const ptr)
11968
11969       "sv_clear"
11970           Clear an SV: call any destructors, free up any memory used by the
11971           body, and free the body itself.  The SV's head is not freed,
11972           although its type is set to all 1's so that it won't inadvertently
11973           be assumed to be live during global destruction etc.  This function
11974           should only be called when "REFCNT" is zero.  Most of the time
11975           you'll want to call "sv_free()" (or its macro wrapper
11976           "SvREFCNT_dec") instead.
11977
11978            void  sv_clear(SV *const orig_sv)
11979
11980       "sv_cmp"
11981           Compares the strings in two SVs.  Returns -1, 0, or 1 indicating
11982           whether the string in "sv1" is less than, equal to, or greater than
11983           the string in "sv2".  Is UTF-8 and 'use bytes' aware, handles get
11984           magic, and will coerce its args to strings if necessary.  See also
11985           "sv_cmp_locale".
11986
11987            I32  sv_cmp(SV *const sv1, SV *const sv2)
11988
11989       "sv_cmp_flags"
11990           Compares the strings in two SVs.  Returns -1, 0, or 1 indicating
11991           whether the string in "sv1" is less than, equal to, or greater than
11992           the string in "sv2".  Is UTF-8 and 'use bytes' aware and will
11993           coerce its args to strings if necessary.  If the flags has the
11994           "SV_GMAGIC" bit set, it handles get magic.  See also
11995           "sv_cmp_locale_flags".
11996
11997            I32  sv_cmp_flags(SV *const sv1, SV *const sv2, const U32 flags)
11998
11999       "sv_cmp_locale"
12000           Compares the strings in two SVs in a locale-aware manner.  Is UTF-8
12001           and 'use bytes' aware, handles get magic, and will coerce its args
12002           to strings if necessary.  See also "sv_cmp".
12003
12004            I32  sv_cmp_locale(SV *const sv1, SV *const sv2)
12005
12006       "sv_cmp_locale_flags"
12007           Compares the strings in two SVs in a locale-aware manner.  Is UTF-8
12008           and 'use bytes' aware and will coerce its args to strings if
12009           necessary.  If the flags contain "SV_GMAGIC", it handles get magic.
12010           See also "sv_cmp_flags".
12011
12012            I32  sv_cmp_locale_flags(SV *const sv1, SV *const sv2,
12013                                     const U32 flags)
12014
12015       "sv_collxfrm"
12016           This calls "sv_collxfrm_flags" with the SV_GMAGIC flag.  See
12017           "sv_collxfrm_flags".
12018
12019            char*  sv_collxfrm(SV *const sv, STRLEN *const nxp)
12020
12021       "sv_collxfrm_flags"
12022           Add Collate Transform magic to an SV if it doesn't already have it.
12023           If the flags contain "SV_GMAGIC", it handles get-magic.
12024
12025           Any scalar variable may carry "PERL_MAGIC_collxfrm" magic that
12026           contains the scalar data of the variable, but transformed to such a
12027           format that a normal memory comparison can be used to compare the
12028           data according to the locale settings.
12029
12030            char*  sv_collxfrm_flags(SV *const sv, STRLEN *const nxp,
12031                                     I32 const flags)
12032
12033       "sv_copypv"
12034       "sv_copypv_nomg"
12035       "sv_copypv_flags"
12036           These copy a stringified representation of the source SV into the
12037           destination SV.  They automatically perform coercion of numeric
12038           values into strings.  Guaranteed to preserve the "UTF8" flag even
12039           from overloaded objects.  Similar in nature to "sv_2pv[_flags]" but
12040           they operate directly on an SV instead of just the string.  Mostly
12041           they use ""sv_2pv_flags"" in perlintern to do the work, except when
12042           that would lose the UTF-8'ness of the PV.
12043
12044           The three forms differ only in whether or not they perform 'get
12045           magic' on "sv".  "sv_copypv_nomg" skips 'get magic'; "sv_copypv"
12046           performs it; and "sv_copypv_flags" either performs it (if the
12047           "SV_GMAGIC" bit is set in "flags") or doesn't (if that bit is
12048           cleared).
12049
12050            void  sv_copypv      (SV *const dsv, SV *const ssv)
12051            void  sv_copypv_nomg (SV *const dsv, SV *const ssv)
12052            void  sv_copypv_flags(SV *const dsv, SV *const ssv,
12053                                  const I32 flags)
12054
12055       "SvCUR"
12056           Returns the length, in bytes, of the PV inside the SV.  Note that
12057           this may not match Perl's "length"; for that, use
12058           "sv_len_utf8(sv)". See "SvLEN" also.
12059
12060            STRLEN  SvCUR(SV* sv)
12061
12062       "SvCUR_set"
12063           Sets the current length, in bytes, of the C string which is in the
12064           SV.  See "SvCUR" and "SvIV_set">.
12065
12066            void  SvCUR_set(SV* sv, STRLEN len)
12067
12068       "sv_dec"
12069       "sv_dec_nomg"
12070           These auto-decrement the value in the SV, doing string to numeric
12071           conversion if necessary.  They both handle operator overloading.
12072
12073           They differ only in that:
12074
12075           "sv_dec" handles 'get' magic; "sv_dec_nomg" skips 'get' magic.
12076
12077            void  sv_dec(SV *const sv)
12078
12079       "sv_derived_from"
12080           Exactly like "sv_derived_from_pv", but doesn't take a "flags"
12081           parameter.
12082
12083            bool  sv_derived_from(SV* sv, const char *const name)
12084
12085       "sv_derived_from_pv"
12086           Exactly like "sv_derived_from_pvn", but takes a nul-terminated
12087           string instead of a string/length pair.
12088
12089            bool  sv_derived_from_pv(SV* sv, const char *const name,
12090                                     U32 flags)
12091
12092       "sv_derived_from_pvn"
12093           Returns a boolean indicating whether the SV is derived from the
12094           specified class at the C level.  To check derivation at the Perl
12095           level, call "isa()" as a normal Perl method.
12096
12097           Currently, the only significant value for "flags" is SVf_UTF8.
12098
12099            bool  sv_derived_from_pvn(SV* sv, const char *const name,
12100                                      const STRLEN len, U32 flags)
12101
12102       "sv_derived_from_sv"
12103           Exactly like "sv_derived_from_pvn", but takes the name string in
12104           the form of an SV instead of a string/length pair. This is the
12105           advised form.
12106
12107            bool  sv_derived_from_sv(SV* sv, SV *namesv, U32 flags)
12108
12109       "sv_does"
12110           Like "sv_does_pv", but doesn't take a "flags" parameter.
12111
12112            bool  sv_does(SV* sv, const char *const name)
12113
12114       "sv_does_pv"
12115           Like "sv_does_sv", but takes a nul-terminated string instead of an
12116           SV.
12117
12118            bool  sv_does_pv(SV* sv, const char *const name, U32 flags)
12119
12120       "sv_does_pvn"
12121           Like "sv_does_sv", but takes a string/length pair instead of an SV.
12122
12123            bool  sv_does_pvn(SV* sv, const char *const name,
12124                              const STRLEN len, U32 flags)
12125
12126       "sv_does_sv"
12127           Returns a boolean indicating whether the SV performs a specific,
12128           named role.  The SV can be a Perl object or the name of a Perl
12129           class.
12130
12131            bool  sv_does_sv(SV* sv, SV* namesv, U32 flags)
12132
12133       "SvEND"
12134           Returns a pointer to the spot just after the last character in the
12135           string which is in the SV, where there is usually a trailing "NUL"
12136           character (even though Perl scalars do not strictly require it).
12137           See "SvCUR".  Access the character as "*(SvEND(sv))".
12138
12139           Warning: If "SvCUR" is equal to "SvLEN", then "SvEND" points to
12140           unallocated memory.
12141
12142            char*  SvEND(SV* sv)
12143
12144       "sv_eq"
12145           Returns a boolean indicating whether the strings in the two SVs are
12146           identical.  Is UTF-8 and 'use bytes' aware, handles get magic, and
12147           will coerce its args to strings if necessary.
12148
12149            I32  sv_eq(SV* sv1, SV* sv2)
12150
12151       "sv_eq_flags"
12152           Returns a boolean indicating whether the strings in the two SVs are
12153           identical.  Is UTF-8 and 'use bytes' aware and coerces its args to
12154           strings if necessary.  If the flags has the "SV_GMAGIC" bit set, it
12155           handles get-magic, too.
12156
12157            I32  sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)
12158
12159       "sv_force_normal"
12160           Undo various types of fakery on an SV: if the PV is a shared
12161           string, make a private copy; if we're a ref, stop refing; if we're
12162           a glob, downgrade to an "xpvmg".  See also "sv_force_normal_flags".
12163
12164            void  sv_force_normal(SV *sv)
12165
12166       "sv_force_normal_flags"
12167           Undo various types of fakery on an SV, where fakery means "more
12168           than" a string: if the PV is a shared string, make a private copy;
12169           if we're a ref, stop refing; if we're a glob, downgrade to an
12170           "xpvmg"; if we're a copy-on-write scalar, this is the on-write time
12171           when we do the copy, and is also used locally; if this is a
12172           vstring, drop the vstring magic.  If "SV_COW_DROP_PV" is set then a
12173           copy-on-write scalar drops its PV buffer (if any) and becomes
12174           "SvPOK_off" rather than making a copy.  (Used where this scalar is
12175           about to be set to some other value.)  In addition, the "flags"
12176           parameter gets passed to "sv_unref_flags()" when unreffing.
12177           "sv_force_normal" calls this function with flags set to 0.
12178
12179           This function is expected to be used to signal to perl that this SV
12180           is about to be written to, and any extra book-keeping needs to be
12181           taken care of.  Hence, it croaks on read-only values.
12182
12183            void  sv_force_normal_flags(SV *const sv, const U32 flags)
12184
12185       "sv_free"
12186           Decrement an SV's reference count, and if it drops to zero, call
12187           "sv_clear" to invoke destructors and free up any memory used by the
12188           body; finally, deallocating the SV's head itself.  Normally called
12189           via a wrapper macro "SvREFCNT_dec".
12190
12191            void  sv_free(SV *const sv)
12192
12193       "SvGAMAGIC"
12194           Returns true if the SV has get magic or overloading.  If either is
12195           true then the scalar is active data, and has the potential to
12196           return a new value every time it is accessed.  Hence you must be
12197           careful to only read it once per user logical operation and work
12198           with that returned value.  If neither is true then the scalar's
12199           value cannot change unless written to.
12200
12201            U32  SvGAMAGIC(SV* sv)
12202
12203       "SvGETMAGIC"
12204           Invokes "mg_get" on an SV if it has 'get' magic.  For example, this
12205           will call "FETCH" on a tied variable.  This macro evaluates its
12206           argument more than once.
12207
12208            void  SvGETMAGIC(SV* sv)
12209
12210       "sv_gets"
12211           Get a line from the filehandle and store it into the SV, optionally
12212           appending to the currently-stored string.  If "append" is not 0,
12213           the line is appended to the SV instead of overwriting it.  "append"
12214           should be set to the byte offset that the appended string should
12215           start at in the SV (typically, "SvCUR(sv)" is a suitable choice).
12216
12217            char*  sv_gets(SV *const sv, PerlIO *const fp, I32 append)
12218
12219       "sv_get_backrefs"
12220           NOTE: "sv_get_backrefs" is experimental and may change or be
12221           removed without notice.
12222
12223           If "sv" is the target of a weak reference then it returns the back
12224           references structure associated with the sv; otherwise return
12225           "NULL".
12226
12227           When returning a non-null result the type of the return is
12228           relevant. If it is an AV then the elements of the AV are the weak
12229           reference RVs which point at this item. If it is any other type
12230           then the item itself is the weak reference.
12231
12232           See also "Perl_sv_add_backref()", "Perl_sv_del_backref()",
12233           "Perl_sv_kill_backrefs()"
12234
12235            SV*  sv_get_backrefs(SV *const sv)
12236
12237       "SvGROW"
12238           Expands the character buffer in the SV so that it has room for the
12239           indicated number of bytes (remember to reserve space for an extra
12240           trailing "NUL" character).  Calls "sv_grow" to perform the
12241           expansion if necessary.  Returns a pointer to the character buffer.
12242           SV must be of type >= "SVt_PV".  One alternative is to call
12243           "sv_grow" if you are not sure of the type of SV.
12244
12245           You might mistakenly think that "len" is the number of bytes to add
12246           to the existing size, but instead it is the total size "sv" should
12247           be.
12248
12249            char *  SvGROW(SV* sv, STRLEN len)
12250
12251       "sv_inc"
12252       "sv_inc_nomg"
12253           These auto-increment the value in the SV, doing string to numeric
12254           conversion if necessary.  They both handle operator overloading.
12255
12256           They differ only in that "sv_inc" performs 'get' magic;
12257           "sv_inc_nomg" skips any magic.
12258
12259            void  sv_inc(SV *const sv)
12260
12261       "sv_insert"
12262           Inserts and/or replaces a string at the specified offset/length
12263           within the SV.  Similar to the Perl "substr()" function, with
12264           "littlelen" bytes starting at "little" replacing "len" bytes of the
12265           string in "bigstr" starting at "offset".  Handles get magic.
12266
12267            void  sv_insert(SV *const bigstr, const STRLEN offset,
12268                            const STRLEN len, const char *const little,
12269                            const STRLEN littlelen)
12270
12271       "sv_insert_flags"
12272           Same as "sv_insert", but the extra "flags" are passed to the
12273           "SvPV_force_flags" that applies to "bigstr".
12274
12275            void  sv_insert_flags(SV *const bigstr, const STRLEN offset,
12276                                  const STRLEN len, const char *little,
12277                                  const STRLEN littlelen, const U32 flags)
12278
12279       "SvIOK"
12280           Returns a U32 value indicating whether the SV contains an integer.
12281
12282            U32  SvIOK(SV* sv)
12283
12284       "SvIOK_notUV"
12285           Returns a boolean indicating whether the SV contains a signed
12286           integer.
12287
12288            bool  SvIOK_notUV(SV* sv)
12289
12290       "SvIOK_off"
12291           Unsets the IV status of an SV.
12292
12293            void  SvIOK_off(SV* sv)
12294
12295       "SvIOK_on"
12296           Tells an SV that it is an integer.
12297
12298            void  SvIOK_on(SV* sv)
12299
12300       "SvIOK_only"
12301           Tells an SV that it is an integer and disables all other "OK" bits.
12302
12303            void  SvIOK_only(SV* sv)
12304
12305       "SvIOK_only_UV"
12306           Tells an SV that it is an unsigned integer and disables all other
12307           "OK" bits.
12308
12309            void  SvIOK_only_UV(SV* sv)
12310
12311       "SvIOKp"
12312           Returns a U32 value indicating whether the SV contains an integer.
12313           Checks the private setting.  Use "SvIOK" instead.
12314
12315            U32  SvIOKp(SV* sv)
12316
12317       "SvIOK_UV"
12318           Returns a boolean indicating whether the SV contains an integer
12319           that must be interpreted as unsigned.  A non-negative integer whose
12320           value is within the range of both an IV and a UV may be flagged as
12321           either "SvUOK" or "SvIOK".
12322
12323            bool  SvIOK_UV(SV* sv)
12324
12325       "sv_isa"
12326           Returns a boolean indicating whether the SV is blessed into the
12327           specified class.
12328
12329           This does not check for subtypes or method overloading. Use
12330           "sv_isa_sv" to verify an inheritance relationship in the same way
12331           as the "isa" operator by respecting any "isa()" method overloading;
12332           or "sv_derived_from_sv" to test directly on the actual object type.
12333
12334            int  sv_isa(SV* sv, const char *const name)
12335
12336       "sv_isa_sv"
12337           NOTE: "sv_isa_sv" is experimental and may change or be removed
12338           without notice.
12339
12340           Returns a boolean indicating whether the SV is an object reference
12341           and is derived from the specified class, respecting any "isa()"
12342           method overloading it may have. Returns false if "sv" is not a
12343           reference to an object, or is not derived from the specified class.
12344
12345           This is the function used to implement the behaviour of the "isa"
12346           operator.
12347
12348           Does not invoke magic on "sv".
12349
12350           Not to be confused with the older "sv_isa" function, which does not
12351           use an overloaded "isa()" method, nor will check subclassing.
12352
12353            bool  sv_isa_sv(SV* sv, SV* namesv)
12354
12355       "SvIsCOW"
12356           Returns a U32 value indicating whether the SV is Copy-On-Write
12357           (either shared hash key scalars, or full Copy On Write scalars if
12358           5.9.0 is configured for COW).
12359
12360            U32  SvIsCOW(SV* sv)
12361
12362       "SvIsCOW_shared_hash"
12363           Returns a boolean indicating whether the SV is Copy-On-Write shared
12364           hash key scalar.
12365
12366            bool  SvIsCOW_shared_hash(SV* sv)
12367
12368       "sv_isobject"
12369           Returns a boolean indicating whether the SV is an RV pointing to a
12370           blessed object.  If the SV is not an RV, or if the object is not
12371           blessed, then this will return false.
12372
12373            int  sv_isobject(SV* sv)
12374
12375       "SvIV"
12376       "SvIVx"
12377       "SvIV_nomg"
12378           These coerce the given SV to IV and return it.  The returned value
12379           in many circumstances will get stored in "sv"'s IV slot, but not in
12380           all cases.  (Use "sv_setiv" to make sure it does).
12381
12382           "SvIVx" is different from the others in that it is guaranteed to
12383           evaluate "sv" exactly once; the others may evaluate it multiple
12384           times.  Only use this form if "sv" is an expression with side
12385           effects, otherwise use the more efficient "SvIV".
12386
12387           "SvIV_nomg" is the same as "SvIV", but does not perform 'get'
12388           magic.
12389
12390            IV  SvIV(SV* sv)
12391
12392       "SvIV_set"
12393           Set the value of the IV pointer in sv to val.  It is possible to
12394           perform the same function of this macro with an lvalue assignment
12395           to "SvIVX".  With future Perls, however, it will be more efficient
12396           to use "SvIV_set" instead of the lvalue assignment to "SvIVX".
12397
12398            void  SvIV_set(SV* sv, IV val)
12399
12400       "SvIVX"
12401           Returns the raw value in the SV's IV slot, without checks or
12402           conversions.  Only use when you are sure "SvIOK" is true.  See also
12403           "SvIV".
12404
12405            IV  SvIVX(SV* sv)
12406
12407       "SvLEN"
12408           Returns the size of the string buffer in the SV, not including any
12409           part attributable to "SvOOK".  See "SvCUR".
12410
12411            STRLEN  SvLEN(SV* sv)
12412
12413       "sv_len"
12414           Returns the length of the string in the SV.  Handles magic and type
12415           coercion and sets the UTF8 flag appropriately.  See also "SvCUR",
12416           which gives raw access to the "xpv_cur" slot.
12417
12418            STRLEN  sv_len(SV *const sv)
12419
12420       "SvLEN_set"
12421           Set the size of the string buffer for the SV. See "SvLEN".
12422
12423            void  SvLEN_set(SV* sv, STRLEN len)
12424
12425       "sv_len_utf8"
12426           Returns the number of characters in the string in an SV, counting
12427           wide UTF-8 bytes as a single character.  Handles magic and type
12428           coercion.
12429
12430            STRLEN  sv_len_utf8(SV *const sv)
12431
12432       "SvLOCK"
12433           Arranges for a mutual exclusion lock to be obtained on "sv" if a
12434           suitable module has been loaded.
12435
12436            void  SvLOCK(SV* sv)
12437
12438       "sv_magic"
12439           Adds magic to an SV.  First upgrades "sv" to type "SVt_PVMG" if
12440           necessary, then adds a new magic item of type "how" to the head of
12441           the magic list.
12442
12443           See "sv_magicext" (which "sv_magic" now calls) for a description of
12444           the handling of the "name" and "namlen" arguments.
12445
12446           You need to use "sv_magicext" to add magic to "SvREADONLY" SVs and
12447           also to add more than one instance of the same "how".
12448
12449            void  sv_magic(SV *const sv, SV *const obj, const int how,
12450                           const char *const name, const I32 namlen)
12451
12452       "sv_magicext"
12453           Adds magic to an SV, upgrading it if necessary.  Applies the
12454           supplied "vtable" and returns a pointer to the magic added.
12455
12456           Note that "sv_magicext" will allow things that "sv_magic" will not.
12457           In particular, you can add magic to "SvREADONLY" SVs, and add more
12458           than one instance of the same "how".
12459
12460           If "namlen" is greater than zero then a "savepvn" copy of "name" is
12461           stored, if "namlen" is zero then "name" is stored as-is and - as
12462           another special case - if "(name && namlen == HEf_SVKEY)" then
12463           "name" is assumed to contain an SV* and is stored as-is with its
12464           "REFCNT" incremented.
12465
12466           (This is now used as a subroutine by "sv_magic".)
12467
12468            MAGIC *  sv_magicext(SV *const sv, SV *const obj, const int how,
12469                                 const MGVTBL *const vtbl,
12470                                 const char *const name, const I32 namlen)
12471
12472       "SvMAGIC_set"
12473           Set the value of the MAGIC pointer in "sv" to val.  See "SvIV_set".
12474
12475            void  SvMAGIC_set(SV* sv, MAGIC* val)
12476
12477       "sv_mortalcopy"
12478           Creates a new SV which is a copy of the original SV (using
12479           "sv_setsv").  The new SV is marked as mortal.  It will be destroyed
12480           "soon", either by an explicit call to "FREETMPS", or by an implicit
12481           call at places such as statement boundaries.  See also
12482           "sv_newmortal" and "sv_2mortal".
12483
12484            SV*  sv_mortalcopy(SV *const oldsv)
12485
12486       "sv_mortalcopy_flags"
12487           Like "sv_mortalcopy", but the extra "flags" are passed to the
12488           "sv_setsv_flags".
12489
12490            SV*  sv_mortalcopy_flags(SV *const oldsv, U32 flags)
12491
12492       "sv_newmortal"
12493           Creates a new null SV which is mortal.  The reference count of the
12494           SV is set to 1.  It will be destroyed "soon", either by an explicit
12495           call to "FREETMPS", or by an implicit call at places such as
12496           statement boundaries.  See also "sv_mortalcopy" and "sv_2mortal".
12497
12498            SV*  sv_newmortal()
12499
12500       "SvNIOK"
12501           Returns a U32 value indicating whether the SV contains a number,
12502           integer or double.
12503
12504            U32  SvNIOK(SV* sv)
12505
12506       "SvNIOK_off"
12507           Unsets the NV/IV status of an SV.
12508
12509            void  SvNIOK_off(SV* sv)
12510
12511       "SvNIOKp"
12512           Returns a U32 value indicating whether the SV contains a number,
12513           integer or double.  Checks the private setting.  Use "SvNIOK"
12514           instead.
12515
12516            U32  SvNIOKp(SV* sv)
12517
12518       "SvNOK"
12519           Returns a U32 value indicating whether the SV contains a double.
12520
12521            U32  SvNOK(SV* sv)
12522
12523       "SvNOK_off"
12524           Unsets the NV status of an SV.
12525
12526            void  SvNOK_off(SV* sv)
12527
12528       "SvNOK_on"
12529           Tells an SV that it is a double.
12530
12531            void  SvNOK_on(SV* sv)
12532
12533       "SvNOK_only"
12534           Tells an SV that it is a double and disables all other OK bits.
12535
12536            void  SvNOK_only(SV* sv)
12537
12538       "SvNOKp"
12539           Returns a U32 value indicating whether the SV contains a double.
12540           Checks the private setting.  Use "SvNOK" instead.
12541
12542            U32  SvNOKp(SV* sv)
12543
12544       "sv_nolocking"
12545           "DEPRECATED!"  It is planned to remove "sv_nolocking" from a future
12546           release of Perl.  Do not use it for new code; remove it from
12547           existing code.
12548
12549           Dummy routine which "locks" an SV when there is no locking module
12550           present.  Exists to avoid test for a "NULL" function pointer and
12551           because it could potentially warn under some level of strict-ness.
12552
12553           "Superseded" by "sv_nosharing()".
12554
12555            void  sv_nolocking(SV *sv)
12556
12557       "sv_nounlocking"
12558           "DEPRECATED!"  It is planned to remove "sv_nounlocking" from a
12559           future release of Perl.  Do not use it for new code; remove it from
12560           existing code.
12561
12562           Dummy routine which "unlocks" an SV when there is no locking module
12563           present.  Exists to avoid test for a "NULL" function pointer and
12564           because it could potentially warn under some level of strict-ness.
12565
12566           "Superseded" by "sv_nosharing()".
12567
12568            void  sv_nounlocking(SV *sv)
12569
12570       "SvNV"
12571       "SvNVx"
12572       "SvNV_nomg"
12573           These coerce the given SV to NV and return it.  The returned value
12574           in many circumstances will get stored in "sv"'s NV slot, but not in
12575           all cases.  (Use "sv_setnv" to make sure it does).
12576
12577           "SvNVx" is different from the others in that it is guaranteed to
12578           evaluate "sv" exactly once; the others may evaluate it multiple
12579           times.  Only use this form if "sv" is an expression with side
12580           effects, otherwise use the more efficient "SvNV".
12581
12582           "SvNV_nomg" is the same as "SvNV", but does not perform 'get'
12583           magic.
12584
12585            NV  SvNV(SV* sv)
12586
12587       "SvNV_set"
12588           Set the value of the NV pointer in "sv" to val.  See "SvIV_set".
12589
12590            void  SvNV_set(SV* sv, NV val)
12591
12592       "SvNVX"
12593           Returns the raw value in the SV's NV slot, without checks or
12594           conversions.  Only use when you are sure "SvNOK" is true.  See also
12595           "SvNV".
12596
12597            NV  SvNVX(SV* sv)
12598
12599       "SvOK"
12600           Returns a U32 value indicating whether the value is defined.  This
12601           is only meaningful for scalars.
12602
12603            U32  SvOK(SV* sv)
12604
12605       "SvOOK"
12606           Returns a U32 indicating whether the pointer to the string buffer
12607           is offset.  This hack is used internally to speed up removal of
12608           characters from the beginning of a "SvPV".  When "SvOOK" is true,
12609           then the start of the allocated string buffer is actually
12610           "SvOOK_offset()" bytes before "SvPVX".  This offset used to be
12611           stored in "SvIVX", but is now stored within the spare part of the
12612           buffer.
12613
12614            U32  SvOOK(SV* sv)
12615
12616       "SvOOK_off"
12617           Remove any string offset.
12618
12619            void  SvOOK_off(SV * sv)
12620
12621       "SvOOK_offset"
12622           Reads into "len" the offset from "SvPVX" back to the true start of
12623           the allocated buffer, which will be non-zero if "sv_chop" has been
12624           used to efficiently remove characters from start of the buffer.
12625           Implemented as a macro, which takes the address of "len", which
12626           must be of type "STRLEN".  Evaluates "sv" more than once.  Sets
12627           "len" to 0 if "SvOOK(sv)" is false.
12628
12629            void  SvOOK_offset(SV*sv, STRLEN len)
12630
12631       "SvPOK"
12632           Returns a U32 value indicating whether the SV contains a character
12633           string.
12634
12635            U32  SvPOK(SV* sv)
12636
12637       "SvPOK_off"
12638           Unsets the PV status of an SV.
12639
12640            void  SvPOK_off(SV* sv)
12641
12642       "SvPOK_on"
12643           Tells an SV that it is a string.
12644
12645            void  SvPOK_on(SV* sv)
12646
12647       "SvPOK_only"
12648           Tells an SV that it is a string and disables all other "OK" bits.
12649           Will also turn off the UTF-8 status.
12650
12651            void  SvPOK_only(SV* sv)
12652
12653       "SvPOK_only_UTF8"
12654           Tells an SV that it is a string and disables all other "OK" bits,
12655           and leaves the UTF-8 status as it was.
12656
12657            void  SvPOK_only_UTF8(SV* sv)
12658
12659       "SvPOKp"
12660           Returns a U32 value indicating whether the SV contains a character
12661           string.  Checks the private setting.  Use "SvPOK" instead.
12662
12663            U32  SvPOKp(SV* sv)
12664
12665       "sv_pos_b2u"
12666           Converts the value pointed to by "offsetp" from a count of bytes
12667           from the start of the string, to a count of the equivalent number
12668           of UTF-8 chars.  Handles magic and type coercion.
12669
12670           Use "sv_pos_b2u_flags" in preference, which correctly handles
12671           strings longer than 2Gb.
12672
12673            void  sv_pos_b2u(SV *const sv, I32 *const offsetp)
12674
12675       "sv_pos_b2u_flags"
12676           Converts "offset" from a count of bytes from the start of the
12677           string, to a count of the equivalent number of UTF-8 chars.
12678           Handles type coercion.  "flags" is passed to "SvPV_flags", and
12679           usually should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
12680
12681            STRLEN  sv_pos_b2u_flags(SV *const sv, STRLEN const offset,
12682                                     U32 flags)
12683
12684       "sv_pos_u2b"
12685           Converts the value pointed to by "offsetp" from a count of UTF-8
12686           chars from the start of the string, to a count of the equivalent
12687           number of bytes; if "lenp" is non-zero, it does the same to "lenp",
12688           but this time starting from the offset, rather than from the start
12689           of the string.  Handles magic and type coercion.
12690
12691           Use "sv_pos_u2b_flags" in preference, which correctly handles
12692           strings longer than 2Gb.
12693
12694            void  sv_pos_u2b(SV *const sv, I32 *const offsetp,
12695                             I32 *const lenp)
12696
12697       "sv_pos_u2b_flags"
12698           Converts the offset from a count of UTF-8 chars from the start of
12699           the string, to a count of the equivalent number of bytes; if "lenp"
12700           is non-zero, it does the same to "lenp", but this time starting
12701           from "offset", rather than from the start of the string.  Handles
12702           type coercion.  "flags" is passed to "SvPV_flags", and usually
12703           should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
12704
12705            STRLEN  sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
12706                                     STRLEN *const lenp, U32 flags)
12707
12708       "SvPV"
12709       "SvPVx"
12710       "SvPV_nomg"
12711       "SvPV_nolen"
12712       "SvPVx_nolen"
12713       "SvPV_nomg_nolen"
12714       "SvPV_mutable"
12715       "SvPV_const"
12716       "SvPVx_const"
12717       "SvPV_nolen_const"
12718       "SvPVx_nolen_const"
12719       "SvPV_nomg_const"
12720       "SvPV_nomg_const_nolen"
12721       "SvPV_flags"
12722       "SvPV_flags_const"
12723       "SvPV_flags_mutable"
12724       "SvPVbyte"
12725       "SvPVbyte_nomg"
12726       "SvPVbyte_nolen"
12727       "SvPVbytex_nolen"
12728       "SvPVbytex"
12729       "SvPVbyte_or_null"
12730       "SvPVbyte_or_null_nomg"
12731       "SvPVutf8"
12732       "SvPVutf8x"
12733       "SvPVutf8_nomg"
12734       "SvPVutf8_nolen"
12735       "SvPVutf8_or_null"
12736       "SvPVutf8_or_null_nomg"
12737           All these return a pointer to the string in "sv", or a stringified
12738           form of "sv" if it does not contain a string.  The SV may cache the
12739           stringified version becoming "SvPOK".
12740
12741           This is a very basic and common operation, so there are lots of
12742           slightly different versions of it.
12743
12744           Note that there is no guarantee that the return value of
12745           "SvPV(sv)", for example, is equal to "SvPVX(sv)", or that
12746           "SvPVX(sv)" contains valid data, or that successive calls to
12747           "SvPV(sv)" (or another of these forms) will return the same pointer
12748           value each time.  This is due to the way that things like
12749           overloading and Copy-On-Write are handled.  In these cases, the
12750           return value may point to a temporary buffer or similar.  If you
12751           absolutely need the "SvPVX" field to be valid (for example, if you
12752           intend to write to it), then see "SvPV_force".
12753
12754           The differences between the forms are:
12755
12756           The forms with neither "byte" nor "utf8" in their names (e.g.,
12757           "SvPV" or "SvPV_nolen") can expose the SV's internal string buffer.
12758           If that buffer consists entirely of bytes 0-255 and includes any
12759           bytes above 127, then you MUST consult "SvUTF8" to determine the
12760           actual code points the string is meant to contain. Generally
12761           speaking, it is probably safer to prefer "SvPVbyte", "SvPVutf8",
12762           and the like. See "How do I pass a Perl string to a C library?" in
12763           perlguts for more details.
12764
12765           The forms with "flags" in their names allow you to use the "flags"
12766           parameter to specify to process 'get' magic (by setting the
12767           "SV_GMAGIC" flag) or to skip 'get' magic (by clearing it).  The
12768           other forms process 'get' magic, except for the ones with "nomg" in
12769           their names, which skip 'get' magic.
12770
12771           The forms that take a "len" parameter will set that variable to the
12772           byte length of the resultant string (these are macros, so don't use
12773           &len).
12774
12775           The forms with "nolen" in their names indicate they don't have a
12776           "len" parameter.  They should be used only when it is known that
12777           the PV is a C string, terminated by a NUL byte, and without
12778           intermediate NUL characters; or when you don't care about its
12779           length.
12780
12781           The forms with "const" in their names return "const char *" so that
12782           the compiler will hopefully complain if you were to try to modify
12783           the contents of the string (unless you cast away const yourself).
12784
12785           The other forms return a mutable pointer so that the string is
12786           modifiable by the caller; this is emphasized for the ones with
12787           "mutable" in their names.
12788
12789           The forms whose name ends in "x" are the same as the corresponding
12790           form without the "x", but the "x" form is guaranteed to evaluate
12791           "sv" exactly once, with a slight loss of efficiency.  Use this if
12792           "sv" is an expression with side effects.
12793
12794           "SvPVutf8" is like "SvPV", but converts "sv" to UTF-8 first if not
12795           already UTF-8.  Similiarly, the other forms with "utf8" in their
12796           names correspond to their respective forms without.
12797
12798           "SvPVutf8_or_null" and "SvPVutf8_or_null_nomg" don't have
12799           corresponding non-"utf8" forms.  Instead they are like
12800           "SvPVutf8_nomg", but when "sv" is undef, they return "NULL".
12801
12802           "SvPVbyte" is like "SvPV", but converts "sv" to byte representation
12803           first if currently encoded as UTF-8.  If "sv" cannot be downgraded
12804           from UTF-8, it croaks.  Similiarly, the other forms with "byte" in
12805           their names correspond to their respective forms without.
12806
12807           "SvPVbyte_or_null" doesn't have a corresponding non-"byte" form.
12808           Instead it is like "SvPVbyte", but when "sv" is undef, it returns
12809           "NULL".
12810
12811            char*         SvPV                 (SV* sv, STRLEN len)
12812            char*         SvPVx                (SV* sv, STRLEN len)
12813            char*         SvPV_nomg            (SV* sv, STRLEN len)
12814            char*         SvPV_nolen           (SV* sv)
12815            char*         SvPVx_nolen          (SV* sv)
12816            char*         SvPV_nomg_nolen      (SV* sv)
12817            char*         SvPV_mutable         (SV* sv, STRLEN len)
12818            const char*   SvPV_const           (SV* sv, STRLEN len)
12819            const char*   SvPVx_const          (SV* sv, STRLEN len)
12820            const char*   SvPV_nolen_const     (SV* sv)
12821            const char*   SvPVx_nolen_const    (SV* sv)
12822            const char*   SvPV_nomg_const      (SV* sv, STRLEN len)
12823            const char*   SvPV_nomg_const_nolen(SV* sv)
12824            char *        SvPV_flags           (SV * sv, STRLEN len,
12825                                                U32 flags)
12826            const char *  SvPV_flags_const     (SV * sv, STRLEN len,
12827                                                U32 flags)
12828            char *        SvPV_flags_mutable   (SV * sv, STRLEN len,
12829                                                U32 flags)
12830            char*         SvPVbyte             (SV* sv, STRLEN len)
12831            char*         SvPVbyte_nomg        (SV* sv, STRLEN len)
12832            char*         SvPVbyte_nolen       (SV* sv)
12833            char*         SvPVbytex_nolen      (SV* sv)
12834            char*         SvPVbytex            (SV* sv, STRLEN len)
12835            char*         SvPVbyte_or_null     (SV* sv, STRLEN len)
12836            char*         SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
12837            char*         SvPVutf8             (SV* sv, STRLEN len)
12838            char*         SvPVutf8x            (SV* sv, STRLEN len)
12839            char*         SvPVutf8_nomg        (SV* sv, STRLEN len)
12840            char*         SvPVutf8_nolen       (SV* sv)
12841            char*         SvPVutf8_or_null     (SV* sv, STRLEN len)
12842            char*         SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
12843
12844       "SvPVbyte"
12845           Like "SvPV", but converts "sv" to byte representation first if
12846           necessary.  If the SV cannot be downgraded from UTF-8, this croaks.
12847
12848            char*  SvPVbyte(SV* sv, STRLEN len)
12849
12850       "SvPVbyte_force"
12851           Like "SvPV_force", but converts "sv" to byte representation first
12852           if necessary.  If the SV cannot be downgraded from UTF-8, this
12853           croaks.
12854
12855            char*  SvPVbyte_force(SV* sv, STRLEN len)
12856
12857       "SvPVbyte_nolen"
12858           Like "SvPV_nolen", but converts "sv" to byte representation first
12859           if necessary.  If the SV cannot be downgraded from UTF-8, this
12860           croaks.
12861
12862            char*  SvPVbyte_nolen(SV* sv)
12863
12864       "SvPVbyte_nomg"
12865           Like "SvPVbyte", but does not process get magic.
12866
12867            char*  SvPVbyte_nomg(SV* sv, STRLEN len)
12868
12869       "SvPVbyte_or_null"
12870           Like "SvPVbyte", but when "sv" is undef, returns "NULL".
12871
12872            char*  SvPVbyte_or_null(SV* sv, STRLEN len)
12873
12874       "SvPVbyte_or_null_nomg"
12875           Like "SvPVbyte_or_null", but does not process get magic.
12876
12877            char*  SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
12878
12879       "SvPVCLEAR"
12880           Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is
12881           properly null terminated. Equivalent to sv_setpvs(""), but more
12882           efficient.
12883
12884            char *  SvPVCLEAR(SV* sv)
12885
12886       "SvPV_force"
12887       "SvPV_force_nolen"
12888       "SvPVx_force"
12889       "SvPV_force_nomg"
12890       "SvPV_force_nomg_nolen"
12891       "SvPV_force_mutable"
12892       "SvPV_force_flags"
12893       "SvPV_force_flags_nolen"
12894       "SvPV_force_flags_mutable"
12895       "SvPVbyte_force"
12896       "SvPVbytex_force"
12897       "SvPVutf8_force"
12898       "SvPVutf8x_force"
12899           These are like "SvPV", returning the string in the SV, but will
12900           force the SV into containing a string ("SvPOK"), and only a string
12901           ("SvPOK_only"), by hook or by crook.  You need to use one of these
12902           "force" routines if you are going to update the "SvPVX" directly.
12903
12904           Note that coercing an arbitrary scalar into a plain PV will
12905           potentially strip useful data from it.  For example if the SV was
12906           "SvROK", then the referent will have its reference count
12907           decremented, and the SV itself may be converted to an "SvPOK"
12908           scalar with a string buffer containing a value such as
12909           "ARRAY(0x1234)".
12910
12911           The differences between the forms are:
12912
12913           The forms with "flags" in their names allow you to use the "flags"
12914           parameter to specify to perform 'get' magic (by setting the
12915           "SV_GMAGIC" flag) or to skip 'get' magic (by clearing it).  The
12916           other forms do perform 'get' magic, except for the ones with "nomg"
12917           in their names, which skip 'get' magic.
12918
12919           The forms that take a "len" parameter will set that variable to the
12920           byte length of the resultant string (these are macros, so don't use
12921           &len).
12922
12923           The forms with "nolen" in their names indicate they don't have a
12924           "len" parameter.  They should be used only when it is known that
12925           the PV is a C string, terminated by a NUL byte, and without
12926           intermediate NUL characters; or when you don't care about its
12927           length.
12928
12929           The forms with "mutable" in their names are effectively the same as
12930           those without, but the name emphasizes that the string is
12931           modifiable by the caller, which it is in all the forms.
12932
12933           "SvPVutf8_force" is like "SvPV_force", but converts "sv" to UTF-8
12934           first if not already UTF-8.
12935
12936           "SvPVutf8x_force" is like "SvPVutf8_force", but guarantees to
12937           evaluate "sv" only once; use the more efficient "SvPVutf8_force"
12938           otherwise.
12939
12940           "SvPVbyte_force" is like "SvPV_force", but converts "sv" to byte
12941           representation first if currently encoded as UTF-8.  If the SV
12942           cannot be downgraded from UTF-8, this croaks.
12943
12944           "SvPVbytex_force" is like "SvPVbyte_force", but guarantees to
12945           evaluate "sv" only once; use the more efficient "SvPVbyte_force"
12946           otherwise.
12947
12948            char*  SvPV_force              (SV* sv, STRLEN len)
12949            char*  SvPV_force_nolen        (SV* sv)
12950            char*  SvPVx_force             (SV* sv, STRLEN len)
12951            char*  SvPV_force_nomg         (SV* sv, STRLEN len)
12952            char*  SvPV_force_nomg_nolen   (SV * sv)
12953            char*  SvPV_force_mutable      (SV * sv, STRLEN len)
12954            char*  SvPV_force_flags        (SV * sv, STRLEN len, U32 flags)
12955            char*  SvPV_force_flags_nolen  (SV * sv, U32 flags)
12956            char*  SvPV_force_flags_mutable(SV * sv, STRLEN len, U32 flags)
12957            char*  SvPVbyte_force          (SV* sv, STRLEN len)
12958            char*  SvPVbytex_force         (SV* sv, STRLEN len)
12959            char*  SvPVutf8_force          (SV* sv, STRLEN len)
12960            char*  SvPVutf8x_force         (SV* sv, STRLEN len)
12961
12962       "SvPV_free"
12963           Frees the PV buffer in "sv", leaving things in a precarious state,
12964           so should only be used as part of a larger operation
12965
12966            void  SvPV_free(SV * sv)
12967
12968       "sv_pvn_force_flags"
12969           Get a sensible string out of the SV somehow.  If "flags" has the
12970           "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate, else
12971           not.  "sv_pvn_force" and "sv_pvn_force_nomg" are implemented in
12972           terms of this function.  You normally want to use the various
12973           wrapper macros instead: see "SvPV_force" and "SvPV_force_nomg".
12974
12975            char*  sv_pvn_force_flags(SV *const sv, STRLEN *const lp,
12976                                      const U32 flags)
12977
12978       "SvPV_renew"
12979           Low level micro optimization of "SvGROW".  It is generally better
12980           to use "SvGROW" instead.  This is because "SvPV_renew" ignores
12981           potential issues that "SvGROW" handles.  "sv" needs to have a real
12982           "PV" that is unencombered by things like COW.  Using
12983           "SV_CHECK_THINKFIRST" or "SV_CHECK_THINKFIRST_COW_DROP" before
12984           calling this should clean it up, but why not just use "SvGROW" if
12985           you're not sure about the provenance?
12986
12987            void  SvPV_renew(SV* sv, STRLEN len)
12988
12989       "SvPV_set"
12990           This is probably not what you want to use, you probably wanted
12991           "sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
12992
12993           Set the value of the PV pointer in "sv" to the Perl allocated
12994           "NUL"-terminated string "val".  See also "SvIV_set".
12995
12996           Remember to free the previous PV buffer. There are many things to
12997           check.  Beware that the existing pointer may be involved in copy-
12998           on-write or other mischief, so do "SvOOK_off(sv)" and use
12999           "sv_force_normal" or "SvPV_force" (or check the "SvIsCOW" flag)
13000           first to make sure this modification is safe. Then finally, if it
13001           is not a COW, call "SvPV_free" to free the previous PV buffer.
13002
13003            void  SvPV_set(SV* sv, char* val)
13004
13005       "SvPVutf8"
13006           Like "SvPV", but converts "sv" to UTF-8 first if necessary.
13007
13008            char*  SvPVutf8(SV* sv, STRLEN len)
13009
13010       "SvPVutf8_force"
13011           Like "SvPV_force", but converts "sv" to UTF-8 first if necessary.
13012
13013            char*  SvPVutf8_force(SV* sv, STRLEN len)
13014
13015       "SvPVutf8_nolen"
13016           Like "SvPV_nolen", but converts "sv" to UTF-8 first if necessary.
13017
13018            char*  SvPVutf8_nolen(SV* sv)
13019
13020       "SvPVutf8_nomg"
13021           Like "SvPVutf8", but does not process get magic.
13022
13023            char*  SvPVutf8_nomg(SV* sv, STRLEN len)
13024
13025       "SvPVutf8_or_null"
13026           Like "SvPVutf8", but when "sv" is undef, returns "NULL".
13027
13028            char*  SvPVutf8_or_null(SV* sv, STRLEN len)
13029
13030       "SvPVutf8_or_null_nomg"
13031           Like "SvPVutf8_or_null", but does not process get magic.
13032
13033            char*  SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
13034
13035       "SvPVX"
13036       "SvPVXx"
13037       "SvPVX_const"
13038       "SvPVX_mutable"
13039           These return a pointer to the physical string in the SV.  The SV
13040           must contain a string.  Prior to 5.9.3 it is not safe to execute
13041           these unless the SV's type >= "SVt_PV".
13042
13043           These are also used to store the name of an autoloaded subroutine
13044           in an XS AUTOLOAD routine.  See "Autoloading with XSUBs" in
13045           perlguts.
13046
13047           "SvPVXx" is identical to "SvPVX".
13048
13049           "SvPVX_mutable" is merely a synonym for "SvPVX", but its name
13050           emphasizes that the string is modifiable by the caller.
13051
13052           "SvPVX_const" differs in that the return value has been cast so
13053           that the compiler will complain if you were to try to modify the
13054           contents of the string, (unless you cast away const yourself).
13055
13056            char*        SvPVX        (SV* sv)
13057            char*        SvPVXx       (SV* sv)
13058            const char*  SvPVX_const  (SV* sv)
13059            char*        SvPVX_mutable(SV* sv)
13060
13061       "SvREADONLY"
13062           Returns true if the argument is readonly, otherwise returns false.
13063           Exposed to perl code via Internals::SvREADONLY().
13064
13065            U32  SvREADONLY(SV* sv)
13066
13067       "SvREADONLY_off"
13068           Mark an object as not-readonly. Exactly what this mean depends on
13069           the object type. Exposed to perl code via Internals::SvREADONLY().
13070
13071            U32  SvREADONLY_off(SV* sv)
13072
13073       "SvREADONLY_on"
13074           Mark an object as readonly. Exactly what this means depends on the
13075           object type. Exposed to perl code via Internals::SvREADONLY().
13076
13077            U32  SvREADONLY_on(SV* sv)
13078
13079       "sv_ref"
13080           Returns a SV describing what the SV passed in is a reference to.
13081
13082           dst can be a SV to be set to the description or NULL, in which case
13083           a mortal SV is returned.
13084
13085           If ob is true and the SV is blessed, the description is the class
13086           name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
13087
13088            SV*  sv_ref(SV *dst, const SV *const sv, const int ob)
13089
13090       "SvREFCNT"
13091           Returns the value of the object's reference count. Exposed to perl
13092           code via Internals::SvREFCNT().
13093
13094            U32  SvREFCNT(SV* sv)
13095
13096       "SvREFCNT_dec"
13097       "SvREFCNT_dec_NN"
13098           These decrement the reference count of the given SV.
13099
13100           "SvREFCNT_dec_NN" may only be used when "sv" is known to not be
13101           "NULL".
13102
13103            void  SvREFCNT_dec(SV *sv)
13104
13105       "SvREFCNT_inc"
13106       "SvREFCNT_inc_NN"
13107       "SvREFCNT_inc_void"
13108       "SvREFCNT_inc_void_NN"
13109       "SvREFCNT_inc_simple"
13110       "SvREFCNT_inc_simple_NN"
13111       "SvREFCNT_inc_simple_void"
13112       "SvREFCNT_inc_simple_void_NN"
13113           These all increment the reference count of the given SV.  The ones
13114           without "void" in their names return the SV.
13115
13116           "SvREFCNT_inc" is the base operation; the rest are optimizations if
13117           various input constraints are known to be true; hence, all can be
13118           replaced with "SvREFCNT_inc".
13119
13120           "SvREFCNT_inc_NN" can only be used if you know "sv" is not "NULL".
13121           Since we don't have to check the NULLness, it's faster and smaller.
13122
13123           "SvREFCNT_inc_void" can only be used if you don't need the return
13124           value.  The macro doesn't need to return a meaningful value.
13125
13126           "SvREFCNT_inc_void_NN" can only be used if you both don't need the
13127           return value, and you know that "sv" is not "NULL".  The macro
13128           doesn't need to return a meaningful value, or check for NULLness,
13129           so it's smaller and faster.
13130
13131           "SvREFCNT_inc_simple" can only be used with expressions without
13132           side effects.  Since we don't have to store a temporary value, it's
13133           faster.
13134
13135           "SvREFCNT_inc_simple_NN" can only be used with expressions without
13136           side effects and you know "sv" is not "NULL".  Since we don't have
13137           to store a temporary value, nor check for NULLness, it's faster and
13138           smaller.
13139
13140           "SvREFCNT_inc_simple_void" can only be used with expressions
13141           without side effects and you don't need the return value.
13142
13143           "SvREFCNT_inc_simple_void_NN" can only be used with expressions
13144           without side effects, you don't need the return value, and you know
13145           "sv" is not "NULL".
13146
13147            SV *  SvREFCNT_inc               (SV *sv)
13148            SV *  SvREFCNT_inc_NN            (SV *sv)
13149            void  SvREFCNT_inc_void          (SV *sv)
13150            void  SvREFCNT_inc_void_NN       (SV* sv)
13151            SV*   SvREFCNT_inc_simple        (SV* sv)
13152            SV*   SvREFCNT_inc_simple_NN     (SV* sv)
13153            void  SvREFCNT_inc_simple_void   (SV* sv)
13154            void  SvREFCNT_inc_simple_void_NN(SV* sv)
13155
13156       "sv_reftype"
13157           Returns a string describing what the SV is a reference to.
13158
13159           If ob is true and the SV is blessed, the string is the class name,
13160           otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
13161
13162            const char*  sv_reftype(const SV *const sv, const int ob)
13163
13164       "sv_replace"
13165           Make the first argument a copy of the second, then delete the
13166           original.  The target SV physically takes over ownership of the
13167           body of the source SV and inherits its flags; however, the target
13168           keeps any magic it owns, and any magic in the source is discarded.
13169           Note that this is a rather specialist SV copying operation; most of
13170           the time you'll want to use "sv_setsv" or one of its many macro
13171           front-ends.
13172
13173            void  sv_replace(SV *const sv, SV *const nsv)
13174
13175       "sv_report_used"
13176           Dump the contents of all SVs not yet freed (debugging aid).
13177
13178            void  sv_report_used()
13179
13180       "sv_reset"
13181           Underlying implementation for the "reset" Perl function.  Note that
13182           the perl-level function is vaguely deprecated.
13183
13184            void  sv_reset(const char* s, HV *const stash)
13185
13186       "SvROK"
13187           Tests if the SV is an RV.
13188
13189            U32  SvROK(SV* sv)
13190
13191       "SvROK_off"
13192           Unsets the RV status of an SV.
13193
13194            void  SvROK_off(SV* sv)
13195
13196       "SvROK_on"
13197           Tells an SV that it is an RV.
13198
13199            void  SvROK_on(SV* sv)
13200
13201       "SvRV"
13202           Dereferences an RV to return the SV.
13203
13204            SV*  SvRV(SV* sv)
13205
13206       "SvRV_set"
13207           Set the value of the RV pointer in "sv" to val.  See "SvIV_set".
13208
13209            void  SvRV_set(SV* sv, SV* val)
13210
13211       "sv_rvunweaken"
13212           Unweaken a reference: Clear the "SvWEAKREF" flag on this RV; remove
13213           the backreference to this RV from the array of backreferences
13214           associated with the target SV, increment the refcount of the
13215           target.  Silently ignores "undef" and warns on non-weak references.
13216
13217            SV*  sv_rvunweaken(SV *const sv)
13218
13219       "sv_rvweaken"
13220           Weaken a reference: set the "SvWEAKREF" flag on this RV; give the
13221           referred-to SV "PERL_MAGIC_backref" magic if it hasn't already; and
13222           push a back-reference to this RV onto the array of backreferences
13223           associated with that magic.  If the RV is magical, set magic will
13224           be called after the RV is cleared.  Silently ignores "undef" and
13225           warns on already-weak references.
13226
13227            SV*  sv_rvweaken(SV *const sv)
13228
13229       "sv_setiv"
13230       "sv_setiv_mg"
13231           These copy an integer into the given SV, upgrading first if
13232           necessary.
13233
13234           They differ only in that "sv_setiv_mg" handles 'set' magic;
13235           "sv_setiv" does not.
13236
13237            void  sv_setiv   (SV *const sv, const IV num)
13238            void  sv_setiv_mg(SV *const sv, const IV i)
13239
13240       "SvSETMAGIC"
13241           Invokes "mg_set" on an SV if it has 'set' magic.  This is necessary
13242           after modifying a scalar, in case it is a magical variable like $|
13243           or a tied variable (it calls "STORE").  This macro evaluates its
13244           argument more than once.
13245
13246            void  SvSETMAGIC(SV* sv)
13247
13248       "sv_setnv"
13249       "sv_setnv_mg"
13250           These copy a double into the given SV, upgrading first if
13251           necessary.
13252
13253           They differ only in that "sv_setnv_mg" handles 'set' magic;
13254           "sv_setnv" does not.
13255
13256            void  sv_setnv(SV *const sv, const NV num)
13257
13258       "sv_setpv"
13259       "sv_setpv_mg"
13260           These copy a string into an SV.  The string must be terminated with
13261           a "NUL" character, and not contain embeded "NUL"'s.
13262
13263           They differ only in that:
13264
13265           "sv_setpv" does not handle 'set' magic; "sv_setpv_mg" does.
13266
13267            void  sv_setpv(SV *const sv, const char *const ptr)
13268
13269       "sv_setpvf"
13270       "sv_setpvf_nocontext"
13271       "sv_setpvf_mg"
13272       "sv_setpvf_mg_nocontext"
13273           These work like "sv_catpvf" but copy the text into the SV instead
13274           of appending it.
13275
13276           The differences between these are:
13277
13278           "sv_setpvf" and "sv_setpvf_nocontext" do not handle 'set' magic;
13279           "sv_setpvf_mg" and "sv_setpvf_mg_nocontext" do.
13280
13281           "sv_setpvf_nocontext" and "sv_setpvf_mg_nocontext" do not take a
13282           thread context ("aTHX") parameter, so are used in situations where
13283           the caller doesn't already have the thread context.
13284
13285           NOTE: "sv_setpvf" must be explicitly called as "Perl_sv_setpvf"
13286           with an "aTHX_" parameter.
13287
13288           NOTE: "sv_setpvf_mg" must be explicitly called as
13289           "Perl_sv_setpvf_mg" with an "aTHX_" parameter.
13290
13291            void  Perl_sv_setpvf        (pTHX_ SV *const sv,
13292                                         const char *const pat, ...)
13293            void  sv_setpvf_nocontext   (SV *const sv, const char *const pat,
13294                                         ...)
13295            void  Perl_sv_setpvf_mg     (pTHX_ SV *const sv,
13296                                         const char *const pat, ...)
13297            void  sv_setpvf_mg_nocontext(SV *const sv, const char *const pat,
13298                                         ...)
13299
13300       "sv_setpviv"
13301       "sv_setpviv_mg"
13302           "DEPRECATED!"  It is planned to remove "sv_setpviv" from a future
13303           release of Perl.  Do not use it for new code; remove it from
13304           existing code.
13305
13306           "DEPRECATED!"  It is planned to remove "sv_setpviv_mg" from a
13307           future release of Perl.  Do not use it for new code; remove it from
13308           existing code.
13309
13310           These copy an integer into the given SV, also updating its string
13311           value.
13312
13313           They differ only in that "sv_setpviv_mg" performs 'set' magic;
13314           "sv_setpviv" skips any magic.
13315
13316            void  sv_setpviv   (SV *const sv, const IV num)
13317            void  sv_setpviv_mg(SV *const sv, const IV iv)
13318
13319       "sv_setpvn"
13320       "sv_setpvn_mg"
13321           These copy a string (possibly containing embedded "NUL" characters)
13322           into an SV.  The "len" parameter indicates the number of bytes to
13323           be copied.  If the "ptr" argument is NULL the SV will become
13324           undefined.
13325
13326           The UTF-8 flag is not changed by these functions.  A terminating
13327           NUL byte is guaranteed.
13328
13329           They differ only in that:
13330
13331           "sv_setpvn" does not handle 'set' magic; "sv_setpvn_mg" does.
13332
13333            void  sv_setpvn(SV *const sv, const char *const ptr,
13334                            const STRLEN len)
13335
13336       "sv_setpvs"
13337           Like "sv_setpvn", but takes a literal string instead of a
13338           string/length pair.
13339
13340            void  sv_setpvs(SV* sv, "literal string")
13341
13342       "sv_setpvs_mg"
13343           Like "sv_setpvn_mg", but takes a literal string instead of a
13344           string/length pair.
13345
13346            void  sv_setpvs_mg(SV* sv, "literal string")
13347
13348       "sv_setpv_bufsize"
13349           Sets the SV to be a string of cur bytes length, with at least len
13350           bytes available. Ensures that there is a null byte at SvEND.
13351           Returns a char * pointer to the SvPV buffer.
13352
13353            char  *  sv_setpv_bufsize(SV *const sv, const STRLEN cur,
13354                                      const STRLEN len)
13355
13356       "sv_setref_iv"
13357           Copies an integer into a new SV, optionally blessing the SV.  The
13358           "rv" argument will be upgraded to an RV.  That RV will be modified
13359           to point to the new SV.  The "classname" argument indicates the
13360           package for the blessing.  Set "classname" to "NULL" to avoid the
13361           blessing.  The new SV will have a reference count of 1, and the RV
13362           will be returned.
13363
13364            SV*  sv_setref_iv(SV *const rv, const char *const classname,
13365                              const IV iv)
13366
13367       "sv_setref_nv"
13368           Copies a double into a new SV, optionally blessing the SV.  The
13369           "rv" argument will be upgraded to an RV.  That RV will be modified
13370           to point to the new SV.  The "classname" argument indicates the
13371           package for the blessing.  Set "classname" to "NULL" to avoid the
13372           blessing.  The new SV will have a reference count of 1, and the RV
13373           will be returned.
13374
13375            SV*  sv_setref_nv(SV *const rv, const char *const classname,
13376                              const NV nv)
13377
13378       "sv_setref_pv"
13379           Copies a pointer into a new SV, optionally blessing the SV.  The
13380           "rv" argument will be upgraded to an RV.  That RV will be modified
13381           to point to the new SV.  If the "pv" argument is "NULL", then
13382           "PL_sv_undef" will be placed into the SV.  The "classname" argument
13383           indicates the package for the blessing.  Set "classname" to "NULL"
13384           to avoid the blessing.  The new SV will have a reference count of
13385           1, and the RV will be returned.
13386
13387           Do not use with other Perl types such as HV, AV, SV, CV, because
13388           those objects will become corrupted by the pointer copy process.
13389
13390           Note that "sv_setref_pvn" copies the string while this copies the
13391           pointer.
13392
13393            SV*  sv_setref_pv(SV *const rv, const char *const classname,
13394                              void *const pv)
13395
13396       "sv_setref_pvn"
13397           Copies a string into a new SV, optionally blessing the SV.  The
13398           length of the string must be specified with "n".  The "rv" argument
13399           will be upgraded to an RV.  That RV will be modified to point to
13400           the new SV.  The "classname" argument indicates the package for the
13401           blessing.  Set "classname" to "NULL" to avoid the blessing.  The
13402           new SV will have a reference count of 1, and the RV will be
13403           returned.
13404
13405           Note that "sv_setref_pv" copies the pointer while this copies the
13406           string.
13407
13408            SV*  sv_setref_pvn(SV *const rv, const char *const classname,
13409                               const char *const pv, const STRLEN n)
13410
13411       "sv_setref_pvs"
13412           Like "sv_setref_pvn", but takes a literal string instead of a
13413           string/length pair.
13414
13415            SV *  sv_setref_pvs(SV *const rv, const char *const classname,
13416                                "literal string")
13417
13418       "sv_setref_uv"
13419           Copies an unsigned integer into a new SV, optionally blessing the
13420           SV.  The "rv" argument will be upgraded to an RV.  That RV will be
13421           modified to point to the new SV.  The "classname" argument
13422           indicates the package for the blessing.  Set "classname" to "NULL"
13423           to avoid the blessing.  The new SV will have a reference count of
13424           1, and the RV will be returned.
13425
13426            SV*  sv_setref_uv(SV *const rv, const char *const classname,
13427                              const UV uv)
13428
13429       "SvSetSV"
13430       "SvSetMagicSV"
13431       "SvSetSV_nosteal"
13432       "SvSetMagicSV_nosteal"
13433           if "dsv" is the same as "ssv", these do nothing.  Otherwise they
13434           all call some form of "sv_setsv".  They may evaluate their
13435           arguments more than once.
13436
13437           The only differences are:
13438
13439           "SvSetMagicSV" and "SvSetMagicSV_nosteal" perform any required
13440           'set' magic afterwards on the destination SV; "SvSetSV" and
13441           "SvSetSV_nosteal" do not.
13442
13443           "SvSetSV_nosteal" "SvSetMagicSV_nosteal" call a non-destructive
13444           version of "sv_setsv".
13445
13446            void  SvSetSV(SV* dsv, SV* ssv)
13447
13448       "sv_setsv"
13449       "sv_setsv_flags"
13450       "sv_setsv_mg"
13451       "sv_setsv_nomg"
13452           These copy the contents of the source SV "ssv" into the destination
13453           SV "dsv".  "ssv" may be destroyed if it is mortal, so don't use
13454           these functions if the source SV needs to be reused.  Loosely
13455           speaking, they perform a copy-by-value, obliterating any previous
13456           content of the destination.
13457
13458           They differ only in that:
13459
13460           "sv_setsv" calls 'get' magic on "ssv", but skips 'set' magic on
13461           "dsv".
13462
13463           "sv_setsv_mg" calls both 'get' magic on "ssv" and 'set' magic on
13464           "dsv".
13465
13466           "sv_setsv_nomg" skips all magic.
13467
13468           "sv_setsv_flags" has a "flags" parameter which you can use to
13469           specify any combination of magic handling, and also you can specify
13470           "SV_NOSTEAL" so that the buffers of temps will not be stolen.
13471
13472           You probably want to instead use one of the assortment of wrappers,
13473           such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
13474           "SvSetMagicSV_nosteal".
13475
13476           "sv_setsv_flags" is the primary function for copying scalars, and
13477           most other copy-ish functions and macros use it underneath.
13478
13479            void  sv_setsv      (SV *dsv, SV *ssv)
13480            void  sv_setsv_flags(SV *dsv, SV *ssv, const I32 flags)
13481            void  sv_setsv_mg   (SV *const dsv, SV *const ssv)
13482            void  sv_setsv_nomg (SV *dsv, SV *ssv)
13483
13484       "sv_setuv"
13485       "sv_setuv_mg"
13486           These copy an unsigned integer into the given SV, upgrading first
13487           if necessary.
13488
13489           They differ only in that "sv_setuv_mg" handles 'set' magic;
13490           "sv_setuv" does not.
13491
13492            void  sv_setuv   (SV *const sv, const UV num)
13493            void  sv_setuv_mg(SV *const sv, const UV u)
13494
13495       "sv_set_undef"
13496           Equivalent to "sv_setsv(sv, &PL_sv_undef)", but more efficient.
13497           Doesn't handle set magic.
13498
13499           The perl equivalent is "$sv = undef;". Note that it doesn't free
13500           any string buffer, unlike "undef $sv".
13501
13502           Introduced in perl 5.25.12.
13503
13504            void  sv_set_undef(SV *sv)
13505
13506       "SvSHARE"
13507           Arranges for "sv" to be shared between threads if a suitable module
13508           has been loaded.
13509
13510            void  SvSHARE(SV* sv)
13511
13512       "SvSHARED_HASH"
13513           Returns the hash for "sv" created by "newSVpvn_share".
13514
13515            struct hek*  SvSHARED_HASH(SV * sv)
13516
13517       "SvSTASH"
13518           Returns the stash of the SV.
13519
13520            HV*  SvSTASH(SV* sv)
13521
13522       "SvSTASH_set"
13523           Set the value of the STASH pointer in "sv" to val.  See "SvIV_set".
13524
13525            void  SvSTASH_set(SV* sv, HV* val)
13526
13527       "SvTAINT"
13528           Taints an SV if tainting is enabled, and if some input to the
13529           current expression is tainted--usually a variable, but possibly
13530           also implicit inputs such as locale settings.  "SvTAINT" propagates
13531           that taintedness to the outputs of an expression in a pessimistic
13532           fashion; i.e., without paying attention to precisely which outputs
13533           are influenced by which inputs.
13534
13535            void  SvTAINT(SV* sv)
13536
13537       "SvTAINTED"
13538           Checks to see if an SV is tainted.  Returns TRUE if it is, FALSE if
13539           not.
13540
13541            bool  SvTAINTED(SV* sv)
13542
13543       "SvTAINTED_off"
13544           Untaints an SV.  Be very careful with this routine, as it short-
13545           circuits some of Perl's fundamental security features.  XS module
13546           authors should not use this function unless they fully understand
13547           all the implications of unconditionally untainting the value.
13548           Untainting should be done in the standard perl fashion, via a
13549           carefully crafted regexp, rather than directly untainting
13550           variables.
13551
13552            void  SvTAINTED_off(SV* sv)
13553
13554       "SvTAINTED_on"
13555           Marks an SV as tainted if tainting is enabled.
13556
13557            void  SvTAINTED_on(SV* sv)
13558
13559       "SvTRUE"
13560       "SvTRUEx"
13561       "SvTRUE_nomg"
13562       "SvTRUE_NN"
13563       "SvTRUE_nomg_NN"
13564           These return a boolean indicating whether Perl would evaluate the
13565           SV as true or false.  See "SvOK" for a defined/undefined test.
13566
13567           As of Perl 5.32, all are guaranteed to evaluate "sv" only once.
13568           Prior to that release, only "SvTRUEx" guaranteed single evaluation;
13569           now "SvTRUEx" is identical to "SvTRUE".
13570
13571           "SvTRUE_nomg" and "TRUE_nomg_NN" do not perform 'get' magic; the
13572           others do unless the scalar is already "SvPOK", "SvIOK", or "SvNOK"
13573           (the public, not the private flags).
13574
13575           "SvTRUE_NN" is like "SvTRUE", but "sv" is assumed to be non-null
13576           (NN).  If there is a possibility that it is NULL, use plain
13577           "SvTRUE".
13578
13579           "SvTRUE_nomg_NN" is like "SvTRUE_nomg", but "sv" is assumed to be
13580           non-null (NN).  If there is a possibility that it is NULL, use
13581           plain "SvTRUE_nomg".
13582
13583            bool  SvTRUE(SV *sv)
13584
13585       "SvTYPE"
13586           Returns the type of the SV.  See "svtype".
13587
13588            svtype  SvTYPE(SV* sv)
13589
13590       "SvUNLOCK"
13591           Releases a mutual exclusion lock on "sv" if a suitable module has
13592           been loaded.
13593
13594            void  SvUNLOCK(SV* sv)
13595
13596       "sv_unmagic"
13597           Removes all magic of type "type" from an SV.
13598
13599            int  sv_unmagic(SV *const sv, const int type)
13600
13601       "sv_unmagicext"
13602           Removes all magic of type "type" with the specified "vtbl" from an
13603           SV.
13604
13605            int  sv_unmagicext(SV *const sv, const int type, MGVTBL *vtbl)
13606
13607       "sv_unref"
13608           Unsets the RV status of the SV, and decrements the reference count
13609           of whatever was being referenced by the RV.  This can almost be
13610           thought of as a reversal of "newSVrv".  This is "sv_unref_flags"
13611           with the "flag" being zero.  See "SvROK_off".
13612
13613            void  sv_unref(SV* sv)
13614
13615       "sv_unref_flags"
13616           Unsets the RV status of the SV, and decrements the reference count
13617           of whatever was being referenced by the RV.  This can almost be
13618           thought of as a reversal of "newSVrv".  The "cflags" argument can
13619           contain "SV_IMMEDIATE_UNREF" to force the reference count to be
13620           decremented (otherwise the decrementing is conditional on the
13621           reference count being different from one or the reference being a
13622           readonly SV).  See "SvROK_off".
13623
13624            void  sv_unref_flags(SV *const ref, const U32 flags)
13625
13626       "SvUOK"
13627           Returns a boolean indicating whether the SV contains an integer
13628           that must be interpreted as unsigned.  A non-negative integer whose
13629           value is within the range of both an IV and a UV may be flagged as
13630           either "SvUOK" or "SvIOK".
13631
13632            bool  SvUOK(SV* sv)
13633
13634       "SvUPGRADE"
13635           Used to upgrade an SV to a more complex form.  Uses "sv_upgrade" to
13636           perform the upgrade if necessary.  See "svtype".
13637
13638            void  SvUPGRADE(SV* sv, svtype type)
13639
13640       "sv_upgrade"
13641           Upgrade an SV to a more complex form.  Generally adds a new body
13642           type to the SV, then copies across as much information as possible
13643           from the old body.  It croaks if the SV is already in a more
13644           complex form than requested.  You generally want to use the
13645           "SvUPGRADE" macro wrapper, which checks the type before calling
13646           "sv_upgrade", and hence does not croak.  See also "svtype".
13647
13648            void  sv_upgrade(SV *const sv, svtype new_type)
13649
13650       "sv_usepvn"
13651           Tells an SV to use "ptr" to find its string value.  Implemented by
13652           calling "sv_usepvn_flags" with "flags" of 0, hence does not handle
13653           'set' magic.  See "sv_usepvn_flags".
13654
13655            void  sv_usepvn(SV* sv, char* ptr, STRLEN len)
13656
13657       "sv_usepvn_flags"
13658           Tells an SV to use "ptr" to find its string value.  Normally the
13659           string is stored inside the SV, but sv_usepvn allows the SV to use
13660           an outside string.  "ptr" should point to memory that was allocated
13661           by "Newx".  It must be the start of a "Newx"-ed block of memory,
13662           and not a pointer to the middle of it (beware of "OOK" and copy-on-
13663           write), and not be from a non-"Newx" memory allocator like
13664           "malloc".  The string length, "len", must be supplied.  By default
13665           this function will "Renew" (i.e. realloc, move) the memory pointed
13666           to by "ptr", so that pointer should not be freed or used by the
13667           programmer after giving it to "sv_usepvn", and neither should any
13668           pointers from "behind" that pointer (e.g. ptr + 1) be used.
13669
13670           If "flags & SV_SMAGIC" is true, will call "SvSETMAGIC".  If
13671           "flags & SV_HAS_TRAILING_NUL" is true, then "ptr[len]" must be
13672           "NUL", and the realloc will be skipped (i.e. the buffer is actually
13673           at least 1 byte longer than "len", and already meets the
13674           requirements for storing in "SvPVX").
13675
13676            void  sv_usepvn_flags(SV *const sv, char* ptr, const STRLEN len,
13677                                  const U32 flags)
13678
13679       "sv_usepvn_mg"
13680           Like "sv_usepvn", but also handles 'set' magic.
13681
13682            void  sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
13683
13684       "SvUTF8"
13685           Returns a U32 value indicating the UTF-8 status of an SV.  If
13686           things are set-up properly, this indicates whether or not the SV
13687           contains UTF-8 encoded data.  You should use this after a call to
13688           "SvPV" or one of its variants, in case any call to string
13689           overloading updates the internal flag.
13690
13691           If you want to take into account the bytes pragma, use "DO_UTF8"
13692           instead.
13693
13694            U32  SvUTF8(SV* sv)
13695
13696       "sv_utf8_decode"
13697           If the PV of the SV is an octet sequence in Perl's extended UTF-8
13698           and contains a multiple-byte character, the "SvUTF8" flag is turned
13699           on so that it looks like a character.  If the PV contains only
13700           single-byte characters, the "SvUTF8" flag stays off.  Scans PV for
13701           validity and returns FALSE if the PV is invalid UTF-8.
13702
13703            bool  sv_utf8_decode(SV *const sv)
13704
13705       "sv_utf8_downgrade"
13706       "sv_utf8_downgrade_flags"
13707       "sv_utf8_downgrade_nomg"
13708           These attempt to convert the PV of an SV from characters to bytes.
13709           If the PV contains a character that cannot fit in a byte, this
13710           conversion will fail; in this case, "FALSE" is returned if
13711           "fail_ok" is true; otherwise they croak.
13712
13713           They are not a general purpose Unicode to byte encoding interface:
13714           use the "Encode" extension for that.
13715
13716           They differ only in that:
13717
13718           "sv_utf8_downgrade" processes 'get' magic on "sv".
13719
13720           "sv_utf8_downgrade_nomg" does not.
13721
13722           "sv_utf8_downgrade_flags" has an additional "flags" parameter in
13723           which you can specify "SV_GMAGIC" to process 'get' magic, or leave
13724           it cleared to not proccess 'get' magic.
13725
13726            bool  sv_utf8_downgrade      (SV *const sv, const bool fail_ok)
13727            bool  sv_utf8_downgrade_flags(SV *const sv, const bool fail_ok,
13728                                          const U32 flags)
13729            bool  sv_utf8_downgrade_nomg (SV *const sv, const bool fail_ok)
13730
13731       "sv_utf8_encode"
13732           Converts the PV of an SV to UTF-8, but then turns the "SvUTF8" flag
13733           off so that it looks like octets again.
13734
13735            void  sv_utf8_encode(SV *const sv)
13736
13737       "sv_utf8_upgrade"
13738       "sv_utf8_upgrade_nomg"
13739       "sv_utf8_upgrade_flags"
13740       "sv_utf8_upgrade_flags_grow"
13741           These convert the PV of an SV to its UTF-8-encoded form.  The SV is
13742           forced to string form if it is not already.  They always set the
13743           "SvUTF8" flag to avoid future validity checks even if the whole
13744           string is the same in UTF-8 as not.  They return the number of
13745           bytes in the converted string
13746
13747           The forms differ in just two ways.  The main difference is whether
13748           or not they perform 'get magic' on "sv".  "sv_utf8_upgrade_nomg"
13749           skips 'get magic'; "sv_utf8_upgrade" performs it; and
13750           "sv_utf8_upgrade_flags" and "sv_utf8_upgrade_flags_grow" either
13751           perform it (if the "SV_GMAGIC" bit is set in "flags") or don't (if
13752           that bit is cleared).
13753
13754           The other difference is that "sv_utf8_upgrade_flags_grow" has an
13755           additional parameter, "extra", which allows the caller to specify
13756           an amount of space to be reserved as spare beyond what is needed
13757           for the actual conversion.  This is used when the caller knows it
13758           will soon be needing yet more space, and it is more efficient to
13759           request space from the system in a single call.  This form is
13760           otherwise identical to "sv_utf8_upgrade_flags".
13761
13762           These are not a general purpose byte encoding to Unicode interface:
13763           use the Encode extension for that.
13764
13765           The "SV_FORCE_UTF8_UPGRADE" flag is now ignored.
13766
13767            STRLEN  sv_utf8_upgrade           (SV *sv)
13768            STRLEN  sv_utf8_upgrade_nomg      (SV *sv)
13769            STRLEN  sv_utf8_upgrade_flags     (SV *const sv, const I32 flags)
13770            STRLEN  sv_utf8_upgrade_flags_grow(SV *const sv, const I32 flags,
13771                                               STRLEN extra)
13772
13773       "SvUTF8_off"
13774           Unsets the UTF-8 status of an SV (the data is not changed, just the
13775           flag).  Do not use frivolously.
13776
13777            void  SvUTF8_off(SV *sv)
13778
13779       "SvUTF8_on"
13780           Turn on the UTF-8 status of an SV (the data is not changed, just
13781           the flag).  Do not use frivolously.
13782
13783            void  SvUTF8_on(SV *sv)
13784
13785       "SvUV"
13786       "SvUVx"
13787       "SvUV_nomg"
13788           These coerce the given SV to UV and return it.  The returned value
13789           in many circumstances will get stored in "sv"'s UV slot, but not in
13790           all cases.  (Use "sv_setuv" to make sure it does).
13791
13792           "SvUVx" is different from the others in that it is guaranteed to
13793           evaluate "sv" exactly once; the others may evaluate it multiple
13794           times.  Only use this form if "sv" is an expression with side
13795           effects, otherwise use the more efficient "SvUV".
13796
13797           "SvUV_nomg" is the same as "SvUV", but does not perform 'get'
13798           magic.
13799
13800            UV  SvUV(SV* sv)
13801
13802       "SvUV_set"
13803           Set the value of the UV pointer in "sv" to val.  See "SvIV_set".
13804
13805            void  SvUV_set(SV* sv, UV val)
13806
13807       "SvUVX"
13808           Returns the raw value in the SV's UV slot, without checks or
13809           conversions.  Only use when you are sure "SvIOK" is true.  See also
13810           "SvUV".
13811
13812            UV  SvUVX(SV* sv)
13813
13814       "SvUVXx"
13815           "DEPRECATED!"  It is planned to remove "SvUVXx" from a future
13816           release of Perl.  Do not use it for new code; remove it from
13817           existing code.
13818
13819           This is an unnecessary synonym for "SvUVX"
13820
13821            UV  SvUVXx(SV* sv)
13822
13823       "sv_vcatpvf"
13824       "sv_vcatpvf_mg"
13825           These process their arguments like "sv_vcatpvfn" called with a non-
13826           null C-style variable argument list, and append the formatted
13827           output to "sv".
13828
13829           They differ only in that "sv_vcatpvf_mg" performs 'set' magic;
13830           "sv_vcatpvf" skips 'set' magic.
13831
13832           Both perform 'get' magic.
13833
13834           They are usually accessed via their frontends "sv_catpvf" and
13835           "sv_catpvf_mg".
13836
13837            void  sv_vcatpvf(SV *const sv, const char *const pat,
13838                             va_list *const args)
13839
13840       "sv_vcatpvfn"
13841       "sv_vcatpvfn_flags"
13842           These process their arguments like vsprintf(3) and append the
13843           formatted output to an SV.  They use an array of SVs if the C-style
13844           variable argument list is missing ("NULL"). Argument reordering
13845           (using format specifiers like "%2$d" or "%*2$d") is supported only
13846           when using an array of SVs; using a C-style "va_list" argument list
13847           with a format string that uses argument reordering will yield an
13848           exception.
13849
13850           When running with taint checks enabled, they indicate via
13851           "maybe_tainted" if results are untrustworthy (often due to the use
13852           of locales).
13853
13854           They assume that "pat" has the same utf8-ness as "sv".  It's the
13855           caller's responsibility to ensure that this is so.
13856
13857           They differ in that "sv_vcatpvfn_flags" has a "flags" parameter in
13858           which you can set or clear the "SV_GMAGIC" and/or SV_SMAGIC flags,
13859           to specify which magic to handle or not handle; whereas plain
13860           "sv_vcatpvfn" always specifies both 'get' and 'set' magic.
13861
13862           They are usually used via one of the frontends "sv_vcatpvf" and
13863           "sv_vcatpvf_mg".
13864
13865            void  sv_vcatpvfn      (SV *const sv, const char *const pat,
13866                                    const STRLEN patlen, va_list *const args,
13867                                    SV **const svargs, const Size_t sv_count,
13868                                    bool *const maybe_tainted)
13869            void  sv_vcatpvfn_flags(SV *const sv, const char *const pat,
13870                                    const STRLEN patlen, va_list *const args,
13871                                    SV **const svargs, const Size_t sv_count,
13872                                    bool *const maybe_tainted,
13873                                    const U32 flags)
13874
13875       "SvVOK"
13876           Returns a boolean indicating whether the SV contains a v-string.
13877
13878            bool  SvVOK(SV* sv)
13879
13880       "sv_vsetpvf"
13881       "sv_vsetpvf_mg"
13882           These work like "sv_vcatpvf" but copy the text into the SV instead
13883           of appending it.
13884
13885           They differ only in that "sv_vsetpvf_mg" performs 'set' magic;
13886           "sv_vsetpvf" skips all magic.
13887
13888           They are usually used via their frontends, "sv_setpvf" and
13889           "sv_setpvf_mg".
13890
13891            void  sv_vsetpvf(SV *const sv, const char *const pat,
13892                             va_list *const args)
13893
13894       "sv_vsetpvfn"
13895           Works like "sv_vcatpvfn" but copies the text into the SV instead of
13896           appending it.
13897
13898           Usually used via one of its frontends "sv_vsetpvf" and
13899           "sv_vsetpvf_mg".
13900
13901            void  sv_vsetpvfn(SV *const sv, const char *const pat,
13902                              const STRLEN patlen, va_list *const args,
13903                              SV **const svargs, const Size_t sv_count,
13904                              bool *const maybe_tainted)
13905
13906       "SvVSTRING_mg"
13907           Returns the vstring magic, or NULL if none
13908
13909            MAGIC*  SvVSTRING_mg(SV * sv)
13910
13911       "vnewSVpvf"
13912           Like "newSVpvf" but but the arguments are an encapsulated argument
13913           list.
13914
13915            SV*  vnewSVpvf(const char *const pat, va_list *const args)
13916

Time

13918       "ASCTIME_R_PROTO"
13919           This symbol encodes the prototype of "asctime_r".  It is zero if
13920           "d_asctime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
13921           macros of reentr.h if "d_asctime_r" is defined.
13922
13923       "CTIME_R_PROTO"
13924           This symbol encodes the prototype of "ctime_r".  It is zero if
13925           "d_ctime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC" macros
13926           of reentr.h if "d_ctime_r" is defined.
13927
13928       "GMTIME_MAX"
13929           This symbol contains the maximum value for the "time_t" offset that
13930           the system function gmtime () accepts, and defaults to 0
13931
13932       "GMTIME_MIN"
13933           This symbol contains the minimum value for the "time_t" offset that
13934           the system function gmtime () accepts, and defaults to 0
13935
13936       "GMTIME_R_PROTO"
13937           This symbol encodes the prototype of "gmtime_r".  It is zero if
13938           "d_gmtime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
13939           macros of reentr.h if "d_gmtime_r" is defined.
13940
13941       "HAS_ASCTIME64"
13942           This symbol, if defined, indicates that the "asctime64" () routine
13943           is available to do the 64bit variant of asctime ()
13944
13945       "HAS_ASCTIME_R"
13946           This symbol, if defined, indicates that the "asctime_r" routine is
13947           available to asctime re-entrantly.
13948
13949       "HAS_CTIME64"
13950           This symbol, if defined, indicates that the "ctime64" () routine is
13951           available to do the 64bit variant of ctime ()
13952
13953       "HAS_CTIME_R"
13954           This symbol, if defined, indicates that the "ctime_r" routine is
13955           available to ctime re-entrantly.
13956
13957       "HAS_DIFFTIME"
13958           This symbol, if defined, indicates that the "difftime" routine is
13959           available.
13960
13961       "HAS_DIFFTIME64"
13962           This symbol, if defined, indicates that the "difftime64" () routine
13963           is available to do the 64bit variant of difftime ()
13964
13965       "HAS_FUTIMES"
13966           This symbol, if defined, indicates that the "futimes" routine is
13967           available to change file descriptor time stamps with "struct
13968           timevals".
13969
13970       "HAS_GETITIMER"
13971           This symbol, if defined, indicates that the "getitimer" routine is
13972           available to return interval timers.
13973
13974       "HAS_GETTIMEOFDAY"
13975           This symbol, if defined, indicates that the "gettimeofday()" system
13976           call is available for a sub-second accuracy clock. Usually, the
13977           file sys/resource.h needs to be included (see "I_SYS_RESOURCE").
13978           The type "Timeval" should be used to refer to ""struct timeval"".
13979
13980       "HAS_GMTIME64"
13981           This symbol, if defined, indicates that the "gmtime64" () routine
13982           is available to do the 64bit variant of gmtime ()
13983
13984       "HAS_GMTIME_R"
13985           This symbol, if defined, indicates that the "gmtime_r" routine is
13986           available to gmtime re-entrantly.
13987
13988       "HAS_LOCALTIME64"
13989           This symbol, if defined, indicates that the "localtime64" ()
13990           routine is available to do the 64bit variant of localtime ()
13991
13992       "HAS_LOCALTIME_R"
13993           This symbol, if defined, indicates that the "localtime_r" routine
13994           is available to localtime re-entrantly.
13995
13996       "HAS_MKTIME"
13997           This symbol, if defined, indicates that the "mktime" routine is
13998           available.
13999
14000       "HAS_MKTIME64"
14001           This symbol, if defined, indicates that the "mktime64" () routine
14002           is available to do the 64bit variant of mktime ()
14003
14004       "HAS_NANOSLEEP"
14005           This symbol, if defined, indicates that the "nanosleep" system call
14006           is available to sleep with 1E-9 sec accuracy.
14007
14008       "HAS_SETITIMER"
14009           This symbol, if defined, indicates that the "setitimer" routine is
14010           available to set interval timers.
14011
14012       "HAS_STRFTIME"
14013           This symbol, if defined, indicates that the "strftime" routine is
14014           available to do time formatting.
14015
14016       "HAS_TIME"
14017           This symbol, if defined, indicates that the "time()" routine
14018           exists.
14019
14020       "HAS_TIMEGM"
14021           This symbol, if defined, indicates that the "timegm" routine is
14022           available to do the opposite of gmtime ()
14023
14024       "HAS_TIMES"
14025           This symbol, if defined, indicates that the "times()" routine
14026           exists.  Note that this became obsolete on some systems ("SUNOS"),
14027           which now use "getrusage()". It may be necessary to include
14028           sys/times.h.
14029
14030       "HAS_TM_TM_GMTOFF"
14031           This symbol, if defined, indicates to the C program that the
14032           "struct tm" has a "tm_gmtoff" field.
14033
14034       "HAS_TM_TM_ZONE"
14035           This symbol, if defined, indicates to the C program that the
14036           "struct tm" has a "tm_zone" field.
14037
14038       "HAS_TZNAME"
14039           This symbol, if defined, indicates that the "tzname[]" array is
14040           available to access timezone names.
14041
14042       "HAS_USLEEP"
14043           This symbol, if defined, indicates that the "usleep" routine is
14044           available to let the process sleep on a sub-second accuracy.
14045
14046       "HAS_USLEEP_PROTO"
14047           This symbol, if defined, indicates that the system provides a
14048           prototype for the "usleep()" function.  Otherwise, it is up to the
14049           program to supply one.  A good guess is
14050
14051            extern int usleep(useconds_t);
14052
14053       "I_TIME"
14054           This symbol is always defined, and indicates to the C program that
14055           it should include time.h.
14056
14057            #ifdef I_TIME
14058                #include <time.h>
14059            #endif
14060
14061       "I_UTIME"
14062           This symbol, if defined, indicates to the C program that it should
14063           include utime.h.
14064
14065            #ifdef I_UTIME
14066                #include <utime.h>
14067            #endif
14068
14069       "LOCALTIME_MAX"
14070           This symbol contains the maximum value for the "time_t" offset that
14071           the system function localtime () accepts, and defaults to 0
14072
14073       "LOCALTIME_MIN"
14074           This symbol contains the minimum value for the "time_t" offset that
14075           the system function localtime () accepts, and defaults to 0
14076
14077       "LOCALTIME_R_NEEDS_TZSET"
14078           Many libc's "localtime_r" implementations do not call tzset, making
14079           them differ from "localtime()", and making timezone changes using
14080           $"ENV"{TZ} without explicitly calling tzset impossible. This symbol
14081           makes us call tzset before "localtime_r"
14082
14083       "LOCALTIME_R_PROTO"
14084           This symbol encodes the prototype of "localtime_r".  It is zero if
14085           "d_localtime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
14086           macros of reentr.h if "d_localtime_r" is defined.
14087
14088       "L_R_TZSET"
14089           If "localtime_r()" needs tzset, it is defined in this define
14090
14091       "mini_mktime"
14092           normalise "struct tm" values without the localtime() semantics (and
14093           overhead) of mktime().
14094
14095            void  mini_mktime(struct tm *ptm)
14096
14097       "my_strftime"
14098           strftime(), but with a different API so that the return value is a
14099           pointer to the formatted result (which MUST be arranged to be FREED
14100           BY THE CALLER).  This allows this function to increase the buffer
14101           size as needed, so that the caller doesn't have to worry about
14102           that.
14103
14104           Note that yday and wday effectively are ignored by this function,
14105           as mini_mktime() overwrites them
14106
14107           Also note that this is always executed in the underlying locale of
14108           the program, giving localized results.
14109
14110           NOTE: "my_strftime" must be explicitly called as "Perl_my_strftime"
14111           with an "aTHX_" parameter.
14112
14113            char *  Perl_my_strftime(pTHX_ const char *fmt, int sec, int min,
14114                                     int hour, int mday, int mon, int year,
14115                                     int wday, int yday, int isdst)
14116

Typedef names

14118       "DB_Hash_t"
14119           This symbol contains the type of the prefix structure element in
14120           the db.h header file.  In older versions of DB, it was int, while
14121           in newer ones it is "size_t".
14122
14123       "DB_Prefix_t"
14124           This symbol contains the type of the prefix structure element in
14125           the db.h header file.  In older versions of DB, it was int, while
14126           in newer ones it is "u_int32_t".
14127
14128       "Direntry_t"
14129           This symbol is set to '"struct direct"' or '"struct dirent"'
14130           depending on whether dirent is available or not. You should use
14131           this pseudo type to portably declare your directory entries.
14132
14133       "Fpos_t"
14134           This symbol holds the type used to declare file positions in libc.
14135           It can be "fpos_t", long, uint, etc... It may be necessary to
14136           include sys/types.h to get any typedef'ed information.
14137
14138       "Free_t"
14139           This variable contains the return type of "free()".  It is usually
14140           void, but occasionally int.
14141
14142       "Gid_t"
14143           This symbol holds the return type of "getgid()" and the type of
14144           argument to "setrgid()" and related functions.  Typically, it is
14145           the type of group ids in the kernel. It can be int, ushort,
14146           "gid_t", etc... It may be necessary to include sys/types.h to get
14147           any typedef'ed information.
14148
14149       "Gid_t_f"
14150           This symbol defines the format string used for printing a "Gid_t".
14151
14152       "Gid_t_sign"
14153           This symbol holds the signedness of a "Gid_t".  1 for unsigned, -1
14154           for signed.
14155
14156       "Gid_t_size"
14157           This symbol holds the size of a "Gid_t" in bytes.
14158
14159       "Groups_t"
14160           This symbol holds the type used for the second argument to
14161           "getgroups()" and "setgroups()".  Usually, this is the same as
14162           gidtype ("gid_t") , but sometimes it isn't.  It can be int, ushort,
14163           "gid_t", etc...  It may be necessary to include sys/types.h to get
14164           any typedef'ed information.  This is only required if you have
14165           "getgroups()" or "setgroups()"..
14166
14167       "Malloc_t"
14168           This symbol is the type of pointer returned by malloc and realloc.
14169
14170       "Mmap_t"
14171           This symbol holds the return type of the "mmap()" system call (and
14172           simultaneously the type of the first argument).  Usually set to
14173           'void *' or '"caddr_t"'.
14174
14175       "Mode_t"
14176           This symbol holds the type used to declare file modes for systems
14177           calls.  It is usually "mode_t", but may be int or unsigned short.
14178           It may be necessary to include sys/types.h to get any typedef'ed
14179           information.
14180
14181       "Netdb_hlen_t"
14182           This symbol holds the type used for the 2nd argument to
14183           "gethostbyaddr()".
14184
14185       "Netdb_host_t"
14186           This symbol holds the type used for the 1st argument to
14187           "gethostbyaddr()".
14188
14189       "Netdb_name_t"
14190           This symbol holds the type used for the argument to
14191           "gethostbyname()".
14192
14193       "Netdb_net_t"
14194           This symbol holds the type used for the 1st argument to
14195           "getnetbyaddr()".
14196
14197       "Off_t"
14198           This symbol holds the type used to declare offsets in the kernel.
14199           It can be int, long, "off_t", etc... It may be necessary to include
14200           sys/types.h to get any typedef'ed information.
14201
14202       "Off_t_size"
14203           This symbol holds the number of bytes used by the "Off_t".
14204
14205       "Pid_t"
14206           This symbol holds the type used to declare process ids in the
14207           kernel.  It can be int, uint, "pid_t", etc... It may be necessary
14208           to include sys/types.h to get any typedef'ed information.
14209
14210       "Rand_seed_t"
14211           This symbol defines the type of the argument of the random seed
14212           function.
14213
14214       "Select_fd_set_t"
14215           This symbol holds the type used for the 2nd, 3rd, and 4th arguments
14216           to select.  Usually, this is '"fd_set" *', if "HAS_FD_SET" is
14217           defined, and 'int *' otherwise.  This is only useful if you have
14218           "select()", of course.
14219
14220       "Shmat_t"
14221           This symbol holds the return type of the "shmat()" system call.
14222           Usually set to 'void *' or 'char *'.
14223
14224       "Signal_t"
14225           This symbol's value is either "void" or "int", corresponding to the
14226           appropriate return type of a signal handler.  Thus, you can declare
14227           a signal handler using ""Signal_t" (*handler)()", and define the
14228           handler using ""Signal_t" "handler(sig)"".
14229
14230       "Size_t"
14231           This symbol holds the type used to declare length parameters for
14232           string functions.  It is usually "size_t", but may be unsigned
14233           long, int, etc.  It may be necessary to include sys/types.h to get
14234           any typedef'ed information.
14235
14236       "Size_t_size"
14237           This symbol holds the size of a "Size_t" in bytes.
14238
14239       "Sock_size_t"
14240           This symbol holds the type used for the size argument of various
14241           socket calls (just the base type, not the pointer-to).
14242
14243       "SSize_t"
14244           This symbol holds the type used by functions that return a count of
14245           bytes or an error condition.  It must be a signed type.  It is
14246           usually "ssize_t", but may be long or int, etc.  It may be
14247           necessary to include sys/types.h or unistd.h to get any typedef'ed
14248           information.  We will pick a type such that "sizeof(SSize_t)" ==
14249           "sizeof(Size_t)".
14250
14251       "Time_t"
14252           This symbol holds the type returned by "time()". It can be long, or
14253           "time_t" on "BSD" sites (in which case sys/types.h should be
14254           included).
14255
14256       "Uid_t"
14257           This symbol holds the type used to declare user ids in the kernel.
14258           It can be int, ushort, "uid_t", etc... It may be necessary to
14259           include sys/types.h to get any typedef'ed information.
14260
14261       "Uid_t_f"
14262           This symbol defines the format string used for printing a "Uid_t".
14263
14264       "Uid_t_sign"
14265           This symbol holds the signedness of a "Uid_t".  1 for unsigned, -1
14266           for signed.
14267
14268       "Uid_t_size"
14269           This symbol holds the size of a "Uid_t" in bytes.
14270

Unicode Support

14272       "Unicode Support" in perlguts has an introduction to this API.
14273
14274       See also "Character classification", "Character case changing", and
14275       "String Handling".  Various functions outside this section also work
14276       specially with Unicode.  Search for the string "utf8" in this document.
14277
14278       "BOM_UTF8"
14279           This is a macro that evaluates to a string constant of the  UTF-8
14280           bytes that define the Unicode BYTE ORDER MARK (U+FEFF) for the
14281           platform that perl is compiled on.  This allows code to use a
14282           mnemonic for this character that works on both ASCII and EBCDIC
14283           platforms.  "sizeof(BOM_UTF8) - 1" can be used to get its length in
14284           bytes.
14285
14286       "bytes_cmp_utf8"
14287           Compares the sequence of characters (stored as octets) in "b",
14288           "blen" with the sequence of characters (stored as UTF-8) in "u",
14289           "ulen".  Returns 0 if they are equal, -1 or -2 if the first string
14290           is less than the second string, +1 or +2 if the first string is
14291           greater than the second string.
14292
14293           -1 or +1 is returned if the shorter string was identical to the
14294           start of the longer string.  -2 or +2 is returned if there was a
14295           difference between characters within the strings.
14296
14297            int  bytes_cmp_utf8(const U8 *b, STRLEN blen, const U8 *u,
14298                                STRLEN ulen)
14299
14300       "bytes_from_utf8"
14301           NOTE: "bytes_from_utf8" is experimental and may change or be
14302           removed without notice.
14303
14304           Converts a potentially UTF-8 encoded string "s" of length *lenp
14305           into native byte encoding.  On input, the boolean *is_utf8p gives
14306           whether or not "s" is actually encoded in UTF-8.
14307
14308           Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-
14309           destructive of the input string.
14310
14311           Do nothing if *is_utf8p is 0, or if there are code points in the
14312           string not expressible in native byte encoding.  In these cases,
14313           *is_utf8p and *lenp are unchanged, and the return value is the
14314           original "s".
14315
14316           Otherwise, *is_utf8p is set to 0, and the return value is a pointer
14317           to a newly created string containing a downgraded copy of "s", and
14318           whose length is returned in *lenp, updated.  The new string is
14319           "NUL"-terminated.  The caller is responsible for arranging for the
14320           memory used by this string to get freed.
14321
14322           Upon successful return, the number of variants in the string can be
14323           computed by having saved the value of *lenp before the call, and
14324           subtracting the after-call value of *lenp from it.
14325
14326            U8*  bytes_from_utf8(const U8 *s, STRLEN *lenp, bool *is_utf8p)
14327
14328       "bytes_to_utf8"
14329           NOTE: "bytes_to_utf8" is experimental and may change or be removed
14330           without notice.
14331
14332           Converts a string "s" of length *lenp bytes from the native
14333           encoding into UTF-8.  Returns a pointer to the newly-created
14334           string, and sets *lenp to reflect the new length in bytes.  The
14335           caller is responsible for arranging for the memory used by this
14336           string to get freed.
14337
14338           Upon successful return, the number of variants in the string can be
14339           computed by having saved the value of *lenp before the call, and
14340           subtracting it from the after-call value of *lenp.
14341
14342           A "NUL" character will be written after the end of the string.
14343
14344           If you want to convert to UTF-8 from encodings other than the
14345           native (Latin1 or EBCDIC), see "sv_recode_to_utf8"().
14346
14347            U8*  bytes_to_utf8(const U8 *s, STRLEN *lenp)
14348
14349       "DO_UTF8"
14350           Returns a bool giving whether or not the PV in "sv" is to be
14351           treated as being encoded in UTF-8.
14352
14353           You should use this after a call to "SvPV()" or one of its
14354           variants, in case any call to string overloading updates the
14355           internal UTF-8 encoding flag.
14356
14357            bool  DO_UTF8(SV* sv)
14358
14359       "foldEQ_utf8"
14360           Returns true if the leading portions of the strings "s1" and "s2"
14361           (either or both of which may be in UTF-8) are the same case-
14362           insensitively; false otherwise.  How far into the strings to
14363           compare is determined by other input parameters.
14364
14365           If "u1" is true, the string "s1" is assumed to be in UTF-8-encoded
14366           Unicode; otherwise it is assumed to be in native 8-bit encoding.
14367           Correspondingly for "u2" with respect to "s2".
14368
14369           If the byte length "l1" is non-zero, it says how far into "s1" to
14370           check for fold equality.  In other words, "s1"+"l1" will be used as
14371           a goal to reach.  The scan will not be considered to be a match
14372           unless the goal is reached, and scanning won't continue past that
14373           goal.  Correspondingly for "l2" with respect to "s2".
14374
14375           If "pe1" is non-"NULL" and the pointer it points to is not "NULL",
14376           that pointer is considered an end pointer to the position 1 byte
14377           past the maximum point in "s1" beyond which scanning will not
14378           continue under any circumstances.  (This routine assumes that UTF-8
14379           encoded input strings are not malformed; malformed input can cause
14380           it to read past "pe1").  This means that if both "l1" and "pe1" are
14381           specified, and "pe1" is less than "s1"+"l1", the match will never
14382           be successful because it can never get as far as its goal (and in
14383           fact is asserted against).  Correspondingly for "pe2" with respect
14384           to "s2".
14385
14386           At least one of "s1" and "s2" must have a goal (at least one of
14387           "l1" and "l2" must be non-zero), and if both do, both have to be
14388           reached for a successful match.   Also, if the fold of a character
14389           is multiple characters, all of them must be matched (see tr21
14390           reference below for 'folding').
14391
14392           Upon a successful match, if "pe1" is non-"NULL", it will be set to
14393           point to the beginning of the next character of "s1" beyond what
14394           was matched.  Correspondingly for "pe2" and "s2".
14395
14396           For case-insensitiveness, the "casefolding" of Unicode is used
14397           instead of upper/lowercasing both the characters, see
14398           <https://www.unicode.org/unicode/reports/tr21/> (Case Mappings).
14399
14400            I32  foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1,
14401                             const char *s2, char **pe2, UV l2, bool u2)
14402
14403       "is_ascii_string"
14404           This is a misleadingly-named synonym for
14405           "is_utf8_invariant_string".  On ASCII-ish platforms, the name isn't
14406           misleading: the ASCII-range characters are exactly the UTF-8
14407           invariants.  But EBCDIC machines have more invariants than just the
14408           ASCII characters, so "is_utf8_invariant_string" is preferred.
14409
14410            bool  is_ascii_string(const U8* const s, STRLEN len)
14411
14412       "is_c9strict_utf8_string"
14413           Returns TRUE if the first "len" bytes of string "s" form a valid
14414           UTF-8-encoded string that conforms to Unicode Corrigendum #9
14415           <http://www.unicode.org/versions/corrigendum9.html>; otherwise it
14416           returns FALSE.  If "len" is 0, it will be calculated using
14417           strlen(s) (which means if you use this option, that "s" can't have
14418           embedded "NUL" characters and has to have a terminating "NUL"
14419           byte).  Note that all characters being ASCII constitute 'a valid
14420           UTF-8 string'.
14421
14422           This function returns FALSE for strings containing any code points
14423           above the Unicode max of 0x10FFFF or surrogate code points, but
14424           accepts non-character code points per Corrigendum #9
14425           <http://www.unicode.org/versions/corrigendum9.html>.
14426
14427           See also "is_utf8_invariant_string",
14428           "is_utf8_invariant_string_loc", "is_utf8_string",
14429           "is_utf8_string_flags", "is_utf8_string_loc",
14430           "is_utf8_string_loc_flags", "is_utf8_string_loclen",
14431           "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
14432           "is_utf8_fixed_width_buf_loc_flags",
14433           "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
14434           "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
14435           "is_c9strict_utf8_string_loc", and
14436           "is_c9strict_utf8_string_loclen".
14437
14438            bool  is_c9strict_utf8_string(const U8 *s, STRLEN len)
14439
14440       "is_c9strict_utf8_string_loc"
14441           Like "is_c9strict_utf8_string" but stores the location of the
14442           failure (in the case of "utf8ness failure") or the location
14443           "s"+"len" (in the case of "utf8ness success") in the "ep" pointer.
14444
14445           See also "is_c9strict_utf8_string_loclen".
14446
14447            bool  is_c9strict_utf8_string_loc(const U8 *s, STRLEN len,
14448                                              const U8 **ep)
14449
14450       "is_c9strict_utf8_string_loclen"
14451           Like "is_c9strict_utf8_string" but stores the location of the
14452           failure (in the case of "utf8ness failure") or the location
14453           "s"+"len" (in the case of "utf8ness success") in the "ep" pointer,
14454           and the number of UTF-8 encoded characters in the "el" pointer.
14455
14456           See also "is_c9strict_utf8_string_loc".
14457
14458            bool  is_c9strict_utf8_string_loclen(const U8 *s, STRLEN len,
14459                                                 const U8 **ep, STRLEN *el)
14460
14461       "isC9_STRICT_UTF8_CHAR"
14462           Evaluates to non-zero if the first few bytes of the string starting
14463           at "s" and looking no further than "e - 1" are well-formed UTF-8
14464           that represents some Unicode non-surrogate code point; otherwise it
14465           evaluates to 0.  If non-zero, the value gives how many bytes
14466           starting at "s" comprise the code point's representation.  Any
14467           bytes remaining before "e", but beyond the ones needed to form the
14468           first code point in "s", are not examined.
14469
14470           The largest acceptable code point is the Unicode maximum 0x10FFFF.
14471           This differs from "isSTRICT_UTF8_CHAR" only in that it accepts non-
14472           character code points.  This corresponds to Unicode Corrigendum #9
14473           <http://www.unicode.org/versions/corrigendum9.html>.  which said
14474           that non-character code points are merely discouraged rather than
14475           completely forbidden in open interchange.  See "Noncharacter code
14476           points" in perlunicode.
14477
14478           Use "isUTF8_CHAR" to check for Perl's extended UTF-8; and
14479           "isUTF8_CHAR_flags" for a more customized definition.
14480
14481           Use "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
14482           "is_c9strict_utf8_string_loclen" to check entire strings.
14483
14484            Size_t  isC9_STRICT_UTF8_CHAR(const U8 * const s0,
14485                                          const U8 * const e)
14486
14487       "is_invariant_string"
14488           This is a somewhat misleadingly-named synonym for
14489           "is_utf8_invariant_string".  "is_utf8_invariant_string" is
14490           preferred, as it indicates under what conditions the string is
14491           invariant.
14492
14493            bool  is_invariant_string(const U8* const s, STRLEN len)
14494
14495       "isSTRICT_UTF8_CHAR"
14496           Evaluates to non-zero if the first few bytes of the string starting
14497           at "s" and looking no further than "e - 1" are well-formed UTF-8
14498           that represents some Unicode code point completely acceptable for
14499           open interchange between all applications; otherwise it evaluates
14500           to 0.  If non-zero, the value gives how many bytes starting at "s"
14501           comprise the code point's representation.  Any bytes remaining
14502           before "e", but beyond the ones needed to form the first code point
14503           in "s", are not examined.
14504
14505           The largest acceptable code point is the Unicode maximum 0x10FFFF,
14506           and must not be a surrogate nor a non-character code point.  Thus
14507           this excludes any code point from Perl's extended UTF-8.
14508
14509           This is used to efficiently decide if the next few bytes in "s" is
14510           legal Unicode-acceptable UTF-8 for a single character.
14511
14512           Use "isC9_STRICT_UTF8_CHAR" to use the Unicode Corrigendum #9
14513           <http://www.unicode.org/versions/corrigendum9.html> definition of
14514           allowable code points; "isUTF8_CHAR" to check for Perl's extended
14515           UTF-8; and "isUTF8_CHAR_flags" for a more customized definition.
14516
14517           Use "is_strict_utf8_string", "is_strict_utf8_string_loc", and
14518           "is_strict_utf8_string_loclen" to check entire strings.
14519
14520            Size_t  isSTRICT_UTF8_CHAR(const U8 * const s0,
14521                                       const U8 * const e)
14522
14523       "is_strict_utf8_string"
14524           Returns TRUE if the first "len" bytes of string "s" form a valid
14525           UTF-8-encoded string that is fully interchangeable by any
14526           application using Unicode rules; otherwise it returns FALSE.  If
14527           "len" is 0, it will be calculated using strlen(s) (which means if
14528           you use this option, that "s" can't have embedded "NUL" characters
14529           and has to have a terminating "NUL" byte).  Note that all
14530           characters being ASCII constitute 'a valid UTF-8 string'.
14531
14532           This function returns FALSE for strings containing any code points
14533           above the Unicode max of 0x10FFFF, surrogate code points, or non-
14534           character code points.
14535
14536           See also "is_utf8_invariant_string",
14537           "is_utf8_invariant_string_loc", "is_utf8_string",
14538           "is_utf8_string_flags", "is_utf8_string_loc",
14539           "is_utf8_string_loc_flags", "is_utf8_string_loclen",
14540           "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
14541           "is_utf8_fixed_width_buf_loc_flags",
14542           "is_utf8_fixed_width_buf_loclen_flags",
14543           "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
14544           "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
14545           "is_c9strict_utf8_string_loclen".
14546
14547            bool  is_strict_utf8_string(const U8 *s, STRLEN len)
14548
14549       "is_strict_utf8_string_loc"
14550           Like "is_strict_utf8_string" but stores the location of the failure
14551           (in the case of "utf8ness failure") or the location "s"+"len" (in
14552           the case of "utf8ness success") in the "ep" pointer.
14553
14554           See also "is_strict_utf8_string_loclen".
14555
14556            bool  is_strict_utf8_string_loc(const U8 *s, STRLEN len,
14557                                            const U8 **ep)
14558
14559       "is_strict_utf8_string_loclen"
14560           Like "is_strict_utf8_string" but stores the location of the failure
14561           (in the case of "utf8ness failure") or the location "s"+"len" (in
14562           the case of "utf8ness success") in the "ep" pointer, and the number
14563           of UTF-8 encoded characters in the "el" pointer.
14564
14565           See also "is_strict_utf8_string_loc".
14566
14567            bool  is_strict_utf8_string_loclen(const U8 *s, STRLEN len,
14568                                               const U8 **ep, STRLEN *el)
14569
14570       "is_utf8_char"
14571           "DEPRECATED!"  It is planned to remove "is_utf8_char" from a future
14572           release of Perl.  Do not use it for new code; remove it from
14573           existing code.
14574
14575           Tests if some arbitrary number of bytes begins in a valid UTF-8
14576           character.  Note that an INVARIANT (i.e. ASCII on non-EBCDIC
14577           machines) character is a valid UTF-8 character.  The actual number
14578           of bytes in the UTF-8 character will be returned if it is valid,
14579           otherwise 0.
14580
14581           This function is deprecated due to the possibility that malformed
14582           input could cause reading beyond the end of the input buffer.  Use
14583           "isUTF8_CHAR" instead.
14584
14585            STRLEN  is_utf8_char(const U8 *s)
14586
14587       "is_utf8_char_buf"
14588           This is identical to the macro "isUTF8_CHAR" in perlapi.
14589
14590            STRLEN  is_utf8_char_buf(const U8 *buf, const U8 *buf_end)
14591
14592       "is_utf8_fixed_width_buf_flags"
14593           Returns TRUE if the fixed-width buffer starting at "s" with length
14594           "len" is entirely valid UTF-8, subject to the restrictions given by
14595           "flags"; otherwise it returns FALSE.
14596
14597           If "flags" is 0, any well-formed UTF-8, as extended by Perl, is
14598           accepted without restriction.  If the final few bytes of the buffer
14599           do not form a complete code point, this will return TRUE anyway,
14600           provided that "is_utf8_valid_partial_char_flags" returns TRUE for
14601           them.
14602
14603           If "flags" in non-zero, it can be any combination of the
14604           "UTF8_DISALLOW_foo" flags accepted by "utf8n_to_uvchr", and with
14605           the same meanings.
14606
14607           This function differs from "is_utf8_string_flags" only in that the
14608           latter returns FALSE if the final few bytes of the string don't
14609           form a complete code point.
14610
14611            bool  is_utf8_fixed_width_buf_flags(const U8 * const s,
14612                                                STRLEN len, const U32 flags)
14613
14614       "is_utf8_fixed_width_buf_loclen_flags"
14615           Like "is_utf8_fixed_width_buf_loc_flags" but stores the number of
14616           complete, valid characters found in the "el" pointer.
14617
14618            bool  is_utf8_fixed_width_buf_loclen_flags(const U8 * const s,
14619                                                       STRLEN len,
14620                                                       const U8 **ep,
14621                                                       STRLEN *el,
14622                                                       const U32 flags)
14623
14624       "is_utf8_fixed_width_buf_loc_flags"
14625           Like "is_utf8_fixed_width_buf_flags" but stores the location of the
14626           failure in the "ep" pointer.  If the function returns TRUE, *ep
14627           will point to the beginning of any partial character at the end of
14628           the buffer; if there is no partial character *ep will contain
14629           "s"+"len".
14630
14631           See also "is_utf8_fixed_width_buf_loclen_flags".
14632
14633            bool  is_utf8_fixed_width_buf_loc_flags(const U8 * const s,
14634                                                    STRLEN len, const U8 **ep,
14635                                                    const U32 flags)
14636
14637       "is_utf8_invariant_string"
14638           Returns TRUE if the first "len" bytes of the string "s" are the
14639           same regardless of the UTF-8 encoding of the string (or UTF-EBCDIC
14640           encoding on EBCDIC machines); otherwise it returns FALSE.  That is,
14641           it returns TRUE if they are UTF-8 invariant.  On ASCII-ish
14642           machines, all the ASCII characters and only the ASCII characters
14643           fit this definition.  On EBCDIC machines, the ASCII-range
14644           characters are invariant, but so also are the C1 controls.
14645
14646           If "len" is 0, it will be calculated using strlen(s), (which means
14647           if you use this option, that "s" can't have embedded "NUL"
14648           characters and has to have a terminating "NUL" byte).
14649
14650           See also "is_utf8_string", "is_utf8_string_flags",
14651           "is_utf8_string_loc", "is_utf8_string_loc_flags",
14652           "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
14653           "is_utf8_fixed_width_buf_flags",
14654           "is_utf8_fixed_width_buf_loc_flags",
14655           "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
14656           "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
14657           "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
14658           "is_c9strict_utf8_string_loclen".
14659
14660            bool  is_utf8_invariant_string(const U8* const s, STRLEN len)
14661
14662       "is_utf8_invariant_string_loc"
14663           Like "is_utf8_invariant_string" but upon failure, stores the
14664           location of the first UTF-8 variant character in the "ep" pointer;
14665           if all characters are UTF-8 invariant, this function does not
14666           change the contents of *ep.
14667
14668            bool  is_utf8_invariant_string_loc(const U8* const s, STRLEN len,
14669                                               const U8 ** ep)
14670
14671       "is_utf8_string"
14672           Returns TRUE if the first "len" bytes of string "s" form a valid
14673           Perl-extended-UTF-8 string; returns FALSE otherwise.  If "len" is
14674           0, it will be calculated using strlen(s) (which means if you use
14675           this option, that "s" can't have embedded "NUL" characters and has
14676           to have a terminating "NUL" byte).  Note that all characters being
14677           ASCII constitute 'a valid UTF-8 string'.
14678
14679           This function considers Perl's extended UTF-8 to be valid.  That
14680           means that code points above Unicode, surrogates, and non-character
14681           code points are considered valid by this function.  Use
14682           "is_strict_utf8_string", "is_c9strict_utf8_string", or
14683           "is_utf8_string_flags" to restrict what code points are considered
14684           valid.
14685
14686           See also "is_utf8_invariant_string",
14687           "is_utf8_invariant_string_loc", "is_utf8_string_loc",
14688           "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags",
14689           "is_utf8_fixed_width_buf_loc_flags",
14690           "is_utf8_fixed_width_buf_loclen_flags",
14691
14692            bool  is_utf8_string(const U8 *s, STRLEN len)
14693
14694       "is_utf8_string_flags"
14695           Returns TRUE if the first "len" bytes of string "s" form a valid
14696           UTF-8 string, subject to the restrictions imposed by "flags";
14697           returns FALSE otherwise.  If "len" is 0, it will be calculated
14698           using strlen(s) (which means if you use this option, that "s" can't
14699           have embedded "NUL" characters and has to have a terminating "NUL"
14700           byte).  Note that all characters being ASCII constitute 'a valid
14701           UTF-8 string'.
14702
14703           If "flags" is 0, this gives the same results as "is_utf8_string";
14704           if "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the
14705           same results as "is_strict_utf8_string"; and if "flags" is
14706           "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same results
14707           as "is_c9strict_utf8_string".  Otherwise "flags" may be any
14708           combination of the "UTF8_DISALLOW_foo" flags understood by
14709           "utf8n_to_uvchr", with the same meanings.
14710
14711           See also "is_utf8_invariant_string",
14712           "is_utf8_invariant_string_loc", "is_utf8_string",
14713           "is_utf8_string_loc", "is_utf8_string_loc_flags",
14714           "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
14715           "is_utf8_fixed_width_buf_flags",
14716           "is_utf8_fixed_width_buf_loc_flags",
14717           "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
14718           "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
14719           "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
14720           "is_c9strict_utf8_string_loclen".
14721
14722            bool  is_utf8_string_flags(const U8 *s, STRLEN len,
14723                                       const U32 flags)
14724
14725       "is_utf8_string_loc"
14726           Like "is_utf8_string" but stores the location of the failure (in
14727           the case of "utf8ness failure") or the location "s"+"len" (in the
14728           case of "utf8ness success") in the "ep" pointer.
14729
14730           See also "is_utf8_string_loclen".
14731
14732            bool  is_utf8_string_loc(const U8 *s, const STRLEN len,
14733                                     const U8 **ep)
14734
14735       "is_utf8_string_loclen"
14736           Like "is_utf8_string" but stores the location of the failure (in
14737           the case of "utf8ness failure") or the location "s"+"len" (in the
14738           case of "utf8ness success") in the "ep" pointer, and the number of
14739           UTF-8 encoded characters in the "el" pointer.
14740
14741           See also "is_utf8_string_loc".
14742
14743            bool  is_utf8_string_loclen(const U8 *s, STRLEN len,
14744                                        const U8 **ep, STRLEN *el)
14745
14746       "is_utf8_string_loclen_flags"
14747           Like "is_utf8_string_flags" but stores the location of the failure
14748           (in the case of "utf8ness failure") or the location "s"+"len" (in
14749           the case of "utf8ness success") in the "ep" pointer, and the number
14750           of UTF-8 encoded characters in the "el" pointer.
14751
14752           See also "is_utf8_string_loc_flags".
14753
14754            bool  is_utf8_string_loclen_flags(const U8 *s, STRLEN len,
14755                                              const U8 **ep, STRLEN *el,
14756                                              const U32 flags)
14757
14758       "is_utf8_string_loc_flags"
14759           Like "is_utf8_string_flags" but stores the location of the failure
14760           (in the case of "utf8ness failure") or the location "s"+"len" (in
14761           the case of "utf8ness success") in the "ep" pointer.
14762
14763           See also "is_utf8_string_loclen_flags".
14764
14765            bool  is_utf8_string_loc_flags(const U8 *s, STRLEN len,
14766                                           const U8 **ep, const U32 flags)
14767
14768       "is_utf8_valid_partial_char"
14769           Returns 0 if the sequence of bytes starting at "s" and looking no
14770           further than "e - 1" is the UTF-8 encoding, as extended by Perl,
14771           for one or more code points.  Otherwise, it returns 1 if there
14772           exists at least one non-empty sequence of bytes that when appended
14773           to sequence "s", starting at position "e" causes the entire
14774           sequence to be the well-formed UTF-8 of some code point; otherwise
14775           returns 0.
14776
14777           In other words this returns TRUE if "s" points to a partial
14778           UTF-8-encoded code point.
14779
14780           This is useful when a fixed-length buffer is being tested for being
14781           well-formed UTF-8, but the final few bytes in it don't comprise a
14782           full character; that is, it is split somewhere in the middle of the
14783           final code point's UTF-8 representation.  (Presumably when the
14784           buffer is refreshed with the next chunk of data, the new first
14785           bytes will complete the partial code point.)   This function is
14786           used to verify that the final bytes in the current buffer are in
14787           fact the legal beginning of some code point, so that if they
14788           aren't, the failure can be signalled without having to wait for the
14789           next read.
14790
14791            bool  is_utf8_valid_partial_char(const U8 * const s,
14792                                             const U8 * const e)
14793
14794       "is_utf8_valid_partial_char_flags"
14795           Like "is_utf8_valid_partial_char", it returns a boolean giving
14796           whether or not the input is a valid UTF-8 encoded partial
14797           character, but it takes an extra parameter, "flags", which can
14798           further restrict which code points are considered valid.
14799
14800           If "flags" is 0, this behaves identically to
14801           "is_utf8_valid_partial_char".  Otherwise "flags" can be any
14802           combination of the "UTF8_DISALLOW_foo" flags accepted by
14803           "utf8n_to_uvchr".  If there is any sequence of bytes that can
14804           complete the input partial character in such a way that a non-
14805           prohibited character is formed, the function returns TRUE;
14806           otherwise FALSE.  Non character code points cannot be determined
14807           based on partial character input.  But many  of the other possible
14808           excluded types can be determined from just the first one or two
14809           bytes.
14810
14811            bool  is_utf8_valid_partial_char_flags(const U8 * const s,
14812                                                   const U8 * const e,
14813                                                   const U32 flags)
14814
14815       "isUTF8_CHAR"
14816           Evaluates to non-zero if the first few bytes of the string starting
14817           at "s" and looking no further than "e - 1" are well-formed UTF-8,
14818           as extended by Perl, that represents some code point; otherwise it
14819           evaluates to 0.  If non-zero, the value gives how many bytes
14820           starting at "s" comprise the code point's representation.  Any
14821           bytes remaining before "e", but beyond the ones needed to form the
14822           first code point in "s", are not examined.
14823
14824           The code point can be any that will fit in an IV on this machine,
14825           using Perl's extension to official UTF-8 to represent those higher
14826           than the Unicode maximum of 0x10FFFF.  That means that this macro
14827           is used to efficiently decide if the next few bytes in "s" is legal
14828           UTF-8 for a single character.
14829
14830           Use "isSTRICT_UTF8_CHAR" to restrict the acceptable code points to
14831           those defined by Unicode to be fully interchangeable across
14832           applications; "isC9_STRICT_UTF8_CHAR" to use the Unicode
14833           Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>
14834           definition of allowable code points; and "isUTF8_CHAR_flags" for a
14835           more customized definition.
14836
14837           Use "is_utf8_string", "is_utf8_string_loc", and
14838           "is_utf8_string_loclen" to check entire strings.
14839
14840           Note also that a UTF-8 "invariant" character (i.e. ASCII on non-
14841           EBCDIC machines) is a valid UTF-8 character.
14842
14843            Size_t  isUTF8_CHAR(const U8 * const s0, const U8 * const e)
14844
14845       "isUTF8_CHAR_flags"
14846           Evaluates to non-zero if the first few bytes of the string starting
14847           at "s" and looking no further than "e - 1" are well-formed UTF-8,
14848           as extended by Perl, that represents some code point, subject to
14849           the restrictions given by "flags"; otherwise it evaluates to 0.  If
14850           non-zero, the value gives how many bytes starting at "s" comprise
14851           the code point's representation.  Any bytes remaining before "e",
14852           but beyond the ones needed to form the first code point in "s", are
14853           not examined.
14854
14855           If "flags" is 0, this gives the same results as "isUTF8_CHAR"; if
14856           "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the same
14857           results as "isSTRICT_UTF8_CHAR"; and if "flags" is
14858           "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same results
14859           as "isC9_STRICT_UTF8_CHAR".  Otherwise "flags" may be any
14860           combination of the "UTF8_DISALLOW_foo" flags understood by
14861           "utf8n_to_uvchr", with the same meanings.
14862
14863           The three alternative macros are for the most commonly needed
14864           validations; they are likely to run somewhat faster than this more
14865           general one, as they can be inlined into your code.
14866
14867           Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
14868           "is_utf8_string_loclen_flags" to check entire strings.
14869
14870            STRLEN  isUTF8_CHAR_flags(const U8 *s, const U8 *e,
14871                                      const U32 flags)
14872
14873       "LATIN1_TO_NATIVE"
14874           Returns the native  equivalent of the input Latin-1 code point
14875           (including ASCII and control characters) given by "ch".  Thus,
14876           "LATIN1_TO_NATIVE(66)" on EBCDIC platforms returns 194.  These each
14877           represent the character "B" on their respective platforms.  On
14878           ASCII platforms no conversion is needed, so this macro expands to
14879           just its input, adding no time nor space requirements to the
14880           implementation.
14881
14882           For conversion of code points potentially larger than will fit in a
14883           character, use "UNI_TO_NATIVE".
14884
14885            U8  LATIN1_TO_NATIVE(U8 ch)
14886
14887       "NATIVE_TO_LATIN1"
14888           Returns the Latin-1 (including ASCII and control characters)
14889           equivalent of the input native code point given by "ch".  Thus,
14890           "NATIVE_TO_LATIN1(193)" on EBCDIC platforms returns 65.  These each
14891           represent the character "A" on their respective platforms.  On
14892           ASCII platforms no conversion is needed, so this macro expands to
14893           just its input, adding no time nor space requirements to the
14894           implementation.
14895
14896           For conversion of code points potentially larger than will fit in a
14897           character, use "NATIVE_TO_UNI".
14898
14899            U8  NATIVE_TO_LATIN1(U8 ch)
14900
14901       "NATIVE_TO_UNI"
14902           Returns the Unicode  equivalent of the input native code point
14903           given by "ch".  Thus, "NATIVE_TO_UNI(195)" on EBCDIC platforms
14904           returns 67.  These each represent the character "C" on their
14905           respective platforms.  On ASCII platforms no conversion is needed,
14906           so this macro expands to just its input, adding no time nor space
14907           requirements to the implementation.
14908
14909            UV  NATIVE_TO_UNI(UV ch)
14910
14911       "pad_compname_type"
14912           "DEPRECATED!"  It is planned to remove "pad_compname_type" from a
14913           future release of Perl.  Do not use it for new code; remove it from
14914           existing code.
14915
14916           Looks up the type of the lexical variable at position "po" in the
14917           currently-compiling pad.  If the variable is typed, the stash of
14918           the class to which it is typed is returned.  If not, "NULL" is
14919           returned.
14920
14921           Use ""PAD_COMPNAME_TYPE"" in perlintern instead.
14922
14923            HV*  pad_compname_type(const PADOFFSET po)
14924
14925       "pv_uni_display"
14926           Build to the scalar "dsv" a displayable version of the UTF-8
14927           encoded string "spv", length "len", the displayable version being
14928           at most "pvlim" bytes long (if longer, the rest is truncated and
14929           "..." will be appended).
14930
14931           The "flags" argument can have "UNI_DISPLAY_ISPRINT" set to display
14932           "isPRINT()"able characters as themselves, "UNI_DISPLAY_BACKSLASH"
14933           to display the "\\[nrfta\\]" as the backslashed versions (like
14934           "\n") ("UNI_DISPLAY_BACKSLASH" is preferred over
14935           "UNI_DISPLAY_ISPRINT" for "\\").  "UNI_DISPLAY_QQ" (and its alias
14936           "UNI_DISPLAY_REGEX") have both "UNI_DISPLAY_BACKSLASH" and
14937           "UNI_DISPLAY_ISPRINT" turned on.
14938
14939           Additionally, there is now "UNI_DISPLAY_BACKSPACE" which allows
14940           "\b" for a backspace, but only when "UNI_DISPLAY_BACKSLASH" also is
14941           set.
14942
14943           The pointer to the PV of the "dsv" is returned.
14944
14945           See also "sv_uni_display".
14946
14947            char*  pv_uni_display(SV *dsv, const U8 *spv, STRLEN len,
14948                                  STRLEN pvlim, UV flags)
14949
14950       "REPLACEMENT_CHARACTER_UTF8"
14951           This is a macro that evaluates to a string constant of the  UTF-8
14952           bytes that define the Unicode REPLACEMENT CHARACTER (U+FFFD) for
14953           the platform that perl is compiled on.  This allows code to use a
14954           mnemonic for this character that works on both ASCII and EBCDIC
14955           platforms.  "sizeof(REPLACEMENT_CHARACTER_UTF8) - 1" can be used to
14956           get its length in bytes.
14957
14958       "sv_cat_decode"
14959           "encoding" is assumed to be an "Encode" object, the PV of "ssv" is
14960           assumed to be octets in that encoding and decoding the input starts
14961           from the position which "(PV + *offset)" pointed to.  "dsv" will be
14962           concatenated with the decoded UTF-8 string from "ssv".  Decoding
14963           will terminate when the string "tstr" appears in decoding output or
14964           the input ends on the PV of "ssv".  The value which "offset" points
14965           will be modified to the last input position on "ssv".
14966
14967           Returns TRUE if the terminator was found, else returns FALSE.
14968
14969            bool  sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset,
14970                                char* tstr, int tlen)
14971
14972       "sv_recode_to_utf8"
14973           "encoding" is assumed to be an "Encode" object, on entry the PV of
14974           "sv" is assumed to be octets in that encoding, and "sv" will be
14975           converted into Unicode (and UTF-8).
14976
14977           If "sv" already is UTF-8 (or if it is not "POK"), or if "encoding"
14978           is not a reference, nothing is done to "sv".  If "encoding" is not
14979           an "Encode::XS" Encoding object, bad things will happen.  (See
14980           cpan/Encode/encoding.pm and Encode.)
14981
14982           The PV of "sv" is returned.
14983
14984            char*  sv_recode_to_utf8(SV* sv, SV *encoding)
14985
14986       "sv_uni_display"
14987           Build to the scalar "dsv" a displayable version of the scalar "sv",
14988           the displayable version being at most "pvlim" bytes long (if
14989           longer, the rest is truncated and "..." will be appended).
14990
14991           The "flags" argument is as in "pv_uni_display"().
14992
14993           The pointer to the PV of the "dsv" is returned.
14994
14995            char*  sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
14996
14997       "UNICODE_REPLACEMENT"
14998           Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT
14999           CHARACTER
15000
15001       "UNI_TO_NATIVE"
15002           Returns the native  equivalent of the input Unicode code point
15003           given by "ch".  Thus, "UNI_TO_NATIVE(68)" on EBCDIC platforms
15004           returns 196.  These each represent the character "D" on their
15005           respective platforms.  On ASCII platforms no conversion is needed,
15006           so this macro expands to just its input, adding no time nor space
15007           requirements to the implementation.
15008
15009            UV  UNI_TO_NATIVE(UV ch)
15010
15011       "utf8n_to_uvchr"
15012           THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15013           CIRCUMSTANCES.  Most code should use "utf8_to_uvchr_buf"() rather
15014           than call this directly.
15015
15016           Bottom level UTF-8 decode routine.  Returns the native code point
15017           value of the first character in the string "s", which is assumed to
15018           be in UTF-8 (or UTF-EBCDIC) encoding, and no longer than "curlen"
15019           bytes; *retlen (if "retlen" isn't NULL) will be set to the length,
15020           in bytes, of that character.
15021
15022           The value of "flags" determines the behavior when "s" does not
15023           point to a well-formed UTF-8 character.  If "flags" is 0,
15024           encountering a malformation causes zero to be returned and *retlen
15025           is set so that ("s" + *retlen) is the next possible position in "s"
15026           that could begin a non-malformed character.  Also, if UTF-8
15027           warnings haven't been lexically disabled, a warning is raised.
15028           Some UTF-8 input sequences may contain multiple malformations.
15029           This function tries to find every possible one in each call, so
15030           multiple warnings can be raised for the same sequence.
15031
15032           Various ALLOW flags can be set in "flags" to allow (and not warn
15033           on) individual types of malformations, such as the sequence being
15034           overlong (that is, when there is a shorter sequence that can
15035           express the same code point; overlong sequences are expressly
15036           forbidden in the UTF-8 standard due to potential security issues).
15037           Another malformation example is the first byte of a character not
15038           being a legal first byte.  See utf8.h for the list of such flags.
15039           Even if allowed, this function generally returns the Unicode
15040           REPLACEMENT CHARACTER when it encounters a malformation.  There are
15041           flags in utf8.h to override this behavior for the overlong
15042           malformations, but don't do that except for very specialized
15043           purposes.
15044
15045           The "UTF8_CHECK_ONLY" flag overrides the behavior when a non-
15046           allowed (by other flags) malformation is found.  If this flag is
15047           set, the routine assumes that the caller will raise a warning, and
15048           this function will silently just set "retlen" to "-1" (cast to
15049           "STRLEN") and return zero.
15050
15051           Note that this API requires disambiguation between successful
15052           decoding a "NUL" character, and an error return (unless the
15053           "UTF8_CHECK_ONLY" flag is set), as in both cases, 0 is returned,
15054           and, depending on the malformation, "retlen" may be set to 1.  To
15055           disambiguate, upon a zero return, see if the first byte of "s" is 0
15056           as well.  If so, the input was a "NUL"; if not, the input had an
15057           error.  Or you can use "utf8n_to_uvchr_error".
15058
15059           Certain code points are considered problematic.  These are Unicode
15060           surrogates, Unicode non-characters, and code points above the
15061           Unicode maximum of 0x10FFFF.  By default these are considered
15062           regular code points, but certain situations warrant special
15063           handling for them, which can be specified using the "flags"
15064           parameter.  If "flags" contains
15065           "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", all three classes are treated
15066           as malformations and handled as such.  The flags
15067           "UTF8_DISALLOW_SURROGATE", "UTF8_DISALLOW_NONCHAR", and
15068           "UTF8_DISALLOW_SUPER" (meaning above the legal Unicode maximum) can
15069           be set to disallow these categories individually.
15070           "UTF8_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed inputs to
15071           the strict UTF-8 traditionally defined by Unicode.  Use
15072           "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE" to use the strictness
15073           definition given by Unicode Corrigendum #9
15074           <https://www.unicode.org/versions/corrigendum9.html>.  The
15075           difference between traditional strictness and C9 strictness is that
15076           the latter does not forbid non-character code points.  (They are
15077           still discouraged, however.)  For more discussion see "Noncharacter
15078           code points" in perlunicode.
15079
15080           The flags "UTF8_WARN_ILLEGAL_INTERCHANGE",
15081           "UTF8_WARN_ILLEGAL_C9_INTERCHANGE", "UTF8_WARN_SURROGATE",
15082           "UTF8_WARN_NONCHAR", and "UTF8_WARN_SUPER" will cause warning
15083           messages to be raised for their respective categories, but
15084           otherwise the code points are considered valid (not malformations).
15085           To get a category to both be treated as a malformation and raise a
15086           warning, specify both the WARN and DISALLOW flags.  (But note that
15087           warnings are not raised if lexically disabled nor if
15088           "UTF8_CHECK_ONLY" is also specified.)
15089
15090           Extremely high code points were never specified in any standard,
15091           and require an extension to UTF-8 to express, which Perl does.  It
15092           is likely that programs written in something other than Perl would
15093           not be able to read files that contain these; nor would Perl
15094           understand files written by something that uses a different
15095           extension.  For these reasons, there is a separate set of flags
15096           that can warn and/or disallow these extremely high code points,
15097           even if other above-Unicode ones are accepted.  They are the
15098           "UTF8_WARN_PERL_EXTENDED" and "UTF8_DISALLOW_PERL_EXTENDED" flags.
15099           For more information see "UTF8_GOT_PERL_EXTENDED".  Of course
15100           "UTF8_DISALLOW_SUPER" will treat all above-Unicode code points,
15101           including these, as malformations.  (Note that the Unicode standard
15102           considers anything above 0x10FFFF to be illegal, but there are
15103           standards predating it that allow up to 0x7FFF_FFFF (2**31 -1))
15104
15105           A somewhat misleadingly named synonym for "UTF8_WARN_PERL_EXTENDED"
15106           is retained for backward compatibility: "UTF8_WARN_ABOVE_31_BIT".
15107           Similarly, "UTF8_DISALLOW_ABOVE_31_BIT" is usable instead of the
15108           more accurately named "UTF8_DISALLOW_PERL_EXTENDED".  The names are
15109           misleading because these flags can apply to code points that
15110           actually do fit in 31 bits.  This happens on EBCDIC platforms, and
15111           sometimes when the overlong malformation is also present.  The new
15112           names accurately describe the situation in all cases.
15113
15114           All other code points corresponding to Unicode characters,
15115           including private use and those yet to be assigned, are never
15116           considered malformed and never warn.
15117
15118            UV  utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen,
15119                               const U32 flags)
15120
15121       "utf8n_to_uvchr_error"
15122           THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15123           CIRCUMSTANCES.  Most code should use "utf8_to_uvchr_buf"() rather
15124           than call this directly.
15125
15126           This function is for code that needs to know what the precise
15127           malformation(s) are when an error is found.  If you also need to
15128           know the generated warning messages, use "utf8n_to_uvchr_msgs"()
15129           instead.
15130
15131           It is like "utf8n_to_uvchr" but it takes an extra parameter placed
15132           after all the others, "errors".  If this parameter is 0, this
15133           function behaves identically to "utf8n_to_uvchr".  Otherwise,
15134           "errors" should be a pointer to a "U32" variable, which this
15135           function sets to indicate any errors found.  Upon return, if
15136           *errors is 0, there were no errors found.  Otherwise, *errors is
15137           the bit-wise "OR" of the bits described in the list below.  Some of
15138           these bits will be set if a malformation is found, even if the
15139           input "flags" parameter indicates that the given malformation is
15140           allowed; those exceptions are noted:
15141
15142           "UTF8_GOT_PERL_EXTENDED"
15143               The input sequence is not standard UTF-8, but a Perl extension.
15144               This bit is set only if the input "flags" parameter contains
15145               either the "UTF8_DISALLOW_PERL_EXTENDED" or the
15146               "UTF8_WARN_PERL_EXTENDED" flags.
15147
15148               Code points above 0x7FFF_FFFF (2**31 - 1) were never specified
15149               in any standard, and so some extension must be used to express
15150               them.  Perl uses a natural extension to UTF-8 to represent the
15151               ones up to 2**36-1, and invented a further extension to
15152               represent even higher ones, so that any code point that fits in
15153               a 64-bit word can be represented.  Text using these extensions
15154               is not likely to be portable to non-Perl code.  We lump both of
15155               these extensions together and refer to them as Perl extended
15156               UTF-8.  There exist other extensions that people have invented,
15157               incompatible with Perl's.
15158
15159               On EBCDIC platforms starting in Perl v5.24, the Perl extension
15160               for representing extremely high code points kicks in at
15161               0x3FFF_FFFF (2**30 -1), which is lower than on ASCII.  Prior to
15162               that, code points 2**31 and higher were simply unrepresentable,
15163               and a different, incompatible method was used to represent code
15164               points between 2**30 and 2**31 - 1.
15165
15166               On both platforms, ASCII and EBCDIC, "UTF8_GOT_PERL_EXTENDED"
15167               is set if Perl extended UTF-8 is used.
15168
15169               In earlier Perls, this bit was named "UTF8_GOT_ABOVE_31_BIT",
15170               which you still may use for backward compatibility.  That name
15171               is misleading, as this flag may be set when the code point
15172               actually does fit in 31 bits.  This happens on EBCDIC
15173               platforms, and sometimes when the overlong malformation is also
15174               present.  The new name accurately describes the situation in
15175               all cases.
15176
15177           "UTF8_GOT_CONTINUATION"
15178               The input sequence was malformed in that the first byte was a
15179               UTF-8 continuation byte.
15180
15181           "UTF8_GOT_EMPTY"
15182               The input "curlen" parameter was 0.
15183
15184           "UTF8_GOT_LONG"
15185               The input sequence was malformed in that there is some other
15186               sequence that evaluates to the same code point, but that
15187               sequence is shorter than this one.
15188
15189               Until Unicode 3.1, it was legal for programs to accept this
15190               malformation, but it was discovered that this created security
15191               issues.
15192
15193           "UTF8_GOT_NONCHAR"
15194               The code point represented by the input UTF-8 sequence is for a
15195               Unicode non-character code point.  This bit is set only if the
15196               input "flags" parameter contains either the
15197               "UTF8_DISALLOW_NONCHAR" or the "UTF8_WARN_NONCHAR" flags.
15198
15199           "UTF8_GOT_NON_CONTINUATION"
15200               The input sequence was malformed in that a non-continuation
15201               type byte was found in a position where only a continuation
15202               type one should be.  See also "UTF8_GOT_SHORT".
15203
15204           "UTF8_GOT_OVERFLOW"
15205               The input sequence was malformed in that it is for a code point
15206               that is not representable in the number of bits available in an
15207               IV on the current platform.
15208
15209           "UTF8_GOT_SHORT"
15210               The input sequence was malformed in that "curlen" is smaller
15211               than required for a complete sequence.  In other words, the
15212               input is for a partial character sequence.
15213
15214               "UTF8_GOT_SHORT" and "UTF8_GOT_NON_CONTINUATION" both indicate
15215               a too short sequence.  The difference is that
15216               "UTF8_GOT_NON_CONTINUATION" indicates always that there is an
15217               error, while "UTF8_GOT_SHORT" means that an incomplete sequence
15218               was looked at.   If no other flags are present, it means that
15219               the sequence was valid as far as it went.  Depending on the
15220               application, this could mean one of three things:
15221
15222               •   The "curlen" length parameter passed in was too small, and
15223                   the function was prevented from examining all the necessary
15224                   bytes.
15225
15226               •   The buffer being looked at is based on reading data, and
15227                   the data received so far stopped in the middle of a
15228                   character, so that the next read will read the remainder of
15229                   this character.  (It is up to the caller to deal with the
15230                   split bytes somehow.)
15231
15232               •   This is a real error, and the partial sequence is all we're
15233                   going to get.
15234
15235           "UTF8_GOT_SUPER"
15236               The input sequence was malformed in that it is for a non-
15237               Unicode code point; that is, one above the legal Unicode
15238               maximum.  This bit is set only if the input "flags" parameter
15239               contains either the "UTF8_DISALLOW_SUPER" or the
15240               "UTF8_WARN_SUPER" flags.
15241
15242           "UTF8_GOT_SURROGATE"
15243               The input sequence was malformed in that it is for a -Unicode
15244               UTF-16 surrogate code point.  This bit is set only if the input
15245               "flags" parameter contains either the "UTF8_DISALLOW_SURROGATE"
15246               or the "UTF8_WARN_SURROGATE" flags.
15247
15248           To do your own error handling, call this function with the
15249           "UTF8_CHECK_ONLY" flag to suppress any warnings, and then examine
15250           the *errors return.
15251
15252            UV  utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
15253                                     STRLEN *retlen, const U32 flags,
15254                                     U32 * errors)
15255
15256       "utf8n_to_uvchr_msgs"
15257           THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15258           CIRCUMSTANCES.  Most code should use "utf8_to_uvchr_buf"() rather
15259           than call this directly.
15260
15261           This function is for code that needs to know what the precise
15262           malformation(s) are when an error is found, and wants the
15263           corresponding warning and/or error messages to be returned to the
15264           caller rather than be displayed.  All messages that would have been
15265           displayed if all lexical warnings are enabled will be returned.
15266
15267           It is just like "utf8n_to_uvchr_error" but it takes an extra
15268           parameter placed after all the others, "msgs".  If this parameter
15269           is 0, this function behaves identically to "utf8n_to_uvchr_error".
15270           Otherwise, "msgs" should be a pointer to an "AV *" variable, in
15271           which this function creates a new AV to contain any appropriate
15272           messages.  The elements of the array are ordered so that the first
15273           message that would have been displayed is in the 0th element, and
15274           so on.  Each element is a hash with three key-value pairs, as
15275           follows:
15276
15277           "text"
15278               The text of the message as a "SVpv".
15279
15280           "warn_categories"
15281               The warning category (or categories) packed into a "SVuv".
15282
15283           "flag"
15284               A single flag bit associated with this message, in a "SVuv".
15285               The bit corresponds to some bit in the *errors return value,
15286               such as "UTF8_GOT_LONG".
15287
15288           It's important to note that specifying this parameter as non-null
15289           will cause any warnings this function would otherwise generate to
15290           be suppressed, and instead be placed in *msgs.  The caller can
15291           check the lexical warnings state (or not) when choosing what to do
15292           with the returned messages.
15293
15294           If the flag "UTF8_CHECK_ONLY" is passed, no warnings are generated,
15295           and hence no AV is created.
15296
15297           The caller, of course, is responsible for freeing any returned AV.
15298
15299            UV  utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
15300                                    STRLEN *retlen, const U32 flags,
15301                                    U32 * errors, AV ** msgs)
15302
15303       "UTF8SKIP"
15304           returns the number of bytes a non-malformed UTF-8 encoded character
15305           whose first (perhaps only) byte is pointed to by "s".
15306
15307           If there is a possibility of malformed input, use instead:
15308
15309           "UTF8_SAFE_SKIP" if you know the maximum ending pointer in the
15310           buffer pointed to by "s"; or
15311           "UTF8_CHK_SKIP" if you don't know it.
15312
15313           It is better to restructure your code so the end pointer is passed
15314           down so that you know what it actually is at the point of this
15315           call, but if that isn't possible, "UTF8_CHK_SKIP" can minimize the
15316           chance of accessing beyond the end of the input buffer.
15317
15318            STRLEN  UTF8SKIP(char* s)
15319
15320       "UTF8_CHK_SKIP"
15321           This is a safer version of "UTF8SKIP", but still not as safe as
15322           "UTF8_SAFE_SKIP".  This version doesn't blindly assume that the
15323           input string pointed to by "s" is well-formed, but verifies that
15324           there isn't a NUL terminating character before the expected end of
15325           the next character in "s".  The length "UTF8_CHK_SKIP" returns
15326           stops just before any such NUL.
15327
15328           Perl tends to add NULs, as an insurance policy, after the end of
15329           strings in SV's, so it is likely that using this macro will prevent
15330           inadvertent reading beyond the end of the input buffer, even if it
15331           is malformed UTF-8.
15332
15333           This macro is intended to be used by XS modules where the inputs
15334           could be malformed, and it isn't feasible to restructure to use the
15335           safer "UTF8_SAFE_SKIP", for example when interfacing with a C
15336           library.
15337
15338            STRLEN  UTF8_CHK_SKIP(char* s)
15339
15340       "utf8_distance"
15341           Returns the number of UTF-8 characters between the UTF-8 pointers
15342           "a" and "b".
15343
15344           WARNING: use only if you *know* that the pointers point inside the
15345           same UTF-8 buffer.
15346
15347            IV  utf8_distance(const U8 *a, const U8 *b)
15348
15349       "utf8_hop"
15350           Return the UTF-8 pointer "s" displaced by "off" characters, either
15351           forward or backward.
15352
15353           WARNING: do not use the following unless you *know* "off" is within
15354           the UTF-8 data pointed to by "s" *and* that on entry "s" is aligned
15355           on the first byte of character or just after the last byte of a
15356           character.
15357
15358            U8*  utf8_hop(const U8 *s, SSize_t off)
15359
15360       "utf8_hop_back"
15361           Return the UTF-8 pointer "s" displaced by up to "off" characters,
15362           backward.
15363
15364           "off" must be non-positive.
15365
15366           "s" must be after or equal to "start".
15367
15368           When moving backward it will not move before "start".
15369
15370           Will not exceed this limit even if the string is not valid "UTF-8".
15371
15372            U8*  utf8_hop_back(const U8 *s, SSize_t off, const U8 *start)
15373
15374       "utf8_hop_forward"
15375           Return the UTF-8 pointer "s" displaced by up to "off" characters,
15376           forward.
15377
15378           "off" must be non-negative.
15379
15380           "s" must be before or equal to "end".
15381
15382           When moving forward it will not move beyond "end".
15383
15384           Will not exceed this limit even if the string is not valid "UTF-8".
15385
15386            U8*  utf8_hop_forward(const U8 *s, SSize_t off, const U8 *end)
15387
15388       "utf8_hop_safe"
15389           Return the UTF-8 pointer "s" displaced by up to "off" characters,
15390           either forward or backward.
15391
15392           When moving backward it will not move before "start".
15393
15394           When moving forward it will not move beyond "end".
15395
15396           Will not exceed those limits even if the string is not valid
15397           "UTF-8".
15398
15399            U8*  utf8_hop_safe(const U8 *s, SSize_t off, const U8 *start,
15400                               const U8 *end)
15401
15402       "UTF8_IS_INVARIANT"
15403           Evaluates to 1 if the byte "c" represents the same character when
15404           encoded in UTF-8 as when not; otherwise evaluates to 0.  UTF-8
15405           invariant characters can be copied as-is when converting to/from
15406           UTF-8, saving time.
15407
15408           In spite of the name, this macro gives the correct result if the
15409           input string from which "c" comes is not encoded in UTF-8.
15410
15411           See "UVCHR_IS_INVARIANT" for checking if a UV is invariant.
15412
15413            bool  UTF8_IS_INVARIANT(char c)
15414
15415       "UTF8_IS_NONCHAR"
15416           Evaluates to non-zero if the first few bytes of the string starting
15417           at "s" and looking no further than "e - 1" are well-formed UTF-8
15418           that represents one of the Unicode non-character code points;
15419           otherwise it evaluates to 0.  If non-zero, the value gives how many
15420           bytes starting at "s" comprise the code point's representation.
15421
15422            bool  UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
15423
15424       "UTF8_IS_SUPER"
15425           Recall that Perl recognizes an extension to UTF-8 that can encode
15426           code points larger than the ones defined by Unicode, which are
15427           0..0x10FFFF.
15428
15429           This macro evaluates to non-zero if the first few bytes of the
15430           string starting at "s" and looking no further than "e - 1" are from
15431           this UTF-8 extension; otherwise it evaluates to 0.  If non-zero,
15432           the value gives how many bytes starting at "s" comprise the code
15433           point's representation.
15434
15435           0 is returned if the bytes are not well-formed extended UTF-8, or
15436           if they represent a code point that cannot fit in a UV on the
15437           current platform.  Hence this macro can give different results when
15438           run on a 64-bit word machine than on one with a 32-bit word size.
15439
15440           Note that it is illegal to have code points that are larger than
15441           what can fit in an IV on the current machine.
15442
15443            bool  UTF8_IS_SUPER(const U8 *s, const U8 *e)
15444
15445       "UTF8_IS_SURROGATE"
15446           Evaluates to non-zero if the first few bytes of the string starting
15447           at "s" and looking no further than "e - 1" are well-formed UTF-8
15448           that represents one of the Unicode surrogate code points; otherwise
15449           it evaluates to 0.  If non-zero, the value gives how many bytes
15450           starting at "s" comprise the code point's representation.
15451
15452            bool  UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
15453
15454       "utf8_length"
15455           Returns the number of characters in the sequence of UTF-8-encoded
15456           bytes starting at "s" and ending at the byte just before "e".  If
15457           <s> and <e> point to the same place, it returns 0 with no warning
15458           raised.
15459
15460           If "e < s" or if the scan would end up past "e", it raises a UTF8
15461           warning and returns the number of valid characters.
15462
15463            STRLEN  utf8_length(const U8* s, const U8 *e)
15464
15465       "UTF8_MAXBYTES"
15466           The maximum width of a single UTF-8 encoded character, in bytes.
15467
15468           NOTE: Strictly speaking Perl's UTF-8 should not be called UTF-8
15469           since UTF-8 is an encoding of Unicode, and Unicode's upper limit,
15470           0x10FFFF, can be expressed with 4 bytes.  However, Perl thinks of
15471           UTF-8 as a way to encode non-negative integers in a binary format,
15472           even those above Unicode.
15473
15474       "UTF8_MAXBYTES_CASE"
15475           The maximum number of UTF-8 bytes a single Unicode character can
15476           uppercase/lowercase/titlecase/fold into.
15477
15478       "UTF8_SAFE_SKIP"
15479           returns 0 if "s >= e"; otherwise returns the number of bytes in the
15480           UTF-8 encoded character whose first  byte is pointed to by "s".
15481           But it never returns beyond "e".  On DEBUGGING builds, it asserts
15482           that "s <= e".
15483
15484            STRLEN  UTF8_SAFE_SKIP(char* s, char* e)
15485
15486       "UTF8_SKIP"
15487           This is a synonym for "UTF8SKIP"
15488
15489            STRLEN  UTF8_SKIP(char* s)
15490
15491       "utf8_to_bytes"
15492           NOTE: "utf8_to_bytes" is experimental and may change or be removed
15493           without notice.
15494
15495           Converts a string "s" of length *lenp from UTF-8 into native byte
15496           encoding.  Unlike "bytes_to_utf8", this over-writes the original
15497           string, and updates *lenp to contain the new length.  Returns zero
15498           on failure (leaving "s" unchanged) setting *lenp to -1.
15499
15500           Upon successful return, the number of variants in the string can be
15501           computed by having saved the value of *lenp before the call, and
15502           subtracting the after-call value of *lenp from it.
15503
15504           If you need a copy of the string, see "bytes_from_utf8".
15505
15506            U8*  utf8_to_bytes(U8 *s, STRLEN *lenp)
15507
15508       "utf8_to_uvchr"
15509           "DEPRECATED!"  It is planned to remove "utf8_to_uvchr" from a
15510           future release of Perl.  Do not use it for new code; remove it from
15511           existing code.
15512
15513           Returns the native code point of the first character in the string
15514           "s" which is assumed to be in UTF-8 encoding; "retlen" will be set
15515           to the length, in bytes, of that character.
15516
15517           Some, but not all, UTF-8 malformations are detected, and in fact,
15518           some malformed input could cause reading beyond the end of the
15519           input buffer, which is why this function is deprecated.  Use
15520           "utf8_to_uvchr_buf" instead.
15521
15522           If "s" points to one of the detected malformations, and UTF8
15523           warnings are enabled, zero is returned and *retlen is set (if
15524           "retlen" isn't "NULL") to -1.  If those warnings are off, the
15525           computed value if well-defined (or the Unicode REPLACEMENT
15526           CHARACTER, if not) is silently returned, and *retlen is set (if
15527           "retlen" isn't NULL) so that ("s" + *retlen) is the next possible
15528           position in "s" that could begin a non-malformed character.  See
15529           "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is
15530           returned.
15531
15532            UV  utf8_to_uvchr(const U8 *s, STRLEN *retlen)
15533
15534       "utf8_to_uvchr_buf"
15535           Returns the native code point of the first character in the string
15536           "s" which is assumed to be in UTF-8 encoding; "send" points to 1
15537           beyond the end of "s".  *retlen will be set to the length, in
15538           bytes, of that character.
15539
15540           If "s" does not point to a well-formed UTF-8 character and UTF8
15541           warnings are enabled, zero is returned and *retlen is set (if
15542           "retlen" isn't "NULL") to -1.  If those warnings are off, the
15543           computed value, if well-defined (or the Unicode REPLACEMENT
15544           CHARACTER if not), is silently returned, and *retlen is set (if
15545           "retlen" isn't "NULL") so that ("s" + *retlen) is the next possible
15546           position in "s" that could begin a non-malformed character.  See
15547           "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is
15548           returned.
15549
15550            UV  utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen)
15551
15552       "UVCHR_IS_INVARIANT"
15553           Evaluates to 1 if the representation of code point "cp" is the same
15554           whether or not it is encoded in UTF-8; otherwise evaluates to 0.
15555           UTF-8 invariant characters can be copied as-is when converting
15556           to/from UTF-8, saving time.  "cp" is Unicode if above 255;
15557           otherwise is platform-native.
15558
15559            bool  UVCHR_IS_INVARIANT(UV cp)
15560
15561       "UVCHR_SKIP"
15562           returns the number of bytes required to represent the code point
15563           "cp" when encoded as UTF-8.  "cp" is a native (ASCII or EBCDIC)
15564           code point if less than 255; a Unicode code point otherwise.
15565
15566            STRLEN  UVCHR_SKIP(UV cp)
15567
15568       "uvchr_to_utf8"
15569           Adds the UTF-8 representation of the native code point "uv" to the
15570           end of the string "d"; "d" should have at least "UVCHR_SKIP(uv)+1"
15571           (up to "UTF8_MAXBYTES+1") free bytes available.  The return value
15572           is the pointer to the byte after the end of the new character.  In
15573           other words,
15574
15575               d = uvchr_to_utf8(d, uv);
15576
15577           is the recommended wide native character-aware way of saying
15578
15579               *(d++) = uv;
15580
15581           This function accepts any code point from 0.."IV_MAX" as input.
15582           "IV_MAX" is typically 0x7FFF_FFFF in a 32-bit word.
15583
15584           It is possible to forbid or warn on non-Unicode code points, or
15585           those that may be problematic by using "uvchr_to_utf8_flags".
15586
15587            U8*  uvchr_to_utf8(U8 *d, UV uv)
15588
15589       "uvchr_to_utf8_flags"
15590           Adds the UTF-8 representation of the native code point "uv" to the
15591           end of the string "d"; "d" should have at least "UVCHR_SKIP(uv)+1"
15592           (up to "UTF8_MAXBYTES+1") free bytes available.  The return value
15593           is the pointer to the byte after the end of the new character.  In
15594           other words,
15595
15596               d = uvchr_to_utf8_flags(d, uv, flags);
15597
15598           or, in most cases,
15599
15600               d = uvchr_to_utf8_flags(d, uv, 0);
15601
15602           This is the Unicode-aware way of saying
15603
15604               *(d++) = uv;
15605
15606           If "flags" is 0, this function accepts any code point from
15607           0.."IV_MAX" as input.  "IV_MAX" is typically 0x7FFF_FFFF in a
15608           32-bit word.
15609
15610           Specifying "flags" can further restrict what is allowed and not
15611           warned on, as follows:
15612
15613           If "uv" is a Unicode surrogate code point and
15614           "UNICODE_WARN_SURROGATE" is set, the function will raise a warning,
15615           provided UTF8 warnings are enabled.  If instead
15616           "UNICODE_DISALLOW_SURROGATE" is set, the function will fail and
15617           return NULL.  If both flags are set, the function will both warn
15618           and return NULL.
15619
15620           Similarly, the "UNICODE_WARN_NONCHAR" and
15621           "UNICODE_DISALLOW_NONCHAR" flags affect how the function handles a
15622           Unicode non-character.
15623
15624           And likewise, the "UNICODE_WARN_SUPER" and "UNICODE_DISALLOW_SUPER"
15625           flags affect the handling of code points that are above the Unicode
15626           maximum of 0x10FFFF.  Languages other than Perl may not be able to
15627           accept files that contain these.
15628
15629           The flag "UNICODE_WARN_ILLEGAL_INTERCHANGE" selects all three of
15630           the above WARN flags; and "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE"
15631           selects all three DISALLOW flags.
15632           "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed inputs
15633           to the strict UTF-8 traditionally defined by Unicode.  Similarly,
15634           "UNICODE_WARN_ILLEGAL_C9_INTERCHANGE" and
15635           "UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE" are shortcuts to select
15636           the above-Unicode and surrogate flags, but not the non-character
15637           ones, as defined in Unicode Corrigendum #9
15638           <https://www.unicode.org/versions/corrigendum9.html>.  See
15639           "Noncharacter code points" in perlunicode.
15640
15641           Extremely high code points were never specified in any standard,
15642           and require an extension to UTF-8 to express, which Perl does.  It
15643           is likely that programs written in something other than Perl would
15644           not be able to read files that contain these; nor would Perl
15645           understand files written by something that uses a different
15646           extension.  For these reasons, there is a separate set of flags
15647           that can warn and/or disallow these extremely high code points,
15648           even if other above-Unicode ones are accepted.  They are the
15649           "UNICODE_WARN_PERL_EXTENDED" and "UNICODE_DISALLOW_PERL_EXTENDED"
15650           flags.  For more information see "UTF8_GOT_PERL_EXTENDED".  Of
15651           course "UNICODE_DISALLOW_SUPER" will treat all above-Unicode code
15652           points, including these, as malformations.  (Note that the Unicode
15653           standard considers anything above 0x10FFFF to be illegal, but there
15654           are standards predating it that allow up to 0x7FFF_FFFF (2**31 -1))
15655
15656           A somewhat misleadingly named synonym for
15657           "UNICODE_WARN_PERL_EXTENDED" is retained for backward
15658           compatibility: "UNICODE_WARN_ABOVE_31_BIT".  Similarly,
15659           "UNICODE_DISALLOW_ABOVE_31_BIT" is usable instead of the more
15660           accurately named "UNICODE_DISALLOW_PERL_EXTENDED".  The names are
15661           misleading because on EBCDIC platforms,these flags can apply to
15662           code points that actually do fit in 31 bits.  The new names
15663           accurately describe the situation in all cases.
15664
15665            U8*  uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
15666
15667       "uvchr_to_utf8_flags_msgs"
15668           THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15669           CIRCUMSTANCES.
15670
15671           Most code should use ""uvchr_to_utf8_flags"()" rather than call
15672           this directly.
15673
15674           This function is for code that wants any warning and/or error
15675           messages to be returned to the caller rather than be displayed.
15676           All messages that would have been displayed if all lexical warnings
15677           are enabled will be returned.
15678
15679           It is just like "uvchr_to_utf8_flags" but it takes an extra
15680           parameter placed after all the others, "msgs".  If this parameter
15681           is 0, this function behaves identically to "uvchr_to_utf8_flags".
15682           Otherwise, "msgs" should be a pointer to an "HV *" variable, in
15683           which this function creates a new HV to contain any appropriate
15684           messages.  The hash has three key-value pairs, as follows:
15685
15686           "text"
15687               The text of the message as a "SVpv".
15688
15689           "warn_categories"
15690               The warning category (or categories) packed into a "SVuv".
15691
15692           "flag"
15693               A single flag bit associated with this message, in a "SVuv".
15694               The bit corresponds to some bit in the *errors return value,
15695               such as "UNICODE_GOT_SURROGATE".
15696
15697           It's important to note that specifying this parameter as non-null
15698           will cause any warnings this function would otherwise generate to
15699           be suppressed, and instead be placed in *msgs.  The caller can
15700           check the lexical warnings state (or not) when choosing what to do
15701           with the returned messages.
15702
15703           The caller, of course, is responsible for freeing any returned HV.
15704
15705            U8*  uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags, HV ** msgs)
15706

Utility Functions

15708       "C_ARRAY_END"
15709           Returns a pointer to one element past the final element of the
15710           input C array.
15711
15712            void *  C_ARRAY_END(void *a)
15713
15714       "C_ARRAY_LENGTH"
15715           Returns the number of elements in the input C array (so you want
15716           your zero-based indices to be less than but not equal to).
15717
15718            STRLEN  C_ARRAY_LENGTH(void *a)
15719
15720       "getcwd_sv"
15721           Fill "sv" with current working directory
15722
15723            int  getcwd_sv(SV* sv)
15724
15725       "IN_PERL_COMPILETIME"
15726           Returns 1 if this macro is being called during the compilation
15727           phase of the program; otherwise 0;
15728
15729            bool  IN_PERL_COMPILETIME
15730
15731       "IN_PERL_RUNTIME"
15732           Returns 1 if this macro is being called during the execution phase
15733           of the program; otherwise 0;
15734
15735            bool  IN_PERL_RUNTIME
15736
15737       "IS_SAFE_SYSCALL"
15738           Same as "is_safe_syscall".
15739
15740            bool  IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
15741                                  NN const char *what, NN const char *op_name)
15742
15743       "is_safe_syscall"
15744           Test that the given "pv" (with length "len") doesn't contain any
15745           internal "NUL" characters.  If it does, set "errno" to "ENOENT",
15746           optionally warn using the "syscalls" category, and return FALSE.
15747
15748           Return TRUE if the name is safe.
15749
15750           "what" and "op_name" are used in any warning.
15751
15752           Used by the "IS_SAFE_SYSCALL()" macro.
15753
15754            bool  is_safe_syscall(const char *pv, STRLEN len,
15755                                  const char *what, const char *op_name)
15756
15757       "my_setenv"
15758           A wrapper for the C library setenv(3).  Don't use the latter, as
15759           the perl version has desirable safeguards
15760
15761            void  my_setenv(const char* nam, const char* val)
15762
15763       "Poison"
15764           PoisonWith(0xEF) for catching access to freed memory.
15765
15766            void  Poison(void* dest, int nitems, type)
15767
15768       "PoisonFree"
15769           PoisonWith(0xEF) for catching access to freed memory.
15770
15771            void  PoisonFree(void* dest, int nitems, type)
15772
15773       "PoisonNew"
15774           PoisonWith(0xAB) for catching access to allocated but uninitialized
15775           memory.
15776
15777            void  PoisonNew(void* dest, int nitems, type)
15778
15779       "PoisonWith"
15780           Fill up memory with a byte pattern (a byte repeated over and over
15781           again) that hopefully catches attempts to access uninitialized
15782           memory.
15783
15784            void  PoisonWith(void* dest, int nitems, type, U8 byte)
15785
15786       "StructCopy"
15787           This is an architecture-independent macro to copy one structure to
15788           another.
15789
15790            void  StructCopy(type *src, type *dest, type)
15791
15792       "sv_destroyable"
15793           Dummy routine which reports that object can be destroyed when there
15794           is no sharing module present.  It ignores its single SV argument,
15795           and returns 'true'.  Exists to avoid test for a "NULL" function
15796           pointer and because it could potentially warn under some level of
15797           strict-ness.
15798
15799            bool  sv_destroyable(SV *sv)
15800
15801       "sv_nosharing"
15802           Dummy routine which "shares" an SV when there is no sharing module
15803           present.  Or "locks" it.  Or "unlocks" it.  In other words, ignores
15804           its single SV argument.  Exists to avoid test for a "NULL" function
15805           pointer and because it could potentially warn under some level of
15806           strict-ness.
15807
15808            void  sv_nosharing(SV *sv)
15809

Versioning

15811       "new_version"
15812           Returns a new version object based on the passed in SV:
15813
15814               SV *sv = new_version(SV *ver);
15815
15816           Does not alter the passed in ver SV.  See "upg_version" if you want
15817           to upgrade the SV.
15818
15819            SV*  new_version(SV *ver)
15820
15821       "PERL_REVISION"
15822           "DEPRECATED!"  It is planned to remove "PERL_REVISION" from a
15823           future release of Perl.  Do not use it for new code; remove it from
15824           existing code.
15825
15826           The major number component of the perl interpreter currently being
15827           compiled or executing.  This has been 5 from 1993 into 2020.
15828
15829           Instead use one of the version comparison macros.  See
15830           "PERL_VERSION_EQ".
15831
15832       "PERL_SUBVERSION"
15833           "DEPRECATED!"  It is planned to remove "PERL_SUBVERSION" from a
15834           future release of Perl.  Do not use it for new code; remove it from
15835           existing code.
15836
15837           The micro number component of the perl interpreter currently being
15838           compiled or executing.  In stable releases this gives the dot
15839           release number for maintenance updates.  In development releases
15840           this gives a tag for a snapshot of the status at various points in
15841           the development cycle.
15842
15843           Instead use one of the version comparison macros.  See
15844           "PERL_VERSION_EQ".
15845
15846       "PERL_VERSION"
15847           "DEPRECATED!"  It is planned to remove "PERL_VERSION" from a future
15848           release of Perl.  Do not use it for new code; remove it from
15849           existing code.
15850
15851           The minor number component of the perl interpreter currently being
15852           compiled or executing.  Between 1993 into 2020, this has ranged
15853           from 0 to 33.
15854
15855           Instead use one of the version comparison macros.  See
15856           "PERL_VERSION_EQ".
15857
15858       "PERL_VERSION_EQ"
15859       "PERL_VERSION_NE"
15860       "PERL_VERSION_LT"
15861       "PERL_VERSION_LE"
15862       "PERL_VERSION_GT"
15863       "PERL_VERSION_GE"
15864           Returns whether or not the perl currently being compiled has the
15865           specified relationship to the perl given by the parameters.  For
15866           example,
15867
15868            #if PERL_VERSION_GT(5,24,2)
15869              code that will only be compiled on perls after v5.24.2
15870            #else
15871              fallback code
15872            #endif
15873
15874           Note that this is usable in making compile-time decisions
15875
15876           You may use the special value '*' for the final number to mean ALL
15877           possible values for it.  Thus,
15878
15879            #if PERL_VERSION_EQ(5,31,'*')
15880
15881           means all perls in the 5.31 series.  And
15882
15883            #if PERL_VERSION_NE(5,24,'*')
15884
15885           means all perls EXCEPT 5.24 ones.  And
15886
15887            #if PERL_VERSION_LE(5,9,'*')
15888
15889           is effectively
15890
15891            #if PERL_VERSION_LT(5,10,0)
15892
15893           This means you don't have to think so much when converting from the
15894           existing deprecated "PERL_VERSION" to using this macro:
15895
15896            #if PERL_VERSION <= 9
15897
15898           becomes
15899
15900            #if PERL_VERSION_LE(5,9,'*')
15901
15902            bool  PERL_VERSION_EQ(const U8 major, const U8 minor,
15903                                  const U8 patch)
15904
15905       "prescan_version"
15906           Validate that a given string can be parsed as a version object, but
15907           doesn't actually perform the parsing.  Can use either strict or lax
15908           validation rules.  Can optionally set a number of hint variables to
15909           save the parsing code some time when tokenizing.
15910
15911            const char*  prescan_version(const char *s, bool strict,
15912                                         const char** errstr, bool *sqv,
15913                                         int *ssaw_decimal, int *swidth,
15914                                         bool *salpha)
15915
15916       "scan_version"
15917           Returns a pointer to the next character after the parsed version
15918           string, as well as upgrading the passed in SV to an RV.
15919
15920           Function must be called with an already existing SV like
15921
15922               sv = newSV(0);
15923               s = scan_version(s, SV *sv, bool qv);
15924
15925           Performs some preprocessing to the string to ensure that it has the
15926           correct characteristics of a version.  Flags the object if it
15927           contains an underscore (which denotes this is an alpha version).
15928           The boolean qv denotes that the version should be interpreted as if
15929           it had multiple decimals, even if it doesn't.
15930
15931            const char*  scan_version(const char *s, SV *rv, bool qv)
15932
15933       "upg_version"
15934           In-place upgrade of the supplied SV to a version object.
15935
15936               SV *sv = upg_version(SV *sv, bool qv);
15937
15938           Returns a pointer to the upgraded SV.  Set the boolean qv if you
15939           want to force this SV to be interpreted as an "extended" version.
15940
15941            SV*  upg_version(SV *ver, bool qv)
15942
15943       "vcmp"
15944           Version object aware cmp.  Both operands must already have been
15945           converted into version objects.
15946
15947            int  vcmp(SV *lhv, SV *rhv)
15948
15949       "vnormal"
15950           Accepts a version object and returns the normalized string
15951           representation.  Call like:
15952
15953               sv = vnormal(rv);
15954
15955           NOTE: you can pass either the object directly or the SV contained
15956           within the RV.
15957
15958           The SV returned has a refcount of 1.
15959
15960            SV*  vnormal(SV *vs)
15961
15962       "vnumify"
15963           Accepts a version object and returns the normalized floating point
15964           representation.  Call like:
15965
15966               sv = vnumify(rv);
15967
15968           NOTE: you can pass either the object directly or the SV contained
15969           within the RV.
15970
15971           The SV returned has a refcount of 1.
15972
15973            SV*  vnumify(SV *vs)
15974
15975       "vstringify"
15976           In order to maintain maximum compatibility with earlier versions of
15977           Perl, this function will return either the floating point notation
15978           or the multiple dotted notation, depending on whether the original
15979           version contained 1 or more dots, respectively.
15980
15981           The SV returned has a refcount of 1.
15982
15983            SV*  vstringify(SV *vs)
15984
15985       "vverify"
15986           Validates that the SV contains valid internal structure for a
15987           version object.  It may be passed either the version object (RV) or
15988           the hash itself (HV).  If the structure is valid, it returns the
15989           HV.  If the structure is invalid, it returns NULL.
15990
15991               SV *hv = vverify(sv);
15992
15993           Note that it only confirms the bare minimum structure (so as not to
15994           get confused by derived classes which may contain additional hash
15995           entries):
15996
15997           •   The SV is an HV or a reference to an HV
15998
15999           •   The hash contains a "version" key
16000
16001           •   The "version" key has a reference to an AV as its value
16002
16003            SV*  vverify(SV *vs)
16004

Warning and Dieing

16006       In all these calls, the "U32 wn" parameters are warning category
16007       constants.  You can see the ones currently available in "Category
16008       Hierarchy" in warnings, just capitalize all letters in the names and
16009       prefix them by "WARN_".  So, for example, the category "void" used in a
16010       perl program becomes "WARN_VOID" when used in XS code and passed to one
16011       of the calls below.
16012
16013       "ckWARN"
16014       "ckWARN2"
16015       "ckWARN3"
16016       "ckWARN4"
16017           These return a boolean as to whether or not warnings are enabled
16018           for any of the warning category(ies) parameters:  "w", "w1", ....
16019
16020           Should any of the categories by default be enabled even if not
16021           within the scope of "use warnings", instead use the "ckWARN_d"
16022           macros.
16023
16024           The categories must be completely independent, one may not be
16025           subclassed from the other.
16026
16027            bool  ckWARN (U32 w)
16028            bool  ckWARN2(U32 w1, U32 w2)
16029            bool  ckWARN3(U32 w1, U32 w2, U32 w3)
16030            bool  ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
16031
16032       "ckWARN_d"
16033       "ckWARN2_d"
16034       "ckWARN3_d"
16035       "ckWARN4_d"
16036           Like "ckWARN", but for use if and only if the warning category(ies)
16037           is by default enabled even if not within the scope of
16038           "use warnings".
16039
16040            bool  ckWARN_d (U32 w)
16041            bool  ckWARN2_d(U32 w1, U32 w2)
16042            bool  ckWARN3_d(U32 w1, U32 w2, U32 w3)
16043            bool  ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
16044
16045       "ck_warner"
16046       "ck_warner_d"
16047           If none of the warning categories given by "err" are enabled, do
16048           nothing; otherwise call "warner"  or "warner_nocontext" with the
16049           passed-in parameters;.
16050
16051           "err" must be one of the "packWARN", "packWARN2", "packWARN3",
16052           "packWARN4" macros populated with the appropriate number of warning
16053           categories.
16054
16055           The two forms differ only in that "ck_warner_d" should be used if
16056           warnings for any of the categories are by default enabled.
16057
16058           NOTE: "ck_warner" must be explicitly called as "Perl_ck_warner"
16059           with an "aTHX_" parameter.
16060
16061           NOTE: "ck_warner_d" must be explicitly called as "Perl_ck_warner_d"
16062           with an "aTHX_" parameter.
16063
16064            void  Perl_ck_warner(pTHX_ U32 err, const char* pat, ...)
16065
16066       "CLEAR_ERRSV"
16067           Clear the contents of $@, setting it to the empty string.
16068
16069           This replaces any read-only SV with a fresh SV and removes any
16070           magic.
16071
16072            void  CLEAR_ERRSV()
16073
16074       "croak"
16075       "croak_nocontext"
16076           These are XS interfaces to Perl's "die" function.
16077
16078           They take a sprintf-style format pattern and argument list, which
16079           are used to generate a string message.  If the message does not end
16080           with a newline, then it will be extended with some indication of
16081           the current location in the code, as described for "mess_sv".
16082
16083           The error message will be used as an exception, by default
16084           returning control to the nearest enclosing "eval", but subject to
16085           modification by a $SIG{__DIE__} handler.  In any case, these croak
16086           functions never return normally.
16087
16088           For historical reasons, if "pat" is null then the contents of
16089           "ERRSV" ($@) will be used as an error message or object instead of
16090           building an error message from arguments.  If you want to throw a
16091           non-string object, or build an error message in an SV yourself, it
16092           is preferable to use the "croak_sv" function, which does not
16093           involve clobbering "ERRSV".
16094
16095           The two forms differ only in that "croak_nocontext" does not take a
16096           thread context ("aTHX") parameter.  It is usually preferred as it
16097           takes up fewer bytes of code than plain "Perl_croak", and time is
16098           rarely a critical resource when you are about to throw an
16099           exception.
16100
16101           NOTE: "croak" must be explicitly called as "Perl_croak" with an
16102           "aTHX_" parameter.
16103
16104            void  Perl_croak     (pTHX_ const char* pat, ...)
16105            void  croak_nocontext(const char* pat, ...)
16106
16107       "croak_no_modify"
16108           This encapsulates a common reason for dying, generating terser
16109           object code than using the generic "Perl_croak".  It is exactly
16110           equivalent to "Perl_croak(aTHX_ "%s", PL_no_modify)" (which expands
16111           to something like "Modification of a read-only value attempted").
16112
16113           Less code used on exception code paths reduces CPU cache pressure.
16114
16115            void  croak_no_modify()
16116
16117       "croak_sv"
16118           This is an XS interface to Perl's "die" function.
16119
16120           "baseex" is the error message or object.  If it is a reference, it
16121           will be used as-is.  Otherwise it is used as a string, and if it
16122           does not end with a newline then it will be extended with some
16123           indication of the current location in the code, as described for
16124           "mess_sv".
16125
16126           The error message or object will be used as an exception, by
16127           default returning control to the nearest enclosing "eval", but
16128           subject to modification by a $SIG{__DIE__} handler.  In any case,
16129           the "croak_sv" function never returns normally.
16130
16131           To die with a simple string message, the "croak" function may be
16132           more convenient.
16133
16134            void  croak_sv(SV *baseex)
16135
16136       "die"
16137           Behaves the same as "croak", except for the return type.  It should
16138           be used only where the "OP *" return type is required.  The
16139           function never actually returns.
16140
16141           NOTE: "die" must be explicitly called as "Perl_die" with an "aTHX_"
16142           parameter.
16143
16144            OP*  Perl_die(pTHX_ const char* pat, ...)
16145
16146       "die_sv"
16147       "die_nocontext"
16148           These ehave the same as "croak_sv", except for the return type.  It
16149           should be used only where the "OP *" return type is required.  The
16150           functions never actually return.
16151
16152           The two forms differ only in that "die_nocontext" does not take a
16153           thread context ("aTHX") parameter, so is used in situations where
16154           the caller doesn't already have the thread context.
16155
16156            OP*  die_sv       (SV *baseex)
16157            OP*  die_nocontext(const char* pat, ...)
16158
16159       "ERRSV"
16160           Returns the SV for $@, creating it if needed.
16161
16162            SV *  ERRSV
16163
16164       "packWARN"
16165       "packWARN2"
16166       "packWARN3"
16167       "packWARN4"
16168           These macros are used to pack warning categories into a single U32
16169           to pass to macros and functions that take a warning category
16170           parameter.  The number of categories to pack is given by the name,
16171           with a corresponding number of category parameters passed.
16172
16173            U32  packWARN (U32 w1)
16174            U32  packWARN2(U32 w1, U32 w2)
16175            U32  packWARN3(U32 w1, U32 w2, U32 w3)
16176            U32  packWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
16177
16178       "PL_curcop"
16179           The currently active COP (control op) roughly representing the
16180           current statement in the source.
16181
16182           On threaded perls, each thread has an independent copy of this
16183           variable; each initialized at creation time with the current value
16184           of the creating thread's copy.
16185
16186            COP*  PL_curcop
16187
16188       "PL_curstash"
16189           The stash for the package code will be compiled into.
16190
16191           On threaded perls, each thread has an independent copy of this
16192           variable; each initialized at creation time with the current value
16193           of the creating thread's copy.
16194
16195            HV*  PL_curstash
16196
16197       "PL_defgv"
16198           The GV representing *_.  Useful for access to $_.
16199
16200           On threaded perls, each thread has an independent copy of this
16201           variable; each initialized at creation time with the current value
16202           of the creating thread's copy.
16203
16204            GV *  PL_defgv
16205
16206       "SANE_ERRSV"
16207           Clean up ERRSV so we can safely set it.
16208
16209           This replaces any read-only SV with a fresh writable copy and
16210           removes any magic.
16211
16212            void  SANE_ERRSV()
16213
16214       "vcroak"
16215           This is an XS interface to Perl's "die" function.
16216
16217           "pat" and "args" are a sprintf-style format pattern and
16218           encapsulated argument list.  These are used to generate a string
16219           message.  If the message does not end with a newline, then it will
16220           be extended with some indication of the current location in the
16221           code, as described for "mess_sv".
16222
16223           The error message will be used as an exception, by default
16224           returning control to the nearest enclosing "eval", but subject to
16225           modification by a $SIG{__DIE__} handler.  In any case, the "croak"
16226           function never returns normally.
16227
16228           For historical reasons, if "pat" is null then the contents of
16229           "ERRSV" ($@) will be used as an error message or object instead of
16230           building an error message from arguments.  If you want to throw a
16231           non-string object, or build an error message in an SV yourself, it
16232           is preferable to use the "croak_sv" function, which does not
16233           involve clobbering "ERRSV".
16234
16235            void  vcroak(const char* pat, va_list* args)
16236
16237       "vwarn"
16238           This is an XS interface to Perl's "warn" function.
16239
16240           This is like "warn", but "args" are an encapsulated argument list.
16241
16242           Unlike with "vcroak", "pat" is not permitted to be null.
16243
16244            void  vwarn(const char* pat, va_list* args)
16245
16246       "vwarner"
16247           This is like "warner", but "args" are an encapsulated argument
16248           list.
16249
16250            void  vwarner(U32 err, const char* pat, va_list* args)
16251
16252       "warn"
16253       "warn_nocontext"
16254           These are XS interfaces to Perl's "warn" function.
16255
16256           They take a sprintf-style format pattern and argument list, which
16257           are used to generate a string message.  If the message does not end
16258           with a newline, then it will be extended with some indication of
16259           the current location in the code, as described for "mess_sv".
16260
16261           The error message or object will by default be written to standard
16262           error, but this is subject to modification by a $SIG{__WARN__}
16263           handler.
16264
16265           Unlike with "croak", "pat" is not permitted to be null.
16266
16267           The two forms differ only in that "warn_nocontext" does not take a
16268           thread context ("aTHX") parameter, so is used in situations where
16269           the caller doesn't already have the thread context.
16270
16271           NOTE: "warn" must be explicitly called as "Perl_warn" with an
16272           "aTHX_" parameter.
16273
16274            void  Perl_warn     (pTHX_ const char* pat, ...)
16275            void  warn_nocontext(const char* pat, ...)
16276
16277       "warner"
16278       "warner_nocontext"
16279           These output a warning of the specified category (or categories)
16280           given by "err", using the sprintf-style format pattern "pat", and
16281           argument list.
16282
16283           "err" must be one of the "packWARN", "packWARN2", "packWARN3",
16284           "packWARN4" macros populated with the appropriate number of warning
16285           categories.  If any of the warning categories they specify is
16286           fatal, a fatal exception is thrown.
16287
16288           In any event a message is generated by the pattern and arguments.
16289           If the message does not end with a newline, then it will be
16290           extended with some indication of the current location in the code,
16291           as described for "mess_sv".
16292
16293           The error message or object will by default be written to standard
16294           error, but this is subject to modification by a $SIG{__WARN__}
16295           handler.
16296
16297           "pat" is not permitted to be null.
16298
16299           The two forms differ only in that "warner_nocontext" does not take
16300           a thread context ("aTHX") parameter, so is used in situations where
16301           the caller doesn't already have the thread context.
16302
16303           These functions differ from the similarly named "warn" functions,
16304           in that the latter are for XS code to unconditionally display a
16305           warning, whereas these are for code that may be compiling a perl
16306           program, and does extra checking to see if the warning should be
16307           fatal.
16308
16309           NOTE: "warner" must be explicitly called as "Perl_warner" with an
16310           "aTHX_" parameter.
16311
16312            void  Perl_warner     (pTHX_ U32 err, const char* pat, ...)
16313            void  warner_nocontext(U32 err, const char* pat, ...)
16314
16315       "warn_sv"
16316           This is an XS interface to Perl's "warn" function.
16317
16318           "baseex" is the error message or object.  If it is a reference, it
16319           will be used as-is.  Otherwise it is used as a string, and if it
16320           does not end with a newline then it will be extended with some
16321           indication of the current location in the code, as described for
16322           "mess_sv".
16323
16324           The error message or object will by default be written to standard
16325           error, but this is subject to modification by a $SIG{__WARN__}
16326           handler.
16327
16328           To warn with a simple string message, the "warn" function may be
16329           more convenient.
16330
16331            void  warn_sv(SV *baseex)
16332

XS

16334       xsubpp compiles XS code into C.  See "xsubpp" in perlutil.
16335
16336       "ax"
16337           Variable which is setup by "xsubpp" to indicate the stack base
16338           offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros.  The
16339           "dMARK" macro must be called prior to setup the "MARK" variable.
16340
16341            I32  ax
16342
16343       "CLASS"
16344           Variable which is setup by "xsubpp" to indicate the class name for
16345           a C++ XS constructor.  This is always a "char*".  See "THIS".
16346
16347            char*  CLASS
16348
16349       "dAX"
16350           Sets up the "ax" variable.  This is usually handled automatically
16351           by "xsubpp" by calling "dXSARGS".
16352
16353              dAX;
16354
16355       "dAXMARK"
16356           Sets up the "ax" variable and stack marker variable "mark".  This
16357           is usually handled automatically by "xsubpp" by calling "dXSARGS".
16358
16359              dAXMARK;
16360
16361       "dITEMS"
16362           Sets up the "items" variable.  This is usually handled
16363           automatically by "xsubpp" by calling "dXSARGS".
16364
16365              dITEMS;
16366
16367       "dMY_CXT_SV"
16368           Now a placeholder that declares nothing
16369
16370              dMY_CXT_SV;
16371
16372       "dUNDERBAR"
16373           Sets up any variable needed by the "UNDERBAR" macro.  It used to
16374           define "padoff_du", but it is currently a noop.  However, it is
16375           strongly advised to still use it for ensuring past and future
16376           compatibility.
16377
16378              dUNDERBAR;
16379
16380       "dXSARGS"
16381           Sets up stack and mark pointers for an XSUB, calling "dSP" and
16382           "dMARK".  Sets up the "ax" and "items" variables by calling "dAX"
16383           and "dITEMS".  This is usually handled automatically by "xsubpp".
16384
16385              dXSARGS;
16386
16387       "dXSI32"
16388           Sets up the "ix" variable for an XSUB which has aliases.  This is
16389           usually handled automatically by "xsubpp".
16390
16391              dXSI32;
16392
16393       "items"
16394           Variable which is setup by "xsubpp" to indicate the number of items
16395           on the stack.  See "Variable-length Parameter Lists" in perlxs.
16396
16397            I32  items
16398
16399       "ix"
16400           Variable which is setup by "xsubpp" to indicate which of an XSUB's
16401           aliases was used to invoke it.  See "The ALIAS: Keyword" in perlxs.
16402
16403            I32  ix
16404
16405       "RETVAL"
16406           Variable which is setup by "xsubpp" to hold the return value for an
16407           XSUB.  This is always the proper type for the XSUB.  See "The
16408           RETVAL Variable" in perlxs.
16409
16410            type  RETVAL
16411
16412       "ST"
16413           Used to access elements on the XSUB's stack.
16414
16415            SV*  ST(int ix)
16416
16417       "THIS"
16418           Variable which is setup by "xsubpp" to designate the object in a
16419           C++ XSUB.  This is always the proper type for the C++ object.  See
16420           "CLASS" and "Using XS With C++" in perlxs.
16421
16422            type  THIS
16423
16424       "UNDERBAR"
16425           The SV* corresponding to the $_ variable.  Works even if there is a
16426           lexical $_ in scope.
16427
16428       "XS"
16429           Macro to declare an XSUB and its C parameter list.  This is handled
16430           by "xsubpp".  It is the same as using the more explicit
16431           "XS_EXTERNAL" macro; the latter is preferred.
16432
16433       "XS_EXTERNAL"
16434           Macro to declare an XSUB and its C parameter list explicitly
16435           exporting the symbols.
16436
16437       "XS_INTERNAL"
16438           Macro to declare an XSUB and its C parameter list without exporting
16439           the symbols.  This is handled by "xsubpp" and generally preferable
16440           over exporting the XSUB symbols unnecessarily.
16441
16442       "XSPROTO"
16443           Macro used by "XS_INTERNAL" and "XS_EXTERNAL" to declare a function
16444           prototype.  You probably shouldn't be using this directly yourself.
16445

Undocumented elements

16447       The following functions have been flagged as part of the public API,
16448       but are currently undocumented.  Use them at your own risk, as the
16449       interfaces are subject to change.  Functions that are not listed in
16450       this document are not intended for public use, and should NOT be used
16451       under any circumstances.
16452
16453       If you feel you need to use one of these functions, first send email to
16454       perl5-porters@perl.org <mailto:perl5-porters@perl.org>.  It may be that
16455       there is a good reason for the function not being documented, and it
16456       should be removed from this list; or it may just be that no one has
16457       gotten around to documenting it.  In the latter case, you will be asked
16458       to submit a patch to document the function.  Once your patch is
16459       accepted, it will indicate that the interface is stable (unless it is
16460       explicitly marked otherwise) and usable by you.
16461
16462        amagic_call        gv_name_set            PerlIO_fill
16463        amagic_deref_call  gv_SVadd               PerlIO_unread
16464        any_dup            he_dup                 pmop_dump
16465        atfork_lock        hek_dup                pop_scope
16466        atfork_unlock      hv_delayfree_ent       pregfree
16467        block_gimme        hv_eiter_p             ptr_table_fetch
16468        call_atexit        hv_eiter_set           ptr_table_free
16469        call_list          hv_free_ent            ptr_table_new
16470        clear_defarray     hv_ksplit              ptr_table_split
16471        clone_params_del   hv_name_set            ptr_table_store
16472        clone_params_new   hv_placeholders_get    push_scope
16473        CvDEPTH            hv_placeholders_set    re_compile
16474        deb                hv_rand_set            regdump
16475        deb_nocontext      hv_riter_p             repeatcpy
16476        debop              hv_riter_set           rsignal_state
16477        debprofdump        init_stacks            rvpv_dup
16478        debstack           init_tm                save_adelete
16479        debstackptrs       is_lvalue_sub          save_aelem
16480        dirp_dup           leave_scope            save_aelem_flags
16481        do_aspawn          magic_dump             save_alloc
16482        do_close           markstack_grow         save_generic_pvref
16483        do_join            mfree                  save_generic_svref
16484        do_open            mg_dup                 save_hdelete
16485        do_openn           mg_size                save_helem
16486        doref              mro_get_from_name      save_helem_flags
16487        do_spawn           mro_set_mro            save_hints
16488        do_spawn_nowait    my_chsize              save_op
16489        do_sprintf         my_cxt_init            save_padsv_and_mortalize
16490        dounwind           my_dirfd               save_pushi32ptr
16491        dowantarray        my_failure_exit        save_pushptr
16492        dump_eval          my_fflush_all          save_pushptrptr
16493        dump_form          my_fork                save_set_svflags
16494        dump_mstats        my_pclose              save_shared_pvref
16495        dump_sub           my_popen               savestack_grow
16496        filter_del         my_popen_list          savestack_grow_cnt
16497        fp_dup             my_socketpair          save_vptr
16498        get_context        newANONATTRSUB         scan_vstring
16499        get_mstats         newANONHASH            seed
16500        get_op_descs       newANONLIST            set_context
16501        get_op_names       newANONSUB             share_hek
16502        get_ppaddr         newAVREF               si_dup
16503        get_vtbl           newCVREF               ss_dup
16504        gp_dup             newFORM                start_subparse
16505        gp_free            newGVgen               sv_2pvbyte_flags
16506        gp_ref             newGVgen_flags         sv_2pvutf8_flags
16507        gv_add_by_type     newGVREF               SvAMAGIC_off
16508        Gv_AMupdate        newHVhv                SvAMAGIC_on
16509        gv_autoload_pv     newHVREF               sv_dup
16510        gv_autoload_pvn    newIO                  sv_dup_inc
16511        gv_autoload_sv     newMYSUB               sv_peek
16512        gv_AVadd           newPROG                sys_intern_clear
16513        gv_dump            new_stackinfo          sys_intern_dup
16514        gv_efullname3      newSVREF               sys_intern_init
16515        gv_efullname4      op_refcnt_lock         taint_env
16516        gv_fullname3       op_refcnt_unlock       taint_proper
16517        gv_fullname4       parser_dup             unsharepvn
16518        gv_handler         perl_alloc_using       vdeb
16519        gv_HVadd           perl_clone_using
16520        gv_IOadd           PerlIO_context_layers
16521

AUTHORS

16523       Until May 1997, this document was maintained by Jeff Okamoto
16524       <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
16525
16526       With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
16527       Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
16528       Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
16529       Stephen McCamant, and Gurusamy Sarathy.
16530
16531       API Listing originally by Dean Roehrich <roehrich@cray.com>.
16532
16533       Updated to be autogenerated from comments in the source by Benjamin
16534       Stuhl.
16535

SEE ALSO

16537       config.h, perlapio, perlcall, perlclib, perlfilter, perlguts,
16538       perlintern, perlinterp, perliol, perlmroapi, perlreguts, perlxs
16539
16540
16541
16542perl v5.34.0                      2021-10-18                        PERLAPI(1)
Impressum