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       Some specialized items are instead documented in config.h, perlapio,
13       perlcall, perlclib, perlfilter, perlguts, perlmroapi, perlxs,
14       perlxstut, and warnings.
15
16       At the end is a list of functions which have yet to be documented.
17       Patches welcome!  The interfaces of these are subject to change without
18       notice.
19
20       Anything not listed here is not part of the public API, and should not
21       be used by extension writers at all.  For these reasons, blindly using
22       functions listed in proto.h is to be avoided when writing extensions.
23
24       In Perl, unlike C, a string of characters may generally contain
25       embedded "NUL" characters.  Sometimes in the documentation a Perl
26       string is referred to as a "buffer" to distinguish it from a C string,
27       but sometimes they are both just referred to as strings.
28
29       Note that all Perl API global variables must be referenced with the
30       "PL_" prefix.  Again, those not listed here are not to be used by
31       extension writers, and can be changed or removed without notice; same
32       with macros.  Some macros are provided for compatibility with the
33       older, unadorned names, but this support may be disabled in a future
34       release.
35
36       Perl was originally written to handle US-ASCII only (that is characters
37       whose ordinal numbers are in the range 0 - 127).  And documentation and
38       comments may still use the term ASCII, when sometimes in fact the
39       entire range from 0 - 255 is meant.
40
41       The non-ASCII characters below 256 can have various meanings, depending
42       on various things.  (See, most notably, perllocale.)  But usually the
43       whole range can be referred to as ISO-8859-1.  Often, the term
44       "Latin-1" (or "Latin1") is used as an equivalent for ISO-8859-1.  But
45       some people treat "Latin1" as referring just to the characters in the
46       range 128 through 255, or somethimes from 160 through 255.  This
47       documentation uses "Latin1" and "Latin-1" to refer to all 256
48       characters.
49
50       Note that Perl can be compiled and run under either ASCII or EBCDIC
51       (See perlebcdic).  Most of the documentation (and even comments in the
52       code) ignore the EBCDIC possibility.  For almost all purposes the
53       differences are transparent.  As an example, under EBCDIC, instead of
54       UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so whenever
55       this documentation refers to "utf8" (and variants of that name,
56       including in function names), it also (essentially transparently) means
57       "UTF-EBCDIC".  But the ordinals of characters differ between ASCII,
58       EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may
59       occupy a different number of bytes than in UTF-8.
60
61       The listing below is alphabetical, case insensitive.
62

Array Manipulation Functions

64       av_clear
65               Frees the all the elements of an array, leaving it empty.  The
66               XS equivalent of "@array = ()".  See also "av_undef".
67
68               Note that it is possible that the actions of a destructor
69               called directly or indirectly by freeing an element of the
70               array could cause the reference count of the array itself to be
71               reduced (e.g. by deleting an entry in the symbol table). So it
72               is a possibility that the AV could have been freed (or even
73               reallocated) on return from the call unless you hold a
74               reference to it.
75
76                       void    av_clear(AV *av)
77
78       av_create_and_push
79               NOTE: this function is experimental and may change or be
80               removed without notice.
81
82               Push an SV onto the end of the array, creating the array if
83               necessary.  A small internal helper function to remove a
84               commonly duplicated idiom.
85
86               NOTE: this function must be explicitly called as
87               Perl_av_create_and_push with an aTHX_ parameter.
88
89                       void    Perl_av_create_and_push(pTHX_ AV **const avp,
90                                                       SV *const val)
91
92       av_create_and_unshift_one
93               NOTE: this function is experimental and may change or be
94               removed without notice.
95
96               Unshifts an SV onto the beginning of the array, creating the
97               array if necessary.  A small internal helper function to remove
98               a commonly duplicated idiom.
99
100               NOTE: this function must be explicitly called as
101               Perl_av_create_and_unshift_one with an aTHX_ parameter.
102
103                       SV**    Perl_av_create_and_unshift_one(pTHX_
104                                                              AV **const avp,
105                                                              SV *const val)
106
107       av_delete
108               Deletes the element indexed by "key" from the array, makes the
109               element mortal, and returns it.  If "flags" equals "G_DISCARD",
110               the element is freed and NULL is returned. NULL is also
111               returned if "key" is out of range.
112
113               Perl equivalent: "splice(@myarray, $key, 1, undef)" (with the
114               "splice" in void context if "G_DISCARD" is present).
115
116                       SV*     av_delete(AV *av, SSize_t key, I32 flags)
117
118       av_exists
119               Returns true if the element indexed by "key" has been
120               initialized.
121
122               This relies on the fact that uninitialized array elements are
123               set to "NULL".
124
125               Perl equivalent: "exists($myarray[$key])".
126
127                       bool    av_exists(AV *av, SSize_t key)
128
129       av_extend
130               Pre-extend an array so that it is capable of storing values at
131               indexes "0..key". Thus "av_extend(av,99)" guarantees that the
132               array can store 100 elements, i.e. that "av_store(av, 0, sv)"
133               through "av_store(av, 99, sv)" on a plain array will work
134               without any further memory allocation.
135
136               If the av argument is a tied array then will call the "EXTEND"
137               tied array method with an argument of "(key+1)".
138
139                       void    av_extend(AV *av, SSize_t key)
140
141       av_fetch
142               Returns the SV at the specified index in the array.  The "key"
143               is the index.  If lval is true, you are guaranteed to get a
144               real SV back (in case it wasn't real before), which you can
145               then modify.  Check that the return value is non-null before
146               dereferencing it to a "SV*".
147
148               See "Understanding the Magic of Tied Hashes and Arrays" in
149               perlguts for more information on how to use this function on
150               tied arrays.
151
152               The rough perl equivalent is $myarray[$key].
153
154                       SV**    av_fetch(AV *av, SSize_t key, I32 lval)
155
156       AvFILL  Same as "av_top_index()" or "av_tindex()".
157
158                       int     AvFILL(AV* av)
159
160       av_fill Set the highest index in the array to the given number,
161               equivalent to Perl's "$#array = $fill;".
162
163               The number of elements in the array will be "fill + 1" after
164               "av_fill()" returns.  If the array was previously shorter, then
165               the additional elements appended are set to NULL.  If the array
166               was longer, then the excess elements are freed.
167               "av_fill(av, -1)" is the same as "av_clear(av)".
168
169                       void    av_fill(AV *av, SSize_t fill)
170
171       av_len  Same as "av_top_index".  Note that, unlike what the name
172               implies, it returns the highest index in the array.  This is
173               unlike "sv_len", which returns what you would expect.
174
175               To get the true number of elements in the array, instead use
176               "av_count".
177
178                       SSize_t av_len(AV *av)
179
180       av_make Creates a new AV and populates it with a list of SVs.  The SVs
181               are copied into the array, so they may be freed after the call
182               to "av_make".  The new AV will have a reference count of 1.
183
184               Perl equivalent: "my @new_array = ($scalar1, $scalar2,
185               $scalar3...);"
186
187                       AV*     av_make(SSize_t size, SV **strp)
188
189       av_pop  Removes one SV from the end of the array, reducing its size by
190               one and returning the SV (transferring control of one reference
191               count) to the caller.  Returns &PL_sv_undef if the array is
192               empty.
193
194               Perl equivalent: "pop(@myarray);"
195
196                       SV*     av_pop(AV *av)
197
198       av_push Pushes an SV (transferring control of one reference count) onto
199               the end of the array.  The array will grow automatically to
200               accommodate the addition.
201
202               Perl equivalent: "push @myarray, $val;".
203
204                       void    av_push(AV *av, SV *val)
205
206       av_shift
207               Removes one SV from the start of the array, reducing its size
208               by one and returning the SV (transferring control of one
209               reference count) to the caller.  Returns &PL_sv_undef if the
210               array is empty.
211
212               Perl equivalent: "shift(@myarray);"
213
214                       SV*     av_shift(AV *av)
215
216       av_store
217               Stores an SV in an array.  The array index is specified as
218               "key".  The return value will be "NULL" if the operation failed
219               or if the value did not need to be actually stored within the
220               array (as in the case of tied arrays).  Otherwise, it can be
221               dereferenced to get the "SV*" that was stored there (= "val")).
222
223               Note that the caller is responsible for suitably incrementing
224               the reference count of "val" before the call, and decrementing
225               it if the function returned "NULL".
226
227               Approximate Perl equivalent: "splice(@myarray, $key, 1, $val)".
228
229               See "Understanding the Magic of Tied Hashes and Arrays" in
230               perlguts for more information on how to use this function on
231               tied arrays.
232
233                       SV**    av_store(AV *av, SSize_t key, SV *val)
234
235       av_tindex
236               Same as "av_top_index()".
237
238                       SSize_t av_tindex(AV *av)
239
240       av_top_index
241               Returns the highest index in the array.  The number of elements
242               in the array is "av_top_index(av) + 1".  Returns -1 if the
243               array is empty.
244
245               The Perl equivalent for this is $#myarray.
246
247               (A slightly shorter form is "av_tindex".)
248
249                       SSize_t av_top_index(AV *av)
250
251       av_undef
252               Undefines the array. The XS equivalent of "undef(@array)".
253
254               As well as freeing all the elements of the array (like
255               "av_clear()"), this also frees the memory used by the av to
256               store its list of scalars.
257
258               See "av_clear" for a note about the array possibly being
259               invalid on return.
260
261                       void    av_undef(AV *av)
262
263       av_unshift
264               Unshift the given number of "undef" values onto the beginning
265               of the array.  The array will grow automatically to accommodate
266               the addition.
267
268               Perl equivalent: "unshift @myarray, ((undef) x $num);"
269
270                       void    av_unshift(AV *av, SSize_t num)
271
272       get_av  Returns the AV of the specified Perl global or package array
273               with the given name (so it won't work on lexical variables).
274               "flags" are passed to "gv_fetchpv".  If "GV_ADD" is set and the
275               Perl variable does not exist then it will be created.  If
276               "flags" is zero and the variable does not exist then NULL is
277               returned.
278
279               Perl equivalent: "@{"$name"}".
280
281               NOTE: the perl_ form of this function is deprecated.
282
283                       AV*     get_av(const char *name, I32 flags)
284
285       newAV   Creates a new AV.  The reference count is set to 1.
286
287               Perl equivalent: "my @array;".
288
289                       AV*     newAV()
290
291       sortsv  In-place sort an array of SV pointers with the given comparison
292               routine.
293
294               Currently this always uses mergesort.  See "sortsv_flags" for a
295               more flexible routine.
296
297                       void    sortsv(SV** array, size_t num_elts,
298                                      SVCOMPARE_t cmp)
299

Callback Functions

301       call_argv
302               Performs a callback to the specified named and package-scoped
303               Perl subroutine with "argv" (a "NULL"-terminated array of
304               strings) as arguments.  See perlcall.
305
306               Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
307
308               NOTE: the perl_ form of this function is deprecated.
309
310                       I32     call_argv(const char* sub_name, I32 flags,
311                                         char** argv)
312
313       call_method
314               Performs a callback to the specified Perl method.  The blessed
315               object must be on the stack.  See perlcall.
316
317               NOTE: the perl_ form of this function is deprecated.
318
319                       I32     call_method(const char* methname, I32 flags)
320
321       call_pv Performs a callback to the specified Perl sub.  See perlcall.
322
323               NOTE: the perl_ form of this function is deprecated.
324
325                       I32     call_pv(const char* sub_name, I32 flags)
326
327       call_sv Performs a callback to the Perl sub specified by the SV.
328
329               If neither the "G_METHOD" nor "G_METHOD_NAMED" flag is
330               supplied, the SV may be any of a CV, a GV, a reference to a CV,
331               a reference to a GV or "SvPV(sv)" will be used as the name of
332               the sub to call.
333
334               If the "G_METHOD" flag is supplied, the SV may be a reference
335               to a CV or "SvPV(sv)" will be used as the name of the method to
336               call.
337
338               If the "G_METHOD_NAMED" flag is supplied, "SvPV(sv)" will be
339               used as the name of the method to call.
340
341               Some other values are treated specially for internal use and
342               should not be depended on.
343
344               See perlcall.
345
346               NOTE: the perl_ form of this function is deprecated.
347
348                       I32     call_sv(SV* sv, volatile I32 flags)
349
350       ENTER   Opening bracket on a callback.  See "LEAVE" and perlcall.
351
352                               ENTER;
353
354       ENTER_with_name
355               Same as "ENTER", but when debugging is enabled it also
356               associates the given literal string with the new scope.
357
358                               ENTER_with_name("name");
359
360       eval_pv Tells Perl to "eval" the given string in scalar context and
361               return an SV* result.
362
363               NOTE: the perl_ form of this function is deprecated.
364
365                       SV*     eval_pv(const char* p, I32 croak_on_error)
366
367       eval_sv Tells Perl to "eval" the string in the SV.  It supports the
368               same flags as "call_sv", with the obvious exception of
369               "G_EVAL".  See perlcall.
370
371               The "G_RETHROW" flag can be used if you only need eval_sv() to
372               execute code specified by a string, but not catch any errors.
373
374               NOTE: the perl_ form of this function is deprecated.
375
376                       I32     eval_sv(SV* sv, I32 flags)
377
378       FREETMPS
379               Closing bracket for temporaries on a callback.  See "SAVETMPS"
380               and perlcall.
381
382                               FREETMPS;
383
384       LEAVE   Closing bracket on a callback.  See "ENTER" and perlcall.
385
386                               LEAVE;
387
388       LEAVE_with_name
389               Same as "LEAVE", but when debugging is enabled it first checks
390               that the scope has the given name. "name" must be a literal
391               string.
392
393                               LEAVE_with_name("name");
394
395       SAVETMPS
396               Opening bracket for temporaries on a callback.  See "FREETMPS"
397               and perlcall.
398
399                               SAVETMPS;
400

Character case changing

402       Perl uses "full" Unicode case mappings.  This means that converting a
403       single character to another case may result in a sequence of more than
404       one character.  For example, the uppercase of "ss" (LATIN SMALL LETTER
405       SHARP S) is the two character sequence "SS".  This presents some
406       complications   The lowercase of all characters in the range 0..255 is
407       a single character, and thus "toLOWER_L1" is furnished.  But,
408       "toUPPER_L1" can't exist, as it couldn't return a valid result for all
409       legal inputs.  Instead "toUPPER_uvchr" has an API that does allow every
410       possible legal result to be returned.)  Likewise no other function that
411       is crippled by not being able to give the correct results for the full
412       range of possible inputs has been implemented here.
413
414       toFOLD  Converts the specified character to foldcase.  If the input is
415               anything but an ASCII uppercase character, that input character
416               itself is returned.  Variant "toFOLD_A" is equivalent.  (There
417               is no equivalent "to_FOLD_L1" for the full Latin1 range, as the
418               full generality of "toFOLD_uvchr" is needed there.)
419
420                       U8      toFOLD(U8 ch)
421
422       toFOLD_utf8
423               Converts the first UTF-8 encoded character in the sequence
424               starting at "p" and extending no further than "e - 1" to its
425               foldcase version, and stores that in UTF-8 in "s", and its
426               length in bytes in "lenp".  Note that the buffer pointed to by
427               "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
428               foldcase version may be longer than the original character.
429
430               The first code point of the foldcased version is returned (but
431               note, as explained at the top of this section, that there may
432               be more).
433
434               It will not attempt to read beyond "e - 1", provided that the
435               constraint "s < e" is true (this is asserted for in
436               "-DDEBUGGING" builds).  If the UTF-8 for the input character is
437               malformed in some way, the program may croak, or the function
438               may return the REPLACEMENT CHARACTER, at the discretion of the
439               implementation, and subject to change in future releases.
440
441                       UV      toFOLD_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
442
443       toFOLD_utf8_safe
444               Same as "toFOLD_utf8".
445
446                       UV      toFOLD_utf8_safe(U8* p, U8* e, U8* s,
447                                                STRLEN* lenp)
448
449       toFOLD_uvchr
450               Converts the code point "cp" to its foldcase version, and
451               stores that in UTF-8 in "s", and its length in bytes in "lenp".
452               The code point is interpreted as native if less than 256;
453               otherwise as Unicode.  Note that the buffer pointed to by "s"
454               needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
455               foldcase version may be longer than the original character.
456
457               The first code point of the foldcased version is returned (but
458               note, as explained at the top of this section, that there may
459               be more).
460
461                       UV      toFOLD_uvchr(UV cp, U8* s, STRLEN* lenp)
462
463       toLOWER Converts the specified character to lowercase.  If the input is
464               anything but an ASCII uppercase character, that input character
465               itself is returned.  Variant "toLOWER_A" is equivalent.
466
467                       U8      toLOWER(U8 ch)
468
469       toLOWER_L1
470               Converts the specified Latin1 character to lowercase.  The
471               results are undefined if the input doesn't fit in a byte.
472
473                       U8      toLOWER_L1(U8 ch)
474
475       toLOWER_LC
476               Converts the specified character to lowercase using the current
477               locale's rules, if possible; otherwise returns the input
478               character itself.
479
480                       U8      toLOWER_LC(U8 ch)
481
482       toLOWER_utf8
483               Converts the first UTF-8 encoded character in the sequence
484               starting at "p" and extending no further than "e - 1" to its
485               lowercase version, and stores that in UTF-8 in "s", and its
486               length in bytes in "lenp".  Note that the buffer pointed to by
487               "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
488               lowercase version may be longer than the original character.
489
490               The first code point of the lowercased version is returned (but
491               note, as explained at the top of this section, that there may
492               be more).  It will not attempt to read beyond "e - 1", provided
493               that the constraint "s < e" is true (this is asserted for in
494               "-DDEBUGGING" builds).  If the UTF-8 for the input character is
495               malformed in some way, the program may croak, or the function
496               may return the REPLACEMENT CHARACTER, at the discretion of the
497               implementation, and subject to change in future releases.
498
499                       UV      toLOWER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
500
501       toLOWER_utf8_safe
502               Same as "toLOWER_utf8".
503
504                       UV      toLOWER_utf8_safe(U8* p, U8* e, U8* s,
505                                                 STRLEN* lenp)
506
507       toLOWER_uvchr
508               Converts the code point "cp" to its lowercase version, and
509               stores that in UTF-8 in "s", and its length in bytes in "lenp".
510               The code point is interpreted as native if less than 256;
511               otherwise as Unicode.  Note that the buffer pointed to by "s"
512               needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
513               lowercase version may be longer than the original character.
514
515               The first code point of the lowercased version is returned (but
516               note, as explained at the top of this section, that there may
517               be more).
518
519                       UV      toLOWER_uvchr(UV cp, U8* s, STRLEN* lenp)
520
521       toTITLE Converts the specified character to titlecase.  If the input is
522               anything but an ASCII lowercase character, that input character
523               itself is returned.  Variant "toTITLE_A" is equivalent.  (There
524               is no "toTITLE_L1" for the full Latin1 range, as the full
525               generality of "toTITLE_uvchr" is needed there.  Titlecase is
526               not a concept used in locale handling, so there is no
527               functionality for that.)
528
529                       U8      toTITLE(U8 ch)
530
531       toTITLE_utf8
532               Converts the first UTF-8 encoded character in the sequence
533               starting at "p" and extending no further than "e - 1" to its
534               titlecase version, and stores that in UTF-8 in "s", and its
535               length in bytes in "lenp".  Note that the buffer pointed to by
536               "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
537               titlecase version may be longer than the original character.
538
539               The first code point of the titlecased version is returned (but
540               note, as explained at the top of this section, that there may
541               be more).
542
543               It will not attempt to read beyond "e - 1", provided that the
544               constraint "s < e" is true (this is asserted for in
545               "-DDEBUGGING" builds).  If the UTF-8 for the input character is
546               malformed in some way, the program may croak, or the function
547               may return the REPLACEMENT CHARACTER, at the discretion of the
548               implementation, and subject to change in future releases.
549
550                       UV      toTITLE_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
551
552       toTITLE_utf8_safe
553               Same as "toTITLE_utf8".
554
555                       UV      toTITLE_utf8_safe(U8* p, U8* e, U8* s,
556                                                 STRLEN* lenp)
557
558       toTITLE_uvchr
559               Converts the code point "cp" to its titlecase version, and
560               stores that in UTF-8 in "s", and its length in bytes in "lenp".
561               The code point is interpreted as native if less than 256;
562               otherwise as Unicode.  Note that the buffer pointed to by "s"
563               needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
564               titlecase version may be longer than the original character.
565
566               The first code point of the titlecased version is returned (but
567               note, as explained at the top of this section, that there may
568               be more).
569
570                       UV      toTITLE_uvchr(UV cp, U8* s, STRLEN* lenp)
571
572       toUPPER Converts the specified character to uppercase.  If the input is
573               anything but an ASCII lowercase character, that input character
574               itself is returned.  Variant "toUPPER_A" is equivalent.
575
576                       U8      toUPPER(int ch)
577
578       toUPPER_utf8
579               Converts the first UTF-8 encoded character in the sequence
580               starting at "p" and extending no further than "e - 1" to its
581               uppercase version, and stores that in UTF-8 in "s", and its
582               length in bytes in "lenp".  Note that the buffer pointed to by
583               "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
584               uppercase version may be longer than the original character.
585
586               The first code point of the uppercased version is returned (but
587               note, as explained at the top of this section, that there may
588               be more).
589
590               It will not attempt to read beyond "e - 1", provided that the
591               constraint "s < e" is true (this is asserted for in
592               "-DDEBUGGING" builds).  If the UTF-8 for the input character is
593               malformed in some way, the program may croak, or the function
594               may return the REPLACEMENT CHARACTER, at the discretion of the
595               implementation, and subject to change in future releases.
596
597                       UV      toUPPER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
598
599       toUPPER_utf8_safe
600               Same as "toUPPER_utf8".
601
602                       UV      toUPPER_utf8_safe(U8* p, U8* e, U8* s,
603                                                 STRLEN* lenp)
604
605       toUPPER_uvchr
606               Converts the code point "cp" to its uppercase version, and
607               stores that in UTF-8 in "s", and its length in bytes in "lenp".
608               The code point is interpreted as native if less than 256;
609               otherwise as Unicode.  Note that the buffer pointed to by "s"
610               needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
611               uppercase version may be longer than the original character.
612
613               The first code point of the uppercased version is returned (but
614               note, as explained at the top of this section, that there may
615               be more.)
616
617                       UV      toUPPER_uvchr(UV cp, U8* s, STRLEN* lenp)
618
619       WIDEST_UTYPE
620               Yields the widest unsigned integer type on the platform,
621               currently either "U32" or 64.  This can be used in declarations
622               such as
623
624                WIDEST_UTYPE my_uv;
625
626               or casts
627
628                my_uv = (WIDEST_UTYPE) val;
629

Character classification

631       This section is about functions (really macros) that classify
632       characters into types, such as punctuation versus alphabetic, etc.
633       Most of these are analogous to regular expression character classes.
634       (See "POSIX Character Classes" in perlrecharclass.)  There are several
635       variants for each class.  (Not all macros have all variants; each item
636       below lists the ones valid for it.)  None are affected by "use bytes",
637       and only the ones with "LC" in the name are affected by the current
638       locale.
639
640       The base function, e.g., "isALPHA()", takes any signed or unsigned
641       value, treating it as a code point, and returns a boolean as to whether
642       or not the character represented by it is (or on non-ASCII platforms,
643       corresponds to) an ASCII character in the named class based on
644       platform, Unicode, and Perl rules.  If the input is a number that
645       doesn't fit in an octet, FALSE is returned.
646
647       Variant "isFOO_A" (e.g., "isALPHA_A()") is identical to the base
648       function with no suffix "_A".  This variant is used to emphasize by its
649       name that only ASCII-range characters can return TRUE.
650
651       Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivalent) character
652       set onto the platform.  That is, the code points that are ASCII are
653       unaffected, since ASCII is a subset of Latin-1.  But the non-ASCII code
654       points are treated as if they are Latin-1 characters.  For example,
655       "isWORDCHAR_L1()" will return true when called with the code point
656       0xDF, which is a word character in both ASCII and EBCDIC (though it
657       represents different characters in each).  If the input is a number
658       that doesn't fit in an octet, FALSE is returned.  (Perl's documentation
659       uses a colloquial definition of Latin-1, to include all code points
660       below 256.)
661
662       Variant "isFOO_uvchr" is exactly like the "isFOO_L1" variant, for
663       inputs below 256, but if the code point is larger than 255, Unicode
664       rules are used to determine if it is in the character class.  For
665       example, "isWORDCHAR_uvchr(0x100)" returns TRUE, since 0x100 is LATIN
666       CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.
667
668       Variants "isFOO_utf8" and "isFOO_utf8_safe" are like "isFOO_uvchr", but
669       are used for UTF-8 encoded strings.  The two forms are different names
670       for the same thing.  Each call to one of these classifies the first
671       character of the string starting at "p".  The second parameter, "e",
672       points to anywhere in the string beyond the first character, up to one
673       byte past the end of the entire string.  Although both variants are
674       identical, the suffix "_safe" in one name emphasizes that it will not
675       attempt to read beyond "e - 1", provided that the constraint "s < e" is
676       true (this is asserted for in "-DDEBUGGING" builds).  If the UTF-8 for
677       the input character is malformed in some way, the program may croak, or
678       the function may return FALSE, at the discretion of the implementation,
679       and subject to change in future releases.
680
681       Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but
682       the result is based on the current locale, which is what "LC" in the
683       name stands for.  If Perl can determine that the current locale is a
684       UTF-8 locale, it uses the published Unicode rules; otherwise, it uses
685       the C library function that gives the named classification.  For
686       example, "isDIGIT_LC()" when not in a UTF-8 locale returns the result
687       of calling "isdigit()".  FALSE is always returned if the input won't
688       fit into an octet.  On some platforms where the C library function is
689       known to be defective, Perl changes its result to follow the POSIX
690       standard's rules.
691
692       Variant "isFOO_LC_uvchr" acts exactly like "isFOO_LC" for inputs less
693       than 256, but for larger ones it returns the Unicode classification of
694       the code point.
695
696       Variants "isFOO_LC_utf8" and "isFOO_LC_utf8_safe" are like
697       "isFOO_LC_uvchr", but are used for UTF-8 encoded strings.  The two
698       forms are different names for the same thing.  Each call to one of
699       these classifies the first character of the string starting at "p".
700       The second parameter, "e", points to anywhere in the string beyond the
701       first character, up to one byte past the end of the entire string.
702       Although both variants are identical, the suffix "_safe" in one name
703       emphasizes that it will not attempt to read beyond "e - 1", provided
704       that the constraint "s < e" is true (this is asserted for in
705       "-DDEBUGGING" builds).  If the UTF-8 for the input character is
706       malformed in some way, the program may croak, or the function may
707       return FALSE, at the discretion of the implementation, and subject to
708       change in future releases.
709
710       isALPHA Returns a boolean indicating whether the specified input is one
711               of "[A-Za-z]", analogous to "m/[[:alpha:]]/".  See the top of
712               this section for an explanation of variants "isALPHA_A",
713               "isALPHA_L1", "isALPHA_uvchr", "isALPHA_utf8",
714               "isALPHA_utf8_safe", "isALPHA_LC", "isALPHA_LC_uvchr",
715               "isALPHA_LC_utf8", and "isALPHA_LC_utf8_safe".
716
717                       bool    isALPHA(int ch)
718
719       isALPHANUMERIC
720               Returns a boolean indicating whether the specified character is
721               one of "[A-Za-z0-9]", analogous to "m/[[:alnum:]]/".  See the
722               top of this section for an explanation of variants
723               "isALPHANUMERIC_A", "isALPHANUMERIC_L1",
724               "isALPHANUMERIC_uvchr", "isALPHANUMERIC_utf8",
725               "isALPHANUMERIC_utf8_safe", "isALPHANUMERIC_LC",
726               "isALPHANUMERIC_LC_uvchr", "isALPHANUMERIC_LC_utf8", and
727               "isALPHANUMERIC_LC_utf8_safe".
728
729               A (discouraged from use) synonym is "isALNUMC" (where the "C"
730               suffix means this corresponds to the C language alphanumeric
731               definition).  Also there are the variants "isALNUMC_A",
732               "isALNUMC_L1" "isALNUMC_LC", and "isALNUMC_LC_uvchr".
733
734                       bool    isALPHANUMERIC(int ch)
735
736       isASCII Returns a boolean indicating whether the specified character is
737               one of the 128 characters in the ASCII character set, analogous
738               to "m/[[:ascii:]]/".  On non-ASCII platforms, it returns TRUE
739               iff this character corresponds to an ASCII character.  Variants
740               "isASCII_A()" and "isASCII_L1()" are identical to "isASCII()".
741               See the top of this section for an explanation of variants
742               "isASCII_uvchr", "isASCII_utf8", "isASCII_utf8_safe",
743               "isASCII_LC", "isASCII_LC_uvchr", "isASCII_LC_utf8", and
744               "isASCII_LC_utf8_safe".  Note, however, that some platforms do
745               not have the C library routine "isascii()".  In these cases,
746               the variants whose names contain "LC" are the same as the
747               corresponding ones without.
748
749                       bool    isASCII(int ch)
750
751       isBLANK Returns a boolean indicating whether the specified character is
752               a character considered to be a blank, analogous to
753               "m/[[:blank:]]/".  See the top of this section for an
754               explanation of variants "isBLANK_A", "isBLANK_L1",
755               "isBLANK_uvchr", "isBLANK_utf8", "isBLANK_utf8_safe",
756               "isBLANK_LC", "isBLANK_LC_uvchr", "isBLANK_LC_utf8", and
757               "isBLANK_LC_utf8_safe".  Note, however, that some platforms do
758               not have the C library routine "isblank()".  In these cases,
759               the variants whose names contain "LC" are the same as the
760               corresponding ones without.
761
762                       bool    isBLANK(char ch)
763
764       isCNTRL Returns a boolean indicating whether the specified character is
765               a control character, analogous to "m/[[:cntrl:]]/".  See the
766               top of this section for an explanation of variants "isCNTRL_A",
767               "isCNTRL_L1", "isCNTRL_uvchr", "isCNTRL_utf8",
768               "isCNTRL_utf8_safe", "isCNTRL_LC", "isCNTRL_LC_uvchr",
769               "isCNTRL_LC_utf8" and "isCNTRL_LC_utf8_safe".  On EBCDIC
770               platforms, you almost always want to use the "isCNTRL_L1"
771               variant.
772
773                       bool    isCNTRL(char ch)
774
775       isDIGIT Returns a boolean indicating whether the specified character is
776               a digit, analogous to "m/[[:digit:]]/".  Variants "isDIGIT_A"
777               and "isDIGIT_L1" are identical to "isDIGIT".  See the top of
778               this section for an explanation of variants "isDIGIT_uvchr",
779               "isDIGIT_utf8", "isDIGIT_utf8_safe", "isDIGIT_LC",
780               "isDIGIT_LC_uvchr", "isDIGIT_LC_utf8", and
781               "isDIGIT_LC_utf8_safe".
782
783                       bool    isDIGIT(char ch)
784
785       isGRAPH Returns a boolean indicating whether the specified character is
786               a graphic character, analogous to "m/[[:graph:]]/".  See the
787               top of this section for an explanation of variants "isGRAPH_A",
788               "isGRAPH_L1", "isGRAPH_uvchr", "isGRAPH_utf8",
789               "isGRAPH_utf8_safe", "isGRAPH_LC", "isGRAPH_LC_uvchr",
790               "isGRAPH_LC_utf8_safe", and "isGRAPH_LC_utf8_safe".
791
792                       bool    isGRAPH(char ch)
793
794       isIDCONT
795               Returns a boolean indicating whether the specified character
796               can be the second or succeeding character of an identifier.
797               This is very close to, but not quite the same as the official
798               Unicode property "XID_Continue".  The difference is that this
799               returns true only if the input character also matches
800               "isWORDCHAR".  See the top of this section for an explanation
801               of variants "isIDCONT_A", "isIDCONT_L1", "isIDCONT_uvchr",
802               "isIDCONT_utf8", "isIDCONT_utf8_safe", "isIDCONT_LC",
803               "isIDCONT_LC_uvchr", "isIDCONT_LC_utf8", and
804               "isIDCONT_LC_utf8_safe".
805
806                       bool    isIDCONT(char ch)
807
808       isIDFIRST
809               Returns a boolean indicating whether the specified character
810               can be the first character of an identifier.  This is very
811               close to, but not quite the same as the official Unicode
812               property "XID_Start".  The difference is that this returns true
813               only if the input character also matches "isWORDCHAR".  See the
814               top of this section for an explanation of variants
815               "isIDFIRST_A", "isIDFIRST_L1", "isIDFIRST_uvchr",
816               "isIDFIRST_utf8", "isIDFIRST_utf8_safe", "isIDFIRST_LC",
817               "isIDFIRST_LC_uvchr", "isIDFIRST_LC_utf8", and
818               "isIDFIRST_LC_utf8_safe".
819
820                       bool    isIDFIRST(char ch)
821
822       isLOWER Returns a boolean indicating whether the specified character is
823               a lowercase character, analogous to "m/[[:lower:]]/".  See the
824               top of this section for an explanation of variants "isLOWER_A",
825               "isLOWER_L1", "isLOWER_uvchr", "isLOWER_utf8",
826               "isLOWER_utf8_safe", "isLOWER_LC", "isLOWER_LC_uvchr",
827               "isLOWER_LC_utf8", and "isLOWER_LC_utf8_safe".
828
829                       bool    isLOWER(char ch)
830
831       isOCTAL Returns a boolean indicating whether the specified character is
832               an octal digit, [0-7].  The only two variants are "isOCTAL_A"
833               and "isOCTAL_L1"; each is identical to "isOCTAL".
834
835                       bool    isOCTAL(char ch)
836
837       isPRINT Returns a boolean indicating whether the specified character is
838               a printable character, analogous to "m/[[:print:]]/".  See the
839               top of this section for an explanation of variants "isPRINT_A",
840               "isPRINT_L1", "isPRINT_uvchr", "isPRINT_utf8",
841               "isPRINT_utf8_safe", "isPRINT_LC", "isPRINT_LC_uvchr",
842               "isPRINT_LC_utf8", and "isPRINT_LC_utf8_safe".
843
844                       bool    isPRINT(char ch)
845
846       isPSXSPC
847               (short for Posix Space) Starting in 5.18, this is identical in
848               all its forms to the corresponding "isSPACE()" macros.  The
849               locale forms of this macro are identical to their corresponding
850               "isSPACE()" forms in all Perl releases.  In releases prior to
851               5.18, the non-locale forms differ from their "isSPACE()" forms
852               only in that the "isSPACE()" forms don't match a Vertical Tab,
853               and the "isPSXSPC()" forms do.  Otherwise they are identical.
854               Thus this macro is analogous to what "m/[[:space:]]/" matches
855               in a regular expression.  See the top of this section for an
856               explanation of variants "isPSXSPC_A", "isPSXSPC_L1",
857               "isPSXSPC_uvchr", "isPSXSPC_utf8", "isPSXSPC_utf8_safe",
858               "isPSXSPC_LC", "isPSXSPC_LC_uvchr", "isPSXSPC_LC_utf8", and
859               "isPSXSPC_LC_utf8_safe".
860
861                       bool    isPSXSPC(char ch)
862
863       isPUNCT Returns a boolean indicating whether the specified character is
864               a punctuation character, analogous to "m/[[:punct:]]/".  Note
865               that the definition of what is punctuation isn't as
866               straightforward as one might desire.  See "POSIX Character
867               Classes" in perlrecharclass for details.  See the top of this
868               section for an explanation of variants "isPUNCT_A",
869               "isPUNCT_L1", "isPUNCT_uvchr", "isPUNCT_utf8",
870               "isPUNCT_utf8_safe", "isPUNCT_LC", "isPUNCT_LC_uvchr",
871               "isPUNCT_LC_utf8", and "isPUNCT_LC_utf8_safe".
872
873                       bool    isPUNCT(char ch)
874
875       isSPACE Returns a boolean indicating whether the specified character is
876               a whitespace character.  This is analogous to what "m/\s/"
877               matches in a regular expression.  Starting in Perl 5.18 this
878               also matches what "m/[[:space:]]/" does.  Prior to 5.18, only
879               the locale forms of this macro (the ones with "LC" in their
880               names) matched precisely what "m/[[:space:]]/" does.  In those
881               releases, the only difference, in the non-locale variants, was
882               that "isSPACE()" did not match a vertical tab.  (See "isPSXSPC"
883               for a macro that matches a vertical tab in all releases.)  See
884               the top of this section for an explanation of variants
885               "isSPACE_A", "isSPACE_L1", "isSPACE_uvchr", "isSPACE_utf8",
886               "isSPACE_utf8_safe", "isSPACE_LC", "isSPACE_LC_uvchr",
887               "isSPACE_LC_utf8", and "isSPACE_LC_utf8_safe".
888
889                       bool    isSPACE(char ch)
890
891       isUPPER Returns a boolean indicating whether the specified character is
892               an uppercase character, analogous to "m/[[:upper:]]/".  See the
893               top of this section for an explanation of variants "isUPPER_A",
894               "isUPPER_L1", "isUPPER_uvchr", "isUPPER_utf8",
895               "isUPPER_utf8_safe", "isUPPER_LC", "isUPPER_LC_uvchr",
896               "isUPPER_LC_utf8", and "isUPPER_LC_utf8_safe".
897
898                       bool    isUPPER(char ch)
899
900       isWORDCHAR
901               Returns a boolean indicating whether the specified character is
902               a character that is a word character, analogous to what "m/\w/"
903               and "m/[[:word:]]/" match in a regular expression.  A word
904               character is an alphabetic character, a decimal digit, a
905               connecting punctuation character (such as an underscore), or a
906               "mark" character that attaches to one of those (like some sort
907               of accent).  "isALNUM()" is a synonym provided for backward
908               compatibility, even though a word character includes more than
909               the standard C language meaning of alphanumeric.  See the top
910               of this section for an explanation of variants "isWORDCHAR_A",
911               "isWORDCHAR_L1", "isWORDCHAR_uvchr", "isWORDCHAR_utf8", and
912               "isWORDCHAR_utf8_safe".  "isWORDCHAR_LC",
913               "isWORDCHAR_LC_uvchr", "isWORDCHAR_LC_utf8", and
914               "isWORDCHAR_LC_utf8_safe" are also as described there, but
915               additionally include the platform's native underscore.
916
917                       bool    isWORDCHAR(char ch)
918
919       isXDIGIT
920               Returns a boolean indicating whether the specified character is
921               a hexadecimal digit.  In the ASCII range these are
922               "[0-9A-Fa-f]".  Variants "isXDIGIT_A()" and "isXDIGIT_L1()" are
923               identical to "isXDIGIT()".  See the top of this section for an
924               explanation of variants "isXDIGIT_uvchr", "isXDIGIT_utf8",
925               "isXDIGIT_utf8_safe", "isXDIGIT_LC", "isXDIGIT_LC_uvchr",
926               "isXDIGIT_LC_utf8", and "isXDIGIT_LC_utf8_safe".
927
928                       bool    isXDIGIT(char ch)
929

Cloning an interpreter

931       perl_clone
932               Create and return a new interpreter by cloning the current one.
933
934               "perl_clone" takes these flags as parameters:
935
936               "CLONEf_COPY_STACKS" - is used to, well, copy the stacks also,
937               without it we only clone the data and zero the stacks, with it
938               we copy the stacks and the new perl interpreter is ready to run
939               at the exact same point as the previous one.  The pseudo-fork
940               code uses "COPY_STACKS" while the threads->create doesn't.
941
942               "CLONEf_KEEP_PTR_TABLE" - "perl_clone" keeps a ptr_table with
943               the pointer of the old variable as a key and the new variable
944               as a value, this allows it to check if something has been
945               cloned and not clone it again, but rather just use the value
946               and increase the refcount.  If "KEEP_PTR_TABLE" is not set then
947               "perl_clone" will kill the ptr_table using the function
948               "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;".  A reason
949               to keep it around is if you want to dup some of your own
950               variables which are outside the graph that perl scans.
951
952               "CLONEf_CLONE_HOST" - This is a win32 thing, it is ignored on
953               unix, it tells perl's win32host code (which is c++) to clone
954               itself, this is needed on win32 if you want to run two threads
955               at the same time, if you just want to do some stuff in a
956               separate perl interpreter and then throw it away and return to
957               the original one, you don't need to do anything.
958
959                       PerlInterpreter* perl_clone(
960                                            PerlInterpreter *proto_perl,
961                                            UV flags
962                                        )
963

Compile-time scope hooks

965       BhkDISABLE
966               NOTE: this function is experimental and may change or be
967               removed without notice.
968
969               Temporarily disable an entry in this BHK structure, by clearing
970               the appropriate flag.  "which" is a preprocessor token
971               indicating which entry to disable.
972
973                       void    BhkDISABLE(BHK *hk, which)
974
975       BhkENABLE
976               NOTE: this function is experimental and may change or be
977               removed without notice.
978
979               Re-enable an entry in this BHK structure, by setting the
980               appropriate flag.  "which" is a preprocessor token indicating
981               which entry to enable.  This will assert (under -DDEBUGGING) if
982               the entry doesn't contain a valid pointer.
983
984                       void    BhkENABLE(BHK *hk, which)
985
986       BhkENTRY_set
987               NOTE: this function is experimental and may change or be
988               removed without notice.
989
990               Set an entry in the BHK structure, and set the flags to
991               indicate it is valid.  "which" is a preprocessing token
992               indicating which entry to set.  The type of "ptr" depends on
993               the entry.
994
995                       void    BhkENTRY_set(BHK *hk, which, void *ptr)
996
997       blockhook_register
998               NOTE: this function is experimental and may change or be
999               removed without notice.
1000
1001               Register a set of hooks to be called when the Perl lexical
1002               scope changes at compile time.  See "Compile-time scope hooks"
1003               in perlguts.
1004
1005               NOTE: this function must be explicitly called as
1006               Perl_blockhook_register with an aTHX_ parameter.
1007
1008                       void    Perl_blockhook_register(pTHX_ BHK *hk)
1009

COP Hint Hashes

1011       cophh_2hv
1012               NOTE: this function is experimental and may change or be
1013               removed without notice.
1014
1015               Generates and returns a standard Perl hash representing the
1016               full set of key/value pairs in the cop hints hash "cophh".
1017               "flags" is currently unused and must be zero.
1018
1019                       HV *    cophh_2hv(const COPHH *cophh, U32 flags)
1020
1021       cophh_copy
1022               NOTE: this function is experimental and may change or be
1023               removed without notice.
1024
1025               Make and return a complete copy of the cop hints hash "cophh".
1026
1027                       COPHH * cophh_copy(COPHH *cophh)
1028
1029       cophh_delete_pv
1030               NOTE: this function is experimental and may change or be
1031               removed without notice.
1032
1033               Like "cophh_delete_pvn", but takes a nul-terminated string
1034               instead of a string/length pair.
1035
1036                       COPHH * cophh_delete_pv(const COPHH *cophh,
1037                                               const char *key, U32 hash,
1038                                               U32 flags)
1039
1040       cophh_delete_pvn
1041               NOTE: this function is experimental and may change or be
1042               removed without notice.
1043
1044               Delete a key and its associated value from the cop hints hash
1045               "cophh", and returns the modified hash.  The returned hash
1046               pointer is in general not the same as the hash pointer that was
1047               passed in.  The input hash is consumed by the function, and the
1048               pointer to it must not be subsequently used.  Use "cophh_copy"
1049               if you need both hashes.
1050
1051               The key is specified by "keypv" and "keylen".  If "flags" has
1052               the "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1053               UTF-8, otherwise they are interpreted as Latin-1.  "hash" is a
1054               precomputed hash of the key string, or zero if it has not been
1055               precomputed.
1056
1057                       COPHH * cophh_delete_pvn(COPHH *cophh,
1058                                                const char *keypv,
1059                                                STRLEN keylen, U32 hash,
1060                                                U32 flags)
1061
1062       cophh_delete_pvs
1063               NOTE: this function is experimental and may change or be
1064               removed without notice.
1065
1066               Like "cophh_delete_pvn", but takes a literal string instead of
1067               a string/length pair, and no precomputed hash.
1068
1069                       COPHH * cophh_delete_pvs(const COPHH *cophh, "key",
1070                                                U32 flags)
1071
1072       cophh_delete_sv
1073               NOTE: this function is experimental and may change or be
1074               removed without notice.
1075
1076               Like "cophh_delete_pvn", but takes a Perl scalar instead of a
1077               string/length pair.
1078
1079                       COPHH * cophh_delete_sv(const COPHH *cophh, SV *key,
1080                                               U32 hash, U32 flags)
1081
1082       cophh_fetch_pv
1083               NOTE: this function is experimental and may change or be
1084               removed without notice.
1085
1086               Like "cophh_fetch_pvn", but takes a nul-terminated string
1087               instead of a string/length pair.
1088
1089                       SV *    cophh_fetch_pv(const COPHH *cophh,
1090                                              const char *key, U32 hash,
1091                                              U32 flags)
1092
1093       cophh_fetch_pvn
1094               NOTE: this function is experimental and may change or be
1095               removed without notice.
1096
1097               Look up the entry in the cop hints hash "cophh" with the key
1098               specified by "keypv" and "keylen".  If "flags" has the
1099               "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1100               UTF-8, otherwise they are interpreted as Latin-1.  "hash" is a
1101               precomputed hash of the key string, or zero if it has not been
1102               precomputed.  Returns a mortal scalar copy of the value
1103               associated with the key, or &PL_sv_placeholder if there is no
1104               value associated with the key.
1105
1106                       SV *    cophh_fetch_pvn(const COPHH *cophh,
1107                                               const char *keypv,
1108                                               STRLEN keylen, U32 hash,
1109                                               U32 flags)
1110
1111       cophh_fetch_pvs
1112               NOTE: this function is experimental and may change or be
1113               removed without notice.
1114
1115               Like "cophh_fetch_pvn", but takes a literal string instead of a
1116               string/length pair, and no precomputed hash.
1117
1118                       SV *    cophh_fetch_pvs(const COPHH *cophh, "key",
1119                                               U32 flags)
1120
1121       cophh_fetch_sv
1122               NOTE: this function is experimental and may change or be
1123               removed without notice.
1124
1125               Like "cophh_fetch_pvn", but takes a Perl scalar instead of a
1126               string/length pair.
1127
1128                       SV *    cophh_fetch_sv(const COPHH *cophh, SV *key,
1129                                              U32 hash, U32 flags)
1130
1131       cophh_free
1132               NOTE: this function is experimental and may change or be
1133               removed without notice.
1134
1135               Discard the cop hints hash "cophh", freeing all resources
1136               associated with it.
1137
1138                       void    cophh_free(COPHH *cophh)
1139
1140       cophh_new_empty
1141               NOTE: this function is experimental and may change or be
1142               removed without notice.
1143
1144               Generate and return a fresh cop hints hash containing no
1145               entries.
1146
1147                       COPHH * cophh_new_empty()
1148
1149       cophh_store_pv
1150               NOTE: this function is experimental and may change or be
1151               removed without notice.
1152
1153               Like "cophh_store_pvn", but takes a nul-terminated string
1154               instead of a string/length pair.
1155
1156                       COPHH * cophh_store_pv(const COPHH *cophh,
1157                                              const char *key, U32 hash,
1158                                              SV *value, U32 flags)
1159
1160       cophh_store_pvn
1161               NOTE: this function is experimental and may change or be
1162               removed without notice.
1163
1164               Stores a value, associated with a key, in the cop hints hash
1165               "cophh", and returns the modified hash.  The returned hash
1166               pointer is in general not the same as the hash pointer that was
1167               passed in.  The input hash is consumed by the function, and the
1168               pointer to it must not be subsequently used.  Use "cophh_copy"
1169               if you need both hashes.
1170
1171               The key is specified by "keypv" and "keylen".  If "flags" has
1172               the "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1173               UTF-8, otherwise they are interpreted as Latin-1.  "hash" is a
1174               precomputed hash of the key string, or zero if it has not been
1175               precomputed.
1176
1177               "value" is the scalar value to store for this key.  "value" is
1178               copied by this function, which thus does not take ownership of
1179               any reference to it, and later changes to the scalar will not
1180               be reflected in the value visible in the cop hints hash.
1181               Complex types of scalar will not be stored with referential
1182               integrity, but will be coerced to strings.
1183
1184                       COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
1185                                               STRLEN keylen, U32 hash,
1186                                               SV *value, U32 flags)
1187
1188       cophh_store_pvs
1189               NOTE: this function is experimental and may change or be
1190               removed without notice.
1191
1192               Like "cophh_store_pvn", but takes a literal string instead of a
1193               string/length pair, and no precomputed hash.
1194
1195                       COPHH * cophh_store_pvs(const COPHH *cophh, "key",
1196                                               SV *value, U32 flags)
1197
1198       cophh_store_sv
1199               NOTE: this function is experimental and may change or be
1200               removed without notice.
1201
1202               Like "cophh_store_pvn", but takes a Perl scalar instead of a
1203               string/length pair.
1204
1205                       COPHH * cophh_store_sv(const COPHH *cophh, SV *key,
1206                                              U32 hash, SV *value, U32 flags)
1207

COP Hint Reading

1209       cop_hints_2hv
1210               Generates and returns a standard Perl hash representing the
1211               full set of hint entries in the cop "cop".  "flags" is
1212               currently unused and must be zero.
1213
1214                       HV *    cop_hints_2hv(const COP *cop, U32 flags)
1215
1216       cop_hints_fetch_pv
1217               Like "cop_hints_fetch_pvn", but takes a nul-terminated string
1218               instead of a string/length pair.
1219
1220                       SV *    cop_hints_fetch_pv(const COP *cop,
1221                                                  const char *key, U32 hash,
1222                                                  U32 flags)
1223
1224       cop_hints_fetch_pvn
1225               Look up the hint entry in the cop "cop" with the key specified
1226               by "keypv" and "keylen".  If "flags" has the "COPHH_KEY_UTF8"
1227               bit set, the key octets are interpreted as UTF-8, otherwise
1228               they are interpreted as Latin-1.  "hash" is a precomputed hash
1229               of the key string, or zero if it has not been precomputed.
1230               Returns a mortal scalar copy of the value associated with the
1231               key, or &PL_sv_placeholder if there is no value associated with
1232               the key.
1233
1234                       SV *    cop_hints_fetch_pvn(const COP *cop,
1235                                                   const char *keypv,
1236                                                   STRLEN keylen, U32 hash,
1237                                                   U32 flags)
1238
1239       cop_hints_fetch_pvs
1240               Like "cop_hints_fetch_pvn", but takes a literal string instead
1241               of a string/length pair, and no precomputed hash.
1242
1243                       SV *    cop_hints_fetch_pvs(const COP *cop, "key",
1244                                                   U32 flags)
1245
1246       cop_hints_fetch_sv
1247               Like "cop_hints_fetch_pvn", but takes a Perl scalar instead of
1248               a string/length pair.
1249
1250                       SV *    cop_hints_fetch_sv(const COP *cop, SV *key,
1251                                                  U32 hash, U32 flags)
1252
1253       CopLABEL
1254               Returns the label attached to a cop.
1255
1256                       const char * CopLABEL(COP *const cop)
1257
1258       CopLABEL_len
1259               Returns the label attached to a cop, and stores its length in
1260               bytes into *len.
1261
1262                       const char * CopLABEL_len(COP *const cop, STRLEN *len)
1263
1264       CopLABEL_len_flags
1265               Returns the label attached to a cop, and stores its length in
1266               bytes into *len.  Upon return, *flags will be set to either
1267               "SVf_UTF8" or 0.
1268
1269                       const char * CopLABEL_len_flags(COP *const cop,
1270                                                       STRLEN *len, U32 *flags)
1271

Custom Operators

1273       custom_op_register
1274               Register a custom op.  See "Custom Operators" in perlguts.
1275
1276               NOTE: this function must be explicitly called as
1277               Perl_custom_op_register with an aTHX_ parameter.
1278
1279                       void    Perl_custom_op_register(pTHX_
1280                                                       Perl_ppaddr_t ppaddr,
1281                                                       const XOP *xop)
1282
1283       Perl_custom_op_xop
1284               Return the XOP structure for a given custom op.  This macro
1285               should be considered internal to "OP_NAME" and the other access
1286               macros: use them instead.  This macro does call a function.
1287               Prior to 5.19.6, this was implemented as a function.
1288
1289                       const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
1290
1291       XopDISABLE
1292               Temporarily disable a member of the XOP, by clearing the
1293               appropriate flag.
1294
1295                       void    XopDISABLE(XOP *xop, which)
1296
1297       XopENABLE
1298               Reenable a member of the XOP which has been disabled.
1299
1300                       void    XopENABLE(XOP *xop, which)
1301
1302       XopENTRY
1303               Return a member of the XOP structure.  "which" is a cpp token
1304               indicating which entry to return.  If the member is not set
1305               this will return a default value.  The return type depends on
1306               "which".  This macro evaluates its arguments more than once.
1307               If you are using "Perl_custom_op_xop" to retreive a "XOP *"
1308               from a "OP *", use the more efficient "XopENTRYCUSTOM" instead.
1309
1310                               XopENTRY(XOP *xop, which)
1311
1312       XopENTRYCUSTOM
1313               Exactly like "XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o),
1314               which)" but more efficient.  The "which" parameter is identical
1315               to "XopENTRY".
1316
1317                               XopENTRYCUSTOM(const OP *o, which)
1318
1319       XopENTRY_set
1320               Set a member of the XOP structure.  "which" is a cpp token
1321               indicating which entry to set.  See "Custom Operators" in
1322               perlguts for details about the available members and how they
1323               are used.  This macro evaluates its argument more than once.
1324
1325                       void    XopENTRY_set(XOP *xop, which, value)
1326
1327       XopFLAGS
1328               Return the XOP's flags.
1329
1330                       U32     XopFLAGS(XOP *xop)
1331

CV Manipulation Functions

1333       This section documents functions to manipulate CVs which are code-
1334       values, or subroutines.  For more information, see perlguts.
1335
1336       caller_cx
1337               The XSUB-writer's equivalent of caller().  The returned
1338               "PERL_CONTEXT" structure can be interrogated to find all the
1339               information returned to Perl by "caller".  Note that XSUBs
1340               don't get a stack frame, so "caller_cx(0, NULL)" will return
1341               information for the immediately-surrounding Perl code.
1342
1343               This function skips over the automatic calls to &DB::sub made
1344               on the behalf of the debugger.  If the stack frame requested
1345               was a sub called by "DB::sub", the return value will be the
1346               frame for the call to "DB::sub", since that has the correct
1347               line number/etc. for the call site.  If dbcxp is non-"NULL", it
1348               will be set to a pointer to the frame for the sub call itself.
1349
1350                       const PERL_CONTEXT * caller_cx(
1351                                                I32 level,
1352                                                const PERL_CONTEXT **dbcxp
1353                                            )
1354
1355       CvSTASH Returns the stash of the CV.  A stash is the symbol table hash,
1356               containing the package-scoped variables in the package where
1357               the subroutine was defined.  For more information, see
1358               perlguts.
1359
1360               This also has a special use with XS AUTOLOAD subs.  See
1361               "Autoloading with XSUBs" in perlguts.
1362
1363                       HV*     CvSTASH(CV* cv)
1364
1365       find_runcv
1366               Locate the CV corresponding to the currently executing sub or
1367               eval.  If "db_seqp" is non_null, skip CVs that are in the DB
1368               package and populate *db_seqp with the cop sequence number at
1369               the point that the DB:: code was entered.  (This allows
1370               debuggers to eval in the scope of the breakpoint rather than in
1371               the scope of the debugger itself.)
1372
1373                       CV*     find_runcv(U32 *db_seqp)
1374
1375       get_cv  Uses "strlen" to get the length of "name", then calls
1376               "get_cvn_flags".
1377
1378               NOTE: the perl_ form of this function is deprecated.
1379
1380                       CV*     get_cv(const char* name, I32 flags)
1381
1382       get_cvn_flags
1383               Returns the CV of the specified Perl subroutine.  "flags" are
1384               passed to "gv_fetchpvn_flags".  If "GV_ADD" is set and the Perl
1385               subroutine does not exist then it will be declared (which has
1386               the same effect as saying "sub name;").  If "GV_ADD" is not set
1387               and the subroutine does not exist then NULL is returned.
1388
1389                       CV*     get_cvn_flags(const char* name, STRLEN len,
1390                                             I32 flags)
1391

"xsubpp" variables and internal functions

1393       ax      Variable which is setup by "xsubpp" to indicate the stack base
1394               offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros.
1395               The "dMARK" macro must be called prior to setup the "MARK"
1396               variable.
1397
1398                       I32     ax
1399
1400       CLASS   Variable which is setup by "xsubpp" to indicate the class name
1401               for a C++ XS constructor.  This is always a "char*".  See
1402               "THIS".
1403
1404                       char*   CLASS
1405
1406       dAX     Sets up the "ax" variable.  This is usually handled
1407               automatically by "xsubpp" by calling "dXSARGS".
1408
1409                               dAX;
1410
1411       dAXMARK Sets up the "ax" variable and stack marker variable "mark".
1412               This is usually handled automatically by "xsubpp" by calling
1413               "dXSARGS".
1414
1415                               dAXMARK;
1416
1417       dITEMS  Sets up the "items" variable.  This is usually handled
1418               automatically by "xsubpp" by calling "dXSARGS".
1419
1420                               dITEMS;
1421
1422       dUNDERBAR
1423               Sets up any variable needed by the "UNDERBAR" macro.  It used
1424               to define "padoff_du", but it is currently a noop.  However, it
1425               is strongly advised to still use it for ensuring past and
1426               future compatibility.
1427
1428                               dUNDERBAR;
1429
1430       dXSARGS Sets up stack and mark pointers for an XSUB, calling "dSP" and
1431               "dMARK".  Sets up the "ax" and "items" variables by calling
1432               "dAX" and "dITEMS".  This is usually handled automatically by
1433               "xsubpp".
1434
1435                               dXSARGS;
1436
1437       dXSI32  Sets up the "ix" variable for an XSUB which has aliases.  This
1438               is usually handled automatically by "xsubpp".
1439
1440                               dXSI32;
1441
1442       items   Variable which is setup by "xsubpp" to indicate the number of
1443               items on the stack.  See "Variable-length Parameter Lists" in
1444               perlxs.
1445
1446                       I32     items
1447
1448       ix      Variable which is setup by "xsubpp" to indicate which of an
1449               XSUB's aliases was used to invoke it.  See "The ALIAS: Keyword"
1450               in perlxs.
1451
1452                       I32     ix
1453
1454       RETVAL  Variable which is setup by "xsubpp" to hold the return value
1455               for an XSUB.  This is always the proper type for the XSUB.  See
1456               "The RETVAL Variable" in perlxs.
1457
1458                       (whatever)      RETVAL
1459
1460       ST      Used to access elements on the XSUB's stack.
1461
1462                       SV*     ST(int ix)
1463
1464       THIS    Variable which is setup by "xsubpp" to designate the object in
1465               a C++ XSUB.  This is always the proper type for the C++ object.
1466               See "CLASS" and "Using XS With C++" in perlxs.
1467
1468                       (whatever)      THIS
1469
1470       UNDERBAR
1471               The SV* corresponding to the $_ variable.  Works even if there
1472               is a lexical $_ in scope.
1473
1474       XS      Macro to declare an XSUB and its C parameter list.  This is
1475               handled by "xsubpp".  It is the same as using the more explicit
1476               "XS_EXTERNAL" macro.
1477
1478       XS_EXTERNAL
1479               Macro to declare an XSUB and its C parameter list explicitly
1480               exporting the symbols.
1481
1482       XS_INTERNAL
1483               Macro to declare an XSUB and its C parameter list without
1484               exporting the symbols.  This is handled by "xsubpp" and
1485               generally preferable over exporting the XSUB symbols
1486               unnecessarily.
1487

Debugging Utilities

1489       dump_all
1490               Dumps the entire optree of the current program starting at
1491               "PL_main_root" to "STDERR".  Also dumps the optrees for all
1492               visible subroutines in "PL_defstash".
1493
1494                       void    dump_all()
1495
1496       dump_packsubs
1497               Dumps the optrees for all visible subroutines in "stash".
1498
1499                       void    dump_packsubs(const HV* stash)
1500
1501       op_class
1502               Given an op, determine what type of struct it has been
1503               allocated as.  Returns one of the OPclass enums, such as
1504               OPclass_LISTOP.
1505
1506                       OPclass op_class(const OP *o)
1507
1508       op_dump Dumps the optree starting at OP "o" to "STDERR".
1509
1510                       void    op_dump(const OP *o)
1511
1512       sv_dump Dumps the contents of an SV to the "STDERR" filehandle.
1513
1514               For an example of its output, see Devel::Peek.
1515
1516                       void    sv_dump(SV* sv)
1517

Display and Dump functions

1519       pv_display
1520               Similar to
1521
1522                 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
1523
1524               except that an additional "\0" will be appended to the string
1525               when len > cur and pv[cur] is "\0".
1526
1527               Note that the final string may be up to 7 chars longer than
1528               pvlim.
1529
1530                       char*   pv_display(SV *dsv, const char *pv, STRLEN cur,
1531                                          STRLEN len, STRLEN pvlim)
1532
1533       pv_escape
1534               Escapes at most the first "count" chars of "pv" and puts the
1535               results into "dsv" such that the size of the escaped string
1536               will not exceed "max" chars and will not contain any incomplete
1537               escape sequences.  The number of bytes escaped will be returned
1538               in the "STRLEN *escaped" parameter if it is not null.  When the
1539               "dsv" parameter is null no escaping actually occurs, but the
1540               number of bytes that would be escaped were it not null will be
1541               calculated.
1542
1543               If flags contains "PERL_PV_ESCAPE_QUOTE" then any double quotes
1544               in the string will also be escaped.
1545
1546               Normally the SV will be cleared before the escaped string is
1547               prepared, but when "PERL_PV_ESCAPE_NOCLEAR" is set this will
1548               not occur.
1549
1550               If "PERL_PV_ESCAPE_UNI" is set then the input string is treated
1551               as UTF-8 if "PERL_PV_ESCAPE_UNI_DETECT" is set then the input
1552               string is scanned using "is_utf8_string()" to determine if it
1553               is UTF-8.
1554
1555               If "PERL_PV_ESCAPE_ALL" is set then all input chars will be
1556               output using "\x01F1" style escapes, otherwise if
1557               "PERL_PV_ESCAPE_NONASCII" is set, only non-ASCII chars will be
1558               escaped using this style; otherwise, only chars above 255 will
1559               be so escaped; other non printable chars will use octal or
1560               common escaped patterns like "\n".  Otherwise, if
1561               "PERL_PV_ESCAPE_NOBACKSLASH" then all chars below 255 will be
1562               treated as printable and will be output as literals.
1563
1564               If "PERL_PV_ESCAPE_FIRSTCHAR" is set then only the first char
1565               of the string will be escaped, regardless of max.  If the
1566               output is to be in hex, then it will be returned as a plain hex
1567               sequence.  Thus the output will either be a single char, an
1568               octal escape sequence, a special escape like "\n" or a hex
1569               value.
1570
1571               If "PERL_PV_ESCAPE_RE" is set then the escape char used will be
1572               a "%" and not a "\\".  This is because regexes very often
1573               contain backslashed sequences, whereas "%" is not a
1574               particularly common character in patterns.
1575
1576               Returns a pointer to the escaped text as held by "dsv".
1577
1578                       char*   pv_escape(SV *dsv, char const * const str,
1579                                         const STRLEN count, const STRLEN max,
1580                                         STRLEN * const escaped,
1581                                         const U32 flags)
1582
1583       pv_pretty
1584               Converts a string into something presentable, handling escaping
1585               via "pv_escape()" and supporting quoting and ellipses.
1586
1587               If the "PERL_PV_PRETTY_QUOTE" flag is set then the result will
1588               be double quoted with any double quotes in the string escaped.
1589               Otherwise if the "PERL_PV_PRETTY_LTGT" flag is set then the
1590               result be wrapped in angle brackets.
1591
1592               If the "PERL_PV_PRETTY_ELLIPSES" flag is set and not all
1593               characters in string were output then an ellipsis "..." will be
1594               appended to the string.  Note that this happens AFTER it has
1595               been quoted.
1596
1597               If "start_color" is non-null then it will be inserted after the
1598               opening quote (if there is one) but before the escaped text.
1599               If "end_color" is non-null then it will be inserted after the
1600               escaped text but before any quotes or ellipses.
1601
1602               Returns a pointer to the prettified text as held by "dsv".
1603
1604                       char*   pv_pretty(SV *dsv, char const * const str,
1605                                         const STRLEN count, const STRLEN max,
1606                                         char const * const start_color,
1607                                         char const * const end_color,
1608                                         const U32 flags)
1609

Embedding Functions

1611       cv_clone
1612               Clone a CV, making a lexical closure.  "proto" supplies the
1613               prototype of the function: its code, pad structure, and other
1614               attributes.  The prototype is combined with a capture of outer
1615               lexicals to which the code refers, which are taken from the
1616               currently-executing instance of the immediately surrounding
1617               code.
1618
1619                       CV*     cv_clone(CV* proto)
1620
1621       cv_name Returns an SV containing the name of the CV, mainly for use in
1622               error reporting.  The CV may actually be a GV instead, in which
1623               case the returned SV holds the GV's name.  Anything other than
1624               a GV or CV is treated as a string already holding the sub name,
1625               but this could change in the future.
1626
1627               An SV may be passed as a second argument.  If so, the name will
1628               be assigned to it and it will be returned.  Otherwise the
1629               returned SV will be a new mortal.
1630
1631               If "flags" has the "CV_NAME_NOTQUAL" bit set, then the package
1632               name will not be included.  If the first argument is neither a
1633               CV nor a GV, this flag is ignored (subject to change).
1634
1635                       SV *    cv_name(CV *cv, SV *sv, U32 flags)
1636
1637       cv_undef
1638               Clear out all the active components of a CV.  This can happen
1639               either by an explicit "undef &foo", or by the reference count
1640               going to zero.  In the former case, we keep the "CvOUTSIDE"
1641               pointer, so that any anonymous children can still follow the
1642               full lexical scope chain.
1643
1644                       void    cv_undef(CV* cv)
1645
1646       find_rundefsv
1647               Returns the global variable $_.
1648
1649                       SV*     find_rundefsv()
1650
1651       find_rundefsvoffset
1652               DEPRECATED!  It is planned to remove this function from a
1653               future release of Perl.  Do not use it for new code; remove it
1654               from existing code.
1655
1656               Until the lexical $_ feature was removed, this function would
1657               find the position of the lexical $_ in the pad of the
1658               currently-executing function and return the offset in the
1659               current pad, or "NOT_IN_PAD".
1660
1661               Now it always returns "NOT_IN_PAD".
1662
1663                       PADOFFSET find_rundefsvoffset()
1664
1665       intro_my
1666               "Introduce" "my" variables to visible status.  This is called
1667               during parsing at the end of each statement to make lexical
1668               variables visible to subsequent statements.
1669
1670                       U32     intro_my()
1671
1672       load_module
1673               Loads the module whose name is pointed to by the string part of
1674               "name".  Note that the actual module name, not its filename,
1675               should be given.  Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver,
1676               if specified and not NULL, provides version semantics similar
1677               to "use Foo::Bar VERSION". The optional trailing arguments can
1678               be used to specify arguments to the module's "import()" method,
1679               similar to "use Foo::Bar VERSION LIST"; their precise handling
1680               depends on the flags. The flags argument is a bitwise-ORed
1681               collection of any of "PERL_LOADMOD_DENY",
1682               "PERL_LOADMOD_NOIMPORT", or "PERL_LOADMOD_IMPORT_OPS" (or 0 for
1683               no flags).
1684
1685               If "PERL_LOADMOD_NOIMPORT" is set, the module is loaded as if
1686               with an empty import list, as in "use Foo::Bar ()"; this is the
1687               only circumstance in which the trailing optional arguments may
1688               be omitted entirely. Otherwise, if "PERL_LOADMOD_IMPORT_OPS" is
1689               set, the trailing arguments must consist of exactly one "OP*",
1690               containing the op tree that produces the relevant import
1691               arguments. Otherwise, the trailing arguments must all be "SV*"
1692               values that will be used as import arguments; and the list must
1693               be terminated with "(SV*) NULL". If neither
1694               "PERL_LOADMOD_NOIMPORT" nor "PERL_LOADMOD_IMPORT_OPS" is set,
1695               the trailing "NULL" pointer is needed even if no import
1696               arguments are desired. The reference count for each specified
1697               "SV*" argument is decremented. In addition, the "name" argument
1698               is modified.
1699
1700               If "PERL_LOADMOD_DENY" is set, the module is loaded as if with
1701               "no" rather than "use".
1702
1703                       void    load_module(U32 flags, SV* name, SV* ver, ...)
1704
1705       my_exit A wrapper for the C library exit(3), honoring what
1706               "PL_exit_flags" in perlapi say to do.
1707
1708                       void    my_exit(U32 status)
1709
1710       newPADNAMELIST
1711               NOTE: this function is experimental and may change or be
1712               removed without notice.
1713
1714               Creates a new pad name list.  "max" is the highest index for
1715               which space is allocated.
1716
1717                       PADNAMELIST * newPADNAMELIST(size_t max)
1718
1719       newPADNAMEouter
1720               NOTE: this function is experimental and may change or be
1721               removed without notice.
1722
1723               Constructs and returns a new pad name.  Only use this function
1724               for names that refer to outer lexicals.  (See also
1725               "newPADNAMEpvn".)  "outer" is the outer pad name that this one
1726               mirrors.  The returned pad name has the "PADNAMEt_OUTER" flag
1727               already set.
1728
1729                       PADNAME * newPADNAMEouter(PADNAME *outer)
1730
1731       newPADNAMEpvn
1732               NOTE: this function is experimental and may change or be
1733               removed without notice.
1734
1735               Constructs and returns a new pad name.  "s" must be a UTF-8
1736               string.  Do not use this for pad names that point to outer
1737               lexicals.  See "newPADNAMEouter".
1738
1739                       PADNAME * newPADNAMEpvn(const char *s, STRLEN len)
1740
1741       nothreadhook
1742               Stub that provides thread hook for perl_destruct when there are
1743               no threads.
1744
1745                       int     nothreadhook()
1746
1747       pad_add_anon
1748               Allocates a place in the currently-compiling pad (via
1749               "pad_alloc") for an anonymous function that is lexically scoped
1750               inside the currently-compiling function.  The function "func"
1751               is linked into the pad, and its "CvOUTSIDE" link to the outer
1752               scope is weakened to avoid a reference loop.
1753
1754               One reference count is stolen, so you may need to do
1755               "SvREFCNT_inc(func)".
1756
1757               "optype" should be an opcode indicating the type of operation
1758               that the pad entry is to support.  This doesn't affect
1759               operational semantics, but is used for debugging.
1760
1761                       PADOFFSET pad_add_anon(CV* func, I32 optype)
1762
1763       pad_add_name_pv
1764               Exactly like "pad_add_name_pvn", but takes a nul-terminated
1765               string instead of a string/length pair.
1766
1767                       PADOFFSET pad_add_name_pv(const char *name,
1768                                                 const U32 flags,
1769                                                 HV *typestash, HV *ourstash)
1770
1771       pad_add_name_pvn
1772               Allocates a place in the currently-compiling pad for a named
1773               lexical variable.  Stores the name and other metadata in the
1774               name part of the pad, and makes preparations to manage the
1775               variable's lexical scoping.  Returns the offset of the
1776               allocated pad slot.
1777
1778               "namepv"/"namelen" specify the variable's name, including
1779               leading sigil.  If "typestash" is non-null, the name is for a
1780               typed lexical, and this identifies the type.  If "ourstash" is
1781               non-null, it's a lexical reference to a package variable, and
1782               this identifies the package.  The following flags can be OR'ed
1783               together:
1784
1785                padadd_OUR          redundantly specifies if it's a package var
1786                padadd_STATE        variable will retain value persistently
1787                padadd_NO_DUP_CHECK skip check for lexical shadowing
1788
1789                       PADOFFSET pad_add_name_pvn(const char *namepv,
1790                                                  STRLEN namelen, U32 flags,
1791                                                  HV *typestash, HV *ourstash)
1792
1793       pad_add_name_sv
1794               Exactly like "pad_add_name_pvn", but takes the name string in
1795               the form of an SV instead of a string/length pair.
1796
1797                       PADOFFSET pad_add_name_sv(SV *name, U32 flags,
1798                                                 HV *typestash, HV *ourstash)
1799
1800       pad_alloc
1801               NOTE: this function is experimental and may change or be
1802               removed without notice.
1803
1804               Allocates a place in the currently-compiling pad, returning the
1805               offset of the allocated pad slot.  No name is initially
1806               attached to the pad slot.  "tmptype" is a set of flags
1807               indicating the kind of pad entry required, which will be set in
1808               the value SV for the allocated pad entry:
1809
1810                   SVs_PADMY    named lexical variable ("my", "our", "state")
1811                   SVs_PADTMP   unnamed temporary store
1812                   SVf_READONLY constant shared between recursion levels
1813
1814               "SVf_READONLY" has been supported here only since perl 5.20.
1815               To work with earlier versions as well, use
1816               "SVf_READONLY|SVs_PADTMP".  "SVf_READONLY" does not cause the
1817               SV in the pad slot to be marked read-only, but simply tells
1818               "pad_alloc" that it will be made read-only (by the caller), or
1819               at least should be treated as such.
1820
1821               "optype" should be an opcode indicating the type of operation
1822               that the pad entry is to support.  This doesn't affect
1823               operational semantics, but is used for debugging.
1824
1825                       PADOFFSET pad_alloc(I32 optype, U32 tmptype)
1826
1827       pad_findmy_pv
1828               Exactly like "pad_findmy_pvn", but takes a nul-terminated
1829               string instead of a string/length pair.
1830
1831                       PADOFFSET pad_findmy_pv(const char* name, U32 flags)
1832
1833       pad_findmy_pvn
1834               Given the name of a lexical variable, find its position in the
1835               currently-compiling pad.  "namepv"/"namelen" specify the
1836               variable's name, including leading sigil.  "flags" is reserved
1837               and must be zero.  If it is not in the current pad but appears
1838               in the pad of any lexically enclosing scope, then a pseudo-
1839               entry for it is added in the current pad.  Returns the offset
1840               in the current pad, or "NOT_IN_PAD" if no such lexical is in
1841               scope.
1842
1843                       PADOFFSET pad_findmy_pvn(const char* namepv,
1844                                                STRLEN namelen, U32 flags)
1845
1846       pad_findmy_sv
1847               Exactly like "pad_findmy_pvn", but takes the name string in the
1848               form of an SV instead of a string/length pair.
1849
1850                       PADOFFSET pad_findmy_sv(SV* name, U32 flags)
1851
1852       padnamelist_fetch
1853               NOTE: this function is experimental and may change or be
1854               removed without notice.
1855
1856               Fetches the pad name from the given index.
1857
1858                       PADNAME * padnamelist_fetch(PADNAMELIST *pnl,
1859                                                   SSize_t key)
1860
1861       padnamelist_store
1862               NOTE: this function is experimental and may change or be
1863               removed without notice.
1864
1865               Stores the pad name (which may be null) at the given index,
1866               freeing any existing pad name in that slot.
1867
1868                       PADNAME ** padnamelist_store(PADNAMELIST *pnl,
1869                                                    SSize_t key, PADNAME *val)
1870
1871       pad_setsv
1872               Set the value at offset "po" in the current (compiling or
1873               executing) pad.  Use the macro "PAD_SETSV()" rather than
1874               calling this function directly.
1875
1876                       void    pad_setsv(PADOFFSET po, SV* sv)
1877
1878       pad_sv  Get the value at offset "po" in the current (compiling or
1879               executing) pad.  Use macro "PAD_SV" instead of calling this
1880               function directly.
1881
1882                       SV*     pad_sv(PADOFFSET po)
1883
1884       pad_tidy
1885               NOTE: this function is experimental and may change or be
1886               removed without notice.
1887
1888               Tidy up a pad at the end of compilation of the code to which it
1889               belongs.  Jobs performed here are: remove most stuff from the
1890               pads of anonsub prototypes; give it a @_; mark temporaries as
1891               such.  "type" indicates the kind of subroutine:
1892
1893                   padtidy_SUB        ordinary subroutine
1894                   padtidy_SUBCLONE   prototype for lexical closure
1895                   padtidy_FORMAT     format
1896
1897                       void    pad_tidy(padtidy_type type)
1898
1899       perl_alloc
1900               Allocates a new Perl interpreter.  See perlembed.
1901
1902                       PerlInterpreter* perl_alloc()
1903
1904       perl_construct
1905               Initializes a new Perl interpreter.  See perlembed.
1906
1907                       void    perl_construct(PerlInterpreter *my_perl)
1908
1909       perl_destruct
1910               Shuts down a Perl interpreter.  See perlembed for a tutorial.
1911
1912               "my_perl" points to the Perl interpreter.  It must have been
1913               previously created through the use of "perl_alloc" and
1914               "perl_construct".  It may have been initialised through
1915               "perl_parse", and may have been used through "perl_run" and
1916               other means.  This function should be called for any Perl
1917               interpreter that has been constructed with "perl_construct",
1918               even if subsequent operations on it failed, for example if
1919               "perl_parse" returned a non-zero value.
1920
1921               If the interpreter's "PL_exit_flags" word has the
1922               "PERL_EXIT_DESTRUCT_END" flag set, then this function will
1923               execute code in "END" blocks before performing the rest of
1924               destruction.  If it is desired to make any use of the
1925               interpreter between "perl_parse" and "perl_destruct" other than
1926               just calling "perl_run", then this flag should be set early on.
1927               This matters if "perl_run" will not be called, or if anything
1928               else will be done in addition to calling "perl_run".
1929
1930               Returns a value be a suitable value to pass to the C library
1931               function "exit" (or to return from "main"), to serve as an exit
1932               code indicating the nature of the way the interpreter
1933               terminated.  This takes into account any failure of
1934               "perl_parse" and any early exit from "perl_run".  The exit code
1935               is of the type required by the host operating system, so
1936               because of differing exit code conventions it is not portable
1937               to interpret specific numeric values as having specific
1938               meanings.
1939
1940                       int     perl_destruct(PerlInterpreter *my_perl)
1941
1942       perl_free
1943               Releases a Perl interpreter.  See perlembed.
1944
1945                       void    perl_free(PerlInterpreter *my_perl)
1946
1947       perl_parse
1948               Tells a Perl interpreter to parse a Perl script.  This performs
1949               most of the initialisation of a Perl interpreter.  See
1950               perlembed for a tutorial.
1951
1952               "my_perl" points to the Perl interpreter that is to parse the
1953               script.  It must have been previously created through the use
1954               of "perl_alloc" and "perl_construct".  "xsinit" points to a
1955               callback function that will be called to set up the ability for
1956               this Perl interpreter to load XS extensions, or may be null to
1957               perform no such setup.
1958
1959               "argc" and "argv" supply a set of command-line arguments to the
1960               Perl interpreter, as would normally be passed to the "main"
1961               function of a C program.  "argv[argc]" must be null.  These
1962               arguments are where the script to parse is specified, either by
1963               naming a script file or by providing a script in a "-e" option.
1964               If $0 will be written to in the Perl interpreter, then the
1965               argument strings must be in writable memory, and so mustn't
1966               just be string constants.
1967
1968               "env" specifies a set of environment variables that will be
1969               used by this Perl interpreter.  If non-null, it must point to a
1970               null-terminated array of environment strings.  If null, the
1971               Perl interpreter will use the environment supplied by the
1972               "environ" global variable.
1973
1974               This function initialises the interpreter, and parses and
1975               compiles the script specified by the command-line arguments.
1976               This includes executing code in "BEGIN", "UNITCHECK", and
1977               "CHECK" blocks.  It does not execute "INIT" blocks or the main
1978               program.
1979
1980               Returns an integer of slightly tricky interpretation.  The
1981               correct use of the return value is as a truth value indicating
1982               whether there was a failure in initialisation.  If zero is
1983               returned, this indicates that initialisation was successful,
1984               and it is safe to proceed to call "perl_run" and make other use
1985               of it.  If a non-zero value is returned, this indicates some
1986               problem that means the interpreter wants to terminate.  The
1987               interpreter should not be just abandoned upon such failure; the
1988               caller should proceed to shut the interpreter down cleanly with
1989               "perl_destruct" and free it with "perl_free".
1990
1991               For historical reasons, the non-zero return value also attempts
1992               to be a suitable value to pass to the C library function "exit"
1993               (or to return from "main"), to serve as an exit code indicating
1994               the nature of the way initialisation terminated.  However, this
1995               isn't portable, due to differing exit code conventions.  A
1996               historical bug is preserved for the time being: if the Perl
1997               built-in "exit" is called during this function's execution,
1998               with a type of exit entailing a zero exit code under the host
1999               operating system's conventions, then this function returns zero
2000               rather than a non-zero value.  This bug, [perl #2754], leads to
2001               "perl_run" being called (and therefore "INIT" blocks and the
2002               main program running) despite a call to "exit".  It has been
2003               preserved because a popular module-installing module has come
2004               to rely on it and needs time to be fixed.  This issue is [perl
2005               #132577], and the original bug is due to be fixed in Perl 5.30.
2006
2007                       int     perl_parse(PerlInterpreter *my_perl,
2008                                          XSINIT_t xsinit, int argc,
2009                                          char** argv, char** env)
2010
2011       perl_run
2012               Tells a Perl interpreter to run its main program.  See
2013               perlembed for a tutorial.
2014
2015               "my_perl" points to the Perl interpreter.  It must have been
2016               previously created through the use of "perl_alloc" and
2017               "perl_construct", and initialised through "perl_parse".  This
2018               function should not be called if "perl_parse" returned a non-
2019               zero value, indicating a failure in initialisation or
2020               compilation.
2021
2022               This function executes code in "INIT" blocks, and then executes
2023               the main program.  The code to be executed is that established
2024               by the prior call to "perl_parse".  If the interpreter's
2025               "PL_exit_flags" word does not have the "PERL_EXIT_DESTRUCT_END"
2026               flag set, then this function will also execute code in "END"
2027               blocks.  If it is desired to make any further use of the
2028               interpreter after calling this function, then "END" blocks
2029               should be postponed to "perl_destruct" time by setting that
2030               flag.
2031
2032               Returns an integer of slightly tricky interpretation.  The
2033               correct use of the return value is as a truth value indicating
2034               whether the program terminated non-locally.  If zero is
2035               returned, this indicates that the program ran to completion,
2036               and it is safe to make other use of the interpreter (provided
2037               that the "PERL_EXIT_DESTRUCT_END" flag was set as described
2038               above).  If a non-zero value is returned, this indicates that
2039               the interpreter wants to terminate early.  The interpreter
2040               should not be just abandoned because of this desire to
2041               terminate; the caller should proceed to shut the interpreter
2042               down cleanly with "perl_destruct" and free it with "perl_free".
2043
2044               For historical reasons, the non-zero return value also attempts
2045               to be a suitable value to pass to the C library function "exit"
2046               (or to return from "main"), to serve as an exit code indicating
2047               the nature of the way the program terminated.  However, this
2048               isn't portable, due to differing exit code conventions.  An
2049               attempt is made to return an exit code of the type required by
2050               the host operating system, but because it is constrained to be
2051               non-zero, it is not necessarily possible to indicate every type
2052               of exit.  It is only reliable on Unix, where a zero exit code
2053               can be augmented with a set bit that will be ignored.  In any
2054               case, this function is not the correct place to acquire an exit
2055               code: one should get that from "perl_destruct".
2056
2057                       int     perl_run(PerlInterpreter *my_perl)
2058
2059       require_pv
2060               Tells Perl to "require" the file named by the string argument.
2061               It is analogous to the Perl code "eval "require '$file'"".
2062               It's even implemented that way; consider using load_module
2063               instead.
2064
2065               NOTE: the perl_ form of this function is deprecated.
2066
2067                       void    require_pv(const char* pv)
2068

Exception Handling (simple) Macros

2070       dXCPT   Set up necessary local variables for exception handling.  See
2071               "Exception Handling" in perlguts.
2072
2073                               dXCPT;
2074
2075       XCPT_CATCH
2076               Introduces a catch block.  See "Exception Handling" in
2077               perlguts.
2078
2079       XCPT_RETHROW
2080               Rethrows a previously caught exception.  See "Exception
2081               Handling" in perlguts.
2082
2083                               XCPT_RETHROW;
2084
2085       XCPT_TRY_END
2086               Ends a try block.  See "Exception Handling" in perlguts.
2087
2088       XCPT_TRY_START
2089               Starts a try block.  See "Exception Handling" in perlguts.
2090

Functions in file inline.h

2092       av_count
2093               Returns the number of elements in the array "av".  This is the
2094               true length of the array, including any undefined elements.  It
2095               is always the same as "av_top_index(av) + 1".
2096
2097                       Size_t  av_count(AV *av)
2098

Functions in file vutil.c

2100       new_version
2101               Returns a new version object based on the passed in SV:
2102
2103                   SV *sv = new_version(SV *ver);
2104
2105               Does not alter the passed in ver SV.  See "upg_version" if you
2106               want to upgrade the SV.
2107
2108                       SV*     new_version(SV *ver)
2109
2110       prescan_version
2111               Validate that a given string can be parsed as a version object,
2112               but doesn't actually perform the parsing.  Can use either
2113               strict or lax validation rules.  Can optionally set a number of
2114               hint variables to save the parsing code some time when
2115               tokenizing.
2116
2117                       const char* prescan_version(const char *s, bool strict,
2118                                                   const char** errstr,
2119                                                   bool *sqv,
2120                                                   int *ssaw_decimal,
2121                                                   int *swidth, bool *salpha)
2122
2123       scan_version
2124               Returns a pointer to the next character after the parsed
2125               version string, as well as upgrading the passed in SV to an RV.
2126
2127               Function must be called with an already existing SV like
2128
2129                   sv = newSV(0);
2130                   s = scan_version(s, SV *sv, bool qv);
2131
2132               Performs some preprocessing to the string to ensure that it has
2133               the correct characteristics of a version.  Flags the object if
2134               it contains an underscore (which denotes this is an alpha
2135               version).  The boolean qv denotes that the version should be
2136               interpreted as if it had multiple decimals, even if it doesn't.
2137
2138                       const char* scan_version(const char *s, SV *rv, bool qv)
2139
2140       upg_version
2141               In-place upgrade of the supplied SV to a version object.
2142
2143                   SV *sv = upg_version(SV *sv, bool qv);
2144
2145               Returns a pointer to the upgraded SV.  Set the boolean qv if
2146               you want to force this SV to be interpreted as an "extended"
2147               version.
2148
2149                       SV*     upg_version(SV *ver, bool qv)
2150
2151       vcmp    Version object aware cmp.  Both operands must already have been
2152               converted into version objects.
2153
2154                       int     vcmp(SV *lhv, SV *rhv)
2155
2156       vnormal Accepts a version object and returns the normalized string
2157               representation.  Call like:
2158
2159                   sv = vnormal(rv);
2160
2161               NOTE: you can pass either the object directly or the SV
2162               contained within the RV.
2163
2164               The SV returned has a refcount of 1.
2165
2166                       SV*     vnormal(SV *vs)
2167
2168       vnumify Accepts a version object and returns the normalized floating
2169               point representation.  Call like:
2170
2171                   sv = vnumify(rv);
2172
2173               NOTE: you can pass either the object directly or the SV
2174               contained within the RV.
2175
2176               The SV returned has a refcount of 1.
2177
2178                       SV*     vnumify(SV *vs)
2179
2180       vstringify
2181               In order to maintain maximum compatibility with earlier
2182               versions of Perl, this function will return either the floating
2183               point notation or the multiple dotted notation, depending on
2184               whether the original version contained 1 or more dots,
2185               respectively.
2186
2187               The SV returned has a refcount of 1.
2188
2189                       SV*     vstringify(SV *vs)
2190
2191       vverify Validates that the SV contains valid internal structure for a
2192               version object.  It may be passed either the version object
2193               (RV) or the hash itself (HV).  If the structure is valid, it
2194               returns the HV.  If the structure is invalid, it returns NULL.
2195
2196                   SV *hv = vverify(sv);
2197
2198               Note that it only confirms the bare minimum structure (so as
2199               not to get confused by derived classes which may contain
2200               additional hash entries):
2201
2202               ·   The SV is an HV or a reference to an HV
2203
2204               ·   The hash contains a "version" key
2205
2206               ·   The "version" key has a reference to an AV as its value
2207
2208                       SV*     vverify(SV *vs)
2209

"Gimme" Values

2211       G_ARRAY Used to indicate list context.  See "GIMME_V", "GIMME" and
2212               perlcall.
2213
2214       G_DISCARD
2215               Indicates that arguments returned from a callback should be
2216               discarded.  See perlcall.
2217
2218       G_EVAL  Used to force a Perl "eval" wrapper around a callback.  See
2219               perlcall.
2220
2221       GIMME   A backward-compatible version of "GIMME_V" which can only
2222               return "G_SCALAR" or "G_ARRAY"; in a void context, it returns
2223               "G_SCALAR".  Deprecated.  Use "GIMME_V" instead.
2224
2225                       U32     GIMME
2226
2227       GIMME_V The XSUB-writer's equivalent to Perl's "wantarray".  Returns
2228               "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list
2229               context, respectively.  See perlcall for a usage example.
2230
2231                       U32     GIMME_V
2232
2233       G_NOARGS
2234               Indicates that no arguments are being sent to a callback.  See
2235               perlcall.
2236
2237       G_SCALAR
2238               Used to indicate scalar context.  See "GIMME_V", "GIMME", and
2239               perlcall.
2240
2241       G_VOID  Used to indicate void context.  See "GIMME_V" and perlcall.
2242

Global Variables

2244       These variables are global to an entire process.  They are shared
2245       between all interpreters and all threads in a process.  Any variables
2246       not documented here may be changed or removed without notice, so don't
2247       use them!  If you feel you really do need to use an unlisted variable,
2248       first send email to perl5-porters@perl.org
2249       <mailto:perl5-porters@perl.org>.  It may be that someone there will
2250       point out a way to accomplish what you need without using an internal
2251       variable.  But if not, you should get a go-ahead to document and then
2252       use the variable.
2253
2254       PL_check
2255               Array, indexed by opcode, of functions that will be called for
2256               the "check" phase of optree building during compilation of Perl
2257               code.  For most (but not all) types of op, once the op has been
2258               initially built and populated with child ops it will be
2259               filtered through the check function referenced by the
2260               appropriate element of this array.  The new op is passed in as
2261               the sole argument to the check function, and the check function
2262               returns the completed op.  The check function may (as the name
2263               suggests) check the op for validity and signal errors.  It may
2264               also initialise or modify parts of the ops, or perform more
2265               radical surgery such as adding or removing child ops, or even
2266               throw the op away and return a different op in its place.
2267
2268               This array of function pointers is a convenient place to hook
2269               into the compilation process.  An XS module can put its own
2270               custom check function in place of any of the standard ones, to
2271               influence the compilation of a particular type of op.  However,
2272               a custom check function must never fully replace a standard
2273               check function (or even a custom check function from another
2274               module).  A module modifying checking must instead wrap the
2275               preexisting check function.  A custom check function must be
2276               selective about when to apply its custom behaviour.  In the
2277               usual case where it decides not to do anything special with an
2278               op, it must chain the preexisting op function.  Check functions
2279               are thus linked in a chain, with the core's base checker at the
2280               end.
2281
2282               For thread safety, modules should not write directly to this
2283               array.  Instead, use the function "wrap_op_checker".
2284
2285       PL_keyword_plugin
2286               NOTE: this function is experimental and may change or be
2287               removed without notice.
2288
2289               Function pointer, pointing at a function used to handle
2290               extended keywords.  The function should be declared as
2291
2292                       int keyword_plugin_function(pTHX_
2293                               char *keyword_ptr, STRLEN keyword_len,
2294                               OP **op_ptr)
2295
2296               The function is called from the tokeniser, whenever a possible
2297               keyword is seen.  "keyword_ptr" points at the word in the
2298               parser's input buffer, and "keyword_len" gives its length; it
2299               is not null-terminated.  The function is expected to examine
2300               the word, and possibly other state such as %^H, to decide
2301               whether it wants to handle it as an extended keyword.  If it
2302               does not, the function should return "KEYWORD_PLUGIN_DECLINE",
2303               and the normal parser process will continue.
2304
2305               If the function wants to handle the keyword, it first must
2306               parse anything following the keyword that is part of the syntax
2307               introduced by the keyword.  See "Lexer interface" for details.
2308
2309               When a keyword is being handled, the plugin function must build
2310               a tree of "OP" structures, representing the code that was
2311               parsed.  The root of the tree must be stored in *op_ptr.  The
2312               function then returns a constant indicating the syntactic role
2313               of the construct that it has parsed: "KEYWORD_PLUGIN_STMT" if
2314               it is a complete statement, or "KEYWORD_PLUGIN_EXPR" if it is
2315               an expression.  Note that a statement construct cannot be used
2316               inside an expression (except via "do BLOCK" and similar), and
2317               an expression is not a complete statement (it requires at least
2318               a terminating semicolon).
2319
2320               When a keyword is handled, the plugin function may also have
2321               (compile-time) side effects.  It may modify "%^H", define
2322               functions, and so on.  Typically, if side effects are the main
2323               purpose of a handler, it does not wish to generate any ops to
2324               be included in the normal compilation.  In this case it is
2325               still required to supply an op tree, but it suffices to
2326               generate a single null op.
2327
2328               That's how the *PL_keyword_plugin function needs to behave
2329               overall.  Conventionally, however, one does not completely
2330               replace the existing handler function.  Instead, take a copy of
2331               "PL_keyword_plugin" before assigning your own function pointer
2332               to it.  Your handler function should look for keywords that it
2333               is interested in and handle those.  Where it is not interested,
2334               it should call the saved plugin function, passing on the
2335               arguments it received.  Thus "PL_keyword_plugin" actually
2336               points at a chain of handler functions, all of which have an
2337               opportunity to handle keywords, and only the last function in
2338               the chain (built into the Perl core) will normally return
2339               "KEYWORD_PLUGIN_DECLINE".
2340
2341               For thread safety, modules should not set this variable
2342               directly.  Instead, use the function "wrap_keyword_plugin".
2343
2344       PL_phase
2345               A value that indicates the current Perl interpreter's phase.
2346               Possible values include "PERL_PHASE_CONSTRUCT",
2347               "PERL_PHASE_START", "PERL_PHASE_CHECK", "PERL_PHASE_INIT",
2348               "PERL_PHASE_RUN", "PERL_PHASE_END", and "PERL_PHASE_DESTRUCT".
2349
2350               For example, the following determines whether the interpreter
2351               is in global destruction:
2352
2353                   if (PL_phase == PERL_PHASE_DESTRUCT) {
2354                       // we are in global destruction
2355                   }
2356
2357               "PL_phase" was introduced in Perl 5.14; in prior perls you can
2358               use "PL_dirty" (boolean) to determine whether the interpreter
2359               is in global destruction. (Use of "PL_dirty" is discouraged
2360               since 5.14.)
2361
2362                       enum perl_phase PL_phase
2363

GV Functions

2365       A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
2366       It is a structure that holds a pointer to a scalar, an array, a hash
2367       etc, corresponding to $foo, @foo, %foo.
2368
2369       GVs are usually found as values in stashes (symbol table hashes) where
2370       Perl stores its global variables.
2371
2372       GvAV    Return the AV from the GV.
2373
2374                       AV*     GvAV(GV* gv)
2375
2376       gv_const_sv
2377               If "gv" is a typeglob whose subroutine entry is a constant sub
2378               eligible for inlining, or "gv" is a placeholder reference that
2379               would be promoted to such a typeglob, then returns the value
2380               returned by the sub.  Otherwise, returns "NULL".
2381
2382                       SV*     gv_const_sv(GV* gv)
2383
2384       GvCV    Return the CV from the GV.
2385
2386                       CV*     GvCV(GV* gv)
2387
2388       gv_fetchmeth
2389               Like "gv_fetchmeth_pvn", but lacks a flags parameter.
2390
2391                       GV*     gv_fetchmeth(HV* stash, const char* name,
2392                                            STRLEN len, I32 level)
2393
2394       gv_fetchmethod_autoload
2395               Returns the glob which contains the subroutine to call to
2396               invoke the method on the "stash".  In fact in the presence of
2397               autoloading this may be the glob for "AUTOLOAD".  In this case
2398               the corresponding variable $AUTOLOAD is already setup.
2399
2400               The third parameter of "gv_fetchmethod_autoload" determines
2401               whether AUTOLOAD lookup is performed if the given method is not
2402               present: non-zero means yes, look for AUTOLOAD; zero means no,
2403               don't look for AUTOLOAD.  Calling "gv_fetchmethod" is
2404               equivalent to calling "gv_fetchmethod_autoload" with a non-zero
2405               "autoload" parameter.
2406
2407               These functions grant "SUPER" token as a prefix of the method
2408               name.  Note that if you want to keep the returned glob for a
2409               long time, you need to check for it being "AUTOLOAD", since at
2410               the later time the call may load a different subroutine due to
2411               $AUTOLOAD changing its value.  Use the glob created as a side
2412               effect to do this.
2413
2414               These functions have the same side-effects as "gv_fetchmeth"
2415               with "level==0".  The warning against passing the GV returned
2416               by "gv_fetchmeth" to "call_sv" applies equally to these
2417               functions.
2418
2419                       GV*     gv_fetchmethod_autoload(HV* stash,
2420                                                       const char* name,
2421                                                       I32 autoload)
2422
2423       gv_fetchmeth_autoload
2424               This is the old form of "gv_fetchmeth_pvn_autoload", which has
2425               no flags parameter.
2426
2427                       GV*     gv_fetchmeth_autoload(HV* stash,
2428                                                     const char* name,
2429                                                     STRLEN len, I32 level)
2430
2431       gv_fetchmeth_pv
2432               Exactly like "gv_fetchmeth_pvn", but takes a nul-terminated
2433               string instead of a string/length pair.
2434
2435                       GV*     gv_fetchmeth_pv(HV* stash, const char* name,
2436                                               I32 level, U32 flags)
2437
2438       gv_fetchmeth_pvn
2439               Returns the glob with the given "name" and a defined subroutine
2440               or "NULL".  The glob lives in the given "stash", or in the
2441               stashes accessible via @ISA and "UNIVERSAL::".
2442
2443               The argument "level" should be either 0 or -1.  If "level==0",
2444               as a side-effect creates a glob with the given "name" in the
2445               given "stash" which in the case of success contains an alias
2446               for the subroutine, and sets up caching info for this glob.
2447
2448               The only significant values for "flags" are "GV_SUPER" and
2449               "SVf_UTF8".
2450
2451               "GV_SUPER" indicates that we want to look up the method in the
2452               superclasses of the "stash".
2453
2454               The GV returned from "gv_fetchmeth" may be a method cache
2455               entry, which is not visible to Perl code.  So when calling
2456               "call_sv", you should not use the GV directly; instead, you
2457               should use the method's CV, which can be obtained from the GV
2458               with the "GvCV" macro.
2459
2460                       GV*     gv_fetchmeth_pvn(HV* stash, const char* name,
2461                                                STRLEN len, I32 level,
2462                                                U32 flags)
2463
2464       gv_fetchmeth_pvn_autoload
2465               Same as "gv_fetchmeth_pvn()", but looks for autoloaded
2466               subroutines too.  Returns a glob for the subroutine.
2467
2468               For an autoloaded subroutine without a GV, will create a GV
2469               even if "level < 0".  For an autoloaded subroutine without a
2470               stub, "GvCV()" of the result may be zero.
2471
2472               Currently, the only significant value for "flags" is
2473               "SVf_UTF8".
2474
2475                       GV*     gv_fetchmeth_pvn_autoload(HV* stash,
2476                                                         const char* name,
2477                                                         STRLEN len, I32 level,
2478                                                         U32 flags)
2479
2480       gv_fetchmeth_pv_autoload
2481               Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-
2482               terminated string instead of a string/length pair.
2483
2484                       GV*     gv_fetchmeth_pv_autoload(HV* stash,
2485                                                        const char* name,
2486                                                        I32 level, U32 flags)
2487
2488       gv_fetchmeth_sv
2489               Exactly like "gv_fetchmeth_pvn", but takes the name string in
2490               the form of an SV instead of a string/length pair.
2491
2492                       GV*     gv_fetchmeth_sv(HV* stash, SV* namesv,
2493                                               I32 level, U32 flags)
2494
2495       gv_fetchmeth_sv_autoload
2496               Exactly like "gv_fetchmeth_pvn_autoload", but takes the name
2497               string in the form of an SV instead of a string/length pair.
2498
2499                       GV*     gv_fetchmeth_sv_autoload(HV* stash, SV* namesv,
2500                                                        I32 level, U32 flags)
2501
2502       GvHV    Return the HV from the GV.
2503
2504                       HV*     GvHV(GV* gv)
2505
2506       gv_init The old form of "gv_init_pvn()".  It does not work with UTF-8
2507               strings, as it has no flags parameter.  If the "multi"
2508               parameter is set, the "GV_ADDMULTI" flag will be passed to
2509               "gv_init_pvn()".
2510
2511                       void    gv_init(GV* gv, HV* stash, const char* name,
2512                                       STRLEN len, int multi)
2513
2514       gv_init_pv
2515               Same as "gv_init_pvn()", but takes a nul-terminated string for
2516               the name instead of separate char * and length parameters.
2517
2518                       void    gv_init_pv(GV* gv, HV* stash, const char* name,
2519                                          U32 flags)
2520
2521       gv_init_pvn
2522               Converts a scalar into a typeglob.  This is an incoercible
2523               typeglob; assigning a reference to it will assign to one of its
2524               slots, instead of overwriting it as happens with typeglobs
2525               created by "SvSetSV".  Converting any scalar that is "SvOK()"
2526               may produce unpredictable results and is reserved for perl's
2527               internal use.
2528
2529               "gv" is the scalar to be converted.
2530
2531               "stash" is the parent stash/package, if any.
2532
2533               "name" and "len" give the name.  The name must be unqualified;
2534               that is, it must not include the package name.  If "gv" is a
2535               stash element, it is the caller's responsibility to ensure that
2536               the name passed to this function matches the name of the
2537               element.  If it does not match, perl's internal bookkeeping
2538               will get out of sync.
2539
2540               "flags" can be set to "SVf_UTF8" if "name" is a UTF-8 string,
2541               or the return value of SvUTF8(sv).  It can also take the
2542               "GV_ADDMULTI" flag, which means to pretend that the GV has been
2543               seen before (i.e., suppress "Used once" warnings).
2544
2545                       void    gv_init_pvn(GV* gv, HV* stash, const char* name,
2546                                           STRLEN len, U32 flags)
2547
2548       gv_init_sv
2549               Same as "gv_init_pvn()", but takes an SV * for the name instead
2550               of separate char * and length parameters.  "flags" is currently
2551               unused.
2552
2553                       void    gv_init_sv(GV* gv, HV* stash, SV* namesv,
2554                                          U32 flags)
2555
2556       gv_stashpv
2557               Returns a pointer to the stash for a specified package.  Uses
2558               "strlen" to determine the length of "name", then calls
2559               "gv_stashpvn()".
2560
2561                       HV*     gv_stashpv(const char* name, I32 flags)
2562
2563       gv_stashpvn
2564               Returns a pointer to the stash for a specified package.  The
2565               "namelen" parameter indicates the length of the "name", in
2566               bytes.  "flags" is passed to "gv_fetchpvn_flags()", so if set
2567               to "GV_ADD" then the package will be created if it does not
2568               already exist.  If the package does not exist and "flags" is 0
2569               (or any other setting that does not create packages) then
2570               "NULL" is returned.
2571
2572               Flags may be one of:
2573
2574                   GV_ADD
2575                   SVf_UTF8
2576                   GV_NOADD_NOINIT
2577                   GV_NOINIT
2578                   GV_NOEXPAND
2579                   GV_ADDMG
2580
2581               The most important of which are probably "GV_ADD" and
2582               "SVf_UTF8".
2583
2584               Note, use of "gv_stashsv" instead of "gv_stashpvn" where
2585               possible is strongly recommended for performance reasons.
2586
2587                       HV*     gv_stashpvn(const char* name, U32 namelen,
2588                                           I32 flags)
2589
2590       gv_stashpvs
2591               Like "gv_stashpvn", but takes a literal string instead of a
2592               string/length pair.
2593
2594                       HV*     gv_stashpvs("name", I32 create)
2595
2596       gv_stashsv
2597               Returns a pointer to the stash for a specified package.  See
2598               "gv_stashpvn".
2599
2600               Note this interface is strongly preferred over "gv_stashpvn"
2601               for performance reasons.
2602
2603                       HV*     gv_stashsv(SV* sv, I32 flags)
2604
2605       GvSV    Return the SV from the GV.
2606
2607                       SV*     GvSV(GV* gv)
2608
2609       save_gp Saves the current GP of gv on the save stack to be restored on
2610               scope exit.
2611
2612               If empty is true, replace the GP with a new GP.
2613
2614               If empty is false, mark gv with GVf_INTRO so the next reference
2615               assigned is localized, which is how " local *foo = $someref; "
2616               works.
2617
2618                       void    save_gp(GV* gv, I32 empty)
2619
2620       setdefout
2621               Sets "PL_defoutgv", the default file handle for output, to the
2622               passed in typeglob.  As "PL_defoutgv" "owns" a reference on its
2623               typeglob, the reference count of the passed in typeglob is
2624               increased by one, and the reference count of the typeglob that
2625               "PL_defoutgv" points to is decreased by one.
2626
2627                       void    setdefout(GV* gv)
2628

Handy Values

2630       C_ARRAY_END
2631               Returns a pointer to one element past the final element of the
2632               input C array.
2633
2634                       void *  C_ARRAY_END(void *a)
2635
2636       C_ARRAY_LENGTH
2637               Returns the number of elements in the input C array (so you
2638               want your zero-based indices to be less than but not equal to).
2639
2640                       STRLEN  C_ARRAY_LENGTH(void *a)
2641
2642       cBOOL   Cast-to-bool.  A simple "(bool) expr" cast may not do the right
2643               thing: if "bool" is defined as "char", for example, then the
2644               cast from "int" is implementation-defined.
2645
2646               "(bool)!!(cbool)" in a ternary triggers a bug in xlc on AIX
2647
2648                       bool    cBOOL(bool expr)
2649
2650       Nullav  DEPRECATED!  It is planned to remove this function from a
2651               future release of Perl.  Do not use it for new code; remove it
2652               from existing code.
2653
2654               Null AV pointer.
2655
2656               (deprecated - use "(AV *)NULL" instead)
2657
2658       Nullch  Null character pointer.  (No longer available when "PERL_CORE"
2659               is defined.)
2660
2661       Nullcv  DEPRECATED!  It is planned to remove this function from a
2662               future release of Perl.  Do not use it for new code; remove it
2663               from existing code.
2664
2665               Null CV pointer.
2666
2667               (deprecated - use "(CV *)NULL" instead)
2668
2669       Nullhv  DEPRECATED!  It is planned to remove this function from a
2670               future release of Perl.  Do not use it for new code; remove it
2671               from existing code.
2672
2673               Null HV pointer.
2674
2675               (deprecated - use "(HV *)NULL" instead)
2676
2677       Nullsv  Null SV pointer.  (No longer available when "PERL_CORE" is
2678               defined.)
2679
2680       STR_WITH_LEN
2681               Returns two comma separated tokens of the input literal string,
2682               and its length.  This is convenience macro which helps out in
2683               some API calls.  Note that it can't be used as an argument to
2684               macros or functions that under some configurations might be
2685               macros, which means that it requires the full Perl_xxx(aTHX_
2686               ...) form for any API calls where it's used.
2687
2688                       pair    STR_WITH_LEN("literal string")
2689
2690       __ASSERT_
2691               This is a helper macro to avoid preprocessor issues, replaced
2692               by nothing unless under DEBUGGING, where it expands to an
2693               assert of its argument, followed by a comma (hence the comma
2694               operator).  If we just used a straight assert(), we would get a
2695               comma with nothing before it when not DEBUGGING.
2696
2697                       void    __ASSERT_(bool expr)
2698

Hash Manipulation Functions

2700       A HV structure represents a Perl hash.  It consists mainly of an array
2701       of pointers, each of which points to a linked list of HE structures.
2702       The array is indexed by the hash function of the key, so each linked
2703       list represents all the hash entries with the same hash value.  Each HE
2704       contains a pointer to the actual value, plus a pointer to a HEK
2705       structure which holds the key and hash value.
2706
2707       cop_fetch_label
2708               NOTE: this function is experimental and may change or be
2709               removed without notice.
2710
2711               Returns the label attached to a cop, and stores its length in
2712               bytes into *len.  Upon return, *flags will be set to either
2713               "SVf_UTF8" or 0.
2714
2715               Alternatively, use the macro ""CopLABEL_len_flags""; or if you
2716               don't need to know if the label is UTF-8 or not, the macro
2717               ""CopLABEL_len""; or if you additionally dont need to know the
2718               length, ""CopLABEL"".
2719
2720                       const char * cop_fetch_label(COP *const cop,
2721                                                    STRLEN *len, U32 *flags)
2722
2723       cop_store_label
2724               NOTE: this function is experimental and may change or be
2725               removed without notice.
2726
2727               Save a label into a "cop_hints_hash".  You need to set flags to
2728               "SVf_UTF8" for a UTF-8 label.  Any other flag is ignored.
2729
2730                       void    cop_store_label(COP *const cop,
2731                                               const char *label, STRLEN len,
2732                                               U32 flags)
2733
2734       get_hv  Returns the HV of the specified Perl hash.  "flags" are passed
2735               to "gv_fetchpv".  If "GV_ADD" is set and the Perl variable does
2736               not exist then it will be created.  If "flags" is zero and the
2737               variable does not exist then "NULL" is returned.
2738
2739               NOTE: the perl_ form of this function is deprecated.
2740
2741                       HV*     get_hv(const char *name, I32 flags)
2742
2743       HEf_SVKEY
2744               This flag, used in the length slot of hash entries and magic
2745               structures, specifies the structure contains an "SV*" pointer
2746               where a "char*" pointer is to be expected.  (For information
2747               only--not to be used).
2748
2749       HeHASH  Returns the computed hash stored in the hash entry.
2750
2751                       U32     HeHASH(HE* he)
2752
2753       HeKEY   Returns the actual pointer stored in the key slot of the hash
2754               entry.  The pointer may be either "char*" or "SV*", depending
2755               on the value of "HeKLEN()".  Can be assigned to.  The "HePV()"
2756               or "HeSVKEY()" macros are usually preferable for finding the
2757               value of a key.
2758
2759                       void*   HeKEY(HE* he)
2760
2761       HeKLEN  If this is negative, and amounts to "HEf_SVKEY", it indicates
2762               the entry holds an "SV*" key.  Otherwise, holds the actual
2763               length of the key.  Can be assigned to.  The "HePV()" macro is
2764               usually preferable for finding key lengths.
2765
2766                       STRLEN  HeKLEN(HE* he)
2767
2768       HePV    Returns the key slot of the hash entry as a "char*" value,
2769               doing any necessary dereferencing of possibly "SV*" keys.  The
2770               length of the string is placed in "len" (this is a macro, so do
2771               not use &len).  If you do not care about what the length of the
2772               key is, you may use the global variable "PL_na", though this is
2773               rather less efficient than using a local variable.  Remember
2774               though, that hash keys in perl are free to contain embedded
2775               nulls, so using "strlen()" or similar is not a good way to find
2776               the length of hash keys.  This is very similar to the "SvPV()"
2777               macro described elsewhere in this document.  See also "HeUTF8".
2778
2779               If you are using "HePV" to get values to pass to "newSVpvn()"
2780               to create a new SV, you should consider using
2781               "newSVhek(HeKEY_hek(he))" as it is more efficient.
2782
2783                       char*   HePV(HE* he, STRLEN len)
2784
2785       HeSVKEY Returns the key as an "SV*", or "NULL" if the hash entry does
2786               not contain an "SV*" key.
2787
2788                       SV*     HeSVKEY(HE* he)
2789
2790       HeSVKEY_force
2791               Returns the key as an "SV*".  Will create and return a
2792               temporary mortal "SV*" if the hash entry contains only a
2793               "char*" key.
2794
2795                       SV*     HeSVKEY_force(HE* he)
2796
2797       HeSVKEY_set
2798               Sets the key to a given "SV*", taking care to set the
2799               appropriate flags to indicate the presence of an "SV*" key, and
2800               returns the same "SV*".
2801
2802                       SV*     HeSVKEY_set(HE* he, SV* sv)
2803
2804       HeUTF8  Returns whether the "char *" value returned by "HePV" is
2805               encoded in UTF-8, doing any necessary dereferencing of possibly
2806               "SV*" keys.  The value returned will be 0 or non-0, not
2807               necessarily 1 (or even a value with any low bits set), so do
2808               not blindly assign this to a "bool" variable, as "bool" may be
2809               a typedef for "char".
2810
2811                       U32     HeUTF8(HE* he)
2812
2813       HeVAL   Returns the value slot (type "SV*") stored in the hash entry.
2814               Can be assigned to.
2815
2816                 SV *foo= HeVAL(hv);
2817                 HeVAL(hv)= sv;
2818
2819
2820                       SV*     HeVAL(HE* he)
2821
2822       hv_assert
2823               Check that a hash is in an internally consistent state.
2824
2825               NOTE: this function must be explicitly called as Perl_hv_assert
2826               with an aTHX_ parameter.
2827
2828                       void    Perl_hv_assert(pTHX_ HV *hv)
2829
2830       hv_bucket_ratio
2831               NOTE: this function is experimental and may change or be
2832               removed without notice.
2833
2834               If the hash is tied dispatches through to the SCALAR tied
2835               method, otherwise if the hash contains no keys returns 0,
2836               otherwise returns a mortal sv containing a string specifying
2837               the number of used buckets, followed by a slash, followed by
2838               the number of available buckets.
2839
2840               This function is expensive, it must scan all of the buckets to
2841               determine which are used, and the count is NOT cached.  In a
2842               large hash this could be a lot of buckets.
2843
2844                       SV*     hv_bucket_ratio(HV *hv)
2845
2846       hv_clear
2847               Frees the all the elements of a hash, leaving it empty.  The XS
2848               equivalent of "%hash = ()".  See also "hv_undef".
2849
2850               See "av_clear" for a note about the hash possibly being invalid
2851               on return.
2852
2853                       void    hv_clear(HV *hv)
2854
2855       hv_clear_placeholders
2856               Clears any placeholders from a hash.  If a restricted hash has
2857               any of its keys marked as readonly and the key is subsequently
2858               deleted, the key is not actually deleted but is marked by
2859               assigning it a value of &PL_sv_placeholder.  This tags it so it
2860               will be ignored by future operations such as iterating over the
2861               hash, but will still allow the hash to have a value reassigned
2862               to the key at some future point.  This function clears any such
2863               placeholder keys from the hash.  See "Hash::Util::lock_keys()"
2864               for an example of its use.
2865
2866                       void    hv_clear_placeholders(HV *hv)
2867
2868       hv_copy_hints_hv
2869               A specialised version of "newHVhv" for copying "%^H".  "ohv"
2870               must be a pointer to a hash (which may have "%^H" magic, but
2871               should be generally non-magical), or "NULL" (interpreted as an
2872               empty hash).  The content of "ohv" is copied to a new hash,
2873               which has the "%^H"-specific magic added to it.  A pointer to
2874               the new hash is returned.
2875
2876                       HV *    hv_copy_hints_hv(HV *const ohv)
2877
2878       hv_delete
2879               Deletes a key/value pair in the hash.  The value's SV is
2880               removed from the hash, made mortal, and returned to the caller.
2881               The absolute value of "klen" is the length of the key.  If
2882               "klen" is negative the key is assumed to be in UTF-8-encoded
2883               Unicode.  The "flags" value will normally be zero; if set to
2884               "G_DISCARD" then "NULL" will be returned.  "NULL" will also be
2885               returned if the key is not found.
2886
2887                       SV*     hv_delete(HV *hv, const char *key, I32 klen,
2888                                         I32 flags)
2889
2890       hv_delete_ent
2891               Deletes a key/value pair in the hash.  The value SV is removed
2892               from the hash, made mortal, and returned to the caller.  The
2893               "flags" value will normally be zero; if set to "G_DISCARD" then
2894               "NULL" will be returned.  "NULL" will also be returned if the
2895               key is not found.  "hash" can be a valid precomputed hash
2896               value, or 0 to ask for it to be computed.
2897
2898                       SV*     hv_delete_ent(HV *hv, SV *keysv, I32 flags,
2899                                             U32 hash)
2900
2901       HvENAME Returns the effective name of a stash, or NULL if there is
2902               none.  The effective name represents a location in the symbol
2903               table where this stash resides.  It is updated automatically
2904               when packages are aliased or deleted.  A stash that is no
2905               longer in the symbol table has no effective name.  This name is
2906               preferable to "HvNAME" for use in MRO linearisations and isa
2907               caches.
2908
2909                       char*   HvENAME(HV* stash)
2910
2911       HvENAMELEN
2912               Returns the length of the stash's effective name.
2913
2914                       STRLEN  HvENAMELEN(HV *stash)
2915
2916       HvENAMEUTF8
2917               Returns true if the effective name is in UTF-8 encoding.
2918
2919                       unsigned char HvENAMEUTF8(HV *stash)
2920
2921       hv_exists
2922               Returns a boolean indicating whether the specified hash key
2923               exists.  The absolute value of "klen" is the length of the key.
2924               If "klen" is negative the key is assumed to be in UTF-8-encoded
2925               Unicode.
2926
2927                       bool    hv_exists(HV *hv, const char *key, I32 klen)
2928
2929       hv_exists_ent
2930               Returns a boolean indicating whether the specified hash key
2931               exists.  "hash" can be a valid precomputed hash value, or 0 to
2932               ask for it to be computed.
2933
2934                       bool    hv_exists_ent(HV *hv, SV *keysv, U32 hash)
2935
2936       hv_fetch
2937               Returns the SV which corresponds to the specified key in the
2938               hash.  The absolute value of "klen" is the length of the key.
2939               If "klen" is negative the key is assumed to be in UTF-8-encoded
2940               Unicode.  If "lval" is set then the fetch will be part of a
2941               store.  This means that if there is no value in the hash
2942               associated with the given key, then one is created and a
2943               pointer to it is returned.  The "SV*" it points to can be
2944               assigned to.  But always check that the return value is non-
2945               null before dereferencing it to an "SV*".
2946
2947               See "Understanding the Magic of Tied Hashes and Arrays" in
2948               perlguts for more information on how to use this function on
2949               tied hashes.
2950
2951                       SV**    hv_fetch(HV *hv, const char *key, I32 klen,
2952                                        I32 lval)
2953
2954       hv_fetchs
2955               Like "hv_fetch", but takes a literal string instead of a
2956               string/length pair.
2957
2958                       SV**    hv_fetchs(HV* tb, "key", I32 lval)
2959
2960       hv_fetch_ent
2961               Returns the hash entry which corresponds to the specified key
2962               in the hash.  "hash" must be a valid precomputed hash number
2963               for the given "key", or 0 if you want the function to compute
2964               it.  IF "lval" is set then the fetch will be part of a store.
2965               Make sure the return value is non-null before accessing it.
2966               The return value when "hv" is a tied hash is a pointer to a
2967               static location, so be sure to make a copy of the structure if
2968               you need to store it somewhere.
2969
2970               See "Understanding the Magic of Tied Hashes and Arrays" in
2971               perlguts for more information on how to use this function on
2972               tied hashes.
2973
2974                       HE*     hv_fetch_ent(HV *hv, SV *keysv, I32 lval,
2975                                            U32 hash)
2976
2977       HvFILL  See "hv_fill".
2978
2979                       STRLEN  HvFILL(HV *const hv)
2980
2981       hv_fill Returns the number of hash buckets that happen to be in use.
2982
2983               This function is wrapped by the macro "HvFILL".
2984
2985               As of perl 5.25 this function is used only for debugging
2986               purposes, and the number of used hash buckets is not in any way
2987               cached, thus this function can be costly to execute as it must
2988               iterate over all the buckets in the hash.
2989
2990               NOTE: this function must be explicitly called as Perl_hv_fill
2991               with an aTHX_ parameter.
2992
2993                       STRLEN  Perl_hv_fill(pTHX_ HV *const hv)
2994
2995       hv_iterinit
2996               Prepares a starting point to traverse a hash table.  Returns
2997               the number of keys in the hash, including placeholders (i.e.
2998               the same as "HvTOTALKEYS(hv)").  The return value is currently
2999               only meaningful for hashes without tie magic.
3000
3001               NOTE: Before version 5.004_65, "hv_iterinit" used to return the
3002               number of hash buckets that happen to be in use.  If you still
3003               need that esoteric value, you can get it through the macro
3004               "HvFILL(hv)".
3005
3006                       I32     hv_iterinit(HV *hv)
3007
3008       hv_iterkey
3009               Returns the key from the current position of the hash iterator.
3010               See "hv_iterinit".
3011
3012                       char*   hv_iterkey(HE* entry, I32* retlen)
3013
3014       hv_iterkeysv
3015               Returns the key as an "SV*" from the current position of the
3016               hash iterator.  The return value will always be a mortal copy
3017               of the key.  Also see "hv_iterinit".
3018
3019                       SV*     hv_iterkeysv(HE* entry)
3020
3021       hv_iternext
3022               Returns entries from a hash iterator.  See "hv_iterinit".
3023
3024               You may call "hv_delete" or "hv_delete_ent" on the hash entry
3025               that the iterator currently points to, without losing your
3026               place or invalidating your iterator.  Note that in this case
3027               the current entry is deleted from the hash with your iterator
3028               holding the last reference to it.  Your iterator is flagged to
3029               free the entry on the next call to "hv_iternext", so you must
3030               not discard your iterator immediately else the entry will leak
3031               - call "hv_iternext" to trigger the resource deallocation.
3032
3033                       HE*     hv_iternext(HV *hv)
3034
3035       hv_iternextsv
3036               Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in
3037               one operation.
3038
3039                       SV*     hv_iternextsv(HV *hv, char **key, I32 *retlen)
3040
3041       hv_iternext_flags
3042               NOTE: this function is experimental and may change or be
3043               removed without notice.
3044
3045               Returns entries from a hash iterator.  See "hv_iterinit" and
3046               "hv_iternext".  The "flags" value will normally be zero; if
3047               "HV_ITERNEXT_WANTPLACEHOLDERS" is set the placeholders keys
3048               (for restricted hashes) will be returned in addition to normal
3049               keys.  By default placeholders are automatically skipped over.
3050               Currently a placeholder is implemented with a value that is
3051               &PL_sv_placeholder.  Note that the implementation of
3052               placeholders and restricted hashes may change, and the
3053               implementation currently is insufficiently abstracted for any
3054               change to be tidy.
3055
3056                       HE*     hv_iternext_flags(HV *hv, I32 flags)
3057
3058       hv_iterval
3059               Returns the value from the current position of the hash
3060               iterator.  See "hv_iterkey".
3061
3062                       SV*     hv_iterval(HV *hv, HE *entry)
3063
3064       hv_magic
3065               Adds magic to a hash.  See "sv_magic".
3066
3067                       void    hv_magic(HV *hv, GV *gv, int how)
3068
3069       HvNAME  Returns the package name of a stash, or "NULL" if "stash" isn't
3070               a stash.  See "SvSTASH", "CvSTASH".
3071
3072                       char*   HvNAME(HV* stash)
3073
3074       HvNAMELEN
3075               Returns the length of the stash's name.
3076
3077                       STRLEN  HvNAMELEN(HV *stash)
3078
3079       HvNAMEUTF8
3080               Returns true if the name is in UTF-8 encoding.
3081
3082                       unsigned char HvNAMEUTF8(HV *stash)
3083
3084       hv_scalar
3085               Evaluates the hash in scalar context and returns the result.
3086
3087               When the hash is tied dispatches through to the SCALAR method,
3088               otherwise returns a mortal SV containing the number of keys in
3089               the hash.
3090
3091               Note, prior to 5.25 this function returned what is now returned
3092               by the hv_bucket_ratio() function.
3093
3094                       SV*     hv_scalar(HV *hv)
3095
3096       hv_store
3097               Stores an SV in a hash.  The hash key is specified as "key" and
3098               the absolute value of "klen" is the length of the key.  If
3099               "klen" is negative the key is assumed to be in UTF-8-encoded
3100               Unicode.  The "hash" parameter is the precomputed hash value;
3101               if it is zero then Perl will compute it.
3102
3103               The return value will be "NULL" if the operation failed or if
3104               the value did not need to be actually stored within the hash
3105               (as in the case of tied hashes).  Otherwise it can be
3106               dereferenced to get the original "SV*".  Note that the caller
3107               is responsible for suitably incrementing the reference count of
3108               "val" before the call, and decrementing it if the function
3109               returned "NULL".  Effectively a successful "hv_store" takes
3110               ownership of one reference to "val".  This is usually what you
3111               want; a newly created SV has a reference count of one, so if
3112               all your code does is create SVs then store them in a hash,
3113               "hv_store" will own the only reference to the new SV, and your
3114               code doesn't need to do anything further to tidy up.
3115               "hv_store" is not implemented as a call to "hv_store_ent", and
3116               does not create a temporary SV for the key, so if your key data
3117               is not already in SV form then use "hv_store" in preference to
3118               "hv_store_ent".
3119
3120               See "Understanding the Magic of Tied Hashes and Arrays" in
3121               perlguts for more information on how to use this function on
3122               tied hashes.
3123
3124                       SV**    hv_store(HV *hv, const char *key, I32 klen,
3125                                        SV *val, U32 hash)
3126
3127       hv_stores
3128               Like "hv_store", but takes a literal string instead of a
3129               string/length pair and omits the hash parameter.
3130
3131                       SV**    hv_stores(HV* tb, "key", SV* val)
3132
3133       hv_store_ent
3134               Stores "val" in a hash.  The hash key is specified as "key".
3135               The "hash" parameter is the precomputed hash value; if it is
3136               zero then Perl will compute it.  The return value is the new
3137               hash entry so created.  It will be "NULL" if the operation
3138               failed or if the value did not need to be actually stored
3139               within the hash (as in the case of tied hashes).  Otherwise the
3140               contents of the return value can be accessed using the "He?"
3141               macros described here.  Note that the caller is responsible for
3142               suitably incrementing the reference count of "val" before the
3143               call, and decrementing it if the function returned NULL.
3144               Effectively a successful "hv_store_ent" takes ownership of one
3145               reference to "val".  This is usually what you want; a newly
3146               created SV has a reference count of one, so if all your code
3147               does is create SVs then store them in a hash, "hv_store" will
3148               own the only reference to the new SV, and your code doesn't
3149               need to do anything further to tidy up.  Note that
3150               "hv_store_ent" only reads the "key"; unlike "val" it does not
3151               take ownership of it, so maintaining the correct reference
3152               count on "key" is entirely the caller's responsibility.  The
3153               reason it does not take ownership, is that "key" is not used
3154               after this function returns, and so can be freed immediately.
3155               "hv_store" is not implemented as a call to "hv_store_ent", and
3156               does not create a temporary SV for the key, so if your key data
3157               is not already in SV form then use "hv_store" in preference to
3158               "hv_store_ent".
3159
3160               See "Understanding the Magic of Tied Hashes and Arrays" in
3161               perlguts for more information on how to use this function on
3162               tied hashes.
3163
3164                       HE*     hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
3165
3166       hv_undef
3167               Undefines the hash.  The XS equivalent of "undef(%hash)".
3168
3169               As well as freeing all the elements of the hash (like
3170               "hv_clear()"), this also frees any auxiliary data and storage
3171               associated with the hash.
3172
3173               See "av_clear" for a note about the hash possibly being invalid
3174               on return.
3175
3176                       void    hv_undef(HV *hv)
3177
3178       newHV   Creates a new HV.  The reference count is set to 1.
3179
3180                       HV*     newHV()
3181

Hook manipulation

3183       These functions provide convenient and thread-safe means of
3184       manipulating hook variables.
3185
3186       wrap_op_checker
3187               Puts a C function into the chain of check functions for a
3188               specified op type.  This is the preferred way to manipulate the
3189               "PL_check" array.  "opcode" specifies which type of op is to be
3190               affected.  "new_checker" is a pointer to the C function that is
3191               to be added to that opcode's check chain, and "old_checker_p"
3192               points to the storage location where a pointer to the next
3193               function in the chain will be stored.  The value of
3194               "new_checker" is written into the "PL_check" array, while the
3195               value previously stored there is written to *old_checker_p.
3196
3197               "PL_check" is global to an entire process, and a module wishing
3198               to hook op checking may find itself invoked more than once per
3199               process, typically in different threads.  To handle that
3200               situation, this function is idempotent.  The location
3201               *old_checker_p must initially (once per process) contain a null
3202               pointer.  A C variable of static duration (declared at file
3203               scope, typically also marked "static" to give it internal
3204               linkage) will be implicitly initialised appropriately, if it
3205               does not have an explicit initialiser.  This function will only
3206               actually modify the check chain if it finds *old_checker_p to
3207               be null.  This function is also thread safe on the small scale.
3208               It uses appropriate locking to avoid race conditions in
3209               accessing "PL_check".
3210
3211               When this function is called, the function referenced by
3212               "new_checker" must be ready to be called, except for
3213               *old_checker_p being unfilled.  In a threading situation,
3214               "new_checker" may be called immediately, even before this
3215               function has returned.  *old_checker_p will always be
3216               appropriately set before "new_checker" is called.  If
3217               "new_checker" decides not to do anything special with an op
3218               that it is given (which is the usual case for most uses of op
3219               check hooking), it must chain the check function referenced by
3220               *old_checker_p.
3221
3222               Taken all together, XS code to hook an op checker should
3223               typically look something like this:
3224
3225                   static Perl_check_t nxck_frob;
3226                   static OP *myck_frob(pTHX_ OP *op) {
3227                       ...
3228                       op = nxck_frob(aTHX_ op);
3229                       ...
3230                       return op;
3231                   }
3232                   BOOT:
3233                       wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
3234
3235               If you want to influence compilation of calls to a specific
3236               subroutine, then use "cv_set_call_checker_flags" rather than
3237               hooking checking of all "entersub" ops.
3238
3239                       void    wrap_op_checker(Optype opcode,
3240                                               Perl_check_t new_checker,
3241                                               Perl_check_t *old_checker_p)
3242

Lexer interface

3244       This is the lower layer of the Perl parser, managing characters and
3245       tokens.
3246
3247       lex_bufutf8
3248               NOTE: this function is experimental and may change or be
3249               removed without notice.
3250
3251               Indicates whether the octets in the lexer buffer
3252               ("PL_parser->linestr") should be interpreted as the UTF-8
3253               encoding of Unicode characters.  If not, they should be
3254               interpreted as Latin-1 characters.  This is analogous to the
3255               "SvUTF8" flag for scalars.
3256
3257               In UTF-8 mode, it is not guaranteed that the lexer buffer
3258               actually contains valid UTF-8.  Lexing code must be robust in
3259               the face of invalid encoding.
3260
3261               The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
3262               significant, but not the whole story regarding the input
3263               character encoding.  Normally, when a file is being read, the
3264               scalar contains octets and its "SvUTF8" flag is off, but the
3265               octets should be interpreted as UTF-8 if the "use utf8" pragma
3266               is in effect.  During a string eval, however, the scalar may
3267               have the "SvUTF8" flag on, and in this case its octets should
3268               be interpreted as UTF-8 unless the "use bytes" pragma is in
3269               effect.  This logic may change in the future; use this function
3270               instead of implementing the logic yourself.
3271
3272                       bool    lex_bufutf8()
3273
3274       lex_discard_to
3275               NOTE: this function is experimental and may change or be
3276               removed without notice.
3277
3278               Discards the first part of the "PL_parser->linestr" buffer, up
3279               to "ptr".  The remaining content of the buffer will be moved,
3280               and all pointers into the buffer updated appropriately.  "ptr"
3281               must not be later in the buffer than the position of
3282               "PL_parser->bufptr": it is not permitted to discard text that
3283               has yet to be lexed.
3284
3285               Normally it is not necessarily to do this directly, because it
3286               suffices to use the implicit discarding behaviour of
3287               "lex_next_chunk" and things based on it.  However, if a token
3288               stretches across multiple lines, and the lexing code has kept
3289               multiple lines of text in the buffer for that purpose, then
3290               after completion of the token it would be wise to explicitly
3291               discard the now-unneeded earlier lines, to avoid future multi-
3292               line tokens growing the buffer without bound.
3293
3294                       void    lex_discard_to(char* ptr)
3295
3296       lex_grow_linestr
3297               NOTE: this function is experimental and may change or be
3298               removed without notice.
3299
3300               Reallocates the lexer buffer ("PL_parser->linestr") to
3301               accommodate at least "len" octets (including terminating
3302               "NUL").  Returns a pointer to the reallocated buffer.  This is
3303               necessary before making any direct modification of the buffer
3304               that would increase its length.  "lex_stuff_pvn" provides a
3305               more convenient way to insert text into the buffer.
3306
3307               Do not use "SvGROW" or "sv_grow" directly on
3308               "PL_parser->linestr"; this function updates all of the lexer's
3309               variables that point directly into the buffer.
3310
3311                       char*   lex_grow_linestr(STRLEN len)
3312
3313       lex_next_chunk
3314               NOTE: this function is experimental and may change or be
3315               removed without notice.
3316
3317               Reads in the next chunk of text to be lexed, appending it to
3318               "PL_parser->linestr".  This should be called when lexing code
3319               has looked to the end of the current chunk and wants to know
3320               more.  It is usual, but not necessary, for lexing to have
3321               consumed the entirety of the current chunk at this time.
3322
3323               If "PL_parser->bufptr" is pointing to the very end of the
3324               current chunk (i.e., the current chunk has been entirely
3325               consumed), normally the current chunk will be discarded at the
3326               same time that the new chunk is read in.  If "flags" has the
3327               "LEX_KEEP_PREVIOUS" bit set, the current chunk will not be
3328               discarded.  If the current chunk has not been entirely
3329               consumed, then it will not be discarded regardless of the flag.
3330
3331               Returns true if some new text was added to the buffer, or false
3332               if the buffer has reached the end of the input text.
3333
3334                       bool    lex_next_chunk(U32 flags)
3335
3336       lex_peek_unichar
3337               NOTE: this function is experimental and may change or be
3338               removed without notice.
3339
3340               Looks ahead one (Unicode) character in the text currently being
3341               lexed.  Returns the codepoint (unsigned integer value) of the
3342               next character, or -1 if lexing has reached the end of the
3343               input text.  To consume the peeked character, use
3344               "lex_read_unichar".
3345
3346               If the next character is in (or extends into) the next chunk of
3347               input text, the next chunk will be read in.  Normally the
3348               current chunk will be discarded at the same time, but if
3349               "flags" has the "LEX_KEEP_PREVIOUS" bit set, then the current
3350               chunk will not be discarded.
3351
3352               If the input is being interpreted as UTF-8 and a UTF-8 encoding
3353               error is encountered, an exception is generated.
3354
3355                       I32     lex_peek_unichar(U32 flags)
3356
3357       lex_read_space
3358               NOTE: this function is experimental and may change or be
3359               removed without notice.
3360
3361               Reads optional spaces, in Perl style, in the text currently
3362               being lexed.  The spaces may include ordinary whitespace
3363               characters and Perl-style comments.  "#line" directives are
3364               processed if encountered.  "PL_parser->bufptr" is moved past
3365               the spaces, so that it points at a non-space character (or the
3366               end of the input text).
3367
3368               If spaces extend into the next chunk of input text, the next
3369               chunk will be read in.  Normally the current chunk will be
3370               discarded at the same time, but if "flags" has the
3371               "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
3372               discarded.
3373
3374                       void    lex_read_space(U32 flags)
3375
3376       lex_read_to
3377               NOTE: this function is experimental and may change or be
3378               removed without notice.
3379
3380               Consume text in the lexer buffer, from "PL_parser->bufptr" up
3381               to "ptr".  This advances "PL_parser->bufptr" to match "ptr",
3382               performing the correct bookkeeping whenever a newline character
3383               is passed.  This is the normal way to consume lexed text.
3384
3385               Interpretation of the buffer's octets can be abstracted out by
3386               using the slightly higher-level functions "lex_peek_unichar"
3387               and "lex_read_unichar".
3388
3389                       void    lex_read_to(char* ptr)
3390
3391       lex_read_unichar
3392               NOTE: this function is experimental and may change or be
3393               removed without notice.
3394
3395               Reads the next (Unicode) character in the text currently being
3396               lexed.  Returns the codepoint (unsigned integer value) of the
3397               character read, and moves "PL_parser->bufptr" past the
3398               character, or returns -1 if lexing has reached the end of the
3399               input text.  To non-destructively examine the next character,
3400               use "lex_peek_unichar" instead.
3401
3402               If the next character is in (or extends into) the next chunk of
3403               input text, the next chunk will be read in.  Normally the
3404               current chunk will be discarded at the same time, but if
3405               "flags" has the "LEX_KEEP_PREVIOUS" bit set, then the current
3406               chunk will not be discarded.
3407
3408               If the input is being interpreted as UTF-8 and a UTF-8 encoding
3409               error is encountered, an exception is generated.
3410
3411                       I32     lex_read_unichar(U32 flags)
3412
3413       lex_start
3414               NOTE: this function is experimental and may change or be
3415               removed without notice.
3416
3417               Creates and initialises a new lexer/parser state object,
3418               supplying a context in which to lex and parse from a new source
3419               of Perl code.  A pointer to the new state object is placed in
3420               "PL_parser".  An entry is made on the save stack so that upon
3421               unwinding, the new state object will be destroyed and the
3422               former value of "PL_parser" will be restored.  Nothing else
3423               need be done to clean up the parsing context.
3424
3425               The code to be parsed comes from "line" and "rsfp".  "line", if
3426               non-null, provides a string (in SV form) containing code to be
3427               parsed.  A copy of the string is made, so subsequent
3428               modification of "line" does not affect parsing.  "rsfp", if
3429               non-null, provides an input stream from which code will be read
3430               to be parsed.  If both are non-null, the code in "line" comes
3431               first and must consist of complete lines of input, and "rsfp"
3432               supplies the remainder of the source.
3433
3434               The "flags" parameter is reserved for future use.  Currently it
3435               is only used by perl internally, so extensions should always
3436               pass zero.
3437
3438                       void    lex_start(SV* line, PerlIO *rsfp, U32 flags)
3439
3440       lex_stuff_pv
3441               NOTE: this function is experimental and may change or be
3442               removed without notice.
3443
3444               Insert characters into the lexer buffer ("PL_parser->linestr"),
3445               immediately after the current lexing point
3446               ("PL_parser->bufptr"), reallocating the buffer if necessary.
3447               This means that lexing code that runs later will see the
3448               characters as if they had appeared in the input.  It is not
3449               recommended to do this as part of normal parsing, and most uses
3450               of this facility run the risk of the inserted characters being
3451               interpreted in an unintended manner.
3452
3453               The string to be inserted is represented by octets starting at
3454               "pv" and continuing to the first nul.  These octets are
3455               interpreted as either UTF-8 or Latin-1, according to whether
3456               the "LEX_STUFF_UTF8" flag is set in "flags".  The characters
3457               are recoded for the lexer buffer, according to how the buffer
3458               is currently being interpreted ("lex_bufutf8").  If it is not
3459               convenient to nul-terminate a string to be inserted, the
3460               "lex_stuff_pvn" function is more appropriate.
3461
3462                       void    lex_stuff_pv(const char* pv, U32 flags)
3463
3464       lex_stuff_pvn
3465               NOTE: this function is experimental and may change or be
3466               removed without notice.
3467
3468               Insert characters into the lexer buffer ("PL_parser->linestr"),
3469               immediately after the current lexing point
3470               ("PL_parser->bufptr"), reallocating the buffer if necessary.
3471               This means that lexing code that runs later will see the
3472               characters as if they had appeared in the input.  It is not
3473               recommended to do this as part of normal parsing, and most uses
3474               of this facility run the risk of the inserted characters being
3475               interpreted in an unintended manner.
3476
3477               The string to be inserted is represented by "len" octets
3478               starting at "pv".  These octets are interpreted as either UTF-8
3479               or Latin-1, according to whether the "LEX_STUFF_UTF8" flag is
3480               set in "flags".  The characters are recoded for the lexer
3481               buffer, according to how the buffer is currently being
3482               interpreted ("lex_bufutf8").  If a string to be inserted is
3483               available as a Perl scalar, the "lex_stuff_sv" function is more
3484               convenient.
3485
3486                       void    lex_stuff_pvn(const char* pv, STRLEN len,
3487                                             U32 flags)
3488
3489       lex_stuff_pvs
3490               NOTE: this function is experimental and may change or be
3491               removed without notice.
3492
3493               Like "lex_stuff_pvn", but takes a literal string instead of a
3494               string/length pair.
3495
3496                       void    lex_stuff_pvs("pv", U32 flags)
3497
3498       lex_stuff_sv
3499               NOTE: this function is experimental and may change or be
3500               removed without notice.
3501
3502               Insert characters into the lexer buffer ("PL_parser->linestr"),
3503               immediately after the current lexing point
3504               ("PL_parser->bufptr"), reallocating the buffer if necessary.
3505               This means that lexing code that runs later will see the
3506               characters as if they had appeared in the input.  It is not
3507               recommended to do this as part of normal parsing, and most uses
3508               of this facility run the risk of the inserted characters being
3509               interpreted in an unintended manner.
3510
3511               The string to be inserted is the string value of "sv".  The
3512               characters are recoded for the lexer buffer, according to how
3513               the buffer is currently being interpreted ("lex_bufutf8").  If
3514               a string to be inserted is not already a Perl scalar, the
3515               "lex_stuff_pvn" function avoids the need to construct a scalar.
3516
3517                       void    lex_stuff_sv(SV* sv, U32 flags)
3518
3519       lex_unstuff
3520               NOTE: this function is experimental and may change or be
3521               removed without notice.
3522
3523               Discards text about to be lexed, from "PL_parser->bufptr" up to
3524               "ptr".  Text following "ptr" will be moved, and the buffer
3525               shortened.  This hides the discarded text from any lexing code
3526               that runs later, as if the text had never appeared.
3527
3528               This is not the normal way to consume lexed text.  For that,
3529               use "lex_read_to".
3530
3531                       void    lex_unstuff(char* ptr)
3532
3533       parse_arithexpr
3534               NOTE: this function is experimental and may change or be
3535               removed without notice.
3536
3537               Parse a Perl arithmetic expression.  This may contain operators
3538               of precedence down to the bit shift operators.  The expression
3539               must be followed (and thus terminated) either by a comparison
3540               or lower-precedence operator or by something that would
3541               normally terminate an expression such as semicolon.  If "flags"
3542               has the "PARSE_OPTIONAL" bit set, then the expression is
3543               optional, otherwise it is mandatory.  It is up to the caller to
3544               ensure that the dynamic parser state ("PL_parser" et al) is
3545               correctly set to reflect the source of the code to be parsed
3546               and the lexical context for the expression.
3547
3548               The op tree representing the expression is returned.  If an
3549               optional expression is absent, a null pointer is returned,
3550               otherwise the pointer will be non-null.
3551
3552               If an error occurs in parsing or compilation, in most cases a
3553               valid op tree is returned anyway.  The error is reflected in
3554               the parser state, normally resulting in a single exception at
3555               the top level of parsing which covers all the compilation
3556               errors that occurred.  Some compilation errors, however, will
3557               throw an exception immediately.
3558
3559                       OP*     parse_arithexpr(U32 flags)
3560
3561       parse_barestmt
3562               NOTE: this function is experimental and may change or be
3563               removed without notice.
3564
3565               Parse a single unadorned Perl statement.  This may be a normal
3566               imperative statement or a declaration that has compile-time
3567               effect.  It does not include any label or other affixture.  It
3568               is up to the caller to ensure that the dynamic parser state
3569               ("PL_parser" et al) is correctly set to reflect the source of
3570               the code to be parsed and the lexical context for the
3571               statement.
3572
3573               The op tree representing the statement is returned.  This may
3574               be a null pointer if the statement is null, for example if it
3575               was actually a subroutine definition (which has compile-time
3576               side effects).  If not null, it will be ops directly
3577               implementing the statement, suitable to pass to "newSTATEOP".
3578               It will not normally include a "nextstate" or equivalent op
3579               (except for those embedded in a scope contained entirely within
3580               the statement).
3581
3582               If an error occurs in parsing or compilation, in most cases a
3583               valid op tree (most likely null) is returned anyway.  The error
3584               is reflected in the parser state, normally resulting in a
3585               single exception at the top level of parsing which covers all
3586               the compilation errors that occurred.  Some compilation errors,
3587               however, will throw an exception immediately.
3588
3589               The "flags" parameter is reserved for future use, and must
3590               always be zero.
3591
3592                       OP*     parse_barestmt(U32 flags)
3593
3594       parse_block
3595               NOTE: this function is experimental and may change or be
3596               removed without notice.
3597
3598               Parse a single complete Perl code block.  This consists of an
3599               opening brace, a sequence of statements, and a closing brace.
3600               The block constitutes a lexical scope, so "my" variables and
3601               various compile-time effects can be contained within it.  It is
3602               up to the caller to ensure that the dynamic parser state
3603               ("PL_parser" et al) is correctly set to reflect the source of
3604               the code to be parsed and the lexical context for the
3605               statement.
3606
3607               The op tree representing the code block is returned.  This is
3608               always a real op, never a null pointer.  It will normally be a
3609               "lineseq" list, including "nextstate" or equivalent ops.  No
3610               ops to construct any kind of runtime scope are included by
3611               virtue of it being a block.
3612
3613               If an error occurs in parsing or compilation, in most cases a
3614               valid op tree (most likely null) is returned anyway.  The error
3615               is reflected in the parser state, normally resulting in a
3616               single exception at the top level of parsing which covers all
3617               the compilation errors that occurred.  Some compilation errors,
3618               however, will throw an exception immediately.
3619
3620               The "flags" parameter is reserved for future use, and must
3621               always be zero.
3622
3623                       OP*     parse_block(U32 flags)
3624
3625       parse_fullexpr
3626               NOTE: this function is experimental and may change or be
3627               removed without notice.
3628
3629               Parse a single complete Perl expression.  This allows the full
3630               expression grammar, including the lowest-precedence operators
3631               such as "or".  The expression must be followed (and thus
3632               terminated) by a token that an expression would normally be
3633               terminated by: end-of-file, closing bracketing punctuation,
3634               semicolon, or one of the keywords that signals a postfix
3635               expression-statement modifier.  If "flags" has the
3636               "PARSE_OPTIONAL" bit set, then the expression is optional,
3637               otherwise it is mandatory.  It is up to the caller to ensure
3638               that the dynamic parser state ("PL_parser" et al) is correctly
3639               set to reflect the source of the code to be parsed and the
3640               lexical context for the expression.
3641
3642               The op tree representing the expression is returned.  If an
3643               optional expression is absent, a null pointer is returned,
3644               otherwise the pointer will be non-null.
3645
3646               If an error occurs in parsing or compilation, in most cases a
3647               valid op tree is returned anyway.  The error is reflected in
3648               the parser state, normally resulting in a single exception at
3649               the top level of parsing which covers all the compilation
3650               errors that occurred.  Some compilation errors, however, will
3651               throw an exception immediately.
3652
3653                       OP*     parse_fullexpr(U32 flags)
3654
3655       parse_fullstmt
3656               NOTE: this function is experimental and may change or be
3657               removed without notice.
3658
3659               Parse a single complete Perl statement.  This may be a normal
3660               imperative statement or a declaration that has compile-time
3661               effect, and may include optional labels.  It is up to the
3662               caller to ensure that the dynamic parser state ("PL_parser" et
3663               al) is correctly set to reflect the source of the code to be
3664               parsed and the lexical context for the statement.
3665
3666               The op tree representing the statement is returned.  This may
3667               be a null pointer if the statement is null, for example if it
3668               was actually a subroutine definition (which has compile-time
3669               side effects).  If not null, it will be the result of a
3670               "newSTATEOP" call, normally including a "nextstate" or
3671               equivalent op.
3672
3673               If an error occurs in parsing or compilation, in most cases a
3674               valid op tree (most likely null) is returned anyway.  The error
3675               is reflected in the parser state, normally resulting in a
3676               single exception at the top level of parsing which covers all
3677               the compilation errors that occurred.  Some compilation errors,
3678               however, will throw an exception immediately.
3679
3680               The "flags" parameter is reserved for future use, and must
3681               always be zero.
3682
3683                       OP*     parse_fullstmt(U32 flags)
3684
3685       parse_label
3686               NOTE: this function is experimental and may change or be
3687               removed without notice.
3688
3689               Parse a single label, possibly optional, of the type that may
3690               prefix a Perl statement.  It is up to the caller to ensure that
3691               the dynamic parser state ("PL_parser" et al) is correctly set
3692               to reflect the source of the code to be parsed.  If "flags" has
3693               the "PARSE_OPTIONAL" bit set, then the label is optional,
3694               otherwise it is mandatory.
3695
3696               The name of the label is returned in the form of a fresh
3697               scalar.  If an optional label is absent, a null pointer is
3698               returned.
3699
3700               If an error occurs in parsing, which can only occur if the
3701               label is mandatory, a valid label is returned anyway.  The
3702               error is reflected in the parser state, normally resulting in a
3703               single exception at the top level of parsing which covers all
3704               the compilation errors that occurred.
3705
3706                       SV*     parse_label(U32 flags)
3707
3708       parse_listexpr
3709               NOTE: this function is experimental and may change or be
3710               removed without notice.
3711
3712               Parse a Perl list expression.  This may contain operators of
3713               precedence down to the comma operator.  The expression must be
3714               followed (and thus terminated) either by a low-precedence logic
3715               operator such as "or" or by something that would normally
3716               terminate an expression such as semicolon.  If "flags" has the
3717               "PARSE_OPTIONAL" bit set, then the expression is optional,
3718               otherwise it is mandatory.  It is up to the caller to ensure
3719               that the dynamic parser state ("PL_parser" et al) is correctly
3720               set to reflect the source of the code to be parsed and the
3721               lexical context for the expression.
3722
3723               The op tree representing the expression is returned.  If an
3724               optional expression is absent, a null pointer is returned,
3725               otherwise the pointer will be non-null.
3726
3727               If an error occurs in parsing or compilation, in most cases a
3728               valid op tree is returned anyway.  The error is reflected in
3729               the parser state, normally resulting in a single exception at
3730               the top level of parsing which covers all the compilation
3731               errors that occurred.  Some compilation errors, however, will
3732               throw an exception immediately.
3733
3734                       OP*     parse_listexpr(U32 flags)
3735
3736       parse_stmtseq
3737               NOTE: this function is experimental and may change or be
3738               removed without notice.
3739
3740               Parse a sequence of zero or more Perl statements.  These may be
3741               normal imperative statements, including optional labels, or
3742               declarations that have compile-time effect, or any mixture
3743               thereof.  The statement sequence ends when a closing brace or
3744               end-of-file is encountered in a place where a new statement
3745               could have validly started.  It is up to the caller to ensure
3746               that the dynamic parser state ("PL_parser" et al) is correctly
3747               set to reflect the source of the code to be parsed and the
3748               lexical context for the statements.
3749
3750               The op tree representing the statement sequence is returned.
3751               This may be a null pointer if the statements were all null, for
3752               example if there were no statements or if there were only
3753               subroutine definitions (which have compile-time side effects).
3754               If not null, it will be a "lineseq" list, normally including
3755               "nextstate" or equivalent ops.
3756
3757               If an error occurs in parsing or compilation, in most cases a
3758               valid op tree is returned anyway.  The error is reflected in
3759               the parser state, normally resulting in a single exception at
3760               the top level of parsing which covers all the compilation
3761               errors that occurred.  Some compilation errors, however, will
3762               throw an exception immediately.
3763
3764               The "flags" parameter is reserved for future use, and must
3765               always be zero.
3766
3767                       OP*     parse_stmtseq(U32 flags)
3768
3769       parse_subsignature
3770               NOTE: this function is experimental and may change or be
3771               removed without notice.
3772
3773               Parse a subroutine signature declaration. This is the contents
3774               of the parentheses following a named or anonymous subroutine
3775               declaration when the "signatures" feature is enabled. Note that
3776               this function neither expects nor consumes the opening and
3777               closing parentheses around the signature; it is the caller's
3778               job to handle these.
3779
3780               This function must only be called during parsing of a
3781               subroutine; after "start_subparse" has been called. It might
3782               allocate lexical variables on the pad for the current
3783               subroutine.
3784
3785               The op tree to unpack the arguments from the stack at runtime
3786               is returned.  This op tree should appear at the beginning of
3787               the compiled function. The caller may wish to use
3788               "op_append_list" to build their function body after it, or
3789               splice it together with the body before calling "newATTRSUB".
3790
3791               The "flags" parameter is reserved for future use, and must
3792               always be zero.
3793
3794                       OP*     parse_subsignature(U32 flags)
3795
3796       parse_termexpr
3797               NOTE: this function is experimental and may change or be
3798               removed without notice.
3799
3800               Parse a Perl term expression.  This may contain operators of
3801               precedence down to the assignment operators.  The expression
3802               must be followed (and thus terminated) either by a comma or
3803               lower-precedence operator or by something that would normally
3804               terminate an expression such as semicolon.  If "flags" has the
3805               "PARSE_OPTIONAL" bit set, then the expression is optional,
3806               otherwise it is mandatory.  It is up to the caller to ensure
3807               that the dynamic parser state ("PL_parser" et al) is correctly
3808               set to reflect the source of the code to be parsed and the
3809               lexical context for the expression.
3810
3811               The op tree representing the expression is returned.  If an
3812               optional expression is absent, a null pointer is returned,
3813               otherwise the pointer will be non-null.
3814
3815               If an error occurs in parsing or compilation, in most cases a
3816               valid op tree is returned anyway.  The error is reflected in
3817               the parser state, normally resulting in a single exception at
3818               the top level of parsing which covers all the compilation
3819               errors that occurred.  Some compilation errors, however, will
3820               throw an exception immediately.
3821
3822                       OP*     parse_termexpr(U32 flags)
3823
3824       PL_parser
3825               Pointer to a structure encapsulating the state of the parsing
3826               operation currently in progress.  The pointer can be locally
3827               changed to perform a nested parse without interfering with the
3828               state of an outer parse.  Individual members of "PL_parser"
3829               have their own documentation.
3830
3831       PL_parser->bufend
3832               NOTE: this function is experimental and may change or be
3833               removed without notice.
3834
3835               Direct pointer to the end of the chunk of text currently being
3836               lexed, the end of the lexer buffer.  This is equal to
3837               "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)".  A
3838               "NUL" character (zero octet) is always located at the end of
3839               the buffer, and does not count as part of the buffer's
3840               contents.
3841
3842       PL_parser->bufptr
3843               NOTE: this function is experimental and may change or be
3844               removed without notice.
3845
3846               Points to the current position of lexing inside the lexer
3847               buffer.  Characters around this point may be freely examined,
3848               within the range delimited by "SvPVX("PL_parser->linestr")" and
3849               "PL_parser->bufend".  The octets of the buffer may be intended
3850               to be interpreted as either UTF-8 or Latin-1, as indicated by
3851               "lex_bufutf8".
3852
3853               Lexing code (whether in the Perl core or not) moves this
3854               pointer past the characters that it consumes.  It is also
3855               expected to perform some bookkeeping whenever a newline
3856               character is consumed.  This movement can be more conveniently
3857               performed by the function "lex_read_to", which handles newlines
3858               appropriately.
3859
3860               Interpretation of the buffer's octets can be abstracted out by
3861               using the slightly higher-level functions "lex_peek_unichar"
3862               and "lex_read_unichar".
3863
3864       PL_parser->linestart
3865               NOTE: this function is experimental and may change or be
3866               removed without notice.
3867
3868               Points to the start of the current line inside the lexer
3869               buffer.  This is useful for indicating at which column an error
3870               occurred, and not much else.  This must be updated by any
3871               lexing code that consumes a newline; the function "lex_read_to"
3872               handles this detail.
3873
3874       PL_parser->linestr
3875               NOTE: this function is experimental and may change or be
3876               removed without notice.
3877
3878               Buffer scalar containing the chunk currently under
3879               consideration of the text currently being lexed.  This is
3880               always a plain string scalar (for which "SvPOK" is true).  It
3881               is not intended to be used as a scalar by normal scalar means;
3882               instead refer to the buffer directly by the pointer variables
3883               described below.
3884
3885               The lexer maintains various "char*" pointers to things in the
3886               "PL_parser->linestr" buffer.  If "PL_parser->linestr" is ever
3887               reallocated, all of these pointers must be updated.  Don't
3888               attempt to do this manually, but rather use "lex_grow_linestr"
3889               if you need to reallocate the buffer.
3890
3891               The content of the text chunk in the buffer is commonly exactly
3892               one complete line of input, up to and including a newline
3893               terminator, but there are situations where it is otherwise.
3894               The octets of the buffer may be intended to be interpreted as
3895               either UTF-8 or Latin-1.  The function "lex_bufutf8" tells you
3896               which.  Do not use the "SvUTF8" flag on this scalar, which may
3897               disagree with it.
3898
3899               For direct examination of the buffer, the variable
3900               "PL_parser->bufend" points to the end of the buffer.  The
3901               current lexing position is pointed to by "PL_parser->bufptr".
3902               Direct use of these pointers is usually preferable to
3903               examination of the scalar through normal scalar means.
3904
3905       wrap_keyword_plugin
3906               NOTE: this function is experimental and may change or be
3907               removed without notice.
3908
3909               Puts a C function into the chain of keyword plugins.  This is
3910               the preferred way to manipulate the "PL_keyword_plugin"
3911               variable.  "new_plugin" is a pointer to the C function that is
3912               to be added to the keyword plugin chain, and "old_plugin_p"
3913               points to the storage location where a pointer to the next
3914               function in the chain will be stored.  The value of
3915               "new_plugin" is written into the "PL_keyword_plugin" variable,
3916               while the value previously stored there is written to
3917               *old_plugin_p.
3918
3919               "PL_keyword_plugin" is global to an entire process, and a
3920               module wishing to hook keyword parsing may find itself invoked
3921               more than once per process, typically in different threads.  To
3922               handle that situation, this function is idempotent.  The
3923               location *old_plugin_p must initially (once per process)
3924               contain a null pointer.  A C variable of static duration
3925               (declared at file scope, typically also marked "static" to give
3926               it internal linkage) will be implicitly initialised
3927               appropriately, if it does not have an explicit initialiser.
3928               This function will only actually modify the plugin chain if it
3929               finds *old_plugin_p to be null.  This function is also thread
3930               safe on the small scale.  It uses appropriate locking to avoid
3931               race conditions in accessing "PL_keyword_plugin".
3932
3933               When this function is called, the function referenced by
3934               "new_plugin" must be ready to be called, except for
3935               *old_plugin_p being unfilled.  In a threading situation,
3936               "new_plugin" may be called immediately, even before this
3937               function has returned.  *old_plugin_p will always be
3938               appropriately set before "new_plugin" is called.  If
3939               "new_plugin" decides not to do anything special with the
3940               identifier that it is given (which is the usual case for most
3941               calls to a keyword plugin), it must chain the plugin function
3942               referenced by *old_plugin_p.
3943
3944               Taken all together, XS code to install a keyword plugin should
3945               typically look something like this:
3946
3947                   static Perl_keyword_plugin_t next_keyword_plugin;
3948                   static OP *my_keyword_plugin(pTHX_
3949                       char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
3950                   {
3951                       if (memEQs(keyword_ptr, keyword_len,
3952                                  "my_new_keyword")) {
3953                           ...
3954                       } else {
3955                           return next_keyword_plugin(aTHX_
3956                               keyword_ptr, keyword_len, op_ptr);
3957                       }
3958                   }
3959                   BOOT:
3960                       wrap_keyword_plugin(my_keyword_plugin,
3961                                           &next_keyword_plugin);
3962
3963               Direct access to "PL_keyword_plugin" should be avoided.
3964
3965                       void    wrap_keyword_plugin(
3966                                   Perl_keyword_plugin_t new_plugin,
3967                                   Perl_keyword_plugin_t *old_plugin_p
3968                               )
3969
3971       DECLARATION_FOR_LC_NUMERIC_MANIPULATION
3972               This macro should be used as a statement.  It declares a
3973               private variable (whose name begins with an underscore) that is
3974               needed by the other macros in this section.  Failing to include
3975               this correctly should lead to a syntax error.  For
3976               compatibility with C89 C compilers it should be placed in a
3977               block before any executable statements.
3978
3979                       void    DECLARATION_FOR_LC_NUMERIC_MANIPULATION
3980
3981       IN_LOCALE
3982               Evaluates to TRUE if the plain locale pragma without a
3983               parameter ("use locale") is in effect.
3984
3985                       bool    IN_LOCALE
3986
3987       IN_LOCALE_COMPILETIME
3988               Evaluates to TRUE if, when compiling a perl program (including
3989               an "eval") if the plain locale pragma without a parameter
3990               ("use locale") is in effect.
3991
3992                       bool    IN_LOCALE_COMPILETIME
3993
3994       IN_LOCALE_RUNTIME
3995               Evaluates to TRUE if, when executing a perl program (including
3996               an "eval") if the plain locale pragma without a parameter
3997               ("use locale") is in effect.
3998
3999                       bool    IN_LOCALE_RUNTIME
4000
4001       Perl_langinfo
4002               This is an (almost) drop-in replacement for the system
4003               nl_langinfo(3), taking the same "item" parameter values, and
4004               returning the same information.  But it is more thread-safe
4005               than regular "nl_langinfo()", and hides the quirks of Perl's
4006               locale handling from your code, and can be used on systems that
4007               lack a native "nl_langinfo".
4008
4009               Expanding on these:
4010
4011               ·   The reason it isn't quite a drop-in replacement is actually
4012                   an advantage.  The only difference is that it returns
4013                   "const char *", whereas plain "nl_langinfo()" returns
4014                   "char *", but you are (only by documentation) forbidden to
4015                   write into the buffer.  By declaring this "const", the
4016                   compiler enforces this restriction, so if it is violated,
4017                   you know at compilation time, rather than getting segfaults
4018                   at runtime.
4019
4020               ·   It delivers the correct results for the "RADIXCHAR" and
4021                   "THOUSEP" items, without you having to write extra code.
4022                   The reason for the extra code would be because these are
4023                   from the "LC_NUMERIC" locale category, which is normally
4024                   kept set by Perl so that the radix is a dot, and the
4025                   separator is the empty string, no matter what the
4026                   underlying locale is supposed to be, and so to get the
4027                   expected results, you have to temporarily toggle into the
4028                   underlying locale, and later toggle back.  (You could use
4029                   plain "nl_langinfo" and
4030                   "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" for this but then
4031                   you wouldn't get the other advantages of "Perl_langinfo()";
4032                   not keeping "LC_NUMERIC" in the C (or equivalent) locale
4033                   would break a lot of CPAN, which is expecting the radix
4034                   (decimal point) character to be a dot.)
4035
4036               ·   The system function it replaces can have its static return
4037                   buffer trashed, not only by a subesequent call to that
4038                   function, but by a "freelocale", "setlocale", or other
4039                   locale change.  The returned buffer of this function is not
4040                   changed until the next call to it, so the buffer is never
4041                   in a trashed state.
4042
4043               ·   Its return buffer is per-thread, so it also is never
4044                   overwritten by a call to this function from another thread;
4045                   unlike the function it replaces.
4046
4047               ·   But most importantly, it works on systems that don't have
4048                   "nl_langinfo", such as Windows, hence makes your code more
4049                   portable.  Of the fifty-some possible items specified by
4050                   the POSIX 2008 standard,
4051                   <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
4052                   only one is completely unimplemented, though on non-Windows
4053                   platforms, another significant one is also not
4054                   implemented).  It uses various techniques to recover the
4055                   other items, including calling localeconv(3), and
4056                   strftime(3), both of which are specified in C89, so should
4057                   be always be available.  Later "strftime()" versions have
4058                   additional capabilities; "" is returned for those not
4059                   available on your system.
4060
4061                   It is important to note that when called with an item that
4062                   is recovered by using "localeconv", the buffer from any
4063                   previous explicit call to "localeconv" will be overwritten.
4064                   This means you must save that buffer's contents if you need
4065                   to access them after a call to this function.  (But note
4066                   that you might not want to be using "localeconv()" directly
4067                   anyway, because of issues like the ones listed in the
4068                   second item of this list (above) for "RADIXCHAR" and
4069                   "THOUSEP".  You can use the methods given in perlcall to
4070                   call "localeconv" in POSIX and avoid all the issues, but
4071                   then you have a hash to unpack).
4072
4073                   The details for those items which may deviate from what
4074                   this emulation returns and what a native "nl_langinfo()"
4075                   would return are specified in I18N::Langinfo.
4076
4077               When using "Perl_langinfo" on systems that don't have a native
4078               "nl_langinfo()", you must
4079
4080                #include "perl_langinfo.h"
4081
4082               before the "perl.h" "#include".  You can replace your
4083               "langinfo.h" "#include" with this one.  (Doing it this way
4084               keeps out the symbols that plain "langinfo.h" would try to
4085               import into the namespace for code that doesn't need it.)
4086
4087               The original impetus for "Perl_langinfo()" was so that code
4088               that needs to find out the current currency symbol, floating
4089               point radix character, or digit grouping separator can use, on
4090               all systems, the simpler and more thread-friendly "nl_langinfo"
4091               API instead of localeconv(3) which is a pain to make thread-
4092               friendly.  For other fields returned by "localeconv", it is
4093               better to use the methods given in perlcall to call
4094               "POSIX::localeconv()", which is thread-friendly.
4095
4096                       const char* Perl_langinfo(const nl_item item)
4097
4098       Perl_setlocale
4099               This is an (almost) drop-in replacement for the system
4100               setlocale(3), taking the same parameters, and returning the
4101               same information, except that it returns the correct underlying
4102               "LC_NUMERIC" locale.  Regular "setlocale" will instead return
4103               "C" if the underlying locale has a non-dot decimal point
4104               character, or a non-empty thousands separator for displaying
4105               floating point numbers.  This is because perl keeps that locale
4106               category such that it has a dot and empty separator, changing
4107               the locale briefly during the operations where the underlying
4108               one is required. "Perl_setlocale" knows about this, and
4109               compensates; regular "setlocale" doesn't.
4110
4111               Another reason it isn't completely a drop-in replacement is
4112               that it is declared to return "const char *", whereas the
4113               system setlocale omits the "const" (presumably because its API
4114               was specified long ago, and can't be updated; it is illegal to
4115               change the information "setlocale" returns; doing so leads to
4116               segfaults.)
4117
4118               Finally, "Perl_setlocale" works under all circumstances,
4119               whereas plain "setlocale" can be completely ineffective on some
4120               platforms under some configurations.
4121
4122               "Perl_setlocale" should not be used to change the locale except
4123               on systems where the predefined variable "${^SAFE_LOCALES}" is
4124               1.  On some such systems, the system "setlocale()" is
4125               ineffective, returning the wrong information, and failing to
4126               actually change the locale.  "Perl_setlocale", however works
4127               properly in all circumstances.
4128
4129               The return points to a per-thread static buffer, which is
4130               overwritten the next time "Perl_setlocale" is called from the
4131               same thread.
4132
4133                       const char* Perl_setlocale(const int category,
4134                                                  const char* locale)
4135
4136       RESTORE_LC_NUMERIC
4137               This is used in conjunction with one of the macros
4138               "STORE_LC_NUMERIC_SET_TO_NEEDED" and
4139               "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
4140               "LC_NUMERIC" state.
4141
4142               A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
4143               been made to declare at compile time a private variable used by
4144               this macro and the two "STORE" ones.  This macro should be
4145               called as a single statement, not an expression, but with an
4146               empty argument list, like this:
4147
4148                {
4149                   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4150                    ...
4151                   RESTORE_LC_NUMERIC();
4152                    ...
4153                }
4154
4155                       void    RESTORE_LC_NUMERIC()
4156
4157       STORE_LC_NUMERIC_FORCE_TO_UNDERLYING
4158               This is used by XS code that is "LC_NUMERIC" locale-aware to
4159               force the locale for category "LC_NUMERIC" to be what perl
4160               thinks is the current underlying locale.  (The perl interpreter
4161               could be wrong about what the underlying locale actually is if
4162               some C or XS code has called the C library function
4163               setlocale(3) behind its back; calling "sync_locale" before
4164               calling this macro will update perl's records.)
4165
4166               A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
4167               been made to declare at compile time a private variable used by
4168               this macro.  This macro should be called as a single statement,
4169               not an expression, but with an empty argument list, like this:
4170
4171                {
4172                   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4173                    ...
4174                   STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
4175                    ...
4176                   RESTORE_LC_NUMERIC();
4177                    ...
4178                }
4179
4180               The private variable is used to save the current locale state,
4181               so that the requisite matching call to "RESTORE_LC_NUMERIC" can
4182               restore it.
4183
4184               On threaded perls not operating with thread-safe functionality,
4185               this macro uses a mutex to force a critical section.  Therefore
4186               the matching RESTORE should be close by, and guaranteed to be
4187               called.
4188
4189                       void    STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
4190
4191       STORE_LC_NUMERIC_SET_TO_NEEDED
4192               This is used to help wrap XS or C code that is "LC_NUMERIC"
4193               locale-aware.  This locale category is generally kept set to a
4194               locale where the decimal radix character is a dot, and the
4195               separator between groups of digits is empty.  This is because
4196               most XS code that reads floating point numbers is expecting
4197               them to have this syntax.
4198
4199               This macro makes sure the current "LC_NUMERIC" state is set
4200               properly, to be aware of locale if the call to the XS or C code
4201               from the Perl program is from within the scope of a
4202               "use locale"; or to ignore locale if the call is instead from
4203               outside such scope.
4204
4205               This macro is the start of wrapping the C or XS code; the wrap
4206               ending is done by calling the "RESTORE_LC_NUMERIC" macro after
4207               the operation.  Otherwise the state can be changed that will
4208               adversely affect other XS code.
4209
4210               A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
4211               been made to declare at compile time a private variable used by
4212               this macro.  This macro should be called as a single statement,
4213               not an expression, but with an empty argument list, like this:
4214
4215                {
4216                   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4217                    ...
4218                   STORE_LC_NUMERIC_SET_TO_NEEDED();
4219                    ...
4220                   RESTORE_LC_NUMERIC();
4221                    ...
4222                }
4223
4224               On threaded perls not operating with thread-safe functionality,
4225               this macro uses a mutex to force a critical section.  Therefore
4226               the matching RESTORE should be close by, and guaranteed to be
4227               called; see "WITH_LC_NUMERIC_SET_TO_NEEDED" for a more
4228               contained way to ensure that.
4229
4230                       void    STORE_LC_NUMERIC_SET_TO_NEEDED()
4231
4232       STORE_LC_NUMERIC_SET_TO_NEEDED_IN
4233               Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
4234               provided as the precalculated value of "IN_LC(LC_NUMERIC)". It
4235               is the caller's responsibility to ensure that the status of
4236               "PL_compiling" and "PL_hints" cannot have changed since the
4237               precalculation.
4238
4239                       void    STORE_LC_NUMERIC_SET_TO_NEEDED_IN(
4240                                   bool in_lc_numeric
4241                               )
4242
4243       switch_to_global_locale
4244               On systems without locale support, or on typical single-
4245               threaded builds, or on platforms that do not support per-thread
4246               locale operations, this function does nothing.  On such systems
4247               that do have locale support, only a locale global to the whole
4248               program is available.
4249
4250               On multi-threaded builds on systems that do have per-thread
4251               locale operations, this function converts the thread it is
4252               running in to use the global locale.  This is for code that has
4253               not yet or cannot be updated to handle multi-threaded locale
4254               operation.  As long as only a single thread is so-converted,
4255               everything works fine, as all the other threads continue to
4256               ignore the global one, so only this thread looks at it.
4257
4258               However, on Windows systems this isn't quite true prior to
4259               Visual Studio 15, at which point Microsoft fixed a bug.  A race
4260               can occur if you use the following operations on earlier
4261               Windows platforms:
4262
4263               POSIX::localeconv
4264               I18N::Langinfo, items "CRNCYSTR" and "THOUSEP"
4265               "Perl_langinfo" in perlapi, items "CRNCYSTR" and "THOUSEP"
4266
4267               The first item is not fixable (except by upgrading to a later
4268               Visual Studio release), but it would be possible to work around
4269               the latter two items by using the Windows API functions
4270               "GetNumberFormat" and "GetCurrencyFormat"; patches welcome.
4271
4272               Without this function call, threads that use the setlocale(3)
4273               system function will not work properly, as all the locale-
4274               sensitive functions will look at the per-thread locale, and
4275               "setlocale" will have no effect on this thread.
4276
4277               Perl code should convert to either call "Perl_setlocale" (which
4278               is a drop-in for the system "setlocale") or use the methods
4279               given in perlcall to call "POSIX::setlocale".  Either one will
4280               transparently properly handle all cases of single- vs multi-
4281               thread, POSIX 2008-supported or not.
4282
4283               Non-Perl libraries, such as "gtk", that call the system
4284               "setlocale" can continue to work if this function is called
4285               before transferring control to the library.
4286
4287               Upon return from the code that needs to use the global locale,
4288               "sync_locale()" should be called to restore the safe multi-
4289               thread operation.
4290
4291                       void    switch_to_global_locale()
4292
4293       sync_locale
4294               "Perl_setlocale" can be used at any time to query or change the
4295               locale (though changing the locale is antisocial and dangerous
4296               on multi-threaded systems that don't have multi-thread safe
4297               locale operations.  (See "Multi-threaded operation" in
4298               perllocale).  Using the system setlocale(3) should be avoided.
4299               Nevertheless, certain non-Perl libraries called from XS, such
4300               as "Gtk" do so, and this can't be changed.  When the locale is
4301               changed by XS code that didn't use "Perl_setlocale", Perl needs
4302               to be told that the locale has changed.  Use this function to
4303               do so, before returning to Perl.
4304
4305               The return value is a boolean: TRUE if the global locale at the
4306               time of call was in effect; and FALSE if a per-thread locale
4307               was in effect.  This can be used by the caller that needs to
4308               restore things as-they-were to decide whether or not to call
4309               "Perl_switch_to_global_locale".
4310
4311                       bool    sync_locale()
4312
4313       WITH_LC_NUMERIC_SET_TO_NEEDED
4314               This macro invokes the supplied statement or block within the
4315               context of a "STORE_LC_NUMERIC_SET_TO_NEEDED" ..
4316               "RESTORE_LC_NUMERIC" pair if required, so eg:
4317
4318                 WITH_LC_NUMERIC_SET_TO_NEEDED(
4319                   SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
4320                 );
4321
4322               is equivalent to:
4323
4324                 {
4325               #ifdef USE_LOCALE_NUMERIC
4326                   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4327                   STORE_LC_NUMERIC_SET_TO_NEEDED();
4328               #endif
4329                   SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
4330               #ifdef USE_LOCALE_NUMERIC
4331                   RESTORE_LC_NUMERIC();
4332               #endif
4333                 }
4334
4335                       void    WITH_LC_NUMERIC_SET_TO_NEEDED(block)
4336
4337       WITH_LC_NUMERIC_SET_TO_NEEDED_IN
4338               Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
4339               provided as the precalculated value of "IN_LC(LC_NUMERIC)". It
4340               is the caller's responsibility to ensure that the status of
4341               "PL_compiling" and "PL_hints" cannot have changed since the
4342               precalculation.
4343
4344                       void    WITH_LC_NUMERIC_SET_TO_NEEDED_IN(
4345                                   bool in_lc_numeric, block
4346                               )
4347

Magical Functions

4349       mg_clear
4350               Clear something magical that the SV represents.  See
4351               "sv_magic".
4352
4353                       int     mg_clear(SV* sv)
4354
4355       mg_copy Copies the magic from one SV to another.  See "sv_magic".
4356
4357                       int     mg_copy(SV *sv, SV *nsv, const char *key,
4358                                       I32 klen)
4359
4360       mg_find Finds the magic pointer for "type" matching the SV.  See
4361               "sv_magic".
4362
4363                       MAGIC*  mg_find(const SV* sv, int type)
4364
4365       mg_findext
4366               Finds the magic pointer of "type" with the given "vtbl" for the
4367               "SV".  See "sv_magicext".
4368
4369                       MAGIC*  mg_findext(const SV* sv, int type,
4370                                          const MGVTBL *vtbl)
4371
4372       mg_free Free any magic storage used by the SV.  See "sv_magic".
4373
4374                       int     mg_free(SV* sv)
4375
4376       mg_freeext
4377               Remove any magic of type "how" using virtual table "vtbl" from
4378               the SV "sv".  See "sv_magic".
4379
4380               "mg_freeext(sv, how, NULL)" is equivalent to "mg_free_type(sv,
4381               how)".
4382
4383                       void    mg_freeext(SV* sv, int how, const MGVTBL *vtbl)
4384
4385       mg_free_type
4386               Remove any magic of type "how" from the SV "sv".  See
4387               "sv_magic".
4388
4389                       void    mg_free_type(SV* sv, int how)
4390
4391       mg_get  Do magic before a value is retrieved from the SV.  The type of
4392               SV must be >= "SVt_PVMG".  See "sv_magic".
4393
4394                       int     mg_get(SV* sv)
4395
4396       mg_length
4397               DEPRECATED!  It is planned to remove this function from a
4398               future release of Perl.  Do not use it for new code; remove it
4399               from existing code.
4400
4401               Reports on the SV's length in bytes, calling length magic if
4402               available, but does not set the UTF8 flag on "sv".  It will
4403               fall back to 'get' magic if there is no 'length' magic, but
4404               with no indication as to whether it called 'get' magic.  It
4405               assumes "sv" is a "PVMG" or higher.  Use "sv_len()" instead.
4406
4407                       U32     mg_length(SV* sv)
4408
4409       mg_magical
4410               Turns on the magical status of an SV.  See "sv_magic".
4411
4412                       void    mg_magical(SV* sv)
4413
4414       mg_set  Do magic after a value is assigned to the SV.  See "sv_magic".
4415
4416                       int     mg_set(SV* sv)
4417
4418       SvGETMAGIC
4419               Invokes "mg_get" on an SV if it has 'get' magic.  For example,
4420               this will call "FETCH" on a tied variable.  This macro
4421               evaluates its argument more than once.
4422
4423                       void    SvGETMAGIC(SV* sv)
4424
4425       SvLOCK  Arranges for a mutual exclusion lock to be obtained on "sv" if
4426               a suitable module has been loaded.
4427
4428                       void    SvLOCK(SV* sv)
4429
4430       SvSETMAGIC
4431               Invokes "mg_set" on an SV if it has 'set' magic.  This is
4432               necessary after modifying a scalar, in case it is a magical
4433               variable like $| or a tied variable (it calls "STORE").  This
4434               macro evaluates its argument more than once.
4435
4436                       void    SvSETMAGIC(SV* sv)
4437
4438       SvSetMagicSV
4439               Like "SvSetSV", but does any set magic required afterwards.
4440
4441                       void    SvSetMagicSV(SV* dsv, SV* ssv)
4442
4443       SvSetMagicSV_nosteal
4444               Like "SvSetSV_nosteal", but does any set magic required
4445               afterwards.
4446
4447                       void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
4448
4449       SvSetSV Calls "sv_setsv" if "dsv" is not the same as "ssv".  May
4450               evaluate arguments more than once.  Does not handle 'set' magic
4451               on the destination SV.
4452
4453                       void    SvSetSV(SV* dsv, SV* ssv)
4454
4455       SvSetSV_nosteal
4456               Calls a non-destructive version of "sv_setsv" if "dsv" is not
4457               the same as "ssv".  May evaluate arguments more than once.
4458
4459                       void    SvSetSV_nosteal(SV* dsv, SV* ssv)
4460
4461       SvSHARE Arranges for "sv" to be shared between threads if a suitable
4462               module has been loaded.
4463
4464                       void    SvSHARE(SV* sv)
4465
4466       sv_string_from_errnum
4467               Generates the message string describing an OS error and returns
4468               it as an SV.  "errnum" must be a value that "errno" could take,
4469               identifying the type of error.
4470
4471               If "tgtsv" is non-null then the string will be written into
4472               that SV (overwriting existing content) and it will be returned.
4473               If "tgtsv" is a null pointer then the string will be written
4474               into a new mortal SV which will be returned.
4475
4476               The message will be taken from whatever locale would be used by
4477               $!, and will be encoded in the SV in whatever manner would be
4478               used by $!.  The details of this process are subject to future
4479               change.  Currently, the message is taken from the C locale by
4480               default (usually producing an English message), and from the
4481               currently selected locale when in the scope of the "use locale"
4482               pragma.  A heuristic attempt is made to decode the message from
4483               the locale's character encoding, but it will only be decoded as
4484               either UTF-8 or ISO-8859-1.  It is always correctly decoded in
4485               a UTF-8 locale, usually in an ISO-8859-1 locale, and never in
4486               any other locale.
4487
4488               The SV is always returned containing an actual string, and with
4489               no other OK bits set.  Unlike $!, a message is even yielded for
4490               "errnum" zero (meaning success), and if no useful message is
4491               available then a useless string (currently empty) is returned.
4492
4493                       SV*     sv_string_from_errnum(int errnum, SV* tgtsv)
4494
4495       SvUNLOCK
4496               Releases a mutual exclusion lock on "sv" if a suitable module
4497               has been loaded.
4498
4499                       void    SvUNLOCK(SV* sv)
4500

Memory Management

4502       Copy    The XSUB-writer's interface to the C "memcpy" function.  The
4503               "src" is the source, "dest" is the destination, "nitems" is the
4504               number of items, and "type" is the type.  May fail on
4505               overlapping copies.  See also "Move".
4506
4507                       void    Copy(void* src, void* dest, int nitems, type)
4508
4509       CopyD   Like "Copy" but returns "dest".  Useful for encouraging
4510               compilers to tail-call optimise.
4511
4512                       void *  CopyD(void* src, void* dest, int nitems, type)
4513
4514       Move    The XSUB-writer's interface to the C "memmove" function.  The
4515               "src" is the source, "dest" is the destination, "nitems" is the
4516               number of items, and "type" is the type.  Can do overlapping
4517               moves.  See also "Copy".
4518
4519                       void    Move(void* src, void* dest, int nitems, type)
4520
4521       MoveD   Like "Move" but returns "dest".  Useful for encouraging
4522               compilers to tail-call optimise.
4523
4524                       void *  MoveD(void* src, void* dest, int nitems, type)
4525
4526       Newx    The XSUB-writer's interface to the C "malloc" function.
4527
4528               Memory obtained by this should ONLY be freed with "Safefree".
4529
4530               In 5.9.3, Newx() and friends replace the older New() API, and
4531               drops the first parameter, x, a debug aid which allowed callers
4532               to identify themselves.  This aid has been superseded by a new
4533               build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in
4534               perlhacktips).  The older API is still there for use in XS
4535               modules supporting older perls.
4536
4537                       void    Newx(void* ptr, int nitems, type)
4538
4539       Newxc   The XSUB-writer's interface to the C "malloc" function, with
4540               cast.  See also "Newx".
4541
4542               Memory obtained by this should ONLY be freed with "Safefree".
4543
4544                       void    Newxc(void* ptr, int nitems, type, cast)
4545
4546       Newxz   The XSUB-writer's interface to the C "malloc" function.  The
4547               allocated memory is zeroed with "memzero".  See also "Newx".
4548
4549               Memory obtained by this should ONLY be freed with "Safefree".
4550
4551                       void    Newxz(void* ptr, int nitems, type)
4552
4553       Poison  PoisonWith(0xEF) for catching access to freed memory.
4554
4555                       void    Poison(void* dest, int nitems, type)
4556
4557       PoisonFree
4558               PoisonWith(0xEF) for catching access to freed memory.
4559
4560                       void    PoisonFree(void* dest, int nitems, type)
4561
4562       PoisonNew
4563               PoisonWith(0xAB) for catching access to allocated but
4564               uninitialized memory.
4565
4566                       void    PoisonNew(void* dest, int nitems, type)
4567
4568       PoisonWith
4569               Fill up memory with a byte pattern (a byte repeated over and
4570               over again) that hopefully catches attempts to access
4571               uninitialized memory.
4572
4573                       void    PoisonWith(void* dest, int nitems, type,
4574                                          U8 byte)
4575
4576       Renew   The XSUB-writer's interface to the C "realloc" function.
4577
4578               Memory obtained by this should ONLY be freed with "Safefree".
4579
4580                       void    Renew(void* ptr, int nitems, type)
4581
4582       Renewc  The XSUB-writer's interface to the C "realloc" function, with
4583               cast.
4584
4585               Memory obtained by this should ONLY be freed with "Safefree".
4586
4587                       void    Renewc(void* ptr, int nitems, type, cast)
4588
4589       Safefree
4590               The XSUB-writer's interface to the C "free" function.
4591
4592               This should ONLY be used on memory obtained using "Newx" and
4593               friends.
4594
4595                       void    Safefree(void* ptr)
4596
4597       savepv  Perl's version of "strdup()".  Returns a pointer to a newly
4598               allocated string which is a duplicate of "pv".  The size of the
4599               string is determined by "strlen()", which means it may not
4600               contain embedded "NUL" characters and must have a trailing
4601               "NUL".  To prevent memory leaks, the memory allocated for the
4602               new string needs to be freed when no longer needed.  This can
4603               be done with the ""Safefree"" function, or "SAVEFREEPV".
4604
4605               On some platforms, Windows for example, all allocated memory
4606               owned by a thread is deallocated when that thread ends.  So if
4607               you need that not to happen, you need to use the shared memory
4608               functions, such as "savesharedpv".
4609
4610                       char*   savepv(const char* pv)
4611
4612       savepvn Perl's version of what "strndup()" would be if it existed.
4613               Returns a pointer to a newly allocated string which is a
4614               duplicate of the first "len" bytes from "pv", plus a trailing
4615               "NUL" byte.  The memory allocated for the new string can be
4616               freed with the "Safefree()" function.
4617
4618               On some platforms, Windows for example, all allocated memory
4619               owned by a thread is deallocated when that thread ends.  So if
4620               you need that not to happen, you need to use the shared memory
4621               functions, such as "savesharedpvn".
4622
4623                       char*   savepvn(const char* pv, Size_t len)
4624
4625       savepvs Like "savepvn", but takes a literal string instead of a
4626               string/length pair.
4627
4628                       char*   savepvs("literal string")
4629
4630       savesharedpv
4631               A version of "savepv()" which allocates the duplicate string in
4632               memory which is shared between threads.
4633
4634                       char*   savesharedpv(const char* pv)
4635
4636       savesharedpvn
4637               A version of "savepvn()" which allocates the duplicate string
4638               in memory which is shared between threads.  (With the specific
4639               difference that a "NULL" pointer is not acceptable)
4640
4641                       char*   savesharedpvn(const char *const pv,
4642                                             const STRLEN len)
4643
4644       savesharedpvs
4645               A version of "savepvs()" which allocates the duplicate string
4646               in memory which is shared between threads.
4647
4648                       char*   savesharedpvs("literal string")
4649
4650       savesharedsvpv
4651               A version of "savesharedpv()" which allocates the duplicate
4652               string in memory which is shared between threads.
4653
4654                       char*   savesharedsvpv(SV *sv)
4655
4656       savesvpv
4657               A version of "savepv()"/"savepvn()" which gets the string to
4658               duplicate from the passed in SV using "SvPV()"
4659
4660               On some platforms, Windows for example, all allocated memory
4661               owned by a thread is deallocated when that thread ends.  So if
4662               you need that not to happen, you need to use the shared memory
4663               functions, such as "savesharedsvpv".
4664
4665                       char*   savesvpv(SV* sv)
4666
4667       StructCopy
4668               This is an architecture-independent macro to copy one structure
4669               to another.
4670
4671                       void    StructCopy(type *src, type *dest, type)
4672
4673       Zero    The XSUB-writer's interface to the C "memzero" function.  The
4674               "dest" is the destination, "nitems" is the number of items, and
4675               "type" is the type.
4676
4677                       void    Zero(void* dest, int nitems, type)
4678
4679       ZeroD   Like "Zero" but returns dest.  Useful for encouraging compilers
4680               to tail-call optimise.
4681
4682                       void *  ZeroD(void* dest, int nitems, type)
4683

Miscellaneous Functions

4685       dump_c_backtrace
4686               Dumps the C backtrace to the given "fp".
4687
4688               Returns true if a backtrace could be retrieved, false if not.
4689
4690                       bool    dump_c_backtrace(PerlIO* fp, int max_depth,
4691                                                int skip)
4692
4693       fbm_compile
4694               Analyzes the string in order to make fast searches on it using
4695               "fbm_instr()" -- the Boyer-Moore algorithm.
4696
4697                       void    fbm_compile(SV* sv, U32 flags)
4698
4699       fbm_instr
4700               Returns the location of the SV in the string delimited by "big"
4701               and "bigend" ("bigend") is the char following the last char).
4702               It returns "NULL" if the string can't be found.  The "sv" does
4703               not have to be "fbm_compiled", but the search will not be as
4704               fast then.
4705
4706                       char*   fbm_instr(unsigned char* big,
4707                                         unsigned char* bigend, SV* littlestr,
4708                                         U32 flags)
4709
4710       foldEQ  Returns true if the leading "len" bytes of the strings "s1" and
4711               "s2" are the same case-insensitively; false otherwise.
4712               Uppercase and lowercase ASCII range bytes match themselves and
4713               their opposite case counterparts.  Non-cased and non-ASCII
4714               range bytes match only themselves.
4715
4716                       I32     foldEQ(const char* a, const char* b, I32 len)
4717
4718       foldEQ_locale
4719               Returns true if the leading "len" bytes of the strings "s1" and
4720               "s2" are the same case-insensitively in the current locale;
4721               false otherwise.
4722
4723                       I32     foldEQ_locale(const char* a, const char* b,
4724                                             I32 len)
4725
4726       form    Takes a sprintf-style format pattern and conventional (non-SV)
4727               arguments and returns the formatted string.
4728
4729                   (char *) Perl_form(pTHX_ const char* pat, ...)
4730
4731               can be used any place a string (char *) is required:
4732
4733                   char * s = Perl_form("%d.%d",major,minor);
4734
4735               Uses a single private buffer so if you want to format several
4736               strings you must explicitly copy the earlier strings away (and
4737               free the copies when you are done).
4738
4739                       char*   form(const char* pat, ...)
4740
4741       getcwd_sv
4742               Fill "sv" with current working directory
4743
4744                       int     getcwd_sv(SV* sv)
4745
4746       get_c_backtrace_dump
4747               Returns a SV containing a dump of "depth" frames of the call
4748               stack, skipping the "skip" innermost ones.  "depth" of 20 is
4749               usually enough.
4750
4751               The appended output looks like:
4752
4753               ...  1   10e004812:0082   Perl_croak   util.c:1716
4754               /usr/bin/perl 2   10df8d6d2:1d72   perl_parse   perl.c:3975
4755               /usr/bin/perl ...
4756
4757               The fields are tab-separated.  The first column is the depth
4758               (zero being the innermost non-skipped frame).  In the
4759               hex:offset, the hex is where the program counter was in
4760               "S_parse_body", and the :offset (might be missing) tells how
4761               much inside the "S_parse_body" the program counter was.
4762
4763               The "util.c:1716" is the source code file and line number.
4764
4765               The /usr/bin/perl is obvious (hopefully).
4766
4767               Unknowns are "-".  Unknowns can happen unfortunately quite
4768               easily: if the platform doesn't support retrieving the
4769               information; if the binary is missing the debug information; if
4770               the optimizer has transformed the code by for example inlining.
4771
4772                       SV*     get_c_backtrace_dump(int max_depth, int skip)
4773
4774       ibcmp   This is a synonym for "(! foldEQ())"
4775
4776                       I32     ibcmp(const char* a, const char* b, I32 len)
4777
4778       ibcmp_locale
4779               This is a synonym for "(! foldEQ_locale())"
4780
4781                       I32     ibcmp_locale(const char* a, const char* b,
4782                                            I32 len)
4783
4784       instr   Same as strstr(3), which finds and returns a pointer to the
4785               first occurrence of the NUL-terminated substring "little" in
4786               the NUL-terminated string "big", returning NULL if not found.
4787               The terminating NUL bytes are not compared.
4788
4789                       char*   instr(const char* big, const char* little)
4790
4791       IS_SAFE_SYSCALL
4792               Same as "is_safe_syscall".
4793
4794                       bool    IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
4795                                               NN const char *what,
4796                                               NN const char *op_name)
4797
4798       is_safe_syscall
4799               Test that the given "pv" (with length "len") doesn't contain
4800               any internal "NUL" characters.  If it does, set "errno" to
4801               "ENOENT", optionally warn using the "syscalls" category, and
4802               return FALSE.
4803
4804               Return TRUE if the name is safe.
4805
4806               "what" and "op_name" are used in any warning.
4807
4808               Used by the "IS_SAFE_SYSCALL()" macro.
4809
4810                       bool    is_safe_syscall(const char *pv, STRLEN len,
4811                                               const char *what,
4812                                               const char *op_name)
4813
4814       LIKELY  Returns the input unchanged, but at the same time it gives a
4815               branch prediction hint to the compiler that this condition is
4816               likely to be true.
4817
4818       memCHRs Returns the position of the first occurence of the byte "c" in
4819               the literal string "list", or NULL if "c" doesn't appear in
4820               "list".  All bytes are treated as unsigned char.  Thus this
4821               macro can be used to determine if "c" is in a set of particular
4822               characters.  Unlike strchr(3), it works even if "c" is "NUL"
4823               (and the set doesn't include "NUL").
4824
4825                       bool    memCHRs("list", char c)
4826
4827       memEQ   Test two buffers (which may contain embedded "NUL" characters,
4828               to see if they are equal.  The "len" parameter indicates the
4829               number of bytes to compare.  Returns zero if equal, or non-zero
4830               if non-equal.
4831
4832                       bool    memEQ(char* s1, char* s2, STRLEN len)
4833
4834       memEQs  Like "memEQ", but the second string is a literal enclosed in
4835               double quotes, "l1" gives the number of bytes in "s1".  Returns
4836               zero if equal, or non-zero if non-equal.
4837
4838                       bool    memEQs(char* s1, STRLEN l1, "s2")
4839
4840       memNE   Test two buffers (which may contain embedded "NUL" characters,
4841               to see if they are not equal.  The "len" parameter indicates
4842               the number of bytes to compare.  Returns zero if non-equal, or
4843               non-zero if equal.
4844
4845                       bool    memNE(char* s1, char* s2, STRLEN len)
4846
4847       memNEs  Like "memNE", but the second string is a literal enclosed in
4848               double quotes, "l1" gives the number of bytes in "s1".  Returns
4849               zero if non-equal, or zero if non-equal.
4850
4851                       bool    memNEs(char* s1, STRLEN l1, "s2")
4852
4853       mess    Take a sprintf-style format pattern and argument list.  These
4854               are used to generate a string message.  If the message does not
4855               end with a newline, then it will be extended with some
4856               indication of the current location in the code, as described
4857               for "mess_sv".
4858
4859               Normally, the resulting message is returned in a new mortal SV.
4860               During global destruction a single SV may be shared between
4861               uses of this function.
4862
4863                       SV*     mess(const char* pat, ...)
4864
4865       mess_sv Expands a message, intended for the user, to include an
4866               indication of the current location in the code, if the message
4867               does not already appear to be complete.
4868
4869               "basemsg" is the initial message or object.  If it is a
4870               reference, it will be used as-is and will be the result of this
4871               function.  Otherwise it is used as a string, and if it already
4872               ends with a newline, it is taken to be complete, and the result
4873               of this function will be the same string.  If the message does
4874               not end with a newline, then a segment such as "at foo.pl line
4875               37" will be appended, and possibly other clauses indicating the
4876               current state of execution.  The resulting message will end
4877               with a dot and a newline.
4878
4879               Normally, the resulting message is returned in a new mortal SV.
4880               During global destruction a single SV may be shared between
4881               uses of this function.  If "consume" is true, then the function
4882               is permitted (but not required) to modify and return "basemsg"
4883               instead of allocating a new SV.
4884
4885                       SV*     mess_sv(SV* basemsg, bool consume)
4886
4887       my_snprintf
4888               The C library "snprintf" functionality, if available and
4889               standards-compliant (uses "vsnprintf", actually).  However, if
4890               the "vsnprintf" is not available, will unfortunately use the
4891               unsafe "vsprintf" which can overrun the buffer (there is an
4892               overrun check, but that may be too late).  Consider using
4893               "sv_vcatpvf" instead, or getting "vsnprintf".
4894
4895                       int     my_snprintf(char *buffer, const Size_t len,
4896                                           const char *format, ...)
4897
4898       my_sprintf
4899               DEPRECATED!  It is planned to remove this function from a
4900               future release of Perl.  Do not use it for new code; remove it
4901               from existing code.
4902
4903               Do NOT use this due to the possibility of overflowing "buffer".
4904               Instead use my_snprintf()
4905
4906                       int     my_sprintf(NN char *buffer, NN const char *pat,
4907                                          ...)
4908
4909       my_strlcat
4910               The C library "strlcat" if available, or a Perl implementation
4911               of it.  This operates on C "NUL"-terminated strings.
4912
4913               "my_strlcat()" appends string "src" to the end of "dst".  It
4914               will append at most "size - strlen(dst) - 1" characters.  It
4915               will then "NUL"-terminate, unless "size" is 0 or the original
4916               "dst" string was longer than "size" (in practice this should
4917               not happen as it means that either "size" is incorrect or that
4918               "dst" is not a proper "NUL"-terminated string).
4919
4920               Note that "size" is the full size of the destination buffer and
4921               the result is guaranteed to be "NUL"-terminated if there is
4922               room.  Note that room for the "NUL" should be included in
4923               "size".
4924
4925               The return value is the total length that "dst" would have if
4926               "size" is sufficiently large.  Thus it is the initial length of
4927               "dst" plus the length of "src".  If "size" is smaller than the
4928               return, the excess was not appended.
4929
4930                       Size_t  my_strlcat(char *dst, const char *src,
4931                                          Size_t size)
4932
4933       my_strlcpy
4934               The C library "strlcpy" if available, or a Perl implementation
4935               of it.  This operates on C "NUL"-terminated strings.
4936
4937               "my_strlcpy()" copies up to "size - 1" characters from the
4938               string "src" to "dst", "NUL"-terminating the result if "size"
4939               is not 0.
4940
4941               The return value is the total length "src" would be if the copy
4942               completely succeeded.  If it is larger than "size", the excess
4943               was not copied.
4944
4945                       Size_t  my_strlcpy(char *dst, const char *src,
4946                                          Size_t size)
4947
4948       my_strnlen
4949               The C library "strnlen" if available, or a Perl implementation
4950               of it.
4951
4952               "my_strnlen()" computes the length of the string, up to
4953               "maxlen" characters.  It will never attempt to address more
4954               than "maxlen" characters, making it suitable for use with
4955               strings that are not guaranteed to be NUL-terminated.
4956
4957                       Size_t  my_strnlen(const char *str, Size_t maxlen)
4958
4959       my_vsnprintf
4960               The C library "vsnprintf" if available and standards-compliant.
4961               However, if the "vsnprintf" is not available, will
4962               unfortunately use the unsafe "vsprintf" which can overrun the
4963               buffer (there is an overrun check, but that may be too late).
4964               Consider using "sv_vcatpvf" instead, or getting "vsnprintf".
4965
4966                       int     my_vsnprintf(char *buffer, const Size_t len,
4967                                            const char *format, va_list ap)
4968
4969       ninstr  Find the first (leftmost) occurrence of a sequence of bytes
4970               within another sequence.  This is the Perl version of
4971               "strstr()", extended to handle arbitrary sequences, potentially
4972               containing embedded "NUL" characters ("NUL" is what the initial
4973               "n" in the function name stands for; some systems have an
4974               equivalent, "memmem()", but with a somewhat different API).
4975
4976               Another way of thinking about this function is finding a needle
4977               in a haystack.  "big" points to the first byte in the haystack.
4978               "big_end" points to one byte beyond the final byte in the
4979               haystack.  "little" points to the first byte in the needle.
4980               "little_end" points to one byte beyond the final byte in the
4981               needle.  All the parameters must be non-"NULL".
4982
4983               The function returns "NULL" if there is no occurrence of
4984               "little" within "big".  If "little" is the empty string, "big"
4985               is returned.
4986
4987               Because this function operates at the byte level, and because
4988               of the inherent characteristics of UTF-8 (or UTF-EBCDIC), it
4989               will work properly if both the needle and the haystack are
4990               strings with the same UTF-8ness, but not if the UTF-8ness
4991               differs.
4992
4993                       char*   ninstr(const char* big, const char* bigend,
4994                                      const char* little, const char* lend)
4995
4996       PERL_SYS_INIT
4997               Provides system-specific tune up of the C runtime environment
4998               necessary to run Perl interpreters.  This should be called only
4999               once, before creating any Perl interpreters.
5000
5001                       void    PERL_SYS_INIT(int *argc, char*** argv)
5002
5003       PERL_SYS_INIT3
5004               Provides system-specific tune up of the C runtime environment
5005               necessary to run Perl interpreters.  This should be called only
5006               once, before creating any Perl interpreters.
5007
5008                       void    PERL_SYS_INIT3(int *argc, char*** argv,
5009                                              char*** env)
5010
5011       PERL_SYS_TERM
5012               Provides system-specific clean up of the C runtime environment
5013               after running Perl interpreters.  This should be called only
5014               once, after freeing any remaining Perl interpreters.
5015
5016                       void    PERL_SYS_TERM()
5017
5018       READ_XDIGIT
5019               Returns the value of an ASCII-range hex digit and advances the
5020               string pointer.  Behaviour is only well defined when
5021               isXDIGIT(*str) is true.
5022
5023                       U8      READ_XDIGIT(char str*)
5024
5025       rninstr Like "ninstr", but instead finds the final (rightmost)
5026               occurrence of a sequence of bytes within another sequence,
5027               returning "NULL" if there is no such occurrence.
5028
5029                       char*   rninstr(const char* big, const char* bigend,
5030                                       const char* little, const char* lend)
5031
5032       STMT_START
5033                STMT_START { statements; } STMT_END;
5034
5035               can be used as a single statement, as in
5036
5037                if (x) STMT_START { ... } STMT_END; else ...
5038
5039               These are often used in macro definitions.  Note that you can't
5040               return a value out of them.
5041
5042       strEQ   Test two "NUL"-terminated strings to see if they are equal.
5043               Returns true or false.
5044
5045                       bool    strEQ(char* s1, char* s2)
5046
5047       strGE   Test two "NUL"-terminated strings to see if the first, "s1", is
5048               greater than or equal to the second, "s2".  Returns true or
5049               false.
5050
5051                       bool    strGE(char* s1, char* s2)
5052
5053       strGT   Test two "NUL"-terminated strings to see if the first, "s1", is
5054               greater than the second, "s2".  Returns true or false.
5055
5056                       bool    strGT(char* s1, char* s2)
5057
5058       strLE   Test two "NUL"-terminated strings to see if the first, "s1", is
5059               less than or equal to the second, "s2".  Returns true or false.
5060
5061                       bool    strLE(char* s1, char* s2)
5062
5063       strLT   Test two "NUL"-terminated strings to see if the first, "s1", is
5064               less than the second, "s2".  Returns true or false.
5065
5066                       bool    strLT(char* s1, char* s2)
5067
5068       strNE   Test two "NUL"-terminated strings to see if they are different.
5069               Returns true or false.
5070
5071                       bool    strNE(char* s1, char* s2)
5072
5073       strnEQ  Test two "NUL"-terminated strings to see if they are equal.
5074               The "len" parameter indicates the number of bytes to compare.
5075               Returns true or false.  (A wrapper for "strncmp").
5076
5077                       bool    strnEQ(char* s1, char* s2, STRLEN len)
5078
5079       strnNE  Test two "NUL"-terminated strings to see if they are different.
5080               The "len" parameter indicates the number of bytes to compare.
5081               Returns true or false.  (A wrapper for "strncmp").
5082
5083                       bool    strnNE(char* s1, char* s2, STRLEN len)
5084
5085       sv_destroyable
5086               Dummy routine which reports that object can be destroyed when
5087               there is no sharing module present.  It ignores its single SV
5088               argument, and returns 'true'.  Exists to avoid test for a
5089               "NULL" function pointer and because it could potentially warn
5090               under some level of strict-ness.
5091
5092                       bool    sv_destroyable(SV *sv)
5093
5094       sv_nosharing
5095               Dummy routine which "shares" an SV when there is no sharing
5096               module present.  Or "locks" it.  Or "unlocks" it.  In other
5097               words, ignores its single SV argument.  Exists to avoid test
5098               for a "NULL" function pointer and because it could potentially
5099               warn under some level of strict-ness.
5100
5101                       void    sv_nosharing(SV *sv)
5102
5103       UNLIKELY
5104               Returns the input unchanged, but at the same time it gives a
5105               branch prediction hint to the compiler that this condition is
5106               likely to be false.
5107
5108       vmess   "pat" and "args" are a sprintf-style format pattern and
5109               encapsulated argument list, respectively.  These are used to
5110               generate a string message.  If the message does not end with a
5111               newline, then it will be extended with some indication of the
5112               current location in the code, as described for "mess_sv".
5113
5114               Normally, the resulting message is returned in a new mortal SV.
5115               During global destruction a single SV may be shared between
5116               uses of this function.
5117
5118                       SV*     vmess(const char* pat, va_list* args)
5119

MRO Functions

5121       These functions are related to the method resolution order of perl
5122       classes Also see perlmroapi.
5123
5124       mro_get_linear_isa
5125               Returns the mro linearisation for the given stash.  By default,
5126               this will be whatever "mro_get_linear_isa_dfs" returns unless
5127               some other MRO is in effect for the stash.  The return value is
5128               a read-only AV*.
5129
5130               You are responsible for "SvREFCNT_inc()" on the return value if
5131               you plan to store it anywhere semi-permanently (otherwise it
5132               might be deleted out from under you the next time the cache is
5133               invalidated).
5134
5135                       AV*     mro_get_linear_isa(HV* stash)
5136
5137       mro_method_changed_in
5138               Invalidates method caching on any child classes of the given
5139               stash, so that they might notice the changes in this one.
5140
5141               Ideally, all instances of "PL_sub_generation++" in perl source
5142               outside of mro.c should be replaced by calls to this.
5143
5144               Perl automatically handles most of the common ways a method
5145               might be redefined.  However, there are a few ways you could
5146               change a method in a stash without the cache code noticing, in
5147               which case you need to call this method afterwards:
5148
5149               1) Directly manipulating the stash HV entries from XS code.
5150
5151               2) Assigning a reference to a readonly scalar constant into a
5152               stash entry in order to create a constant subroutine (like
5153               constant.pm does).
5154
5155               This same method is available from pure perl via,
5156               "mro::method_changed_in(classname)".
5157
5158                       void    mro_method_changed_in(HV* stash)
5159
5160       mro_register
5161               Registers a custom mro plugin.  See perlmroapi for details on
5162               this and other mro functions.
5163
5164               NOTE: this function must be explicitly called as
5165               Perl_mro_register with an aTHX_ parameter.
5166
5167                       void    Perl_mro_register(pTHX_
5168                                                 const struct mro_alg *mro)
5169

Multicall Functions

5171       dMULTICALL
5172               Declare local variables for a multicall.  See "LIGHTWEIGHT
5173               CALLBACKS" in perlcall.
5174
5175                               dMULTICALL;
5176
5177       MULTICALL
5178               Make a lightweight callback.  See "LIGHTWEIGHT CALLBACKS" in
5179               perlcall.
5180
5181                               MULTICALL;
5182
5183       POP_MULTICALL
5184               Closing bracket for a lightweight callback.  See "LIGHTWEIGHT
5185               CALLBACKS" in perlcall.
5186
5187                               POP_MULTICALL;
5188
5189       PUSH_MULTICALL
5190               Opening bracket for a lightweight callback.  See "LIGHTWEIGHT
5191               CALLBACKS" in perlcall.
5192
5193                               PUSH_MULTICALL(CV* the_cv);
5194

Numeric functions

5196       grok_bin
5197               converts a string representing a binary number to numeric form.
5198
5199               On entry "start" and *len_p give the string to scan, *flags
5200               gives conversion flags, and "result" should be "NULL" or a
5201               pointer to an NV.  The scan stops at the end of the string, or
5202               at just before the first invalid character.  Unless
5203               "PERL_SCAN_SILENT_ILLDIGIT" is set in *flags, encountering an
5204               invalid character (except NUL) will also trigger a warning.  On
5205               return *len_p is set to the length of the scanned string, and
5206               *flags gives output flags.
5207
5208               If the value is <= "UV_MAX" it is returned as a UV, the output
5209               flags are clear, and nothing is written to *result.  If the
5210               value is > "UV_MAX", "grok_bin" returns "UV_MAX", sets
5211               "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
5212               an approximation of the correct value into *result (which is an
5213               NV; or the approximation is discarded if "result" is NULL).
5214
5215               The binary number may optionally be prefixed with "0b" or "b"
5216               unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
5217
5218               If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or
5219               all pairs of digits may be separated from each other by a
5220               single underscore; also a single leading underscore is
5221               accepted.
5222
5223                       UV      grok_bin(const char* start, STRLEN* len_p,
5224                                        I32* flags, NV *result)
5225
5226       grok_hex
5227               converts a string representing a hex number to numeric form.
5228
5229               On entry "start" and *len_p give the string to scan, *flags
5230               gives conversion flags, and "result" should be "NULL" or a
5231               pointer to an NV.  The scan stops at the end of the string, or
5232               at just before the first invalid character.  Unless
5233               "PERL_SCAN_SILENT_ILLDIGIT" is set in *flags, encountering an
5234               invalid character (except NUL) will also trigger a warning.  On
5235               return *len_p is set to the length of the scanned string, and
5236               *flags gives output flags.
5237
5238               If the value is <= "UV_MAX" it is returned as a UV, the output
5239               flags are clear, and nothing is written to *result.  If the
5240               value is > "UV_MAX", "grok_hex" returns "UV_MAX", sets
5241               "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
5242               an approximation of the correct value into *result (which is an
5243               NV; or the approximation is discarded if "result" is NULL).
5244
5245               The hex number may optionally be prefixed with "0x" or "x"
5246               unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
5247
5248               If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or
5249               all pairs of digits may be separated from each other by a
5250               single underscore; also a single leading underscore is
5251               accepted.
5252
5253                       UV      grok_hex(const char* start, STRLEN* len_p,
5254                                        I32* flags, NV *result)
5255
5256       grok_infnan
5257               Helper for "grok_number()", accepts various ways of spelling
5258               "infinity" or "not a number", and returns one of the following
5259               flag combinations:
5260
5261                 IS_NUMBER_INFINITY
5262                 IS_NUMBER_NAN
5263                 IS_NUMBER_INFINITY | IS_NUMBER_NEG
5264                 IS_NUMBER_NAN | IS_NUMBER_NEG
5265                 0
5266
5267               possibly |-ed with "IS_NUMBER_TRAILING".
5268
5269               If an infinity or a not-a-number is recognized, *sp will point
5270               to one byte past the end of the recognized string.  If the
5271               recognition fails, zero is returned, and *sp will not move.
5272
5273                       int     grok_infnan(const char** sp, const char *send)
5274
5275       grok_number
5276               Identical to "grok_number_flags()" with "flags" set to zero.
5277
5278                       int     grok_number(const char *pv, STRLEN len,
5279                                           UV *valuep)
5280
5281       grok_number_flags
5282               Recognise (or not) a number.  The type of the number is
5283               returned (0 if unrecognised), otherwise it is a bit-ORed
5284               combination of "IS_NUMBER_IN_UV",
5285               "IS_NUMBER_GREATER_THAN_UV_MAX", "IS_NUMBER_NOT_INT",
5286               "IS_NUMBER_NEG", "IS_NUMBER_INFINITY", "IS_NUMBER_NAN" (defined
5287               in perl.h).
5288
5289               If the value of the number can fit in a UV, it is returned in
5290               *valuep.  "IS_NUMBER_IN_UV" will be set to indicate that
5291               *valuep is valid, "IS_NUMBER_IN_UV" will never be set unless
5292               *valuep is valid, but *valuep may have been assigned to during
5293               processing even though "IS_NUMBER_IN_UV" is not set on return.
5294               If "valuep" is "NULL", "IS_NUMBER_IN_UV" will be set for the
5295               same cases as when "valuep" is non-"NULL", but no actual
5296               assignment (or SEGV) will occur.
5297
5298               "IS_NUMBER_NOT_INT" will be set with "IS_NUMBER_IN_UV" if
5299               trailing decimals were seen (in which case *valuep gives the
5300               true value truncated to an integer), and "IS_NUMBER_NEG" if the
5301               number is negative (in which case *valuep holds the absolute
5302               value).  "IS_NUMBER_IN_UV" is not set if e notation was used or
5303               the number is larger than a UV.
5304
5305               "flags" allows only "PERL_SCAN_TRAILING", which allows for
5306               trailing non-numeric text on an otherwise successful grok,
5307               setting "IS_NUMBER_TRAILING" on the result.
5308
5309                       int     grok_number_flags(const char *pv, STRLEN len,
5310                                                 UV *valuep, U32 flags)
5311
5312       GROK_NUMERIC_RADIX
5313               A synonym for "grok_numeric_radix"
5314
5315                       bool    GROK_NUMERIC_RADIX(NN const char **sp,
5316                                                  NN const char *send)
5317
5318       grok_numeric_radix
5319               Scan and skip for a numeric decimal separator (radix).
5320
5321                       bool    grok_numeric_radix(const char **sp,
5322                                                  const char *send)
5323
5324       grok_oct
5325               converts a string representing an octal number to numeric form.
5326
5327               On entry "start" and *len_p give the string to scan, *flags
5328               gives conversion flags, and "result" should be "NULL" or a
5329               pointer to an NV.  The scan stops at the end of the string, or
5330               at just before the first invalid character.  Unless
5331               "PERL_SCAN_SILENT_ILLDIGIT" is set in *flags, encountering an
5332               invalid character (except NUL) will also trigger a warning.  On
5333               return *len_p is set to the length of the scanned string, and
5334               *flags gives output flags.
5335
5336               If the value is <= "UV_MAX" it is returned as a UV, the output
5337               flags are clear, and nothing is written to *result.  If the
5338               value is > "UV_MAX", "grok_oct" returns "UV_MAX", sets
5339               "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
5340               an approximation of the correct value into *result (which is an
5341               NV; or the approximation is discarded if "result" is NULL).
5342
5343               If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or
5344               all pairs of digits may be separated from each other by a
5345               single underscore; also a single leading underscore is
5346               accepted.
5347
5348               The "PERL_SCAN_DISALLOW_PREFIX" flag is always treated as being
5349               set for this function.
5350
5351                       UV      grok_oct(const char* start, STRLEN* len_p,
5352                                        I32* flags, NV *result)
5353
5354       isinfnan
5355               "Perl_isinfnan()" is a utility function that returns true if
5356               the NV argument is either an infinity or a "NaN", false
5357               otherwise.  To test in more detail, use "Perl_isinf()" and
5358               "Perl_isnan()".
5359
5360               This is also the logical inverse of Perl_isfinite().
5361
5362                       bool    isinfnan(NV nv)
5363
5364       IS_NUMBER_GREATER_THAN_UV_MAX bool IS_NUMBER_GREATER_THAN_UV_MAX
5365       IS_NUMBER_INFINITY bool  IS_NUMBER_INFINITY
5366       IS_NUMBER_IN_UV bool     IS_NUMBER_IN_UV
5367       IS_NUMBER_NAN bool  IS_NUMBER_NAN
5368       IS_NUMBER_NEG bool  IS_NUMBER_NEG
5369       IS_NUMBER_NOT_INT
5370                       bool    IS_NUMBER_NOT_INT
5371
5372       my_strtod
5373               This function is equivalent to the libc strtod() function, and
5374               is available even on platforms that lack plain strtod().  Its
5375               return value is the best available precision depending on
5376               platform capabilities and Configure options.
5377
5378               It properly handles the locale radix character, meaning it
5379               expects a dot except when called from within the scope of
5380               "use locale", in which case the radix character should be that
5381               specified by the current locale.
5382
5383               The synonym Strtod() may be used instead.
5384
5385                       NV      my_strtod(const char * const s, char ** e)
5386
5387       PERL_ABS
5388               Typeless "abs" or "fabs", etc.  (The usage below indicates it
5389               is for integers, but it works for any type.)  Use instead of
5390               these, since the C library ones force their argument to be what
5391               it is expecting, potentially leading to disaster.  But also
5392               beware that this evaluates its argument twice, so no "x++".
5393
5394                       int     PERL_ABS(int)
5395
5396       PERL_INT_MAX
5397               This and "PERL_INT_MIN", "PERL_LONG_MAX", "PERL_LONG_MIN",
5398               "PERL_QUAD_MAX", "PERL_SHORT_MAX", "PERL_SHORT_MIN",
5399               "PERL_UCHAR_MAX", "PERL_UCHAR_MIN", "PERL_UINT_MAX",
5400               "PERL_ULONG_MAX", "PERL_ULONG_MIN", "PERL_UQUAD_MAX",
5401               "PERL_UQUAD_MIN", "PERL_USHORT_MAX", "PERL_USHORT_MIN",
5402               "PERL_QUAD_MIN" give the largest and smallest number
5403               representable in the current platform in variables of the
5404               corresponding types.
5405
5406               For signed types, the smallest representable number is the most
5407               negative number, the one furthest away from zero.
5408
5409               For C99 and later compilers, these correspond to things like
5410               "INT_MAX", which are available to the C code.  But these
5411               constants, furnished by Perl, allow code compiled on earlier
5412               compilers to portably have access to the same constants.
5413
5414       Perl_signbit
5415               NOTE: this function is experimental and may change or be
5416               removed without notice.
5417
5418               Return a non-zero integer if the sign bit on an NV is set, and
5419               0 if it is not.
5420
5421               If Configure detects this system has a "signbit()" that will
5422               work with our NVs, then we just use it via the "#define" in
5423               perl.h.  Otherwise, fall back on this implementation.  The main
5424               use of this function is catching "-0.0".
5425
5426               "Configure" notes:  This function is called 'Perl_signbit'
5427               instead of a plain 'signbit' because it is easy to imagine a
5428               system having a "signbit()" function or macro that doesn't
5429               happen to work with our particular choice of NVs.  We shouldn't
5430               just re-"#define" "signbit" as "Perl_signbit" and expect the
5431               standard system headers to be happy.  Also, this is a no-
5432               context function (no "pTHX_") because "Perl_signbit()" is
5433               usually re-"#defined" in perl.h as a simple macro call to the
5434               system's "signbit()".  Users should just always call
5435               "Perl_signbit()".
5436
5437                       int     Perl_signbit(NV f)
5438
5439       scan_bin
5440               For backwards compatibility.  Use "grok_bin" instead.
5441
5442                       NV      scan_bin(const char* start, STRLEN len,
5443                                        STRLEN* retlen)
5444
5445       scan_hex
5446               For backwards compatibility.  Use "grok_hex" instead.
5447
5448                       NV      scan_hex(const char* start, STRLEN len,
5449                                        STRLEN* retlen)
5450
5451       scan_oct
5452               For backwards compatibility.  Use "grok_oct" instead.
5453
5454                       NV      scan_oct(const char* start, STRLEN len,
5455                                        STRLEN* retlen)
5456
5457       Strtod  This is a synonym for "my_strtod".
5458
5459                       NV      Strtod(NN const char * const s,
5460                                      NULLOK char ** e)
5461
5462       Strtol  Platform and configuration independent "strtol".  This expands
5463               to the appropriate "strotol"-like function based on the
5464               platform and Configure options>.  For example it could expand
5465               to "strtoll" or "strtoq" instead of "strtol".
5466
5467                       NV      Strtol(NN const char * const s,
5468                                      NULLOK char ** e, int base)
5469
5470       Strtoul Platform and configuration independent "strtoul".  This expands
5471               to the appropriate "strotoul"-like function based on the
5472               platform and Configure options>.  For example it could expand
5473               to "strtoull" or "strtouq" instead of "strtoul".
5474
5475                       NV      Strtoul(NN const char * const s,
5476                                       NULLOK char ** e, int base)
5477

Obsolete backwards compatibility functions

5479       Some of these are also deprecated.  You can exclude these from your
5480       compiled Perl by adding this option to Configure:
5481       "-Accflags='-DNO_MATHOMS'"
5482
5483       custom_op_desc
5484               DEPRECATED!  It is planned to remove this function from a
5485               future release of Perl.  Do not use it for new code; remove it
5486               from existing code.
5487
5488               Return the description of a given custom op.  This was once
5489               used by the "OP_DESC" macro, but is no longer: it has only been
5490               kept for compatibility, and should not be used.
5491
5492                       const char * custom_op_desc(const OP *o)
5493
5494       custom_op_name
5495               DEPRECATED!  It is planned to remove this function from a
5496               future release of Perl.  Do not use it for new code; remove it
5497               from existing code.
5498
5499               Return the name for a given custom op.  This was once used by
5500               the "OP_NAME" macro, but is no longer: it has only been kept
5501               for compatibility, and should not be used.
5502
5503                       const char * custom_op_name(const OP *o)
5504
5505       gv_fetchmethod
5506               See "gv_fetchmethod_autoload".
5507
5508                       GV*     gv_fetchmethod(HV* stash, const char* name)
5509
5510       is_utf8_char
5511               DEPRECATED!  It is planned to remove this function from a
5512               future release of Perl.  Do not use it for new code; remove it
5513               from existing code.
5514
5515               Tests if some arbitrary number of bytes begins in a valid UTF-8
5516               character.  Note that an INVARIANT (i.e. ASCII on non-EBCDIC
5517               machines) character is a valid UTF-8 character.  The actual
5518               number of bytes in the UTF-8 character will be returned if it
5519               is valid, otherwise 0.
5520
5521               This function is deprecated due to the possibility that
5522               malformed input could cause reading beyond the end of the input
5523               buffer.  Use "isUTF8_CHAR" instead.
5524
5525                       STRLEN  is_utf8_char(const U8 *s)
5526
5527       is_utf8_char_buf
5528               This is identical to the macro "isUTF8_CHAR" in perlapi.
5529
5530                       STRLEN  is_utf8_char_buf(const U8 *buf,
5531                                                const U8 *buf_end)
5532
5533       pack_cat
5534               The engine implementing "pack()" Perl function.  Note:
5535               parameters "next_in_list" and "flags" are not used.  This call
5536               should not be used; use "packlist" instead.
5537
5538                       void    pack_cat(SV *cat, const char *pat,
5539                                        const char *patend, SV **beglist,
5540                                        SV **endlist, SV ***next_in_list,
5541                                        U32 flags)
5542
5543       pad_compname_type
5544               Looks up the type of the lexical variable at position "po" in
5545               the currently-compiling pad.  If the variable is typed, the
5546               stash of the class to which it is typed is returned.  If not,
5547               "NULL" is returned.
5548
5549                       HV*     pad_compname_type(const PADOFFSET po)
5550
5551       sv_2pvbyte_nolen
5552               Return a pointer to the byte-encoded representation of the SV.
5553               May cause the SV to be downgraded from UTF-8 as a side-effect.
5554
5555               Usually accessed via the "SvPVbyte_nolen" macro.
5556
5557                       char*   sv_2pvbyte_nolen(SV* sv)
5558
5559       sv_2pvutf8_nolen
5560               Return a pointer to the UTF-8-encoded representation of the SV.
5561               May cause the SV to be upgraded to UTF-8 as a side-effect.
5562
5563               Usually accessed via the "SvPVutf8_nolen" macro.
5564
5565                       char*   sv_2pvutf8_nolen(SV* sv)
5566
5567       sv_2pv_nolen
5568               Like "sv_2pv()", but doesn't return the length too.  You should
5569               usually use the macro wrapper "SvPV_nolen(sv)" instead.
5570
5571                       char*   sv_2pv_nolen(SV* sv)
5572
5573       sv_catpvn_mg
5574               Like "sv_catpvn", but also handles 'set' magic.
5575
5576                       void    sv_catpvn_mg(SV *sv, const char *ptr,
5577                                            STRLEN len)
5578
5579       sv_catsv_mg
5580               Like "sv_catsv", but also handles 'set' magic.
5581
5582                       void    sv_catsv_mg(SV *dsv, SV *ssv)
5583
5584       sv_force_normal
5585               Undo various types of fakery on an SV: if the PV is a shared
5586               string, make a private copy; if we're a ref, stop refing; if
5587               we're a glob, downgrade to an "xpvmg".  See also
5588               "sv_force_normal_flags".
5589
5590                       void    sv_force_normal(SV *sv)
5591
5592       sv_iv   DEPRECATED!  It is planned to remove this function from a
5593               future release of Perl.  Do not use it for new code; remove it
5594               from existing code.
5595
5596               A private implementation of the "SvIVx" macro for compilers
5597               which can't cope with complex macro expressions.  Always use
5598               the macro instead.
5599
5600                       IV      sv_iv(SV* sv)
5601
5602       sv_nolocking
5603               DEPRECATED!  It is planned to remove this function from a
5604               future release of Perl.  Do not use it for new code; remove it
5605               from existing code.
5606
5607               Dummy routine which "locks" an SV when there is no locking
5608               module present.  Exists to avoid test for a "NULL" function
5609               pointer and because it could potentially warn under some level
5610               of strict-ness.
5611
5612               "Superseded" by "sv_nosharing()".
5613
5614                       void    sv_nolocking(SV *sv)
5615
5616       sv_nounlocking
5617               DEPRECATED!  It is planned to remove this function from a
5618               future release of Perl.  Do not use it for new code; remove it
5619               from existing code.
5620
5621               Dummy routine which "unlocks" an SV when there is no locking
5622               module present.  Exists to avoid test for a "NULL" function
5623               pointer and because it could potentially warn under some level
5624               of strict-ness.
5625
5626               "Superseded" by "sv_nosharing()".
5627
5628                       void    sv_nounlocking(SV *sv)
5629
5630       sv_nv   DEPRECATED!  It is planned to remove this function from a
5631               future release of Perl.  Do not use it for new code; remove it
5632               from existing code.
5633
5634               A private implementation of the "SvNVx" macro for compilers
5635               which can't cope with complex macro expressions.  Always use
5636               the macro instead.
5637
5638                       NV      sv_nv(SV* sv)
5639
5640       sv_pv   Use the "SvPV_nolen" macro instead
5641
5642                       char*   sv_pv(SV *sv)
5643
5644       sv_pvbyte
5645               Use "SvPVbyte_nolen" instead.
5646
5647                       char*   sv_pvbyte(SV *sv)
5648
5649       sv_pvbyten
5650               DEPRECATED!  It is planned to remove this function from a
5651               future release of Perl.  Do not use it for new code; remove it
5652               from existing code.
5653
5654               A private implementation of the "SvPVbyte" macro for compilers
5655               which can't cope with complex macro expressions.  Always use
5656               the macro instead.
5657
5658                       char*   sv_pvbyten(SV *sv, STRLEN *lp)
5659
5660       sv_pvn  DEPRECATED!  It is planned to remove this function from a
5661               future release of Perl.  Do not use it for new code; remove it
5662               from existing code.
5663
5664               A private implementation of the "SvPV" macro for compilers
5665               which can't cope with complex macro expressions.  Always use
5666               the macro instead.
5667
5668                       char*   sv_pvn(SV *sv, STRLEN *lp)
5669
5670       sv_pvutf8
5671               Use the "SvPVutf8_nolen" macro instead
5672
5673                       char*   sv_pvutf8(SV *sv)
5674
5675       sv_pvutf8n
5676               DEPRECATED!  It is planned to remove this function from a
5677               future release of Perl.  Do not use it for new code; remove it
5678               from existing code.
5679
5680               A private implementation of the "SvPVutf8" macro for compilers
5681               which can't cope with complex macro expressions.  Always use
5682               the macro instead.
5683
5684                       char*   sv_pvutf8n(SV *sv, STRLEN *lp)
5685
5686       sv_taint
5687               Taint an SV.  Use "SvTAINTED_on" instead.
5688
5689                       void    sv_taint(SV* sv)
5690
5691       sv_unref
5692               Unsets the RV status of the SV, and decrements the reference
5693               count of whatever was being referenced by the RV.  This can
5694               almost be thought of as a reversal of "newSVrv".  This is
5695               "sv_unref_flags" with the "flag" being zero.  See "SvROK_off".
5696
5697                       void    sv_unref(SV* sv)
5698
5699       sv_usepvn
5700               Tells an SV to use "ptr" to find its string value.  Implemented
5701               by calling "sv_usepvn_flags" with "flags" of 0, hence does not
5702               handle 'set' magic.  See "sv_usepvn_flags".
5703
5704                       void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
5705
5706       sv_usepvn_mg
5707               Like "sv_usepvn", but also handles 'set' magic.
5708
5709                       void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
5710
5711       sv_uv   DEPRECATED!  It is planned to remove this function from a
5712               future release of Perl.  Do not use it for new code; remove it
5713               from existing code.
5714
5715               A private implementation of the "SvUVx" macro for compilers
5716               which can't cope with complex macro expressions.  Always use
5717               the macro instead.
5718
5719                       UV      sv_uv(SV* sv)
5720
5721       unpack_str
5722               DEPRECATED!  It is planned to remove this function from a
5723               future release of Perl.  Do not use it for new code; remove it
5724               from existing code.
5725
5726               The engine implementing "unpack()" Perl function.  Note:
5727               parameters "strbeg", "new_s" and "ocnt" are not used.  This
5728               call should not be used, use "unpackstring" instead.
5729
5730                       SSize_t unpack_str(const char *pat, const char *patend,
5731                                          const char *s, const char *strbeg,
5732                                          const char *strend, char **new_s,
5733                                          I32 ocnt, U32 flags)
5734
5735       utf8_to_uvchr
5736               DEPRECATED!  It is planned to remove this function from a
5737               future release of Perl.  Do not use it for new code; remove it
5738               from existing code.
5739
5740               Returns the native code point of the first character in the
5741               string "s" which is assumed to be in UTF-8 encoding; "retlen"
5742               will be set to the length, in bytes, of that character.
5743
5744               Some, but not all, UTF-8 malformations are detected, and in
5745               fact, some malformed input could cause reading beyond the end
5746               of the input buffer, which is why this function is deprecated.
5747               Use "utf8_to_uvchr_buf" instead.
5748
5749               If "s" points to one of the detected malformations, and UTF8
5750               warnings are enabled, zero is returned and *retlen is set (if
5751               "retlen" isn't "NULL") to -1.  If those warnings are off, the
5752               computed value if well-defined (or the Unicode REPLACEMENT
5753               CHARACTER, if not) is silently returned, and *retlen is set (if
5754               "retlen" isn't NULL) so that ("s" + *retlen) is the next
5755               possible position in "s" that could begin a non-malformed
5756               character.  See "utf8n_to_uvchr" for details on when the
5757               REPLACEMENT CHARACTER is returned.
5758
5759                       UV      utf8_to_uvchr(const U8 *s, STRLEN *retlen)
5760

Optree construction

5762       newASSIGNOP
5763               Constructs, checks, and returns an assignment op.  "left" and
5764               "right" supply the parameters of the assignment; they are
5765               consumed by this function and become part of the constructed op
5766               tree.
5767
5768               If "optype" is "OP_ANDASSIGN", "OP_ORASSIGN", or
5769               "OP_DORASSIGN", then a suitable conditional optree is
5770               constructed.  If "optype" is the opcode of a binary operator,
5771               such as "OP_BIT_OR", then an op is constructed that performs
5772               the binary operation and assigns the result to the left
5773               argument.  Either way, if "optype" is non-zero then "flags" has
5774               no effect.
5775
5776               If "optype" is zero, then a plain scalar or list assignment is
5777               constructed.  Which type of assignment it is is automatically
5778               determined.  "flags" gives the eight bits of "op_flags", except
5779               that "OPf_KIDS" will be set automatically, and, shifted up
5780               eight bits, the eight bits of "op_private", except that the bit
5781               with value 1 or 2 is automatically set as required.
5782
5783                       OP*     newASSIGNOP(I32 flags, OP* left, I32 optype,
5784                                           OP* right)
5785
5786       newBINOP
5787               Constructs, checks, and returns an op of any binary type.
5788               "type" is the opcode.  "flags" gives the eight bits of
5789               "op_flags", except that "OPf_KIDS" will be set automatically,
5790               and, shifted up eight bits, the eight bits of "op_private",
5791               except that the bit with value 1 or 2 is automatically set as
5792               required.  "first" and "last" supply up to two ops to be the
5793               direct children of the binary op; they are consumed by this
5794               function and become part of the constructed op tree.
5795
5796                       OP*     newBINOP(I32 type, I32 flags, OP* first,
5797                                        OP* last)
5798
5799       newCONDOP
5800               Constructs, checks, and returns a conditional-expression
5801               ("cond_expr") op.  "flags" gives the eight bits of "op_flags",
5802               except that "OPf_KIDS" will be set automatically, and, shifted
5803               up eight bits, the eight bits of "op_private", except that the
5804               bit with value 1 is automatically set.  "first" supplies the
5805               expression selecting between the two branches, and "trueop" and
5806               "falseop" supply the branches; they are consumed by this
5807               function and become part of the constructed op tree.
5808
5809                       OP*     newCONDOP(I32 flags, OP* first, OP* trueop,
5810                                         OP* falseop)
5811
5812       newDEFSVOP
5813               Constructs and returns an op to access $_.
5814
5815                       OP*     newDEFSVOP()
5816
5817       newFOROP
5818               Constructs, checks, and returns an op tree expressing a
5819               "foreach" loop (iteration through a list of values).  This is a
5820               heavyweight loop, with structure that allows exiting the loop
5821               by "last" and suchlike.
5822
5823               "sv" optionally supplies the variable that will be aliased to
5824               each item in turn; if null, it defaults to $_.  "expr" supplies
5825               the list of values to iterate over.  "block" supplies the main
5826               body of the loop, and "cont" optionally supplies a "continue"
5827               block that operates as a second half of the body.  All of these
5828               optree inputs are consumed by this function and become part of
5829               the constructed op tree.
5830
5831               "flags" gives the eight bits of "op_flags" for the "leaveloop"
5832               op and, shifted up eight bits, the eight bits of "op_private"
5833               for the "leaveloop" op, except that (in both cases) some bits
5834               will be set automatically.
5835
5836                       OP*     newFOROP(I32 flags, OP* sv, OP* expr, OP* block,
5837                                        OP* cont)
5838
5839       newGIVENOP
5840               Constructs, checks, and returns an op tree expressing a "given"
5841               block.  "cond" supplies the expression to whose value $_ will
5842               be locally aliased, and "block" supplies the body of the
5843               "given" construct; they are consumed by this function and
5844               become part of the constructed op tree.  "defsv_off" must be
5845               zero (it used to identity the pad slot of lexical $_).
5846
5847                       OP*     newGIVENOP(OP* cond, OP* block,
5848                                          PADOFFSET defsv_off)
5849
5850       newGVOP Constructs, checks, and returns an op of any type that involves
5851               an embedded reference to a GV.  "type" is the opcode.  "flags"
5852               gives the eight bits of "op_flags".  "gv" identifies the GV
5853               that the op should reference; calling this function does not
5854               transfer ownership of any reference to it.
5855
5856                       OP*     newGVOP(I32 type, I32 flags, GV* gv)
5857
5858       newLISTOP
5859               Constructs, checks, and returns an op of any list type.  "type"
5860               is the opcode.  "flags" gives the eight bits of "op_flags",
5861               except that "OPf_KIDS" will be set automatically if required.
5862               "first" and "last" supply up to two ops to be direct children
5863               of the list op; they are consumed by this function and become
5864               part of the constructed op tree.
5865
5866               For most list operators, the check function expects all the kid
5867               ops to be present already, so calling "newLISTOP(OP_JOIN, ...)"
5868               (e.g.) is not appropriate.  What you want to do in that case is
5869               create an op of type "OP_LIST", append more children to it, and
5870               then call "op_convert_list".  See "op_convert_list" for more
5871               information.
5872
5873                       OP*     newLISTOP(I32 type, I32 flags, OP* first,
5874                                         OP* last)
5875
5876       newLOGOP
5877               Constructs, checks, and returns a logical (flow control) op.
5878               "type" is the opcode.  "flags" gives the eight bits of
5879               "op_flags", except that "OPf_KIDS" will be set automatically,
5880               and, shifted up eight bits, the eight bits of "op_private",
5881               except that the bit with value 1 is automatically set.  "first"
5882               supplies the expression controlling the flow, and "other"
5883               supplies the side (alternate) chain of ops; they are consumed
5884               by this function and become part of the constructed op tree.
5885
5886                       OP*     newLOGOP(I32 optype, I32 flags, OP *first,
5887                                        OP *other)
5888
5889       newLOOPEX
5890               Constructs, checks, and returns a loop-exiting op (such as
5891               "goto" or "last").  "type" is the opcode.  "label" supplies the
5892               parameter determining the target of the op; it is consumed by
5893               this function and becomes part of the constructed op tree.
5894
5895                       OP*     newLOOPEX(I32 type, OP* label)
5896
5897       newLOOPOP
5898               Constructs, checks, and returns an op tree expressing a loop.
5899               This is only a loop in the control flow through the op tree; it
5900               does not have the heavyweight loop structure that allows
5901               exiting the loop by "last" and suchlike.  "flags" gives the
5902               eight bits of "op_flags" for the top-level op, except that some
5903               bits will be set automatically as required.  "expr" supplies
5904               the expression controlling loop iteration, and "block" supplies
5905               the body of the loop; they are consumed by this function and
5906               become part of the constructed op tree.  "debuggable" is
5907               currently unused and should always be 1.
5908
5909                       OP*     newLOOPOP(I32 flags, I32 debuggable, OP* expr,
5910                                         OP* block)
5911
5912       newMETHOP
5913               Constructs, checks, and returns an op of method type with a
5914               method name evaluated at runtime.  "type" is the opcode.
5915               "flags" gives the eight bits of "op_flags", except that
5916               "OPf_KIDS" will be set automatically, and, shifted up eight
5917               bits, the eight bits of "op_private", except that the bit with
5918               value 1 is automatically set.  "dynamic_meth" supplies an op
5919               which evaluates method name; it is consumed by this function
5920               and become part of the constructed op tree.  Supported optypes:
5921               "OP_METHOD".
5922
5923                       OP*     newMETHOP(I32 type, I32 flags, OP* dynamic_meth)
5924
5925       newMETHOP_named
5926               Constructs, checks, and returns an op of method type with a
5927               constant method name.  "type" is the opcode.  "flags" gives the
5928               eight bits of "op_flags", and, shifted up eight bits, the eight
5929               bits of "op_private".  "const_meth" supplies a constant method
5930               name; it must be a shared COW string.  Supported optypes:
5931               "OP_METHOD_NAMED".
5932
5933                       OP*     newMETHOP_named(I32 type, I32 flags,
5934                                               SV* const_meth)
5935
5936       newNULLLIST
5937               Constructs, checks, and returns a new "stub" op, which
5938               represents an empty list expression.
5939
5940                       OP*     newNULLLIST()
5941
5942       newOP   Constructs, checks, and returns an op of any base type (any
5943               type that has no extra fields).  "type" is the opcode.  "flags"
5944               gives the eight bits of "op_flags", and, shifted up eight bits,
5945               the eight bits of "op_private".
5946
5947                       OP*     newOP(I32 optype, I32 flags)
5948
5949       newPADOP
5950               Constructs, checks, and returns an op of any type that involves
5951               a reference to a pad element.  "type" is the opcode.  "flags"
5952               gives the eight bits of "op_flags".  A pad slot is
5953               automatically allocated, and is populated with "sv"; this
5954               function takes ownership of one reference to it.
5955
5956               This function only exists if Perl has been compiled to use
5957               ithreads.
5958
5959                       OP*     newPADOP(I32 type, I32 flags, SV* sv)
5960
5961       newPMOP Constructs, checks, and returns an op of any pattern matching
5962               type.  "type" is the opcode.  "flags" gives the eight bits of
5963               "op_flags" and, shifted up eight bits, the eight bits of
5964               "op_private".
5965
5966                       OP*     newPMOP(I32 type, I32 flags)
5967
5968       newPVOP Constructs, checks, and returns an op of any type that involves
5969               an embedded C-level pointer (PV).  "type" is the opcode.
5970               "flags" gives the eight bits of "op_flags".  "pv" supplies the
5971               C-level pointer.  Depending on the op type, the memory
5972               referenced by "pv" may be freed when the op is destroyed.  If
5973               the op is of a freeing type, "pv" must have been allocated
5974               using "PerlMemShared_malloc".
5975
5976                       OP*     newPVOP(I32 type, I32 flags, char* pv)
5977
5978       newRANGE
5979               Constructs and returns a "range" op, with subordinate "flip"
5980               and "flop" ops.  "flags" gives the eight bits of "op_flags" for
5981               the "flip" op and, shifted up eight bits, the eight bits of
5982               "op_private" for both the "flip" and "range" ops, except that
5983               the bit with value 1 is automatically set.  "left" and "right"
5984               supply the expressions controlling the endpoints of the range;
5985               they are consumed by this function and become part of the
5986               constructed op tree.
5987
5988                       OP*     newRANGE(I32 flags, OP* left, OP* right)
5989
5990       newSLICEOP
5991               Constructs, checks, and returns an "lslice" (list slice) op.
5992               "flags" gives the eight bits of "op_flags", except that
5993               "OPf_KIDS" will be set automatically, and, shifted up eight
5994               bits, the eight bits of "op_private", except that the bit with
5995               value 1 or 2 is automatically set as required.  "listval" and
5996               "subscript" supply the parameters of the slice; they are
5997               consumed by this function and become part of the constructed op
5998               tree.
5999
6000                       OP*     newSLICEOP(I32 flags, OP* subscript, OP* listop)
6001
6002       newSTATEOP
6003               Constructs a state op (COP).  The state op is normally a
6004               "nextstate" op, but will be a "dbstate" op if debugging is
6005               enabled for currently-compiled code.  The state op is populated
6006               from "PL_curcop" (or "PL_compiling").  If "label" is non-null,
6007               it supplies the name of a label to attach to the state op; this
6008               function takes ownership of the memory pointed at by "label",
6009               and will free it.  "flags" gives the eight bits of "op_flags"
6010               for the state op.
6011
6012               If "o" is null, the state op is returned.  Otherwise the state
6013               op is combined with "o" into a "lineseq" list op, which is
6014               returned.  "o" is consumed by this function and becomes part of
6015               the returned op tree.
6016
6017                       OP*     newSTATEOP(I32 flags, char* label, OP* o)
6018
6019       newSVOP Constructs, checks, and returns an op of any type that involves
6020               an embedded SV.  "type" is the opcode.  "flags" gives the eight
6021               bits of "op_flags".  "sv" gives the SV to embed in the op; this
6022               function takes ownership of one reference to it.
6023
6024                       OP*     newSVOP(I32 type, I32 flags, SV* sv)
6025
6026       newUNOP Constructs, checks, and returns an op of any unary type.
6027               "type" is the opcode.  "flags" gives the eight bits of
6028               "op_flags", except that "OPf_KIDS" will be set automatically if
6029               required, and, shifted up eight bits, the eight bits of
6030               "op_private", except that the bit with value 1 is automatically
6031               set.  "first" supplies an optional op to be the direct child of
6032               the unary op; it is consumed by this function and become part
6033               of the constructed op tree.
6034
6035                       OP*     newUNOP(I32 type, I32 flags, OP* first)
6036
6037       newUNOP_AUX
6038               Similar to "newUNOP", but creates an "UNOP_AUX" struct instead,
6039               with "op_aux" initialised to "aux"
6040
6041                       OP*     newUNOP_AUX(I32 type, I32 flags, OP* first,
6042                                           UNOP_AUX_item *aux)
6043
6044       newWHENOP
6045               Constructs, checks, and returns an op tree expressing a "when"
6046               block.  "cond" supplies the test expression, and "block"
6047               supplies the block that will be executed if the test evaluates
6048               to true; they are consumed by this function and become part of
6049               the constructed op tree.  "cond" will be interpreted
6050               DWIMically, often as a comparison against $_, and may be null
6051               to generate a "default" block.
6052
6053                       OP*     newWHENOP(OP* cond, OP* block)
6054
6055       newWHILEOP
6056               Constructs, checks, and returns an op tree expressing a "while"
6057               loop.  This is a heavyweight loop, with structure that allows
6058               exiting the loop by "last" and suchlike.
6059
6060               "loop" is an optional preconstructed "enterloop" op to use in
6061               the loop; if it is null then a suitable op will be constructed
6062               automatically.  "expr" supplies the loop's controlling
6063               expression.  "block" supplies the main body of the loop, and
6064               "cont" optionally supplies a "continue" block that operates as
6065               a second half of the body.  All of these optree inputs are
6066               consumed by this function and become part of the constructed op
6067               tree.
6068
6069               "flags" gives the eight bits of "op_flags" for the "leaveloop"
6070               op and, shifted up eight bits, the eight bits of "op_private"
6071               for the "leaveloop" op, except that (in both cases) some bits
6072               will be set automatically.  "debuggable" is currently unused
6073               and should always be 1.  "has_my" can be supplied as true to
6074               force the loop body to be enclosed in its own scope.
6075
6076                       OP*     newWHILEOP(I32 flags, I32 debuggable,
6077                                          LOOP* loop, OP* expr, OP* block,
6078                                          OP* cont, I32 has_my)
6079

Optree Manipulation Functions

6081       alloccopstash
6082               NOTE: this function is experimental and may change or be
6083               removed without notice.
6084
6085               Available only under threaded builds, this function allocates
6086               an entry in "PL_stashpad" for the stash passed to it.
6087
6088                       PADOFFSET alloccopstash(HV *hv)
6089
6090       block_end
6091               Handles compile-time scope exit.  "floor" is the savestack
6092               index returned by "block_start", and "seq" is the body of the
6093               block.  Returns the block, possibly modified.
6094
6095                       OP*     block_end(I32 floor, OP* seq)
6096
6097       block_start
6098               Handles compile-time scope entry.  Arranges for hints to be
6099               restored on block exit and also handles pad sequence numbers to
6100               make lexical variables scope right.  Returns a savestack index
6101               for use with "block_end".
6102
6103                       int     block_start(int full)
6104
6105       ck_entersub_args_list
6106               Performs the default fixup of the arguments part of an
6107               "entersub" op tree.  This consists of applying list context to
6108               each of the argument ops.  This is the standard treatment used
6109               on a call marked with "&", or a method call, or a call through
6110               a subroutine reference, or any other call where the callee
6111               can't be identified at compile time, or a call where the callee
6112               has no prototype.
6113
6114                       OP*     ck_entersub_args_list(OP *entersubop)
6115
6116       ck_entersub_args_proto
6117               Performs the fixup of the arguments part of an "entersub" op
6118               tree based on a subroutine prototype.  This makes various
6119               modifications to the argument ops, from applying context up to
6120               inserting "refgen" ops, and checking the number and syntactic
6121               types of arguments, as directed by the prototype.  This is the
6122               standard treatment used on a subroutine call, not marked with
6123               "&", where the callee can be identified at compile time and has
6124               a prototype.
6125
6126               "protosv" supplies the subroutine prototype to be applied to
6127               the call.  It may be a normal defined scalar, of which the
6128               string value will be used.  Alternatively, for convenience, it
6129               may be a subroutine object (a "CV*" that has been cast to
6130               "SV*") which has a prototype.  The prototype supplied, in
6131               whichever form, does not need to match the actual callee
6132               referenced by the op tree.
6133
6134               If the argument ops disagree with the prototype, for example by
6135               having an unacceptable number of arguments, a valid op tree is
6136               returned anyway.  The error is reflected in the parser state,
6137               normally resulting in a single exception at the top level of
6138               parsing which covers all the compilation errors that occurred.
6139               In the error message, the callee is referred to by the name
6140               defined by the "namegv" parameter.
6141
6142                       OP*     ck_entersub_args_proto(OP *entersubop,
6143                                                      GV *namegv, SV *protosv)
6144
6145       ck_entersub_args_proto_or_list
6146               Performs the fixup of the arguments part of an "entersub" op
6147               tree either based on a subroutine prototype or using default
6148               list-context processing.  This is the standard treatment used
6149               on a subroutine call, not marked with "&", where the callee can
6150               be identified at compile time.
6151
6152               "protosv" supplies the subroutine prototype to be applied to
6153               the call, or indicates that there is no prototype.  It may be a
6154               normal scalar, in which case if it is defined then the string
6155               value will be used as a prototype, and if it is undefined then
6156               there is no prototype.  Alternatively, for convenience, it may
6157               be a subroutine object (a "CV*" that has been cast to "SV*"),
6158               of which the prototype will be used if it has one.  The
6159               prototype (or lack thereof) supplied, in whichever form, does
6160               not need to match the actual callee referenced by the op tree.
6161
6162               If the argument ops disagree with the prototype, for example by
6163               having an unacceptable number of arguments, a valid op tree is
6164               returned anyway.  The error is reflected in the parser state,
6165               normally resulting in a single exception at the top level of
6166               parsing which covers all the compilation errors that occurred.
6167               In the error message, the callee is referred to by the name
6168               defined by the "namegv" parameter.
6169
6170                       OP*     ck_entersub_args_proto_or_list(OP *entersubop,
6171                                                              GV *namegv,
6172                                                              SV *protosv)
6173
6174       cv_const_sv
6175               If "cv" is a constant sub eligible for inlining, returns the
6176               constant value returned by the sub.  Otherwise, returns "NULL".
6177
6178               Constant subs can be created with "newCONSTSUB" or as described
6179               in "Constant Functions" in perlsub.
6180
6181                       SV*     cv_const_sv(const CV *const cv)
6182
6183       cv_get_call_checker
6184               The original form of "cv_get_call_checker_flags", which does
6185               not return checker flags.  When using a checker function
6186               returned by this function, it is only safe to call it with a
6187               genuine GV as its "namegv" argument.
6188
6189                       void    cv_get_call_checker(CV *cv,
6190                                                   Perl_call_checker *ckfun_p,
6191                                                   SV **ckobj_p)
6192
6193       cv_get_call_checker_flags
6194               Retrieves the function that will be used to fix up a call to
6195               "cv".  Specifically, the function is applied to an "entersub"
6196               op tree for a subroutine call, not marked with "&", where the
6197               callee can be identified at compile time as "cv".
6198
6199               The C-level function pointer is returned in *ckfun_p, an SV
6200               argument for it is returned in *ckobj_p, and control flags are
6201               returned in *ckflags_p.  The function is intended to be called
6202               in this manner:
6203
6204                entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
6205
6206               In this call, "entersubop" is a pointer to the "entersub" op,
6207               which may be replaced by the check function, and "namegv"
6208               supplies the name that should be used by the check function to
6209               refer to the callee of the "entersub" op if it needs to emit
6210               any diagnostics.  It is permitted to apply the check function
6211               in non-standard situations, such as to a call to a different
6212               subroutine or to a method call.
6213
6214               "namegv" may not actually be a GV.  If the
6215               "CALL_CHECKER_REQUIRE_GV" bit is clear in *ckflags_p, it is
6216               permitted to pass a CV or other SV instead, anything that can
6217               be used as the first argument to "cv_name".  If the
6218               "CALL_CHECKER_REQUIRE_GV" bit is set in *ckflags_p then the
6219               check function requires "namegv" to be a genuine GV.
6220
6221               By default, the check function is
6222               Perl_ck_entersub_args_proto_or_list, the SV parameter is "cv"
6223               itself, and the "CALL_CHECKER_REQUIRE_GV" flag is clear.  This
6224               implements standard prototype processing.  It can be changed,
6225               for a particular subroutine, by "cv_set_call_checker_flags".
6226
6227               If the "CALL_CHECKER_REQUIRE_GV" bit is set in "gflags" then it
6228               indicates that the caller only knows about the genuine GV
6229               version of "namegv", and accordingly the corresponding bit will
6230               always be set in *ckflags_p, regardless of the check function's
6231               recorded requirements.  If the "CALL_CHECKER_REQUIRE_GV" bit is
6232               clear in "gflags" then it indicates the caller knows about the
6233               possibility of passing something other than a GV as "namegv",
6234               and accordingly the corresponding bit may be either set or
6235               clear in *ckflags_p, indicating the check function's recorded
6236               requirements.
6237
6238               "gflags" is a bitset passed into "cv_get_call_checker_flags",
6239               in which only the "CALL_CHECKER_REQUIRE_GV" bit currently has a
6240               defined meaning (for which see above).  All other bits should
6241               be clear.
6242
6243                       void    cv_get_call_checker_flags(
6244                                   CV *cv, U32 gflags,
6245                                   Perl_call_checker *ckfun_p, SV **ckobj_p,
6246                                   U32 *ckflags_p
6247                               )
6248
6249       cv_set_call_checker
6250               The original form of "cv_set_call_checker_flags", which passes
6251               it the "CALL_CHECKER_REQUIRE_GV" flag for backward-
6252               compatibility.  The effect of that flag setting is that the
6253               check function is guaranteed to get a genuine GV as its
6254               "namegv" argument.
6255
6256                       void    cv_set_call_checker(CV *cv,
6257                                                   Perl_call_checker ckfun,
6258                                                   SV *ckobj)
6259
6260       cv_set_call_checker_flags
6261               Sets the function that will be used to fix up a call to "cv".
6262               Specifically, the function is applied to an "entersub" op tree
6263               for a subroutine call, not marked with "&", where the callee
6264               can be identified at compile time as "cv".
6265
6266               The C-level function pointer is supplied in "ckfun", an SV
6267               argument for it is supplied in "ckobj", and control flags are
6268               supplied in "ckflags".  The function should be defined like
6269               this:
6270
6271                   STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
6272
6273               It is intended to be called in this manner:
6274
6275                   entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
6276
6277               In this call, "entersubop" is a pointer to the "entersub" op,
6278               which may be replaced by the check function, and "namegv"
6279               supplies the name that should be used by the check function to
6280               refer to the callee of the "entersub" op if it needs to emit
6281               any diagnostics.  It is permitted to apply the check function
6282               in non-standard situations, such as to a call to a different
6283               subroutine or to a method call.
6284
6285               "namegv" may not actually be a GV.  For efficiency, perl may
6286               pass a CV or other SV instead.  Whatever is passed can be used
6287               as the first argument to "cv_name".  You can force perl to pass
6288               a GV by including "CALL_CHECKER_REQUIRE_GV" in the "ckflags".
6289
6290               "ckflags" is a bitset, in which only the
6291               "CALL_CHECKER_REQUIRE_GV" bit currently has a defined meaning
6292               (for which see above).  All other bits should be clear.
6293
6294               The current setting for a particular CV can be retrieved by
6295               "cv_get_call_checker_flags".
6296
6297                       void    cv_set_call_checker_flags(
6298                                   CV *cv, Perl_call_checker ckfun, SV *ckobj,
6299                                   U32 ckflags
6300                               )
6301
6302       LINKLIST
6303               Given the root of an optree, link the tree in execution order
6304               using the "op_next" pointers and return the first op executed.
6305               If this has already been done, it will not be redone, and
6306               "o->op_next" will be returned.  If "o->op_next" is not already
6307               set, "o" should be at least an "UNOP".
6308
6309                       OP*     LINKLIST(OP *o)
6310
6311       newCONSTSUB
6312               Behaves like "newCONSTSUB_flags", except that "name" is nul-
6313               terminated rather than of counted length, and no flags are set.
6314               (This means that "name" is always interpreted as Latin-1.)
6315
6316                       CV*     newCONSTSUB(HV* stash, const char* name, SV* sv)
6317
6318       newCONSTSUB_flags
6319               Construct a constant subroutine, also performing some
6320               surrounding jobs.  A scalar constant-valued subroutine is
6321               eligible for inlining at compile-time, and in Perl code can be
6322               created by "sub FOO () { 123 }".  Other kinds of constant
6323               subroutine have other treatment.
6324
6325               The subroutine will have an empty prototype and will ignore any
6326               arguments when called.  Its constant behaviour is determined by
6327               "sv".  If "sv" is null, the subroutine will yield an empty
6328               list.  If "sv" points to a scalar, the subroutine will always
6329               yield that scalar.  If "sv" points to an array, the subroutine
6330               will always yield a list of the elements of that array in list
6331               context, or the number of elements in the array in scalar
6332               context.  This function takes ownership of one counted
6333               reference to the scalar or array, and will arrange for the
6334               object to live as long as the subroutine does.  If "sv" points
6335               to a scalar then the inlining assumes that the value of the
6336               scalar will never change, so the caller must ensure that the
6337               scalar is not subsequently written to.  If "sv" points to an
6338               array then no such assumption is made, so it is ostensibly safe
6339               to mutate the array or its elements, but whether this is really
6340               supported has not been determined.
6341
6342               The subroutine will have "CvFILE" set according to "PL_curcop".
6343               Other aspects of the subroutine will be left in their default
6344               state.  The caller is free to mutate the subroutine beyond its
6345               initial state after this function has returned.
6346
6347               If "name" is null then the subroutine will be anonymous, with
6348               its "CvGV" referring to an "__ANON__" glob.  If "name" is non-
6349               null then the subroutine will be named accordingly, referenced
6350               by the appropriate glob.  "name" is a string of length "len"
6351               bytes giving a sigilless symbol name, in UTF-8 if "flags" has
6352               the "SVf_UTF8" bit set and in Latin-1 otherwise.  The name may
6353               be either qualified or unqualified.  If the name is unqualified
6354               then it defaults to being in the stash specified by "stash" if
6355               that is non-null, or to "PL_curstash" if "stash" is null.  The
6356               symbol is always added to the stash if necessary, with
6357               "GV_ADDMULTI" semantics.
6358
6359               "flags" should not have bits set other than "SVf_UTF8".
6360
6361               If there is already a subroutine of the specified name, then
6362               the new sub will replace the existing one in the glob.  A
6363               warning may be generated about the redefinition.
6364
6365               If the subroutine has one of a few special names, such as
6366               "BEGIN" or "END", then it will be claimed by the appropriate
6367               queue for automatic running of phase-related subroutines.  In
6368               this case the relevant glob will be left not containing any
6369               subroutine, even if it did contain one before.  Execution of
6370               the subroutine will likely be a no-op, unless "sv" was a tied
6371               array or the caller modified the subroutine in some interesting
6372               way before it was executed.  In the case of "BEGIN", the
6373               treatment is buggy: the sub will be executed when only half
6374               built, and may be deleted prematurely, possibly causing a
6375               crash.
6376
6377               The function returns a pointer to the constructed subroutine.
6378               If the sub is anonymous then ownership of one counted reference
6379               to the subroutine is transferred to the caller.  If the sub is
6380               named then the caller does not get ownership of a reference.
6381               In most such cases, where the sub has a non-phase name, the sub
6382               will be alive at the point it is returned by virtue of being
6383               contained in the glob that names it.  A phase-named subroutine
6384               will usually be alive by virtue of the reference owned by the
6385               phase's automatic run queue.  A "BEGIN" subroutine may have
6386               been destroyed already by the time this function returns, but
6387               currently bugs occur in that case before the caller gets
6388               control.  It is the caller's responsibility to ensure that it
6389               knows which of these situations applies.
6390
6391                       CV*     newCONSTSUB_flags(HV* stash, const char* name,
6392                                                 STRLEN len, U32 flags, SV* sv)
6393
6394       newXS   Used by "xsubpp" to hook up XSUBs as Perl subs.  "filename"
6395               needs to be static storage, as it is used directly as CvFILE(),
6396               without a copy being made.
6397
6398       op_append_elem
6399               Append an item to the list of ops contained directly within a
6400               list-type op, returning the lengthened list.  "first" is the
6401               list-type op, and "last" is the op to append to the list.
6402               "optype" specifies the intended opcode for the list.  If
6403               "first" is not already a list of the right type, it will be
6404               upgraded into one.  If either "first" or "last" is null, the
6405               other is returned unchanged.
6406
6407                       OP*     op_append_elem(I32 optype, OP* first, OP* last)
6408
6409       op_append_list
6410               Concatenate the lists of ops contained directly within two
6411               list-type ops, returning the combined list.  "first" and "last"
6412               are the list-type ops to concatenate.  "optype" specifies the
6413               intended opcode for the list.  If either "first" or "last" is
6414               not already a list of the right type, it will be upgraded into
6415               one.  If either "first" or "last" is null, the other is
6416               returned unchanged.
6417
6418                       OP*     op_append_list(I32 optype, OP* first, OP* last)
6419
6420       OP_CLASS
6421               Return the class of the provided OP: that is, which of the *OP
6422               structures it uses.  For core ops this currently gets the
6423               information out of "PL_opargs", which does not always
6424               accurately reflect the type used; in v5.26 onwards, see also
6425               the function "op_class" which can do a better job of
6426               determining the used type.
6427
6428               For custom ops the type is returned from the registration, and
6429               it is up to the registree to ensure it is accurate.  The value
6430               returned will be one of the "OA_"* constants from op.h.
6431
6432                       U32     OP_CLASS(OP *o)
6433
6434       op_contextualize
6435               Applies a syntactic context to an op tree representing an
6436               expression.  "o" is the op tree, and "context" must be
6437               "G_SCALAR", "G_ARRAY", or "G_VOID" to specify the context to
6438               apply.  The modified op tree is returned.
6439
6440                       OP*     op_contextualize(OP* o, I32 context)
6441
6442       op_convert_list
6443               Converts "o" into a list op if it is not one already, and then
6444               converts it into the specified "type", calling its check
6445               function, allocating a target if it needs one, and folding
6446               constants.
6447
6448               A list-type op is usually constructed one kid at a time via
6449               "newLISTOP", "op_prepend_elem" and "op_append_elem".  Then
6450               finally it is passed to "op_convert_list" to make it the right
6451               type.
6452
6453                       OP*     op_convert_list(I32 optype, I32 flags, OP* o)
6454
6455       OP_DESC Return a short description of the provided OP.
6456
6457                       const char * OP_DESC(OP *o)
6458
6459       op_free Free an op and its children. Only use this when an op is no
6460               longer linked to from any optree.
6461
6462                       void    op_free(OP* arg)
6463
6464       OpHAS_SIBLING
6465               Returns true if "o" has a sibling
6466
6467                       bool    OpHAS_SIBLING(OP *o)
6468
6469       OpLASTSIB_set
6470               Marks "o" as having no further siblings and marks o as having
6471               the specified parent. See also "OpMORESIB_set" and
6472               "OpMAYBESIB_set". For a higher-level interface, see
6473               "op_sibling_splice".
6474
6475                       void    OpLASTSIB_set(OP *o, OP *parent)
6476
6477       op_linklist
6478               This function is the implementation of the "LINKLIST" macro.
6479               It should not be called directly.
6480
6481                       OP*     op_linklist(OP *o)
6482
6483       op_lvalue
6484               NOTE: this function is experimental and may change or be
6485               removed without notice.
6486
6487               Propagate lvalue ("modifiable") context to an op and its
6488               children.  "type" represents the context type, roughly based on
6489               the type of op that would do the modifying, although "local()"
6490               is represented by "OP_NULL", because it has no op type of its
6491               own (it is signalled by a flag on the lvalue op).
6492
6493               This function detects things that can't be modified, such as
6494               "$x+1", and generates errors for them.  For example, "$x+1 = 2"
6495               would cause it to be called with an op of type "OP_ADD" and a
6496               "type" argument of "OP_SASSIGN".
6497
6498               It also flags things that need to behave specially in an lvalue
6499               context, such as "$$x = 5" which might have to vivify a
6500               reference in $x.
6501
6502                       OP*     op_lvalue(OP* o, I32 type)
6503
6504       OpMAYBESIB_set
6505               Conditionally does "OpMORESIB_set" or "OpLASTSIB_set" depending
6506               on whether "sib" is non-null. For a higher-level interface, see
6507               "op_sibling_splice".
6508
6509                       void    OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
6510
6511       OpMORESIB_set
6512               Sets the sibling of "o" to the non-zero value "sib". See also
6513               "OpLASTSIB_set" and "OpMAYBESIB_set". For a higher-level
6514               interface, see "op_sibling_splice".
6515
6516                       void    OpMORESIB_set(OP *o, OP *sib)
6517
6518       OP_NAME Return the name of the provided OP.  For core ops this looks up
6519               the name from the op_type; for custom ops from the op_ppaddr.
6520
6521                       const char * OP_NAME(OP *o)
6522
6523       op_null Neutralizes an op when it is no longer needed, but is still
6524               linked to from other ops.
6525
6526                       void    op_null(OP* o)
6527
6528       op_parent
6529               Returns the parent OP of "o", if it has a parent. Returns
6530               "NULL" otherwise.
6531
6532                       OP*     op_parent(OP *o)
6533
6534       op_prepend_elem
6535               Prepend an item to the list of ops contained directly within a
6536               list-type op, returning the lengthened list.  "first" is the op
6537               to prepend to the list, and "last" is the list-type op.
6538               "optype" specifies the intended opcode for the list.  If "last"
6539               is not already a list of the right type, it will be upgraded
6540               into one.  If either "first" or "last" is null, the other is
6541               returned unchanged.
6542
6543                       OP*     op_prepend_elem(I32 optype, OP* first, OP* last)
6544
6545       op_scope
6546               NOTE: this function is experimental and may change or be
6547               removed without notice.
6548
6549               Wraps up an op tree with some additional ops so that at runtime
6550               a dynamic scope will be created.  The original ops run in the
6551               new dynamic scope, and then, provided that they exit normally,
6552               the scope will be unwound.  The additional ops used to create
6553               and unwind the dynamic scope will normally be an
6554               "enter"/"leave" pair, but a "scope" op may be used instead if
6555               the ops are simple enough to not need the full dynamic scope
6556               structure.
6557
6558                       OP*     op_scope(OP* o)
6559
6560       OpSIBLING
6561               Returns the sibling of "o", or "NULL" if there is no sibling
6562
6563                       OP*     OpSIBLING(OP *o)
6564
6565       op_sibling_splice
6566               A general function for editing the structure of an existing
6567               chain of op_sibling nodes.  By analogy with the perl-level
6568               "splice()" function, allows you to delete zero or more
6569               sequential nodes, replacing them with zero or more different
6570               nodes.  Performs the necessary op_first/op_last housekeeping on
6571               the parent node and op_sibling manipulation on the children.
6572               The last deleted node will be marked as the last node by
6573               updating the op_sibling/op_sibparent or op_moresib field as
6574               appropriate.
6575
6576               Note that op_next is not manipulated, and nodes are not freed;
6577               that is the responsibility of the caller.  It also won't create
6578               a new list op for an empty list etc; use higher-level functions
6579               like op_append_elem() for that.
6580
6581               "parent" is the parent node of the sibling chain. It may passed
6582               as "NULL" if the splicing doesn't affect the first or last op
6583               in the chain.
6584
6585               "start" is the node preceding the first node to be spliced.
6586               Node(s) following it will be deleted, and ops will be inserted
6587               after it.  If it is "NULL", the first node onwards is deleted,
6588               and nodes are inserted at the beginning.
6589
6590               "del_count" is the number of nodes to delete.  If zero, no
6591               nodes are deleted.  If -1 or greater than or equal to the
6592               number of remaining kids, all remaining kids are deleted.
6593
6594               "insert" is the first of a chain of nodes to be inserted in
6595               place of the nodes.  If "NULL", no nodes are inserted.
6596
6597               The head of the chain of deleted ops is returned, or "NULL" if
6598               no ops were deleted.
6599
6600               For example:
6601
6602                   action                    before      after         returns
6603                   ------                    -----       -----         -------
6604
6605                                             P           P
6606                   splice(P, A, 2, X-Y-Z)    |           |             B-C
6607                                             A-B-C-D     A-X-Y-Z-D
6608
6609                                             P           P
6610                   splice(P, NULL, 1, X-Y)   |           |             A
6611                                             A-B-C-D     X-Y-B-C-D
6612
6613                                             P           P
6614                   splice(P, NULL, 3, NULL)  |           |             A-B-C
6615                                             A-B-C-D     D
6616
6617                                             P           P
6618                   splice(P, B, 0, X-Y)      |           |             NULL
6619                                             A-B-C-D     A-B-X-Y-C-D
6620
6621               For lower-level direct manipulation of "op_sibparent" and
6622               "op_moresib", see "OpMORESIB_set", "OpLASTSIB_set",
6623               "OpMAYBESIB_set".
6624
6625                       OP*     op_sibling_splice(OP *parent, OP *start,
6626                                                 int del_count, OP* insert)
6627
6628       OP_TYPE_IS
6629               Returns true if the given OP is not a "NULL" pointer and if it
6630               is of the given type.
6631
6632               The negation of this macro, "OP_TYPE_ISNT" is also available as
6633               well as "OP_TYPE_IS_NN" and "OP_TYPE_ISNT_NN" which elide the
6634               NULL pointer check.
6635
6636                       bool    OP_TYPE_IS(OP *o, Optype type)
6637
6638       OP_TYPE_IS_OR_WAS
6639               Returns true if the given OP is not a NULL pointer and if it is
6640               of the given type or used to be before being replaced by an OP
6641               of type OP_NULL.
6642
6643               The negation of this macro, "OP_TYPE_ISNT_AND_WASNT" is also
6644               available as well as "OP_TYPE_IS_OR_WAS_NN" and
6645               "OP_TYPE_ISNT_AND_WASNT_NN" which elide the "NULL" pointer
6646               check.
6647
6648                       bool    OP_TYPE_IS_OR_WAS(OP *o, Optype type)
6649
6650       rv2cv_op_cv
6651               Examines an op, which is expected to identify a subroutine at
6652               runtime, and attempts to determine at compile time which
6653               subroutine it identifies.  This is normally used during Perl
6654               compilation to determine whether a prototype can be applied to
6655               a function call.  "cvop" is the op being considered, normally
6656               an "rv2cv" op.  A pointer to the identified subroutine is
6657               returned, if it could be determined statically, and a null
6658               pointer is returned if it was not possible to determine
6659               statically.
6660
6661               Currently, the subroutine can be identified statically if the
6662               RV that the "rv2cv" is to operate on is provided by a suitable
6663               "gv" or "const" op.  A "gv" op is suitable if the GV's CV slot
6664               is populated.  A "const" op is suitable if the constant value
6665               must be an RV pointing to a CV.  Details of this process may
6666               change in future versions of Perl.  If the "rv2cv" op has the
6667               "OPpENTERSUB_AMPER" flag set then no attempt is made to
6668               identify the subroutine statically: this flag is used to
6669               suppress compile-time magic on a subroutine call, forcing it to
6670               use default runtime behaviour.
6671
6672               If "flags" has the bit "RV2CVOPCV_MARK_EARLY" set, then the
6673               handling of a GV reference is modified.  If a GV was examined
6674               and its CV slot was found to be empty, then the "gv" op has the
6675               "OPpEARLY_CV" flag set.  If the op is not optimised away, and
6676               the CV slot is later populated with a subroutine having a
6677               prototype, that flag eventually triggers the warning "called
6678               too early to check prototype".
6679
6680               If "flags" has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then
6681               instead of returning a pointer to the subroutine it returns a
6682               pointer to the GV giving the most appropriate name for the
6683               subroutine in this context.  Normally this is just the "CvGV"
6684               of the subroutine, but for an anonymous ("CvANON") subroutine
6685               that is referenced through a GV it will be the referencing GV.
6686               The resulting "GV*" is cast to "CV*" to be returned.  A null
6687               pointer is returned as usual if there is no statically-
6688               determinable subroutine.
6689
6690                       CV*     rv2cv_op_cv(OP *cvop, U32 flags)
6691

Pack and Unpack

6693       packlist
6694               The engine implementing "pack()" Perl function.
6695
6696                       void    packlist(SV *cat, const char *pat,
6697                                        const char *patend, SV **beglist,
6698                                        SV **endlist)
6699
6700       unpackstring
6701               The engine implementing the "unpack()" Perl function.
6702
6703               Using the template "pat..patend", this function unpacks the
6704               string "s..strend" into a number of mortal SVs, which it pushes
6705               onto the perl argument (@_) stack (so you will need to issue a
6706               "PUTBACK" before and "SPAGAIN" after the call to this
6707               function).  It returns the number of pushed elements.
6708
6709               The "strend" and "patend" pointers should point to the byte
6710               following the last character of each string.
6711
6712               Although this function returns its values on the perl argument
6713               stack, it doesn't take any parameters from that stack (and thus
6714               in particular there's no need to do a "PUSHMARK" before calling
6715               it, unlike "call_pv" for example).
6716
6717                       SSize_t unpackstring(const char *pat,
6718                                            const char *patend, const char *s,
6719                                            const char *strend, U32 flags)
6720

Pad Data Structures

6722       CvPADLIST
6723               NOTE: this function is experimental and may change or be
6724               removed without notice.
6725
6726               CV's can have CvPADLIST(cv) set to point to a PADLIST.  This is
6727               the CV's scratchpad, which stores lexical variables and opcode
6728               temporary and per-thread values.
6729
6730               For these purposes "formats" are a kind-of CV; eval""s are too
6731               (except they're not callable at will and are always thrown away
6732               after the eval"" is done executing).  Require'd files are
6733               simply evals without any outer lexical scope.
6734
6735               XSUBs do not have a "CvPADLIST".  "dXSTARG" fetches values from
6736               "PL_curpad", but that is really the callers pad (a slot of
6737               which is allocated by every entersub). Do not get or set
6738               "CvPADLIST" if a CV is an XSUB (as determined by "CvISXSUB()"),
6739               "CvPADLIST" slot is reused for a different internal purpose in
6740               XSUBs.
6741
6742               The PADLIST has a C array where pads are stored.
6743
6744               The 0th entry of the PADLIST is a PADNAMELIST which represents
6745               the "names" or rather the "static type information" for
6746               lexicals.  The individual elements of a PADNAMELIST are
6747               PADNAMEs.  Future refactorings might stop the PADNAMELIST from
6748               being stored in the PADLIST's array, so don't rely on it.  See
6749               "PadlistNAMES".
6750
6751               The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the
6752               stack frame at that depth of recursion into the CV.  The 0th
6753               slot of a frame AV is an AV which is @_.  Other entries are
6754               storage for variables and op targets.
6755
6756               Iterating over the PADNAMELIST iterates over all possible pad
6757               items.  Pad slots for targets ("SVs_PADTMP") and GVs end up
6758               having &PL_padname_undef "names", while slots for constants
6759               have &PL_padname_const "names" (see "pad_alloc").  That
6760               &PL_padname_undef and &PL_padname_const are used is an
6761               implementation detail subject to change.  To test for them, use
6762               "!PadnamePV(name)" and "PadnamePV(name) && !PadnameLEN(name)",
6763               respectively.
6764
6765               Only "my"/"our" variable slots get valid names.  The rest are
6766               op targets/GVs/constants which are statically allocated or
6767               resolved at compile time.  These don't have names by which they
6768               can be looked up from Perl code at run time through eval"" the
6769               way "my"/"our" variables can be.  Since they can't be looked up
6770               by "name" but only by their index allocated at compile time
6771               (which is usually in "PL_op->op_targ"), wasting a name SV for
6772               them doesn't make sense.
6773
6774               The pad names in the PADNAMELIST have their PV holding the name
6775               of the variable.  The "COP_SEQ_RANGE_LOW" and "_HIGH" fields
6776               form a range (low+1..high inclusive) of cop_seq numbers for
6777               which the name is valid.  During compilation, these fields may
6778               hold the special value PERL_PADSEQ_INTRO to indicate various
6779               stages:
6780
6781                COP_SEQ_RANGE_LOW        _HIGH
6782                -----------------        -----
6783                PERL_PADSEQ_INTRO            0   variable not yet introduced:
6784                                                 { my ($x
6785                valid-seq#   PERL_PADSEQ_INTRO   variable in scope:
6786                                                 { my ($x);
6787                valid-seq#          valid-seq#   compilation of scope complete:
6788                                                 { my ($x); .... }
6789
6790               When a lexical var hasn't yet been introduced, it already
6791               exists from the perspective of duplicate declarations, but not
6792               for variable lookups, e.g.
6793
6794                   my ($x, $x); # '"my" variable $x masks earlier declaration'
6795                   my $x = $x;  # equal to my $x = $::x;
6796
6797               For typed lexicals "PadnameTYPE" points at the type stash.  For
6798               "our" lexicals, "PadnameOURSTASH" points at the stash of the
6799               associated global (so that duplicate "our" declarations in the
6800               same package can be detected).  "PadnameGEN" is sometimes used
6801               to store the generation number during compilation.
6802
6803               If "PadnameOUTER" is set on the pad name, then that slot in the
6804               frame AV is a REFCNT'ed reference to a lexical from "outside".
6805               Such entries are sometimes referred to as 'fake'.  In this
6806               case, the name does not use 'low' and 'high' to store a cop_seq
6807               range, since it is in scope throughout.  Instead 'high' stores
6808               some flags containing info about the real lexical (is it
6809               declared in an anon, and is it capable of being instantiated
6810               multiple times?), and for fake ANONs, 'low' contains the index
6811               within the parent's pad where the lexical's value is stored, to
6812               make cloning quicker.
6813
6814               If the 'name' is "&" the corresponding entry in the PAD is a CV
6815               representing a possible closure.
6816
6817               Note that formats are treated as anon subs, and are cloned each
6818               time write is called (if necessary).
6819
6820               The flag "SVs_PADSTALE" is cleared on lexicals each time the
6821               "my()" is executed, and set on scope exit.  This allows the
6822               "Variable $x is not available" warning to be generated in
6823               evals, such as
6824
6825                   { my $x = 1; sub f { eval '$x'} } f();
6826
6827               For state vars, "SVs_PADSTALE" is overloaded to mean 'not yet
6828               initialised', but this internal state is stored in a separate
6829               pad entry.
6830
6831                       PADLIST * CvPADLIST(CV *cv)
6832
6833       pad_add_name_pvs
6834               Exactly like "pad_add_name_pvn", but takes a literal string
6835               instead of a string/length pair.
6836
6837                       PADOFFSET pad_add_name_pvs("name", U32 flags,
6838                                                  HV *typestash, HV *ourstash)
6839
6840       PadARRAY
6841               NOTE: this function is experimental and may change or be
6842               removed without notice.
6843
6844               The C array of pad entries.
6845
6846                       SV **   PadARRAY(PAD * pad)
6847
6848       pad_findmy_pvs
6849               Exactly like "pad_findmy_pvn", but takes a literal string
6850               instead of a string/length pair.
6851
6852                       PADOFFSET pad_findmy_pvs("name", U32 flags)
6853
6854       PadlistARRAY
6855               NOTE: this function is experimental and may change or be
6856               removed without notice.
6857
6858               The C array of a padlist, containing the pads.  Only subscript
6859               it with numbers >= 1, as the 0th entry is not guaranteed to
6860               remain usable.
6861
6862                       PAD **  PadlistARRAY(PADLIST * padlist)
6863
6864       PadlistMAX
6865               NOTE: this function is experimental and may change or be
6866               removed without notice.
6867
6868               The index of the last allocated space in the padlist.  Note
6869               that the last pad may be in an earlier slot.  Any entries
6870               following it will be "NULL" in that case.
6871
6872                       SSize_t PadlistMAX(PADLIST * padlist)
6873
6874       PadlistNAMES
6875               NOTE: this function is experimental and may change or be
6876               removed without notice.
6877
6878               The names associated with pad entries.
6879
6880                       PADNAMELIST * PadlistNAMES(PADLIST * padlist)
6881
6882       PadlistNAMESARRAY
6883               NOTE: this function is experimental and may change or be
6884               removed without notice.
6885
6886               The C array of pad names.
6887
6888                       PADNAME ** PadlistNAMESARRAY(PADLIST * padlist)
6889
6890       PadlistNAMESMAX
6891               NOTE: this function is experimental and may change or be
6892               removed without notice.
6893
6894               The index of the last pad name.
6895
6896                       SSize_t PadlistNAMESMAX(PADLIST * padlist)
6897
6898       PadlistREFCNT
6899               NOTE: this function is experimental and may change or be
6900               removed without notice.
6901
6902               The reference count of the padlist.  Currently this is always
6903               1.
6904
6905                       U32     PadlistREFCNT(PADLIST * padlist)
6906
6907       PadMAX  NOTE: this function is experimental and may change or be
6908               removed without notice.
6909
6910               The index of the last pad entry.
6911
6912                       SSize_t PadMAX(PAD * pad)
6913
6914       PadnameLEN
6915               NOTE: this function is experimental and may change or be
6916               removed without notice.
6917
6918               The length of the name.
6919
6920                       STRLEN  PadnameLEN(PADNAME * pn)
6921
6922       PadnamelistARRAY
6923               NOTE: this function is experimental and may change or be
6924               removed without notice.
6925
6926               The C array of pad names.
6927
6928                       PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl)
6929
6930       PadnamelistMAX
6931               NOTE: this function is experimental and may change or be
6932               removed without notice.
6933
6934               The index of the last pad name.
6935
6936                       SSize_t PadnamelistMAX(PADNAMELIST * pnl)
6937
6938       PadnamelistREFCNT
6939               NOTE: this function is experimental and may change or be
6940               removed without notice.
6941
6942               The reference count of the pad name list.
6943
6944                       SSize_t PadnamelistREFCNT(PADNAMELIST * pnl)
6945
6946       PadnamelistREFCNT_dec
6947               NOTE: this function is experimental and may change or be
6948               removed without notice.
6949
6950               Lowers the reference count of the pad name list.
6951
6952                       void    PadnamelistREFCNT_dec(PADNAMELIST * pnl)
6953
6954       PadnamePV
6955               NOTE: this function is experimental and may change or be
6956               removed without notice.
6957
6958               The name stored in the pad name struct.  This returns "NULL"
6959               for a target slot.
6960
6961                       char *  PadnamePV(PADNAME * pn)
6962
6963       PadnameREFCNT
6964               NOTE: this function is experimental and may change or be
6965               removed without notice.
6966
6967               The reference count of the pad name.
6968
6969                       SSize_t PadnameREFCNT(PADNAME * pn)
6970
6971       PadnameREFCNT_dec
6972               NOTE: this function is experimental and may change or be
6973               removed without notice.
6974
6975               Lowers the reference count of the pad name.
6976
6977                       void    PadnameREFCNT_dec(PADNAME * pn)
6978
6979       PadnameSV
6980               NOTE: this function is experimental and may change or be
6981               removed without notice.
6982
6983               Returns the pad name as a mortal SV.
6984
6985                       SV *    PadnameSV(PADNAME * pn)
6986
6987       PadnameUTF8
6988               NOTE: this function is experimental and may change or be
6989               removed without notice.
6990
6991               Whether PadnamePV is in UTF-8.  Currently, this is always true.
6992
6993                       bool    PadnameUTF8(PADNAME * pn)
6994
6995       pad_new Create a new padlist, updating the global variables for the
6996               currently-compiling padlist to point to the new padlist.  The
6997               following flags can be OR'ed together:
6998
6999                   padnew_CLONE        this pad is for a cloned CV
7000                   padnew_SAVE         save old globals on the save stack
7001                   padnew_SAVESUB      also save extra stuff for start of sub
7002
7003                       PADLIST* pad_new(int flags)
7004
7005       PL_comppad
7006               NOTE: this function is experimental and may change or be
7007               removed without notice.
7008
7009               During compilation, this points to the array containing the
7010               values part of the pad for the currently-compiling code.  (At
7011               runtime a CV may have many such value arrays; at compile time
7012               just one is constructed.)  At runtime, this points to the array
7013               containing the currently-relevant values for the pad for the
7014               currently-executing code.
7015
7016       PL_comppad_name
7017               NOTE: this function is experimental and may change or be
7018               removed without notice.
7019
7020               During compilation, this points to the array containing the
7021               names part of the pad for the currently-compiling code.
7022
7023       PL_curpad
7024               NOTE: this function is experimental and may change or be
7025               removed without notice.
7026
7027               Points directly to the body of the "PL_comppad" array.  (I.e.,
7028               this is "PadARRAY(PL_comppad)".)
7029

Per-Interpreter Variables

7031       PL_curcop
7032               The currently active COP (control op) roughly representing the
7033               current statement in the source.
7034
7035                       COP*    PL_curcop
7036
7037       PL_curstash
7038               The stash for the package code will be compiled into.
7039
7040                       HV*     PL_curstash
7041
7042       PL_defgv
7043               The GV representing *_.  Useful for access to $_.
7044
7045                       GV *    PL_defgv
7046
7047       PL_exit_flags
7048               Contains flags controlling perl's behaviour on exit():
7049
7050               ·   "PERL_EXIT_DESTRUCT_END"
7051
7052                   If set, END blocks are executed when the interpreter is
7053                   destroyed.  This is normally set by perl itself after the
7054                   interpreter is constructed.
7055
7056               ·   "PERL_EXIT_ABORT"
7057
7058                   Call "abort()" on exit.  This is used internally by perl
7059                   itself to abort if exit is called while processing exit.
7060
7061               ·   "PERL_EXIT_WARN"
7062
7063                   Warn on exit.
7064
7065               ·   "PERL_EXIT_EXPECTED"
7066
7067                   Set by the "exit" in perlfunc operator.
7068
7069                       U8      PL_exit_flags
7070
7071       PL_modglobal
7072               "PL_modglobal" is a general purpose, interpreter global HV for
7073               use by extensions that need to keep information on a per-
7074               interpreter basis.  In a pinch, it can also be used as a symbol
7075               table for extensions to share data among each other.  It is a
7076               good idea to use keys prefixed by the package name of the
7077               extension that owns the data.
7078
7079                       HV*     PL_modglobal
7080
7081       PL_na   A convenience variable which is typically used with "SvPV" when
7082               one doesn't care about the length of the string.  It is usually
7083               more efficient to either declare a local variable and use that
7084               instead or to use the "SvPV_nolen" macro.
7085
7086                       STRLEN  PL_na
7087
7088       PL_opfreehook
7089               When non-"NULL", the function pointed by this variable will be
7090               called each time an OP is freed with the corresponding OP as
7091               the argument.  This allows extensions to free any extra
7092               attribute they have locally attached to an OP.  It is also
7093               assured to first fire for the parent OP and then for its kids.
7094
7095               When you replace this variable, it is considered a good
7096               practice to store the possibly previously installed hook and
7097               that you recall it inside your own.
7098
7099                       Perl_ophook_t   PL_opfreehook
7100
7101       PL_peepp
7102               Pointer to the per-subroutine peephole optimiser.  This is a
7103               function that gets called at the end of compilation of a Perl
7104               subroutine (or equivalently independent piece of Perl code) to
7105               perform fixups of some ops and to perform small-scale
7106               optimisations.  The function is called once for each subroutine
7107               that is compiled, and is passed, as sole parameter, a pointer
7108               to the op that is the entry point to the subroutine.  It
7109               modifies the op tree in place.
7110
7111               The peephole optimiser should never be completely replaced.
7112               Rather, add code to it by wrapping the existing optimiser.  The
7113               basic way to do this can be seen in "Compile pass 3: peephole
7114               optimization" in perlguts.  If the new code wishes to operate
7115               on ops throughout the subroutine's structure, rather than just
7116               at the top level, it is likely to be more convenient to wrap
7117               the "PL_rpeepp" hook.
7118
7119                       peep_t  PL_peepp
7120
7121       PL_perl_destruct_level
7122               This value may be set when embedding for full cleanup.
7123
7124               Possible values:
7125
7126               ·   0 - none
7127
7128               ·   1 - full
7129
7130               ·   2 or greater - full with checks.
7131
7132               If $ENV{PERL_DESTRUCT_LEVEL} is set to an integer greater than
7133               the value of "PL_perl_destruct_level" its value is used
7134               instead.
7135
7136                       signed char     PL_perl_destruct_level
7137
7138       PL_rpeepp
7139               Pointer to the recursive peephole optimiser.  This is a
7140               function that gets called at the end of compilation of a Perl
7141               subroutine (or equivalently independent piece of Perl code) to
7142               perform fixups of some ops and to perform small-scale
7143               optimisations.  The function is called once for each chain of
7144               ops linked through their "op_next" fields; it is recursively
7145               called to handle each side chain.  It is passed, as sole
7146               parameter, a pointer to the op that is at the head of the
7147               chain.  It modifies the op tree in place.
7148
7149               The peephole optimiser should never be completely replaced.
7150               Rather, add code to it by wrapping the existing optimiser.  The
7151               basic way to do this can be seen in "Compile pass 3: peephole
7152               optimization" in perlguts.  If the new code wishes to operate
7153               only on ops at a subroutine's top level, rather than throughout
7154               the structure, it is likely to be more convenient to wrap the
7155               "PL_peepp" hook.
7156
7157                       peep_t  PL_rpeepp
7158
7159       PL_runops
7160               See "Pluggable runops" in perlguts.
7161
7162                       runops_proc_t   PL_runops
7163
7164       PL_sv_no
7165               This is the "false" SV.  See "PL_sv_yes".  Always refer to this
7166               as &PL_sv_no.
7167
7168                       SV      PL_sv_no
7169
7170       PL_sv_undef
7171               This is the "undef" SV.  Always refer to this as &PL_sv_undef.
7172
7173                       SV      PL_sv_undef
7174
7175       PL_sv_yes
7176               This is the "true" SV.  See "PL_sv_no".  Always refer to this
7177               as &PL_sv_yes.
7178
7179                       SV      PL_sv_yes
7180
7181       PL_sv_zero
7182               This readonly SV has a zero numeric value and a "0" string
7183               value. It's similar to "PL_sv_no" except for its string value.
7184               Can be used as a cheap alternative to mXPUSHi(0) for example.
7185               Always refer to this as &PL_sv_zero. Introduced in 5.28.
7186
7187                       SV      PL_sv_zero
7188

REGEXP Functions

7190       SvRX    Convenience macro to get the REGEXP from a SV.  This is
7191               approximately equivalent to the following snippet:
7192
7193                   if (SvMAGICAL(sv))
7194                       mg_get(sv);
7195                   if (SvROK(sv))
7196                       sv = MUTABLE_SV(SvRV(sv));
7197                   if (SvTYPE(sv) == SVt_REGEXP)
7198                       return (REGEXP*) sv;
7199
7200               "NULL" will be returned if a REGEXP* is not found.
7201
7202                       REGEXP * SvRX(SV *sv)
7203
7204       SvRXOK  Returns a boolean indicating whether the SV (or the one it
7205               references) is a REGEXP.
7206
7207               If you want to do something with the REGEXP* later use SvRX
7208               instead and check for NULL.
7209
7210                       bool    SvRXOK(SV* sv)
7211

Stack Manipulation Macros

7213       dMARK   Declare a stack marker variable, "mark", for the XSUB.  See
7214               "MARK" and "dORIGMARK".
7215
7216                               dMARK;
7217
7218       dORIGMARK
7219               Saves the original stack mark for the XSUB.  See "ORIGMARK".
7220
7221                               dORIGMARK;
7222
7223       dSP     Declares a local copy of perl's stack pointer for the XSUB,
7224               available via the "SP" macro.  See "SP".
7225
7226                               dSP;
7227
7228       EXTEND  Used to extend the argument stack for an XSUB's return values.
7229               Once used, guarantees that there is room for at least "nitems"
7230               to be pushed onto the stack.
7231
7232                       void    EXTEND(SP, SSize_t nitems)
7233
7234       MARK    Stack marker variable for the XSUB.  See "dMARK".
7235
7236       mPUSHi  Push an integer onto the stack.  The stack must have room for
7237               this element.  Does not use "TARG".  See also "PUSHi",
7238               "mXPUSHi" and "XPUSHi".
7239
7240                       void    mPUSHi(IV iv)
7241
7242       mPUSHn  Push a double onto the stack.  The stack must have room for
7243               this element.  Does not use "TARG".  See also "PUSHn",
7244               "mXPUSHn" and "XPUSHn".
7245
7246                       void    mPUSHn(NV nv)
7247
7248       mPUSHp  Push a string onto the stack.  The stack must have room for
7249               this element.  The "len" indicates the length of the string.
7250               Does not use "TARG".  See also "PUSHp", "mXPUSHp" and "XPUSHp".
7251
7252                       void    mPUSHp(char* str, STRLEN len)
7253
7254       mPUSHs  Push an SV onto the stack and mortalizes the SV.  The stack
7255               must have room for this element.  Does not use "TARG".  See
7256               also "PUSHs" and "mXPUSHs".
7257
7258                       void    mPUSHs(SV* sv)
7259
7260       mPUSHu  Push an unsigned integer onto the stack.  The stack must have
7261               room for this element.  Does not use "TARG".  See also "PUSHu",
7262               "mXPUSHu" and "XPUSHu".
7263
7264                       void    mPUSHu(UV uv)
7265
7266       mXPUSHi Push an integer onto the stack, extending the stack if
7267               necessary.  Does not use "TARG".  See also "XPUSHi", "mPUSHi"
7268               and "PUSHi".
7269
7270                       void    mXPUSHi(IV iv)
7271
7272       mXPUSHn Push a double onto the stack, extending the stack if necessary.
7273               Does not use "TARG".  See also "XPUSHn", "mPUSHn" and "PUSHn".
7274
7275                       void    mXPUSHn(NV nv)
7276
7277       mXPUSHp Push a string onto the stack, extending the stack if necessary.
7278               The "len" indicates the length of the string.  Does not use
7279               "TARG".  See also "XPUSHp", "mPUSHp" and "PUSHp".
7280
7281                       void    mXPUSHp(char* str, STRLEN len)
7282
7283       mXPUSHs Push an SV onto the stack, extending the stack if necessary and
7284               mortalizes the SV.  Does not use "TARG".  See also "XPUSHs" and
7285               "mPUSHs".
7286
7287                       void    mXPUSHs(SV* sv)
7288
7289       mXPUSHu Push an unsigned integer onto the stack, extending the stack if
7290               necessary.  Does not use "TARG".  See also "XPUSHu", "mPUSHu"
7291               and "PUSHu".
7292
7293                       void    mXPUSHu(UV uv)
7294
7295       ORIGMARK
7296               The original stack mark for the XSUB.  See "dORIGMARK".
7297
7298       POPi    Pops an integer off the stack.
7299
7300                       IV      POPi
7301
7302       POPl    Pops a long off the stack.
7303
7304                       long    POPl
7305
7306       POPn    Pops a double off the stack.
7307
7308                       NV      POPn
7309
7310       POPp    Pops a string off the stack.
7311
7312                       char*   POPp
7313
7314       POPpbytex
7315               Pops a string off the stack which must consist of bytes i.e.
7316               characters < 256.
7317
7318                       char*   POPpbytex
7319
7320       POPpx   Pops a string off the stack.  Identical to POPp.  There are two
7321               names for historical reasons.
7322
7323                       char*   POPpx
7324
7325       POPs    Pops an SV off the stack.
7326
7327                       SV*     POPs
7328
7329       POPu    Pops an unsigned integer off the stack.
7330
7331                       UV      POPu
7332
7333       POPul   Pops an unsigned long off the stack.
7334
7335                       long    POPul
7336
7337       PUSHi   Push an integer onto the stack.  The stack must have room for
7338               this element.  Handles 'set' magic.  Uses "TARG", so "dTARGET"
7339               or "dXSTARG" should be called to declare it.  Do not call
7340               multiple "TARG"-oriented macros to return lists from XSUB's -
7341               see "mPUSHi" instead.  See also "XPUSHi" and "mXPUSHi".
7342
7343                       void    PUSHi(IV iv)
7344
7345       PUSHMARK
7346               Opening bracket for arguments on a callback.  See "PUTBACK" and
7347               perlcall.
7348
7349                       void    PUSHMARK(SP)
7350
7351       PUSHmortal
7352               Push a new mortal SV onto the stack.  The stack must have room
7353               for this element.  Does not use "TARG".  See also "PUSHs",
7354               "XPUSHmortal" and "XPUSHs".
7355
7356                       void    PUSHmortal
7357
7358       PUSHn   Push a double onto the stack.  The stack must have room for
7359               this element.  Handles 'set' magic.  Uses "TARG", so "dTARGET"
7360               or "dXSTARG" should be called to declare it.  Do not call
7361               multiple "TARG"-oriented macros to return lists from XSUB's -
7362               see "mPUSHn" instead.  See also "XPUSHn" and "mXPUSHn".
7363
7364                       void    PUSHn(NV nv)
7365
7366       PUSHp   Push a string onto the stack.  The stack must have room for
7367               this element.  The "len" indicates the length of the string.
7368               Handles 'set' magic.  Uses "TARG", so "dTARGET" or "dXSTARG"
7369               should be called to declare it.  Do not call multiple
7370               "TARG"-oriented macros to return lists from XSUB's - see
7371               "mPUSHp" instead.  See also "XPUSHp" and "mXPUSHp".
7372
7373                       void    PUSHp(char* str, STRLEN len)
7374
7375       PUSHs   Push an SV onto the stack.  The stack must have room for this
7376               element.  Does not handle 'set' magic.  Does not use "TARG".
7377               See also "PUSHmortal", "XPUSHs", and "XPUSHmortal".
7378
7379                       void    PUSHs(SV* sv)
7380
7381       PUSHu   Push an unsigned integer onto the stack.  The stack must have
7382               room for this element.  Handles 'set' magic.  Uses "TARG", so
7383               "dTARGET" or "dXSTARG" should be called to declare it.  Do not
7384               call multiple "TARG"-oriented macros to return lists from
7385               XSUB's - see "mPUSHu" instead.  See also "XPUSHu" and
7386               "mXPUSHu".
7387
7388                       void    PUSHu(UV uv)
7389
7390       PUTBACK Closing bracket for XSUB arguments.  This is usually handled by
7391               "xsubpp".  See "PUSHMARK" and perlcall for other uses.
7392
7393                               PUTBACK;
7394
7395       SP      Stack pointer.  This is usually handled by "xsubpp".  See "dSP"
7396               and "SPAGAIN".
7397
7398       SPAGAIN Refetch the stack pointer.  Used after a callback.  See
7399               perlcall.
7400
7401                               SPAGAIN;
7402
7403       XPUSHi  Push an integer onto the stack, extending the stack if
7404               necessary.  Handles 'set' magic.  Uses "TARG", so "dTARGET" or
7405               "dXSTARG" should be called to declare it.  Do not call multiple
7406               "TARG"-oriented macros to return lists from XSUB's - see
7407               "mXPUSHi" instead.  See also "PUSHi" and "mPUSHi".
7408
7409                       void    XPUSHi(IV iv)
7410
7411       XPUSHmortal
7412               Push a new mortal SV onto the stack, extending the stack if
7413               necessary.  Does not use "TARG".  See also "XPUSHs",
7414               "PUSHmortal" and "PUSHs".
7415
7416                       void    XPUSHmortal
7417
7418       XPUSHn  Push a double onto the stack, extending the stack if necessary.
7419               Handles 'set' magic.  Uses "TARG", so "dTARGET" or "dXSTARG"
7420               should be called to declare it.  Do not call multiple
7421               "TARG"-oriented macros to return lists from XSUB's - see
7422               "mXPUSHn" instead.  See also "PUSHn" and "mPUSHn".
7423
7424                       void    XPUSHn(NV nv)
7425
7426       XPUSHp  Push a string onto the stack, extending the stack if necessary.
7427               The "len" indicates the length of the string.  Handles 'set'
7428               magic.  Uses "TARG", so "dTARGET" or "dXSTARG" should be called
7429               to declare it.  Do not call multiple "TARG"-oriented macros to
7430               return lists from XSUB's - see "mXPUSHp" instead.  See also
7431               "PUSHp" and "mPUSHp".
7432
7433                       void    XPUSHp(char* str, STRLEN len)
7434
7435       XPUSHs  Push an SV onto the stack, extending the stack if necessary.
7436               Does not handle 'set' magic.  Does not use "TARG".  See also
7437               "XPUSHmortal", "PUSHs" and "PUSHmortal".
7438
7439                       void    XPUSHs(SV* sv)
7440
7441       XPUSHu  Push an unsigned integer onto the stack, extending the stack if
7442               necessary.  Handles 'set' magic.  Uses "TARG", so "dTARGET" or
7443               "dXSTARG" should be called to declare it.  Do not call multiple
7444               "TARG"-oriented macros to return lists from XSUB's - see
7445               "mXPUSHu" instead.  See also "PUSHu" and "mPUSHu".
7446
7447                       void    XPUSHu(UV uv)
7448
7449       XSRETURN
7450               Return from XSUB, indicating number of items on the stack.
7451               This is usually handled by "xsubpp".
7452
7453                       void    XSRETURN(int nitems)
7454
7455       XSRETURN_EMPTY
7456               Return an empty list from an XSUB immediately.
7457
7458                               XSRETURN_EMPTY;
7459
7460       XSRETURN_IV
7461               Return an integer from an XSUB immediately.  Uses "XST_mIV".
7462
7463                       void    XSRETURN_IV(IV iv)
7464
7465       XSRETURN_NO
7466               Return &PL_sv_no from an XSUB immediately.  Uses "XST_mNO".
7467
7468                               XSRETURN_NO;
7469
7470       XSRETURN_NV
7471               Return a double from an XSUB immediately.  Uses "XST_mNV".
7472
7473                       void    XSRETURN_NV(NV nv)
7474
7475       XSRETURN_PV
7476               Return a copy of a string from an XSUB immediately.  Uses
7477               "XST_mPV".
7478
7479                       void    XSRETURN_PV(char* str)
7480
7481       XSRETURN_UNDEF
7482               Return &PL_sv_undef from an XSUB immediately.  Uses
7483               "XST_mUNDEF".
7484
7485                               XSRETURN_UNDEF;
7486
7487       XSRETURN_UV
7488               Return an integer from an XSUB immediately.  Uses "XST_mUV".
7489
7490                       void    XSRETURN_UV(IV uv)
7491
7492       XSRETURN_YES
7493               Return &PL_sv_yes from an XSUB immediately.  Uses "XST_mYES".
7494
7495                               XSRETURN_YES;
7496
7497       XST_mIV Place an integer into the specified position "pos" on the
7498               stack.  The value is stored in a new mortal SV.
7499
7500                       void    XST_mIV(int pos, IV iv)
7501
7502       XST_mNO Place &PL_sv_no into the specified position "pos" on the stack.
7503
7504                       void    XST_mNO(int pos)
7505
7506       XST_mNV Place a double into the specified position "pos" on the stack.
7507               The value is stored in a new mortal SV.
7508
7509                       void    XST_mNV(int pos, NV nv)
7510
7511       XST_mPV Place a copy of a string into the specified position "pos" on
7512               the stack.  The value is stored in a new mortal SV.
7513
7514                       void    XST_mPV(int pos, char* str)
7515
7516       XST_mUNDEF
7517               Place &PL_sv_undef into the specified position "pos" on the
7518               stack.
7519
7520                       void    XST_mUNDEF(int pos)
7521
7522       XST_mUV Place an unsigned integer into the specified position "pos" on
7523               the stack.  The value is stored in a new mortal SV.
7524
7525                       void    XST_mUV(int pos, UV uv)
7526
7527       XST_mYES
7528               Place &PL_sv_yes into the specified position "pos" on the
7529               stack.
7530
7531                       void    XST_mYES(int pos)
7532

SV Flags

7534       SVt_IV  Type flag for scalars.  See "svtype".
7535
7536       SVt_NULL
7537               Type flag for scalars.  See "svtype".
7538
7539       SVt_NV  Type flag for scalars.  See "svtype".
7540
7541       SVt_PV  Type flag for scalars.  See "svtype".
7542
7543       SVt_PVAV
7544               Type flag for arrays.  See "svtype".
7545
7546       SVt_PVCV
7547               Type flag for subroutines.  See "svtype".
7548
7549       SVt_PVFM
7550               Type flag for formats.  See "svtype".
7551
7552       SVt_PVGV
7553               Type flag for typeglobs.  See "svtype".
7554
7555       SVt_PVHV
7556               Type flag for hashes.  See "svtype".
7557
7558       SVt_PVIO
7559               Type flag for I/O objects.  See "svtype".
7560
7561       SVt_PVIV
7562               Type flag for scalars.  See "svtype".
7563
7564       SVt_PVLV
7565               Type flag for scalars.  See "svtype".
7566
7567       SVt_PVMG
7568               Type flag for scalars.  See "svtype".
7569
7570       SVt_PVNV
7571               Type flag for scalars.  See "svtype".
7572
7573       SVt_REGEXP
7574               Type flag for regular expressions.  See "svtype".
7575
7576       svtype  An enum of flags for Perl types.  These are found in the file
7577               sv.h in the "svtype" enum.  Test these flags with the "SvTYPE"
7578               macro.
7579
7580               The types are:
7581
7582                   SVt_NULL
7583                   SVt_IV
7584                   SVt_NV
7585                   SVt_RV
7586                   SVt_PV
7587                   SVt_PVIV
7588                   SVt_PVNV
7589                   SVt_PVMG
7590                   SVt_INVLIST
7591                   SVt_REGEXP
7592                   SVt_PVGV
7593                   SVt_PVLV
7594                   SVt_PVAV
7595                   SVt_PVHV
7596                   SVt_PVCV
7597                   SVt_PVFM
7598                   SVt_PVIO
7599
7600               These are most easily explained from the bottom up.
7601
7602               "SVt_PVIO" is for I/O objects, "SVt_PVFM" for formats,
7603               "SVt_PVCV" for subroutines, "SVt_PVHV" for hashes and
7604               "SVt_PVAV" for arrays.
7605
7606               All the others are scalar types, that is, things that can be
7607               bound to a "$" variable.  For these, the internal types are
7608               mostly orthogonal to types in the Perl language.
7609
7610               Hence, checking "SvTYPE(sv) < SVt_PVAV" is the best way to see
7611               whether something is a scalar.
7612
7613               "SVt_PVGV" represents a typeglob.  If "!SvFAKE(sv)", then it is
7614               a real, incoercible typeglob.  If "SvFAKE(sv)", then it is a
7615               scalar to which a typeglob has been assigned.  Assigning to it
7616               again will stop it from being a typeglob.  "SVt_PVLV"
7617               represents a scalar that delegates to another scalar behind the
7618               scenes.  It is used, e.g., for the return value of "substr" and
7619               for tied hash and array elements.  It can hold any scalar
7620               value, including a typeglob.  "SVt_REGEXP" is for regular
7621               expressions.  "SVt_INVLIST" is for Perl core internal use only.
7622
7623               "SVt_PVMG" represents a "normal" scalar (not a typeglob,
7624               regular expression, or delegate).  Since most scalars do not
7625               need all the internal fields of a PVMG, we save memory by
7626               allocating smaller structs when possible.  All the other types
7627               are just simpler forms of "SVt_PVMG", with fewer internal
7628               fields.  "SVt_NULL" can only hold undef.  "SVt_IV" can hold
7629               undef, an integer, or a reference.  ("SVt_RV" is an alias for
7630               "SVt_IV", which exists for backward compatibility.)  "SVt_NV"
7631               can hold any of those or a double.  "SVt_PV" can only hold
7632               "undef" or a string.  "SVt_PVIV" is a superset of "SVt_PV" and
7633               "SVt_IV".  "SVt_PVNV" is similar.  "SVt_PVMG" can hold anything
7634               "SVt_PVNV" can hold, but it can, but does not have to, be
7635               blessed or magical.
7636

SV Manipulation Functions

7638       boolSV  Returns a true SV if "b" is a true value, or a false SV if "b"
7639               is 0.
7640
7641               See also "PL_sv_yes" and "PL_sv_no".
7642
7643                       SV *    boolSV(bool b)
7644
7645       croak_xs_usage
7646               A specialised variant of "croak()" for emitting the usage
7647               message for xsubs
7648
7649                   croak_xs_usage(cv, "eee_yow");
7650
7651               works out the package name and subroutine name from "cv", and
7652               then calls "croak()".  Hence if "cv" is &ouch::awk, it would
7653               call "croak" as:
7654
7655                Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
7656                                                                    "eee_yow");
7657
7658                       void    croak_xs_usage(const CV *const cv,
7659                                              const char *const params)
7660
7661       get_sv  Returns the SV of the specified Perl scalar.  "flags" are
7662               passed to "gv_fetchpv".  If "GV_ADD" is set and the Perl
7663               variable does not exist then it will be created.  If "flags" is
7664               zero and the variable does not exist then NULL is returned.
7665
7666               NOTE: the perl_ form of this function is deprecated.
7667
7668                       SV*     get_sv(const char *name, I32 flags)
7669
7670       looks_like_number
7671               Test if the content of an SV looks like a number (or is a
7672               number).  "Inf" and "Infinity" are treated as numbers (so will
7673               not issue a non-numeric warning), even if your "atof()" doesn't
7674               grok them.  Get-magic is ignored.
7675
7676                       I32     looks_like_number(SV *const sv)
7677
7678       newRV_inc
7679               Creates an RV wrapper for an SV.  The reference count for the
7680               original SV is incremented.
7681
7682                       SV*     newRV_inc(SV* sv)
7683
7684       newRV_noinc
7685               Creates an RV wrapper for an SV.  The reference count for the
7686               original SV is not incremented.
7687
7688                       SV*     newRV_noinc(SV *const tmpRef)
7689
7690       newSV   Creates a new SV.  A non-zero "len" parameter indicates the
7691               number of bytes of preallocated string space the SV should
7692               have.  An extra byte for a trailing "NUL" is also reserved.
7693               ("SvPOK" is not set for the SV even if string space is
7694               allocated.)  The reference count for the new SV is set to 1.
7695
7696               In 5.9.3, "newSV()" replaces the older "NEWSV()" API, and drops
7697               the first parameter, x, a debug aid which allowed callers to
7698               identify themselves.  This aid has been superseded by a new
7699               build option, "PERL_MEM_LOG" (see "PERL_MEM_LOG" in
7700               perlhacktips).  The older API is still there for use in XS
7701               modules supporting older perls.
7702
7703                       SV*     newSV(const STRLEN len)
7704
7705       newSVhek
7706               Creates a new SV from the hash key structure.  It will generate
7707               scalars that point to the shared string table where possible.
7708               Returns a new (undefined) SV if "hek" is NULL.
7709
7710                       SV*     newSVhek(const HEK *const hek)
7711
7712       newSViv Creates a new SV and copies an integer into it.  The reference
7713               count for the SV is set to 1.
7714
7715                       SV*     newSViv(const IV i)
7716
7717       newSVnv Creates a new SV and copies a floating point value into it.
7718               The reference count for the SV is set to 1.
7719
7720                       SV*     newSVnv(const NV n)
7721
7722       newSVpadname
7723               NOTE: this function is experimental and may change or be
7724               removed without notice.
7725
7726               Creates a new SV containing the pad name.
7727
7728                       SV*     newSVpadname(PADNAME *pn)
7729
7730       newSVpv Creates a new SV and copies a string (which may contain "NUL"
7731               ("\0") characters) into it.  The reference count for the SV is
7732               set to 1.  If "len" is zero, Perl will compute the length using
7733               "strlen()", (which means if you use this option, that "s" can't
7734               have embedded "NUL" characters and has to have a terminating
7735               "NUL" byte).
7736
7737               This function can cause reliability issues if you are likely to
7738               pass in empty strings that are not null terminated, because it
7739               will run strlen on the string and potentially run past valid
7740               memory.
7741
7742               Using "newSVpvn" is a safer alternative for non "NUL"
7743               terminated strings.  For string literals use "newSVpvs"
7744               instead.  This function will work fine for "NUL" terminated
7745               strings, but if you want to avoid the if statement on whether
7746               to call "strlen" use "newSVpvn" instead (calling "strlen"
7747               yourself).
7748
7749                       SV*     newSVpv(const char *const s, const STRLEN len)
7750
7751       newSVpvf
7752               Creates a new SV and initializes it with the string formatted
7753               like "sv_catpvf".
7754
7755                       SV*     newSVpvf(const char *const pat, ...)
7756
7757       newSVpvn
7758               Creates a new SV and copies a string into it, which may contain
7759               "NUL" characters ("\0") and other binary data.  The reference
7760               count for the SV is set to 1.  Note that if "len" is zero, Perl
7761               will create a zero length (Perl) string.  You are responsible
7762               for ensuring that the source buffer is at least "len" bytes
7763               long.  If the "buffer" argument is NULL the new SV will be
7764               undefined.
7765
7766                       SV*     newSVpvn(const char *const buffer,
7767                                        const STRLEN len)
7768
7769       newSVpvn_flags
7770               Creates a new SV and copies a string (which may contain "NUL"
7771               ("\0") characters) into it.  The reference count for the SV is
7772               set to 1.  Note that if "len" is zero, Perl will create a zero
7773               length string.  You are responsible for ensuring that the
7774               source string is at least "len" bytes long.  If the "s"
7775               argument is NULL the new SV will be undefined.  Currently the
7776               only flag bits accepted are "SVf_UTF8" and "SVs_TEMP".  If
7777               "SVs_TEMP" is set, then "sv_2mortal()" is called on the result
7778               before returning.  If "SVf_UTF8" is set, "s" is considered to
7779               be in UTF-8 and the "SVf_UTF8" flag will be set on the new SV.
7780               "newSVpvn_utf8()" is a convenience wrapper for this function,
7781               defined as
7782
7783                   #define newSVpvn_utf8(s, len, u)                    \
7784                       newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
7785
7786                       SV*     newSVpvn_flags(const char *const s,
7787                                              const STRLEN len,
7788                                              const U32 flags)
7789
7790       newSVpvn_share
7791               Creates a new SV with its "SvPVX_const" pointing to a shared
7792               string in the string table.  If the string does not already
7793               exist in the table, it is created first.  Turns on the
7794               "SvIsCOW" flag (or "READONLY" and "FAKE" in 5.16 and earlier).
7795               If the "hash" parameter is non-zero, that value is used;
7796               otherwise the hash is computed.  The string's hash can later be
7797               retrieved from the SV with the "SvSHARED_HASH()" macro.  The
7798               idea here is that as the string table is used for shared hash
7799               keys these strings will have "SvPVX_const == HeKEY" and hash
7800               lookup will avoid string compare.
7801
7802                       SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
7803
7804       newSVpvn_utf8
7805               Creates a new SV and copies a string (which may contain "NUL"
7806               ("\0") characters) into it.  If "utf8" is true, calls
7807               "SvUTF8_on" on the new SV.  Implemented as a wrapper around
7808               "newSVpvn_flags".
7809
7810                       SV*     newSVpvn_utf8(const char* s, STRLEN len,
7811                                             U32 utf8)
7812
7813       newSVpvs
7814               Like "newSVpvn", but takes a literal string instead of a
7815               string/length pair.
7816
7817                       SV*     newSVpvs("literal string")
7818
7819       newSVpvs_flags
7820               Like "newSVpvn_flags", but takes a literal string instead of a
7821               string/length pair.
7822
7823                       SV*     newSVpvs_flags("literal string", U32 flags)
7824
7825       newSVpv_share
7826               Like "newSVpvn_share", but takes a "NUL"-terminated string
7827               instead of a string/length pair.
7828
7829                       SV*     newSVpv_share(const char* s, U32 hash)
7830
7831       newSVpvs_share
7832               Like "newSVpvn_share", but takes a literal string instead of a
7833               string/length pair and omits the hash parameter.
7834
7835                       SV*     newSVpvs_share("literal string")
7836
7837       newSVrv Creates a new SV for the existing RV, "rv", to point to.  If
7838               "rv" is not an RV then it will be upgraded to one.  If
7839               "classname" is non-null then the new SV will be blessed in the
7840               specified package.  The new SV is returned and its reference
7841               count is 1.  The reference count 1 is owned by "rv". See also
7842               newRV_inc() and newRV_noinc() for creating a new RV properly.
7843
7844                       SV*     newSVrv(SV *const rv,
7845                                       const char *const classname)
7846
7847       newSVsv Creates a new SV which is an exact duplicate of the original
7848               SV.  (Uses "sv_setsv".)
7849
7850                       SV*     newSVsv(SV *const old)
7851
7852       newSVsv_nomg
7853               Like "newSVsv" but does not process get magic.
7854
7855                       SV*     newSVsv_nomg(SV *const old)
7856
7857       newSV_type
7858               Creates a new SV, of the type specified.  The reference count
7859               for the new SV is set to 1.
7860
7861                       SV*     newSV_type(const svtype type)
7862
7863       newSVuv Creates a new SV and copies an unsigned integer into it.  The
7864               reference count for the SV is set to 1.
7865
7866                       SV*     newSVuv(const UV u)
7867
7868       sortsv_flags
7869               In-place sort an array of SV pointers with the given comparison
7870               routine, with various SORTf_* flag options.
7871
7872                       void    sortsv_flags(SV** array, size_t num_elts,
7873                                            SVCOMPARE_t cmp, U32 flags)
7874
7875       sv_2bool
7876               This macro is only used by "sv_true()" or its macro equivalent,
7877               and only if the latter's argument is neither "SvPOK", "SvIOK"
7878               nor "SvNOK".  It calls "sv_2bool_flags" with the "SV_GMAGIC"
7879               flag.
7880
7881                       bool    sv_2bool(SV *const sv)
7882
7883       sv_2bool_flags
7884               This function is only used by "sv_true()" and friends,  and
7885               only if the latter's argument is neither "SvPOK", "SvIOK" nor
7886               "SvNOK".  If the flags contain "SV_GMAGIC", then it does an
7887               "mg_get()" first.
7888
7889                       bool    sv_2bool_flags(SV *sv, I32 flags)
7890
7891       sv_2cv  Using various gambits, try to get a CV from an SV; in addition,
7892               try if possible to set *st and *gvp to the stash and GV
7893               associated with it.  The flags in "lref" are passed to
7894               "gv_fetchsv".
7895
7896                       CV*     sv_2cv(SV* sv, HV **const st, GV **const gvp,
7897                                      const I32 lref)
7898
7899       sv_2io  Using various gambits, try to get an IO from an SV: the IO slot
7900               if its a GV; or the recursive result if we're an RV; or the IO
7901               slot of the symbol named after the PV if we're a string.
7902
7903               'Get' magic is ignored on the "sv" passed in, but will be
7904               called on "SvRV(sv)" if "sv" is an RV.
7905
7906                       IO*     sv_2io(SV *const sv)
7907
7908       sv_2iv_flags
7909               Return the integer value of an SV, doing any necessary string
7910               conversion.  If "flags" has the "SV_GMAGIC" bit set, does an
7911               "mg_get()" first.  Normally used via the "SvIV(sv)" and
7912               "SvIVx(sv)" macros.
7913
7914                       IV      sv_2iv_flags(SV *const sv, const I32 flags)
7915
7916       sv_2mortal
7917               Marks an existing SV as mortal.  The SV will be destroyed
7918               "soon", either by an explicit call to "FREETMPS", or by an
7919               implicit call at places such as statement boundaries.
7920               "SvTEMP()" is turned on which means that the SV's string buffer
7921               can be "stolen" if this SV is copied.  See also "sv_newmortal"
7922               and "sv_mortalcopy".
7923
7924                       SV*     sv_2mortal(SV *const sv)
7925
7926       sv_2nv_flags
7927               Return the num value of an SV, doing any necessary string or
7928               integer conversion.  If "flags" has the "SV_GMAGIC" bit set,
7929               does an "mg_get()" first.  Normally used via the "SvNV(sv)" and
7930               "SvNVx(sv)" macros.
7931
7932                       NV      sv_2nv_flags(SV *const sv, const I32 flags)
7933
7934       sv_2pvbyte
7935               Return a pointer to the byte-encoded representation of the SV,
7936               and set *lp to its length.  If the SV is marked as being
7937               encoded as UTF-8, it will downgrade it to a byte string as a
7938               side-effect, if possible.  If the SV cannot be downgraded, this
7939               croaks.
7940
7941               Usually accessed via the "SvPVbyte" macro.
7942
7943                       char*   sv_2pvbyte(SV *sv, STRLEN *const lp)
7944
7945       sv_2pvutf8
7946               Return a pointer to the UTF-8-encoded representation of the SV,
7947               and set *lp to its length.  May cause the SV to be upgraded to
7948               UTF-8 as a side-effect.
7949
7950               Usually accessed via the "SvPVutf8" macro.
7951
7952                       char*   sv_2pvutf8(SV *sv, STRLEN *const lp)
7953
7954       sv_2pv_flags
7955               Returns a pointer to the string value of an SV, and sets *lp to
7956               its length.  If flags has the "SV_GMAGIC" bit set, does an
7957               "mg_get()" first.  Coerces "sv" to a string if necessary.
7958               Normally invoked via the "SvPV_flags" macro.  "sv_2pv()" and
7959               "sv_2pv_nomg" usually end up here too.
7960
7961                       char*   sv_2pv_flags(SV *const sv, STRLEN *const lp,
7962                                            const I32 flags)
7963
7964       sv_2uv_flags
7965               Return the unsigned integer value of an SV, doing any necessary
7966               string conversion.  If "flags" has the "SV_GMAGIC" bit set,
7967               does an "mg_get()" first.  Normally used via the "SvUV(sv)" and
7968               "SvUVx(sv)" macros.
7969
7970                       UV      sv_2uv_flags(SV *const sv, const I32 flags)
7971
7972       sv_backoff
7973               Remove any string offset.  You should normally use the
7974               "SvOOK_off" macro wrapper instead.
7975
7976                       void    sv_backoff(SV *const sv)
7977
7978       sv_bless
7979               Blesses an SV into a specified package.  The SV must be an RV.
7980               The package must be designated by its stash (see "gv_stashpv").
7981               The reference count of the SV is unaffected.
7982
7983                       SV*     sv_bless(SV *const sv, HV *const stash)
7984
7985       sv_catpv
7986               Concatenates the "NUL"-terminated string onto the end of the
7987               string which is in the SV.  If the SV has the UTF-8 status set,
7988               then the bytes appended should be valid UTF-8.  Handles 'get'
7989               magic, but not 'set' magic.  See "sv_catpv_mg".
7990
7991                       void    sv_catpv(SV *const sv, const char* ptr)
7992
7993       sv_catpvf
7994               Processes its arguments like "sprintf", and appends the
7995               formatted output to an SV.  As with "sv_vcatpvfn" called with a
7996               non-null C-style variable argument list, argument reordering is
7997               not supported.  If the appended data contains "wide" characters
7998               (including, but not limited to, SVs with a UTF-8 PV formatted
7999               with %s, and characters >255 formatted with %c), the original
8000               SV might get upgraded to UTF-8.  Handles 'get' magic, but not
8001               'set' magic.  See "sv_catpvf_mg".  If the original SV was
8002               UTF-8, the pattern should be valid UTF-8; if the original SV
8003               was bytes, the pattern should be too.
8004
8005                       void    sv_catpvf(SV *const sv, const char *const pat,
8006                                         ...)
8007
8008       sv_catpvf_mg
8009               Like "sv_catpvf", but also handles 'set' magic.
8010
8011                       void    sv_catpvf_mg(SV *const sv,
8012                                            const char *const pat, ...)
8013
8014       sv_catpvn
8015               Concatenates the string onto the end of the string which is in
8016               the SV.  "len" indicates number of bytes to copy.  If the SV
8017               has the UTF-8 status set, then the bytes appended should be
8018               valid UTF-8.  Handles 'get' magic, but not 'set' magic.  See
8019               "sv_catpvn_mg".
8020
8021                       void    sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
8022
8023       sv_catpvn_flags
8024               Concatenates the string onto the end of the string which is in
8025               the SV.  The "len" indicates number of bytes to copy.
8026
8027               By default, the string appended is assumed to be valid UTF-8 if
8028               the SV has the UTF-8 status set, and a string of bytes
8029               otherwise.  One can force the appended string to be interpreted
8030               as UTF-8 by supplying the "SV_CATUTF8" flag, and as bytes by
8031               supplying the "SV_CATBYTES" flag; the SV or the string appended
8032               will be upgraded to UTF-8 if necessary.
8033
8034               If "flags" has the "SV_SMAGIC" bit set, will "mg_set" on "dsv"
8035               afterwards if appropriate.  "sv_catpvn" and "sv_catpvn_nomg"
8036               are implemented in terms of this function.
8037
8038                       void    sv_catpvn_flags(SV *const dstr,
8039                                               const char *sstr,
8040                                               const STRLEN len,
8041                                               const I32 flags)
8042
8043       sv_catpvn_nomg
8044               Like "sv_catpvn" but doesn't process magic.
8045
8046                       void    sv_catpvn_nomg(SV* sv, const char* ptr,
8047                                              STRLEN len)
8048
8049       sv_catpvs
8050               Like "sv_catpvn", but takes a literal string instead of a
8051               string/length pair.
8052
8053                       void    sv_catpvs(SV* sv, "literal string")
8054
8055       sv_catpvs_flags
8056               Like "sv_catpvn_flags", but takes a literal string instead of a
8057               string/length pair.
8058
8059                       void    sv_catpvs_flags(SV* sv, "literal string",
8060                                               I32 flags)
8061
8062       sv_catpvs_mg
8063               Like "sv_catpvn_mg", but takes a literal string instead of a
8064               string/length pair.
8065
8066                       void    sv_catpvs_mg(SV* sv, "literal string")
8067
8068       sv_catpvs_nomg
8069               Like "sv_catpvn_nomg", but takes a literal string instead of a
8070               string/length pair.
8071
8072                       void    sv_catpvs_nomg(SV* sv, "literal string")
8073
8074       sv_catpv_flags
8075               Concatenates the "NUL"-terminated string onto the end of the
8076               string which is in the SV.  If the SV has the UTF-8 status set,
8077               then the bytes appended should be valid UTF-8.  If "flags" has
8078               the "SV_SMAGIC" bit set, will "mg_set" on the modified SV if
8079               appropriate.
8080
8081                       void    sv_catpv_flags(SV *dstr, const char *sstr,
8082                                              const I32 flags)
8083
8084       sv_catpv_mg
8085               Like "sv_catpv", but also handles 'set' magic.
8086
8087                       void    sv_catpv_mg(SV *const sv, const char *const ptr)
8088
8089       sv_catpv_nomg
8090               Like "sv_catpv" but doesn't process magic.
8091
8092                       void    sv_catpv_nomg(SV* sv, const char* ptr)
8093
8094       sv_catsv
8095               Concatenates the string from SV "ssv" onto the end of the
8096               string in SV "dsv".  If "ssv" is null, does nothing; otherwise
8097               modifies only "dsv".  Handles 'get' magic on both SVs, but no
8098               'set' magic.  See "sv_catsv_mg" and "sv_catsv_nomg".
8099
8100                       void    sv_catsv(SV *dstr, SV *sstr)
8101
8102       sv_catsv_flags
8103               Concatenates the string from SV "ssv" onto the end of the
8104               string in SV "dsv".  If "ssv" is null, does nothing; otherwise
8105               modifies only "dsv".  If "flags" has the "SV_GMAGIC" bit set,
8106               will call "mg_get" on both SVs if appropriate.  If "flags" has
8107               the "SV_SMAGIC" bit set, "mg_set" will be called on the
8108               modified SV afterward, if appropriate.  "sv_catsv",
8109               "sv_catsv_nomg", and "sv_catsv_mg" are implemented in terms of
8110               this function.
8111
8112                       void    sv_catsv_flags(SV *const dsv, SV *const ssv,
8113                                              const I32 flags)
8114
8115       sv_catsv_nomg
8116               Like "sv_catsv" but doesn't process magic.
8117
8118                       void    sv_catsv_nomg(SV* dsv, SV* ssv)
8119
8120       sv_chop Efficient removal of characters from the beginning of the
8121               string buffer.  "SvPOK(sv)", or at least "SvPOKp(sv)", must be
8122               true and "ptr" must be a pointer to somewhere inside the string
8123               buffer.  "ptr" becomes the first character of the adjusted
8124               string.  Uses the "OOK" hack.  On return, only "SvPOK(sv)" and
8125               "SvPOKp(sv)" among the "OK" flags will be true.
8126
8127               Beware: after this function returns, "ptr" and SvPVX_const(sv)
8128               may no longer refer to the same chunk of data.
8129
8130               The unfortunate similarity of this function's name to that of
8131               Perl's "chop" operator is strictly coincidental.  This function
8132               works from the left; "chop" works from the right.
8133
8134                       void    sv_chop(SV *const sv, const char *const ptr)
8135
8136       sv_clear
8137               Clear an SV: call any destructors, free up any memory used by
8138               the body, and free the body itself.  The SV's head is not
8139               freed, although its type is set to all 1's so that it won't
8140               inadvertently be assumed to be live during global destruction
8141               etc.  This function should only be called when "REFCNT" is
8142               zero.  Most of the time you'll want to call "sv_free()" (or its
8143               macro wrapper "SvREFCNT_dec") instead.
8144
8145                       void    sv_clear(SV *const orig_sv)
8146
8147       sv_cmp  Compares the strings in two SVs.  Returns -1, 0, or 1
8148               indicating whether the string in "sv1" is less than, equal to,
8149               or greater than the string in "sv2".  Is UTF-8 and 'use bytes'
8150               aware, handles get magic, and will coerce its args to strings
8151               if necessary.  See also "sv_cmp_locale".
8152
8153                       I32     sv_cmp(SV *const sv1, SV *const sv2)
8154
8155       sv_cmp_flags
8156               Compares the strings in two SVs.  Returns -1, 0, or 1
8157               indicating whether the string in "sv1" is less than, equal to,
8158               or greater than the string in "sv2".  Is UTF-8 and 'use bytes'
8159               aware and will coerce its args to strings if necessary.  If the
8160               flags has the "SV_GMAGIC" bit set, it handles get magic.  See
8161               also "sv_cmp_locale_flags".
8162
8163                       I32     sv_cmp_flags(SV *const sv1, SV *const sv2,
8164                                            const U32 flags)
8165
8166       sv_cmp_locale
8167               Compares the strings in two SVs in a locale-aware manner.  Is
8168               UTF-8 and 'use bytes' aware, handles get magic, and will coerce
8169               its args to strings if necessary.  See also "sv_cmp".
8170
8171                       I32     sv_cmp_locale(SV *const sv1, SV *const sv2)
8172
8173       sv_cmp_locale_flags
8174               Compares the strings in two SVs in a locale-aware manner.  Is
8175               UTF-8 and 'use bytes' aware and will coerce its args to strings
8176               if necessary.  If the flags contain "SV_GMAGIC", it handles get
8177               magic.  See also "sv_cmp_flags".
8178
8179                       I32     sv_cmp_locale_flags(SV *const sv1,
8180                                                   SV *const sv2,
8181                                                   const U32 flags)
8182
8183       sv_collxfrm
8184               This calls "sv_collxfrm_flags" with the SV_GMAGIC flag.  See
8185               "sv_collxfrm_flags".
8186
8187                       char*   sv_collxfrm(SV *const sv, STRLEN *const nxp)
8188
8189       sv_collxfrm_flags
8190               Add Collate Transform magic to an SV if it doesn't already have
8191               it.  If the flags contain "SV_GMAGIC", it handles get-magic.
8192
8193               Any scalar variable may carry "PERL_MAGIC_collxfrm" magic that
8194               contains the scalar data of the variable, but transformed to
8195               such a format that a normal memory comparison can be used to
8196               compare the data according to the locale settings.
8197
8198                       char*   sv_collxfrm_flags(SV *const sv,
8199                                                 STRLEN *const nxp,
8200                                                 I32 const flags)
8201
8202       sv_copypv
8203               Copies a stringified representation of the source SV into the
8204               destination SV.  Automatically performs any necessary "mg_get"
8205               and coercion of numeric values into strings.  Guaranteed to
8206               preserve "UTF8" flag even from overloaded objects.  Similar in
8207               nature to "sv_2pv[_flags]" but operates directly on an SV
8208               instead of just the string.  Mostly uses "sv_2pv_flags" to do
8209               its work, except when that would lose the UTF-8'ness of the PV.
8210
8211                       void    sv_copypv(SV *const dsv, SV *const ssv)
8212
8213       sv_copypv_flags
8214               Implementation of "sv_copypv" and "sv_copypv_nomg".  Calls get
8215               magic iff flags has the "SV_GMAGIC" bit set.
8216
8217                       void    sv_copypv_flags(SV *const dsv, SV *const ssv,
8218                                               const I32 flags)
8219
8220       sv_copypv_nomg
8221               Like "sv_copypv", but doesn't invoke get magic first.
8222
8223                       void    sv_copypv_nomg(SV *const dsv, SV *const ssv)
8224
8225       SvCUR   Returns the length of the string which is in the SV.  See
8226               "SvLEN".
8227
8228                       STRLEN  SvCUR(SV* sv)
8229
8230       SvCUR_set
8231               Set the current length of the string which is in the SV.  See
8232               "SvCUR" and "SvIV_set">.
8233
8234                       void    SvCUR_set(SV* sv, STRLEN len)
8235
8236       sv_dec  Auto-decrement of the value in the SV, doing string to numeric
8237               conversion if necessary.  Handles 'get' magic and operator
8238               overloading.
8239
8240                       void    sv_dec(SV *const sv)
8241
8242       sv_dec_nomg
8243               Auto-decrement of the value in the SV, doing string to numeric
8244               conversion if necessary.  Handles operator overloading.  Skips
8245               handling 'get' magic.
8246
8247                       void    sv_dec_nomg(SV *const sv)
8248
8249       sv_derived_from
8250               Exactly like "sv_derived_from_pv", but doesn't take a "flags"
8251               parameter.
8252
8253                       bool    sv_derived_from(SV* sv, const char *const name)
8254
8255       sv_derived_from_pv
8256               Exactly like "sv_derived_from_pvn", but takes a nul-terminated
8257               string instead of a string/length pair.
8258
8259                       bool    sv_derived_from_pv(SV* sv,
8260                                                  const char *const name,
8261                                                  U32 flags)
8262
8263       sv_derived_from_pvn
8264               Returns a boolean indicating whether the SV is derived from the
8265               specified class at the C level.  To check derivation at the
8266               Perl level, call "isa()" as a normal Perl method.
8267
8268               Currently, the only significant value for "flags" is SVf_UTF8.
8269
8270                       bool    sv_derived_from_pvn(SV* sv,
8271                                                   const char *const name,
8272                                                   const STRLEN len, U32 flags)
8273
8274       sv_derived_from_sv
8275               Exactly like "sv_derived_from_pvn", but takes the name string
8276               in the form of an SV instead of a string/length pair. This is
8277               the advised form.
8278
8279                       bool    sv_derived_from_sv(SV* sv, SV *namesv,
8280                                                  U32 flags)
8281
8282       sv_does Like "sv_does_pv", but doesn't take a "flags" parameter.
8283
8284                       bool    sv_does(SV* sv, const char *const name)
8285
8286       sv_does_pv
8287               Like "sv_does_sv", but takes a nul-terminated string instead of
8288               an SV.
8289
8290                       bool    sv_does_pv(SV* sv, const char *const name,
8291                                          U32 flags)
8292
8293       sv_does_pvn
8294               Like "sv_does_sv", but takes a string/length pair instead of an
8295               SV.
8296
8297                       bool    sv_does_pvn(SV* sv, const char *const name,
8298                                           const STRLEN len, U32 flags)
8299
8300       sv_does_sv
8301               Returns a boolean indicating whether the SV performs a
8302               specific, named role.  The SV can be a Perl object or the name
8303               of a Perl class.
8304
8305                       bool    sv_does_sv(SV* sv, SV* namesv, U32 flags)
8306
8307       SvEND   Returns a pointer to the spot just after the last character in
8308               the string which is in the SV, where there is usually a
8309               trailing "NUL" character (even though Perl scalars do not
8310               strictly require it).  See "SvCUR".  Access the character as
8311               "*(SvEND(sv))".
8312
8313               Warning: If "SvCUR" is equal to "SvLEN", then "SvEND" points to
8314               unallocated memory.
8315
8316                       char*   SvEND(SV* sv)
8317
8318       sv_eq   Returns a boolean indicating whether the strings in the two SVs
8319               are identical.  Is UTF-8 and 'use bytes' aware, handles get
8320               magic, and will coerce its args to strings if necessary.
8321
8322                       I32     sv_eq(SV* sv1, SV* sv2)
8323
8324       sv_eq_flags
8325               Returns a boolean indicating whether the strings in the two SVs
8326               are identical.  Is UTF-8 and 'use bytes' aware and coerces its
8327               args to strings if necessary.  If the flags has the "SV_GMAGIC"
8328               bit set, it handles get-magic, too.
8329
8330                       I32     sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)
8331
8332       sv_force_normal_flags
8333               Undo various types of fakery on an SV, where fakery means "more
8334               than" a string: if the PV is a shared string, make a private
8335               copy; if we're a ref, stop refing; if we're a glob, downgrade
8336               to an "xpvmg"; if we're a copy-on-write scalar, this is the on-
8337               write time when we do the copy, and is also used locally; if
8338               this is a vstring, drop the vstring magic.  If "SV_COW_DROP_PV"
8339               is set then a copy-on-write scalar drops its PV buffer (if any)
8340               and becomes "SvPOK_off" rather than making a copy.  (Used where
8341               this scalar is about to be set to some other value.)  In
8342               addition, the "flags" parameter gets passed to
8343               "sv_unref_flags()" when unreffing.  "sv_force_normal" calls
8344               this function with flags set to 0.
8345
8346               This function is expected to be used to signal to perl that
8347               this SV is about to be written to, and any extra book-keeping
8348               needs to be taken care of.  Hence, it croaks on read-only
8349               values.
8350
8351                       void    sv_force_normal_flags(SV *const sv,
8352                                                     const U32 flags)
8353
8354       sv_free Decrement an SV's reference count, and if it drops to zero,
8355               call "sv_clear" to invoke destructors and free up any memory
8356               used by the body; finally, deallocating the SV's head itself.
8357               Normally called via a wrapper macro "SvREFCNT_dec".
8358
8359                       void    sv_free(SV *const sv)
8360
8361       SvGAMAGIC
8362               Returns true if the SV has get magic or overloading.  If either
8363               is true then the scalar is active data, and has the potential
8364               to return a new value every time it is accessed.  Hence you
8365               must be careful to only read it once per user logical operation
8366               and work with that returned value.  If neither is true then the
8367               scalar's value cannot change unless written to.
8368
8369                       U32     SvGAMAGIC(SV* sv)
8370
8371       sv_gets Get a line from the filehandle and store it into the SV,
8372               optionally appending to the currently-stored string.  If
8373               "append" is not 0, the line is appended to the SV instead of
8374               overwriting it.  "append" should be set to the byte offset that
8375               the appended string should start at in the SV (typically,
8376               "SvCUR(sv)" is a suitable choice).
8377
8378                       char*   sv_gets(SV *const sv, PerlIO *const fp,
8379                                       I32 append)
8380
8381       sv_get_backrefs
8382               NOTE: this function is experimental and may change or be
8383               removed without notice.
8384
8385               If "sv" is the target of a weak reference then it returns the
8386               back references structure associated with the sv; otherwise
8387               return "NULL".
8388
8389               When returning a non-null result the type of the return is
8390               relevant. If it is an AV then the elements of the AV are the
8391               weak reference RVs which point at this item. If it is any other
8392               type then the item itself is the weak reference.
8393
8394               See also "Perl_sv_add_backref()", "Perl_sv_del_backref()",
8395               "Perl_sv_kill_backrefs()"
8396
8397                       SV*     sv_get_backrefs(SV *const sv)
8398
8399       SvGROW  Expands the character buffer in the SV so that it has room for
8400               the indicated number of bytes (remember to reserve space for an
8401               extra trailing "NUL" character).  Calls "sv_grow" to perform
8402               the expansion if necessary.  Returns a pointer to the character
8403               buffer.  SV must be of type >= "SVt_PV".  One alternative is to
8404               call "sv_grow" if you are not sure of the type of SV.
8405
8406               You might mistakenly think that "len" is the number of bytes to
8407               add to the existing size, but instead it is the total size "sv"
8408               should be.
8409
8410                       char *  SvGROW(SV* sv, STRLEN len)
8411
8412       sv_grow Expands the character buffer in the SV.  If necessary, uses
8413               "sv_unref" and upgrades the SV to "SVt_PV".  Returns a pointer
8414               to the character buffer.  Use the "SvGROW" wrapper instead.
8415
8416                       char*   sv_grow(SV *const sv, STRLEN newlen)
8417
8418       sv_inc  Auto-increment of the value in the SV, doing string to numeric
8419               conversion if necessary.  Handles 'get' magic and operator
8420               overloading.
8421
8422                       void    sv_inc(SV *const sv)
8423
8424       sv_inc_nomg
8425               Auto-increment of the value in the SV, doing string to numeric
8426               conversion if necessary.  Handles operator overloading.  Skips
8427               handling 'get' magic.
8428
8429                       void    sv_inc_nomg(SV *const sv)
8430
8431       sv_insert
8432               Inserts and/or replaces a string at the specified offset/length
8433               within the SV.  Similar to the Perl "substr()" function, with
8434               "littlelen" bytes starting at "little" replacing "len" bytes of
8435               the string in "bigstr" starting at "offset".  Handles get
8436               magic.
8437
8438                       void    sv_insert(SV *const bigstr, const STRLEN offset,
8439                                         const STRLEN len,
8440                                         const char *const little,
8441                                         const STRLEN littlelen)
8442
8443       sv_insert_flags
8444               Same as "sv_insert", but the extra "flags" are passed to the
8445               "SvPV_force_flags" that applies to "bigstr".
8446
8447                       void    sv_insert_flags(SV *const bigstr,
8448                                               const STRLEN offset,
8449                                               const STRLEN len,
8450                                               const char *little,
8451                                               const STRLEN littlelen,
8452                                               const U32 flags)
8453
8454       SvIOK   Returns a U32 value indicating whether the SV contains an
8455               integer.
8456
8457                       U32     SvIOK(SV* sv)
8458
8459       SvIOK_notUV
8460               Returns a boolean indicating whether the SV contains a signed
8461               integer.
8462
8463                       bool    SvIOK_notUV(SV* sv)
8464
8465       SvIOK_off
8466               Unsets the IV status of an SV.
8467
8468                       void    SvIOK_off(SV* sv)
8469
8470       SvIOK_on
8471               Tells an SV that it is an integer.
8472
8473                       void    SvIOK_on(SV* sv)
8474
8475       SvIOK_only
8476               Tells an SV that it is an integer and disables all other "OK"
8477               bits.
8478
8479                       void    SvIOK_only(SV* sv)
8480
8481       SvIOK_only_UV
8482               Tells an SV that it is an unsigned integer and disables all
8483               other "OK" bits.
8484
8485                       void    SvIOK_only_UV(SV* sv)
8486
8487       SvIOKp  Returns a U32 value indicating whether the SV contains an
8488               integer.  Checks the private setting.  Use "SvIOK" instead.
8489
8490                       U32     SvIOKp(SV* sv)
8491
8492       SvIOK_UV
8493               Returns a boolean indicating whether the SV contains an integer
8494               that must be interpreted as unsigned.  A non-negative integer
8495               whose value is within the range of both an IV and a UV may be
8496               flagged as either "SvUOK" or "SvIOK".
8497
8498                       bool    SvIOK_UV(SV* sv)
8499
8500       sv_isa  Returns a boolean indicating whether the SV is blessed into the
8501               specified class.
8502
8503               This does not check for subtypes or method overloading. Use
8504               "sv_isa_sv" to verify an inheritance relationship in the same
8505               way as the "isa" operator by respecting any "isa()" method
8506               overloading; or "sv_derived_from_sv" to test directly on the
8507               actual object type.
8508
8509                       int     sv_isa(SV* sv, const char *const name)
8510
8511       sv_isa_sv
8512               NOTE: this function is experimental and may change or be
8513               removed without notice.
8514
8515               Returns a boolean indicating whether the SV is an object
8516               reference and is derived from the specified class, respecting
8517               any "isa()" method overloading it may have. Returns false if
8518               "sv" is not a reference to an object, or is not derived from
8519               the specified class.
8520
8521               This is the function used to implement the behaviour of the
8522               "isa" operator.
8523
8524               Does not invoke magic on "sv".
8525
8526               Not to be confused with the older "sv_isa" function, which does
8527               not use an overloaded "isa()" method, nor will check
8528               subclassing.
8529
8530                       bool    sv_isa_sv(SV* sv, SV* namesv)
8531
8532       SvIsCOW Returns a U32 value indicating whether the SV is Copy-On-Write
8533               (either shared hash key scalars, or full Copy On Write scalars
8534               if 5.9.0 is configured for COW).
8535
8536                       U32     SvIsCOW(SV* sv)
8537
8538       SvIsCOW_shared_hash
8539               Returns a boolean indicating whether the SV is Copy-On-Write
8540               shared hash key scalar.
8541
8542                       bool    SvIsCOW_shared_hash(SV* sv)
8543
8544       sv_isobject
8545               Returns a boolean indicating whether the SV is an RV pointing
8546               to a blessed object.  If the SV is not an RV, or if the object
8547               is not blessed, then this will return false.
8548
8549                       int     sv_isobject(SV* sv)
8550
8551       SvIV    Coerces the given SV to IV and returns it.  The returned value
8552               in many circumstances will get stored in "sv"'s IV slot, but
8553               not in all cases.  (Use "sv_setiv" to make sure it does).
8554
8555               See "SvIVx" for a version which guarantees to evaluate "sv"
8556               only once.
8557
8558                       IV      SvIV(SV* sv)
8559
8560       SvIV_nomg
8561               Like "SvIV" but doesn't process magic.
8562
8563                       IV      SvIV_nomg(SV* sv)
8564
8565       SvIV_set
8566               Set the value of the IV pointer in sv to val.  It is possible
8567               to perform the same function of this macro with an lvalue
8568               assignment to "SvIVX".  With future Perls, however, it will be
8569               more efficient to use "SvIV_set" instead of the lvalue
8570               assignment to "SvIVX".
8571
8572                       void    SvIV_set(SV* sv, IV val)
8573
8574       SvIVX   Returns the raw value in the SV's IV slot, without checks or
8575               conversions.  Only use when you are sure "SvIOK" is true.  See
8576               also "SvIV".
8577
8578                       IV      SvIVX(SV* sv)
8579
8580       SvIVx   Coerces the given SV to IV and returns it.  The returned value
8581               in many circumstances will get stored in "sv"'s IV slot, but
8582               not in all cases.  (Use "sv_setiv" to make sure it does).
8583
8584               This form guarantees to evaluate "sv" only once.  Only use this
8585               if "sv" is an expression with side effects, otherwise use the
8586               more efficient "SvIV".
8587
8588                       IV      SvIVx(SV* sv)
8589
8590       SvLEN   Returns the size of the string buffer in the SV, not including
8591               any part attributable to "SvOOK".  See "SvCUR".
8592
8593                       STRLEN  SvLEN(SV* sv)
8594
8595       sv_len  Returns the length of the string in the SV.  Handles magic and
8596               type coercion and sets the UTF8 flag appropriately.  See also
8597               "SvCUR", which gives raw access to the "xpv_cur" slot.
8598
8599                       STRLEN  sv_len(SV *const sv)
8600
8601       SvLEN_set
8602               Set the size of the string buffer for the SV. See "SvLEN".
8603
8604                       void    SvLEN_set(SV* sv, STRLEN len)
8605
8606       sv_len_utf8
8607               Returns the number of characters in the string in an SV,
8608               counting wide UTF-8 bytes as a single character.  Handles magic
8609               and type coercion.
8610
8611                       STRLEN  sv_len_utf8(SV *const sv)
8612
8613       sv_magic
8614               Adds magic to an SV.  First upgrades "sv" to type "SVt_PVMG" if
8615               necessary, then adds a new magic item of type "how" to the head
8616               of the magic list.
8617
8618               See "sv_magicext" (which "sv_magic" now calls) for a
8619               description of the handling of the "name" and "namlen"
8620               arguments.
8621
8622               You need to use "sv_magicext" to add magic to "SvREADONLY" SVs
8623               and also to add more than one instance of the same "how".
8624
8625                       void    sv_magic(SV *const sv, SV *const obj,
8626                                        const int how, const char *const name,
8627                                        const I32 namlen)
8628
8629       sv_magicext
8630               Adds magic to an SV, upgrading it if necessary.  Applies the
8631               supplied "vtable" and returns a pointer to the magic added.
8632
8633               Note that "sv_magicext" will allow things that "sv_magic" will
8634               not.  In particular, you can add magic to "SvREADONLY" SVs, and
8635               add more than one instance of the same "how".
8636
8637               If "namlen" is greater than zero then a "savepvn" copy of
8638               "name" is stored, if "namlen" is zero then "name" is stored as-
8639               is and - as another special case - if "(name && namlen ==
8640               HEf_SVKEY)" then "name" is assumed to contain an SV* and is
8641               stored as-is with its "REFCNT" incremented.
8642
8643               (This is now used as a subroutine by "sv_magic".)
8644
8645                       MAGIC * sv_magicext(SV *const sv, SV *const obj,
8646                                           const int how,
8647                                           const MGVTBL *const vtbl,
8648                                           const char *const name,
8649                                           const I32 namlen)
8650
8651       SvMAGIC_set
8652               Set the value of the MAGIC pointer in "sv" to val.  See
8653               "SvIV_set".
8654
8655                       void    SvMAGIC_set(SV* sv, MAGIC* val)
8656
8657       sv_mortalcopy
8658               Creates a new SV which is a copy of the original SV (using
8659               "sv_setsv").  The new SV is marked as mortal.  It will be
8660               destroyed "soon", either by an explicit call to "FREETMPS", or
8661               by an implicit call at places such as statement boundaries.
8662               See also "sv_newmortal" and "sv_2mortal".
8663
8664                       SV*     sv_mortalcopy(SV *const oldsv)
8665
8666       sv_mortalcopy_flags
8667               Like "sv_mortalcopy", but the extra "flags" are passed to the
8668               "sv_setsv_flags".
8669
8670                       SV*     sv_mortalcopy_flags(SV *const oldsv, U32 flags)
8671
8672       sv_newmortal
8673               Creates a new null SV which is mortal.  The reference count of
8674               the SV is set to 1.  It will be destroyed "soon", either by an
8675               explicit call to "FREETMPS", or by an implicit call at places
8676               such as statement boundaries.  See also "sv_mortalcopy" and
8677               "sv_2mortal".
8678
8679                       SV*     sv_newmortal()
8680
8681       sv_newref
8682               Increment an SV's reference count.  Use the "SvREFCNT_inc()"
8683               wrapper instead.
8684
8685                       SV*     sv_newref(SV *const sv)
8686
8687       SvNIOK  Returns a U32 value indicating whether the SV contains a
8688               number, integer or double.
8689
8690                       U32     SvNIOK(SV* sv)
8691
8692       SvNIOK_off
8693               Unsets the NV/IV status of an SV.
8694
8695                       void    SvNIOK_off(SV* sv)
8696
8697       SvNIOKp Returns a U32 value indicating whether the SV contains a
8698               number, integer or double.  Checks the private setting.  Use
8699               "SvNIOK" instead.
8700
8701                       U32     SvNIOKp(SV* sv)
8702
8703       SvNOK   Returns a U32 value indicating whether the SV contains a
8704               double.
8705
8706                       U32     SvNOK(SV* sv)
8707
8708       SvNOK_off
8709               Unsets the NV status of an SV.
8710
8711                       void    SvNOK_off(SV* sv)
8712
8713       SvNOK_on
8714               Tells an SV that it is a double.
8715
8716                       void    SvNOK_on(SV* sv)
8717
8718       SvNOK_only
8719               Tells an SV that it is a double and disables all other OK bits.
8720
8721                       void    SvNOK_only(SV* sv)
8722
8723       SvNOKp  Returns a U32 value indicating whether the SV contains a
8724               double.  Checks the private setting.  Use "SvNOK" instead.
8725
8726                       U32     SvNOKp(SV* sv)
8727
8728       SvNV    Coerces the given SV to NV and returns it.  The returned value
8729               in many circumstances will get stored in "sv"'s NV slot, but
8730               not in all cases.  (Use "sv_setnv" to make sure it does).
8731
8732               See "SvNVx" for a version which guarantees to evaluate "sv"
8733               only once.
8734
8735                       NV      SvNV(SV* sv)
8736
8737       SvNV_nomg
8738               Like "SvNV" but doesn't process magic.
8739
8740                       NV      SvNV_nomg(SV* sv)
8741
8742       SvNV_set
8743               Set the value of the NV pointer in "sv" to val.  See
8744               "SvIV_set".
8745
8746                       void    SvNV_set(SV* sv, NV val)
8747
8748       SvNVX   Returns the raw value in the SV's NV slot, without checks or
8749               conversions.  Only use when you are sure "SvNOK" is true.  See
8750               also "SvNV".
8751
8752                       NV      SvNVX(SV* sv)
8753
8754       SvNVx   Coerces the given SV to NV and returns it.  The returned value
8755               in many circumstances will get stored in "sv"'s NV slot, but
8756               not in all cases.  (Use "sv_setnv" to make sure it does).
8757
8758               This form guarantees to evaluate "sv" only once.  Only use this
8759               if "sv" is an expression with side effects, otherwise use the
8760               more efficient "SvNV".
8761
8762                       NV      SvNVx(SV* sv)
8763
8764       SvOK    Returns a U32 value indicating whether the value is defined.
8765               This is only meaningful for scalars.
8766
8767                       U32     SvOK(SV* sv)
8768
8769       SvOOK   Returns a U32 indicating whether the pointer to the string
8770               buffer is offset.  This hack is used internally to speed up
8771               removal of characters from the beginning of a "SvPV".  When
8772               "SvOOK" is true, then the start of the allocated string buffer
8773               is actually "SvOOK_offset()" bytes before "SvPVX".  This offset
8774               used to be stored in "SvIVX", but is now stored within the
8775               spare part of the buffer.
8776
8777                       U32     SvOOK(SV* sv)
8778
8779       SvOOK_offset
8780               Reads into "len" the offset from "SvPVX" back to the true start
8781               of the allocated buffer, which will be non-zero if "sv_chop"
8782               has been used to efficiently remove characters from start of
8783               the buffer.  Implemented as a macro, which takes the address of
8784               "len", which must be of type "STRLEN".  Evaluates "sv" more
8785               than once.  Sets "len" to 0 if "SvOOK(sv)" is false.
8786
8787                       void    SvOOK_offset(SV*sv, STRLEN len)
8788
8789       SvPOK   Returns a U32 value indicating whether the SV contains a
8790               character string.
8791
8792                       U32     SvPOK(SV* sv)
8793
8794       SvPOK_off
8795               Unsets the PV status of an SV.
8796
8797                       void    SvPOK_off(SV* sv)
8798
8799       SvPOK_on
8800               Tells an SV that it is a string.
8801
8802                       void    SvPOK_on(SV* sv)
8803
8804       SvPOK_only
8805               Tells an SV that it is a string and disables all other "OK"
8806               bits.  Will also turn off the UTF-8 status.
8807
8808                       void    SvPOK_only(SV* sv)
8809
8810       SvPOK_only_UTF8
8811               Tells an SV that it is a string and disables all other "OK"
8812               bits, and leaves the UTF-8 status as it was.
8813
8814                       void    SvPOK_only_UTF8(SV* sv)
8815
8816       SvPOKp  Returns a U32 value indicating whether the SV contains a
8817               character string.  Checks the private setting.  Use "SvPOK"
8818               instead.
8819
8820                       U32     SvPOKp(SV* sv)
8821
8822       sv_pos_b2u
8823               Converts the value pointed to by "offsetp" from a count of
8824               bytes from the start of the string, to a count of the
8825               equivalent number of UTF-8 chars.  Handles magic and type
8826               coercion.
8827
8828               Use "sv_pos_b2u_flags" in preference, which correctly handles
8829               strings longer than 2Gb.
8830
8831                       void    sv_pos_b2u(SV *const sv, I32 *const offsetp)
8832
8833       sv_pos_b2u_flags
8834               Converts "offset" from a count of bytes from the start of the
8835               string, to a count of the equivalent number of UTF-8 chars.
8836               Handles type coercion.  "flags" is passed to "SvPV_flags", and
8837               usually should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
8838
8839                       STRLEN  sv_pos_b2u_flags(SV *const sv,
8840                                                STRLEN const offset, U32 flags)
8841
8842       sv_pos_u2b
8843               Converts the value pointed to by "offsetp" from a count of
8844               UTF-8 chars from the start of the string, to a count of the
8845               equivalent number of bytes; if "lenp" is non-zero, it does the
8846               same to "lenp", but this time starting from the offset, rather
8847               than from the start of the string.  Handles magic and type
8848               coercion.
8849
8850               Use "sv_pos_u2b_flags" in preference, which correctly handles
8851               strings longer than 2Gb.
8852
8853                       void    sv_pos_u2b(SV *const sv, I32 *const offsetp,
8854                                          I32 *const lenp)
8855
8856       sv_pos_u2b_flags
8857               Converts the offset from a count of UTF-8 chars from the start
8858               of the string, to a count of the equivalent number of bytes; if
8859               "lenp" is non-zero, it does the same to "lenp", but this time
8860               starting from "offset", rather than from the start of the
8861               string.  Handles type coercion.  "flags" is passed to
8862               "SvPV_flags", and usually should be "SV_GMAGIC|SV_CONST_RETURN"
8863               to handle magic.
8864
8865                       STRLEN  sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
8866                                                STRLEN *const lenp, U32 flags)
8867
8868       SvPV    Returns a pointer to the string in the SV, or a stringified
8869               form of the SV if the SV does not contain a string.  The SV may
8870               cache the stringified version becoming "SvPOK".  Handles 'get'
8871               magic.  The "len" variable will be set to the length of the
8872               string (this is a macro, so don't use &len).  See also "SvPVx"
8873               for a version which guarantees to evaluate "sv" only once.
8874
8875               Note that there is no guarantee that the return value of
8876               "SvPV()" is equal to "SvPVX(sv)", or that "SvPVX(sv)" contains
8877               valid data, or that successive calls to "SvPV(sv)" will return
8878               the same pointer value each time.  This is due to the way that
8879               things like overloading and Copy-On-Write are handled.  In
8880               these cases, the return value may point to a temporary buffer
8881               or similar.  If you absolutely need the "SvPVX" field to be
8882               valid (for example, if you intend to write to it), then see
8883               "SvPV_force".
8884
8885                       char*   SvPV(SV* sv, STRLEN len)
8886
8887       SvPVbyte
8888               Like "SvPV", but converts "sv" to byte representation first if
8889               necessary.  If the SV cannot be downgraded from UTF-8, this
8890               croaks.
8891
8892                       char*   SvPVbyte(SV* sv, STRLEN len)
8893
8894       SvPVbyte_force
8895               Like "SvPV_force", but converts "sv" to byte representation
8896               first if necessary.  If the SV cannot be downgraded from UTF-8,
8897               this croaks.
8898
8899                       char*   SvPVbyte_force(SV* sv, STRLEN len)
8900
8901       SvPVbyte_nolen
8902               Like "SvPV_nolen", but converts "sv" to byte representation
8903               first if necessary.  If the SV cannot be downgraded from UTF-8,
8904               this croaks.
8905
8906                       char*   SvPVbyte_nolen(SV* sv)
8907
8908       SvPVbyte_nomg
8909               Like "SvPVbyte", but does not process get magic.
8910
8911                       char*   SvPVbyte_nomg(SV* sv, STRLEN len)
8912
8913       sv_pvbyten_force
8914               The backend for the "SvPVbytex_force" macro.  Always use the
8915               macro instead.  If the SV cannot be downgraded from UTF-8, this
8916               croaks.
8917
8918                       char*   sv_pvbyten_force(SV *const sv, STRLEN *const lp)
8919
8920       SvPVbyte_or_null
8921               Like "SvPVbyte", but when "sv" is undef, returns "NULL".
8922
8923                       char*   SvPVbyte_or_null(SV* sv, STRLEN len)
8924
8925       SvPVbyte_or_null_nomg
8926               Like "SvPVbyte_or_null", but does not process get magic.
8927
8928                       char*   SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
8929
8930       SvPVbytex
8931               Like "SvPV", but converts "sv" to byte representation first if
8932               necessary.  Guarantees to evaluate "sv" only once; use the more
8933               efficient "SvPVbyte" otherwise.  If the SV cannot be downgraded
8934               from UTF-8, this croaks.
8935
8936                       char*   SvPVbytex(SV* sv, STRLEN len)
8937
8938       SvPVbytex_force
8939               Like "SvPV_force", but converts "sv" to byte representation
8940               first if necessary.  Guarantees to evaluate "sv" only once; use
8941               the more efficient "SvPVbyte_force" otherwise.  If the SV
8942               cannot be downgraded from UTF-8, this croaks.
8943
8944                       char*   SvPVbytex_force(SV* sv, STRLEN len)
8945
8946       SvPVCLEAR
8947               Ensures that sv is a SVt_PV and that its SvCUR is 0, and that
8948               it is properly null terminated. Equivalent to sv_setpvs(""),
8949               but more efficient.
8950
8951                       char *  SvPVCLEAR(SV* sv)
8952
8953       SvPV_force
8954               Like "SvPV" but will force the SV into containing a string
8955               ("SvPOK"), and only a string ("SvPOK_only"), by hook or by
8956               crook.  You need force if you are going to update the "SvPVX"
8957               directly.  Processes get magic.
8958
8959               Note that coercing an arbitrary scalar into a plain PV will
8960               potentially strip useful data from it.  For example if the SV
8961               was "SvROK", then the referent will have its reference count
8962               decremented, and the SV itself may be converted to an "SvPOK"
8963               scalar with a string buffer containing a value such as
8964               "ARRAY(0x1234)".
8965
8966                       char*   SvPV_force(SV* sv, STRLEN len)
8967
8968       SvPV_force_nomg
8969               Like "SvPV_force", but doesn't process get magic.
8970
8971                       char*   SvPV_force_nomg(SV* sv, STRLEN len)
8972
8973       SvPV_nolen
8974               Like "SvPV" but doesn't set a length variable.
8975
8976                       char*   SvPV_nolen(SV* sv)
8977
8978       SvPV_nomg
8979               Like "SvPV" but doesn't process magic.
8980
8981                       char*   SvPV_nomg(SV* sv, STRLEN len)
8982
8983       SvPV_nomg_nolen
8984               Like "SvPV_nolen" but doesn't process magic.
8985
8986                       char*   SvPV_nomg_nolen(SV* sv)
8987
8988       sv_pvn_force
8989               Get a sensible string out of the SV somehow.  A private
8990               implementation of the "SvPV_force" macro for compilers which
8991               can't cope with complex macro expressions.  Always use the
8992               macro instead.
8993
8994                       char*   sv_pvn_force(SV* sv, STRLEN* lp)
8995
8996       sv_pvn_force_flags
8997               Get a sensible string out of the SV somehow.  If "flags" has
8998               the "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate,
8999               else not.  "sv_pvn_force" and "sv_pvn_force_nomg" are
9000               implemented in terms of this function.  You normally want to
9001               use the various wrapper macros instead: see "SvPV_force" and
9002               "SvPV_force_nomg".
9003
9004                       char*   sv_pvn_force_flags(SV *const sv,
9005                                                  STRLEN *const lp,
9006                                                  const I32 flags)
9007
9008       SvPV_set
9009               This is probably not what you want to use, you probably wanted
9010               "sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
9011
9012               Set the value of the PV pointer in "sv" to the Perl allocated
9013               "NUL"-terminated string "val".  See also "SvIV_set".
9014
9015               Remember to free the previous PV buffer. There are many things
9016               to check.  Beware that the existing pointer may be involved in
9017               copy-on-write or other mischief, so do "SvOOK_off(sv)" and use
9018               "sv_force_normal" or "SvPV_force" (or check the "SvIsCOW" flag)
9019               first to make sure this modification is safe. Then finally, if
9020               it is not a COW, call "SvPV_free" to free the previous PV
9021               buffer.
9022
9023                       void    SvPV_set(SV* sv, char* val)
9024
9025       SvPVutf8
9026               Like "SvPV", but converts "sv" to UTF-8 first if necessary.
9027
9028                       char*   SvPVutf8(SV* sv, STRLEN len)
9029
9030       sv_pvutf8n_force
9031               The backend for the "SvPVutf8x_force" macro.  Always use the
9032               macro instead.
9033
9034                       char*   sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
9035
9036       SvPVutf8x
9037               Like "SvPV", but converts "sv" to UTF-8 first if necessary.
9038               Guarantees to evaluate "sv" only once; use the more efficient
9039               "SvPVutf8" otherwise.
9040
9041                       char*   SvPVutf8x(SV* sv, STRLEN len)
9042
9043       SvPVutf8x_force
9044               Like "SvPV_force", but converts "sv" to UTF-8 first if
9045               necessary.  Guarantees to evaluate "sv" only once; use the more
9046               efficient "SvPVutf8_force" otherwise.
9047
9048                       char*   SvPVutf8x_force(SV* sv, STRLEN len)
9049
9050       SvPVutf8_force
9051               Like "SvPV_force", but converts "sv" to UTF-8 first if
9052               necessary.
9053
9054                       char*   SvPVutf8_force(SV* sv, STRLEN len)
9055
9056       SvPVutf8_nolen
9057               Like "SvPV_nolen", but converts "sv" to UTF-8 first if
9058               necessary.
9059
9060                       char*   SvPVutf8_nolen(SV* sv)
9061
9062       SvPVutf8_nomg
9063               Like "SvPVutf8", but does not process get magic.
9064
9065                       char*   SvPVutf8_nomg(SV* sv, STRLEN len)
9066
9067       SvPVutf8_or_null
9068               Like "SvPVutf8", but when "sv" is undef, returns "NULL".
9069
9070                       char*   SvPVutf8_or_null(SV* sv, STRLEN len)
9071
9072       SvPVutf8_or_null_nomg
9073               Like "SvPVutf8_or_null", but does not process get magic.
9074
9075                       char*   SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
9076
9077       SvPVX   Returns a pointer to the physical string in the SV.  The SV
9078               must contain a string.  Prior to 5.9.3 it is not safe to
9079               execute this macro unless the SV's type >= "SVt_PV".
9080
9081               This is also used to store the name of an autoloaded subroutine
9082               in an XS AUTOLOAD routine.  See "Autoloading with XSUBs" in
9083               perlguts.
9084
9085                       char*   SvPVX(SV* sv)
9086
9087       SvPVx   A version of "SvPV" which guarantees to evaluate "sv" only
9088               once.  Only use this if "sv" is an expression with side
9089               effects, otherwise use the more efficient "SvPV".
9090
9091                       char*   SvPVx(SV* sv, STRLEN len)
9092
9093       SvREADONLY
9094               Returns true if the argument is readonly, otherwise returns
9095               false.  Exposed to perl code via Internals::SvREADONLY().
9096
9097                       U32     SvREADONLY(SV* sv)
9098
9099       SvREADONLY_off
9100               Mark an object as not-readonly. Exactly what this mean depends
9101               on the object type. Exposed to perl code via
9102               Internals::SvREADONLY().
9103
9104                       U32     SvREADONLY_off(SV* sv)
9105
9106       SvREADONLY_on
9107               Mark an object as readonly. Exactly what this means depends on
9108               the object type. Exposed to perl code via
9109               Internals::SvREADONLY().
9110
9111                       U32     SvREADONLY_on(SV* sv)
9112
9113       sv_ref  Returns a SV describing what the SV passed in is a reference
9114               to.
9115
9116               dst can be a SV to be set to the description or NULL, in which
9117               case a mortal SV is returned.
9118
9119               If ob is true and the SV is blessed, the description is the
9120               class name, otherwise it is the type of the SV, "SCALAR",
9121               "ARRAY" etc.
9122
9123                       SV*     sv_ref(SV *dst, const SV *const sv,
9124                                      const int ob)
9125
9126       SvREFCNT
9127               Returns the value of the object's reference count. Exposed to
9128               perl code via Internals::SvREFCNT().
9129
9130                       U32     SvREFCNT(SV* sv)
9131
9132       SvREFCNT_dec
9133               Decrements the reference count of the given SV.  "sv" may be
9134               "NULL".
9135
9136                       void    SvREFCNT_dec(SV *sv)
9137
9138       SvREFCNT_dec_NN
9139               Same as "SvREFCNT_dec", but can only be used if you know "sv"
9140               is not "NULL".  Since we don't have to check the NULLness, it's
9141               faster and smaller.
9142
9143                       void    SvREFCNT_dec_NN(SV *sv)
9144
9145       SvREFCNT_inc
9146               Increments the reference count of the given SV, returning the
9147               SV.
9148
9149               All of the following "SvREFCNT_inc"* are optimized versions of
9150               "SvREFCNT_inc", and can be replaced with "SvREFCNT_inc".
9151
9152                       SV *    SvREFCNT_inc(SV *sv)
9153
9154       SvREFCNT_inc_NN
9155               Same as "SvREFCNT_inc", but can only be used if you know "sv"
9156               is not "NULL".  Since we don't have to check the NULLness, it's
9157               faster and smaller.
9158
9159                       SV *    SvREFCNT_inc_NN(SV *sv)
9160
9161       SvREFCNT_inc_simple
9162               Same as "SvREFCNT_inc", but can only be used with expressions
9163               without side effects.  Since we don't have to store a temporary
9164               value, it's faster.
9165
9166                       SV*     SvREFCNT_inc_simple(SV* sv)
9167
9168       SvREFCNT_inc_simple_NN
9169               Same as "SvREFCNT_inc_simple", but can only be used if you know
9170               "sv" is not "NULL".  Since we don't have to check the NULLness,
9171               it's faster and smaller.
9172
9173                       SV*     SvREFCNT_inc_simple_NN(SV* sv)
9174
9175       SvREFCNT_inc_simple_void
9176               Same as "SvREFCNT_inc_simple", but can only be used if you
9177               don't need the return value.  The macro doesn't need to return
9178               a meaningful value.
9179
9180                       void    SvREFCNT_inc_simple_void(SV* sv)
9181
9182       SvREFCNT_inc_simple_void_NN
9183               Same as "SvREFCNT_inc", but can only be used if you don't need
9184               the return value, and you know that "sv" is not "NULL".  The
9185               macro doesn't need to return a meaningful value, or check for
9186               NULLness, so it's smaller and faster.
9187
9188                       void    SvREFCNT_inc_simple_void_NN(SV* sv)
9189
9190       SvREFCNT_inc_void
9191               Same as "SvREFCNT_inc", but can only be used if you don't need
9192               the return value.  The macro doesn't need to return a
9193               meaningful value.
9194
9195                       void    SvREFCNT_inc_void(SV *sv)
9196
9197       SvREFCNT_inc_void_NN
9198               Same as "SvREFCNT_inc", but can only be used if you don't need
9199               the return value, and you know that "sv" is not "NULL".  The
9200               macro doesn't need to return a meaningful value, or check for
9201               NULLness, so it's smaller and faster.
9202
9203                       void    SvREFCNT_inc_void_NN(SV* sv)
9204
9205       sv_reftype
9206               Returns a string describing what the SV is a reference to.
9207
9208               If ob is true and the SV is blessed, the string is the class
9209               name, otherwise it is the type of the SV, "SCALAR", "ARRAY"
9210               etc.
9211
9212                       const char* sv_reftype(const SV *const sv, const int ob)
9213
9214       sv_replace
9215               Make the first argument a copy of the second, then delete the
9216               original.  The target SV physically takes over ownership of the
9217               body of the source SV and inherits its flags; however, the
9218               target keeps any magic it owns, and any magic in the source is
9219               discarded.  Note that this is a rather specialist SV copying
9220               operation; most of the time you'll want to use "sv_setsv" or
9221               one of its many macro front-ends.
9222
9223                       void    sv_replace(SV *const sv, SV *const nsv)
9224
9225       sv_report_used
9226               Dump the contents of all SVs not yet freed (debugging aid).
9227
9228                       void    sv_report_used()
9229
9230       sv_reset
9231               Underlying implementation for the "reset" Perl function.  Note
9232               that the perl-level function is vaguely deprecated.
9233
9234                       void    sv_reset(const char* s, HV *const stash)
9235
9236       SvROK   Tests if the SV is an RV.
9237
9238                       U32     SvROK(SV* sv)
9239
9240       SvROK_off
9241               Unsets the RV status of an SV.
9242
9243                       void    SvROK_off(SV* sv)
9244
9245       SvROK_on
9246               Tells an SV that it is an RV.
9247
9248                       void    SvROK_on(SV* sv)
9249
9250       SvRV    Dereferences an RV to return the SV.
9251
9252                       SV*     SvRV(SV* sv)
9253
9254       SvRV_set
9255               Set the value of the RV pointer in "sv" to val.  See
9256               "SvIV_set".
9257
9258                       void    SvRV_set(SV* sv, SV* val)
9259
9260       sv_rvunweaken
9261               Unweaken a reference: Clear the "SvWEAKREF" flag on this RV;
9262               remove the backreference to this RV from the array of
9263               backreferences associated with the target SV, increment the
9264               refcount of the target.  Silently ignores "undef" and warns on
9265               non-weak references.
9266
9267                       SV*     sv_rvunweaken(SV *const sv)
9268
9269       sv_rvweaken
9270               Weaken a reference: set the "SvWEAKREF" flag on this RV; give
9271               the referred-to SV "PERL_MAGIC_backref" magic if it hasn't
9272               already; and push a back-reference to this RV onto the array of
9273               backreferences associated with that magic.  If the RV is
9274               magical, set magic will be called after the RV is cleared.
9275               Silently ignores "undef" and warns on already-weak references.
9276
9277                       SV*     sv_rvweaken(SV *const sv)
9278
9279       sv_setiv
9280               Copies an integer into the given SV, upgrading first if
9281               necessary.  Does not handle 'set' magic.  See also
9282               "sv_setiv_mg".
9283
9284                       void    sv_setiv(SV *const sv, const IV num)
9285
9286       sv_setiv_mg
9287               Like "sv_setiv", but also handles 'set' magic.
9288
9289                       void    sv_setiv_mg(SV *const sv, const IV i)
9290
9291       sv_setnv
9292               Copies a double into the given SV, upgrading first if
9293               necessary.  Does not handle 'set' magic.  See also
9294               "sv_setnv_mg".
9295
9296                       void    sv_setnv(SV *const sv, const NV num)
9297
9298       sv_setnv_mg
9299               Like "sv_setnv", but also handles 'set' magic.
9300
9301                       void    sv_setnv_mg(SV *const sv, const NV num)
9302
9303       sv_setpv
9304               Copies a string into an SV.  The string must be terminated with
9305               a "NUL" character, and not contain embeded "NUL"'s.  Does not
9306               handle 'set' magic.  See "sv_setpv_mg".
9307
9308                       void    sv_setpv(SV *const sv, const char *const ptr)
9309
9310       sv_setpvf
9311               Works like "sv_catpvf" but copies the text into the SV instead
9312               of appending it.  Does not handle 'set' magic.  See
9313               "sv_setpvf_mg".
9314
9315                       void    sv_setpvf(SV *const sv, const char *const pat,
9316                                         ...)
9317
9318       sv_setpvf_mg
9319               Like "sv_setpvf", but also handles 'set' magic.
9320
9321                       void    sv_setpvf_mg(SV *const sv,
9322                                            const char *const pat, ...)
9323
9324       sv_setpviv
9325               DEPRECATED!  It is planned to remove this function from a
9326               future release of Perl.  Do not use it for new code; remove it
9327               from existing code.
9328
9329               Copies an integer into the given SV, also updating its string
9330               value.  Does not handle 'set' magic.  See "sv_setpviv_mg".
9331
9332                       void    sv_setpviv(SV *const sv, const IV num)
9333
9334       sv_setpviv_mg
9335               DEPRECATED!  It is planned to remove this function from a
9336               future release of Perl.  Do not use it for new code; remove it
9337               from existing code.
9338
9339               Like "sv_setpviv", but also handles 'set' magic.
9340
9341                       void    sv_setpviv_mg(SV *const sv, const IV iv)
9342
9343       sv_setpvn
9344               Copies a string (possibly containing embedded "NUL" characters)
9345               into an SV.  The "len" parameter indicates the number of bytes
9346               to be copied.  If the "ptr" argument is NULL the SV will become
9347               undefined.  Does not handle 'set' magic.  See "sv_setpvn_mg".
9348
9349               The UTF-8 flag is not changed by this function.  A terminating
9350               NUL byte is guaranteed.
9351
9352                       void    sv_setpvn(SV *const sv, const char *const ptr,
9353                                         const STRLEN len)
9354
9355       sv_setpvn_mg
9356               Like "sv_setpvn", but also handles 'set' magic.
9357
9358                       void    sv_setpvn_mg(SV *const sv,
9359                                            const char *const ptr,
9360                                            const STRLEN len)
9361
9362       sv_setpvs
9363               Like "sv_setpvn", but takes a literal string instead of a
9364               string/length pair.
9365
9366                       void    sv_setpvs(SV* sv, "literal string")
9367
9368       sv_setpvs_mg
9369               Like "sv_setpvn_mg", but takes a literal string instead of a
9370               string/length pair.
9371
9372                       void    sv_setpvs_mg(SV* sv, "literal string")
9373
9374       sv_setpv_bufsize
9375               Sets the SV to be a string of cur bytes length, with at least
9376               len bytes available. Ensures that there is a null byte at
9377               SvEND.  Returns a char * pointer to the SvPV buffer.
9378
9379                       char  * sv_setpv_bufsize(SV *const sv, const STRLEN cur,
9380                                                const STRLEN len)
9381
9382       sv_setpv_mg
9383               Like "sv_setpv", but also handles 'set' magic.
9384
9385                       void    sv_setpv_mg(SV *const sv, const char *const ptr)
9386
9387       sv_setref_iv
9388               Copies an integer into a new SV, optionally blessing the SV.
9389               The "rv" argument will be upgraded to an RV.  That RV will be
9390               modified to point to the new SV.  The "classname" argument
9391               indicates the package for the blessing.  Set "classname" to
9392               "NULL" to avoid the blessing.  The new SV will have a reference
9393               count of 1, and the RV will be returned.
9394
9395                       SV*     sv_setref_iv(SV *const rv,
9396                                            const char *const classname,
9397                                            const IV iv)
9398
9399       sv_setref_nv
9400               Copies a double into a new SV, optionally blessing the SV.  The
9401               "rv" argument will be upgraded to an RV.  That RV will be
9402               modified to point to the new SV.  The "classname" argument
9403               indicates the package for the blessing.  Set "classname" to
9404               "NULL" to avoid the blessing.  The new SV will have a reference
9405               count of 1, and the RV will be returned.
9406
9407                       SV*     sv_setref_nv(SV *const rv,
9408                                            const char *const classname,
9409                                            const NV nv)
9410
9411       sv_setref_pv
9412               Copies a pointer into a new SV, optionally blessing the SV.
9413               The "rv" argument will be upgraded to an RV.  That RV will be
9414               modified to point to the new SV.  If the "pv" argument is
9415               "NULL", then "PL_sv_undef" will be placed into the SV.  The
9416               "classname" argument indicates the package for the blessing.
9417               Set "classname" to "NULL" to avoid the blessing.  The new SV
9418               will have a reference count of 1, and the RV will be returned.
9419
9420               Do not use with other Perl types such as HV, AV, SV, CV,
9421               because those objects will become corrupted by the pointer copy
9422               process.
9423
9424               Note that "sv_setref_pvn" copies the string while this copies
9425               the pointer.
9426
9427                       SV*     sv_setref_pv(SV *const rv,
9428                                            const char *const classname,
9429                                            void *const pv)
9430
9431       sv_setref_pvn
9432               Copies a string into a new SV, optionally blessing the SV.  The
9433               length of the string must be specified with "n".  The "rv"
9434               argument will be upgraded to an RV.  That RV will be modified
9435               to point to the new SV.  The "classname" argument indicates the
9436               package for the blessing.  Set "classname" to "NULL" to avoid
9437               the blessing.  The new SV will have a reference count of 1, and
9438               the RV will be returned.
9439
9440               Note that "sv_setref_pv" copies the pointer while this copies
9441               the string.
9442
9443                       SV*     sv_setref_pvn(SV *const rv,
9444                                             const char *const classname,
9445                                             const char *const pv,
9446                                             const STRLEN n)
9447
9448       sv_setref_pvs
9449               Like "sv_setref_pvn", but takes a literal string instead of a
9450               string/length pair.
9451
9452                       SV *    sv_setref_pvs(SV *const rv,
9453                                             const char *const classname,
9454                                             "literal string")
9455
9456       sv_setref_uv
9457               Copies an unsigned integer into a new SV, optionally blessing
9458               the SV.  The "rv" argument will be upgraded to an RV.  That RV
9459               will be modified to point to the new SV.  The "classname"
9460               argument indicates the package for the blessing.  Set
9461               "classname" to "NULL" to avoid the blessing.  The new SV will
9462               have a reference count of 1, and the RV will be returned.
9463
9464                       SV*     sv_setref_uv(SV *const rv,
9465                                            const char *const classname,
9466                                            const UV uv)
9467
9468       sv_setsv
9469               Copies the contents of the source SV "ssv" into the destination
9470               SV "dsv".  The source SV may be destroyed if it is mortal, so
9471               don't use this function if the source SV needs to be reused.
9472               Does not handle 'set' magic on destination SV.  Calls 'get'
9473               magic on source SV.  Loosely speaking, it performs a copy-by-
9474               value, obliterating any previous content of the destination.
9475
9476               You probably want to use one of the assortment of wrappers,
9477               such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
9478               "SvSetMagicSV_nosteal".
9479
9480                       void    sv_setsv(SV *dstr, SV *sstr)
9481
9482       sv_setsv_flags
9483               Copies the contents of the source SV "ssv" into the destination
9484               SV "dsv".  The source SV may be destroyed if it is mortal, so
9485               don't use this function if the source SV needs to be reused.
9486               Does not handle 'set' magic.  Loosely speaking, it performs a
9487               copy-by-value, obliterating any previous content of the
9488               destination.  If the "flags" parameter has the "SV_GMAGIC" bit
9489               set, will "mg_get" on "ssv" if appropriate, else not.  If the
9490               "flags" parameter has the "SV_NOSTEAL" bit set then the buffers
9491               of temps will not be stolen.  "sv_setsv" and "sv_setsv_nomg"
9492               are implemented in terms of this function.
9493
9494               You probably want to use one of the assortment of wrappers,
9495               such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
9496               "SvSetMagicSV_nosteal".
9497
9498               This is the primary function for copying scalars, and most
9499               other copy-ish functions and macros use this underneath.
9500
9501                       void    sv_setsv_flags(SV *dstr, SV *sstr,
9502                                              const I32 flags)
9503
9504       sv_setsv_mg
9505               Like "sv_setsv", but also handles 'set' magic.
9506
9507                       void    sv_setsv_mg(SV *const dstr, SV *const sstr)
9508
9509       sv_setsv_nomg
9510               Like "sv_setsv" but doesn't process magic.
9511
9512                       void    sv_setsv_nomg(SV* dsv, SV* ssv)
9513
9514       sv_setuv
9515               Copies an unsigned integer into the given SV, upgrading first
9516               if necessary.  Does not handle 'set' magic.  See also
9517               "sv_setuv_mg".
9518
9519                       void    sv_setuv(SV *const sv, const UV num)
9520
9521       sv_setuv_mg
9522               Like "sv_setuv", but also handles 'set' magic.
9523
9524                       void    sv_setuv_mg(SV *const sv, const UV u)
9525
9526       sv_set_undef
9527               Equivalent to "sv_setsv(sv, &PL_sv_undef)", but more efficient.
9528               Doesn't handle set magic.
9529
9530               The perl equivalent is "$sv = undef;". Note that it doesn't
9531               free any string buffer, unlike "undef $sv".
9532
9533               Introduced in perl 5.25.12.
9534
9535                       void    sv_set_undef(SV *sv)
9536
9537       SvSTASH Returns the stash of the SV.
9538
9539                       HV*     SvSTASH(SV* sv)
9540
9541       SvSTASH_set
9542               Set the value of the STASH pointer in "sv" to val.  See
9543               "SvIV_set".
9544
9545                       void    SvSTASH_set(SV* sv, HV* val)
9546
9547       SvTAINT Taints an SV if tainting is enabled, and if some input to the
9548               current expression is tainted--usually a variable, but possibly
9549               also implicit inputs such as locale settings.  "SvTAINT"
9550               propagates that taintedness to the outputs of an expression in
9551               a pessimistic fashion; i.e., without paying attention to
9552               precisely which outputs are influenced by which inputs.
9553
9554                       void    SvTAINT(SV* sv)
9555
9556       SvTAINTED
9557               Checks to see if an SV is tainted.  Returns TRUE if it is,
9558               FALSE if not.
9559
9560                       bool    SvTAINTED(SV* sv)
9561
9562       sv_tainted
9563               Test an SV for taintedness.  Use "SvTAINTED" instead.
9564
9565                       bool    sv_tainted(SV *const sv)
9566
9567       SvTAINTED_off
9568               Untaints an SV.  Be very careful with this routine, as it
9569               short-circuits some of Perl's fundamental security features.
9570               XS module authors should not use this function unless they
9571               fully understand all the implications of unconditionally
9572               untainting the value.  Untainting should be done in the
9573               standard perl fashion, via a carefully crafted regexp, rather
9574               than directly untainting variables.
9575
9576                       void    SvTAINTED_off(SV* sv)
9577
9578       SvTAINTED_on
9579               Marks an SV as tainted if tainting is enabled.
9580
9581                       void    SvTAINTED_on(SV* sv)
9582
9583       SvTRUE  Returns a boolean indicating whether Perl would evaluate the SV
9584               as true or false.  See "SvOK" for a defined/undefined test.
9585               Handles 'get' magic unless the scalar is already "SvPOK",
9586               "SvIOK" or "SvNOK" (the public, not the private flags).
9587
9588               As of Perl 5.32, this is guaranteed to evaluate "sv" only once.
9589               Prior to that release, use "SvTRUEx" for single evaluation.
9590
9591                       bool    SvTRUE(SV* sv)
9592
9593       sv_true Returns true if the SV has a true value by Perl's rules.  Use
9594               the "SvTRUE" macro instead, which may call "sv_true()" or may
9595               instead use an in-line version.
9596
9597                       I32     sv_true(SV *const sv)
9598
9599       SvTRUE_nomg
9600               Returns a boolean indicating whether Perl would evaluate the SV
9601               as true or false.  See "SvOK" for a defined/undefined test.
9602               Does not handle 'get' magic.
9603
9604                       bool    SvTRUE_nomg(SV* sv)
9605
9606       SvTRUEx Returns a boolean indicating whether Perl would evaluate the SV
9607               as true or false.  See "SvOK" for a defined/undefined test.
9608               Handles 'get' magic unless the scalar is already "SvPOK",
9609               "SvIOK" or "SvNOK" (the public, not the private flags).
9610
9611               This form guarantees to evaluate "sv" only once.  Only use this
9612               if "sv" is an expression with side effects, otherwise use the
9613               more efficient "SvTRUE".
9614
9615                       bool    SvTRUEx(SV* sv)
9616
9617       SvTYPE  Returns the type of the SV.  See "svtype".
9618
9619                       svtype  SvTYPE(SV* sv)
9620
9621       sv_unmagic
9622               Removes all magic of type "type" from an SV.
9623
9624                       int     sv_unmagic(SV *const sv, const int type)
9625
9626       sv_unmagicext
9627               Removes all magic of type "type" with the specified "vtbl" from
9628               an SV.
9629
9630                       int     sv_unmagicext(SV *const sv, const int type,
9631                                             MGVTBL *vtbl)
9632
9633       sv_unref_flags
9634               Unsets the RV status of the SV, and decrements the reference
9635               count of whatever was being referenced by the RV.  This can
9636               almost be thought of as a reversal of "newSVrv".  The "cflags"
9637               argument can contain "SV_IMMEDIATE_UNREF" to force the
9638               reference count to be decremented (otherwise the decrementing
9639               is conditional on the reference count being different from one
9640               or the reference being a readonly SV).  See "SvROK_off".
9641
9642                       void    sv_unref_flags(SV *const ref, const U32 flags)
9643
9644       sv_untaint
9645               Untaint an SV.  Use "SvTAINTED_off" instead.
9646
9647                       void    sv_untaint(SV *const sv)
9648
9649       SvUOK   Returns a boolean indicating whether the SV contains an integer
9650               that must be interpreted as unsigned.  A non-negative integer
9651               whose value is within the range of both an IV and a UV may be
9652               flagged as either "SvUOK" or "SvIOK".
9653
9654                       bool    SvUOK(SV* sv)
9655
9656       SvUPGRADE
9657               Used to upgrade an SV to a more complex form.  Uses
9658               "sv_upgrade" to perform the upgrade if necessary.  See
9659               "svtype".
9660
9661                       void    SvUPGRADE(SV* sv, svtype type)
9662
9663       sv_upgrade
9664               Upgrade an SV to a more complex form.  Generally adds a new
9665               body type to the SV, then copies across as much information as
9666               possible from the old body.  It croaks if the SV is already in
9667               a more complex form than requested.  You generally want to use
9668               the "SvUPGRADE" macro wrapper, which checks the type before
9669               calling "sv_upgrade", and hence does not croak.  See also
9670               "svtype".
9671
9672                       void    sv_upgrade(SV *const sv, svtype new_type)
9673
9674       sv_usepvn_flags
9675               Tells an SV to use "ptr" to find its string value.  Normally
9676               the string is stored inside the SV, but sv_usepvn allows the SV
9677               to use an outside string.  "ptr" should point to memory that
9678               was allocated by "Newx".  It must be the start of a "Newx"-ed
9679               block of memory, and not a pointer to the middle of it (beware
9680               of "OOK" and copy-on-write), and not be from a non-"Newx"
9681               memory allocator like "malloc".  The string length, "len", must
9682               be supplied.  By default this function will "Renew" (i.e.
9683               realloc, move) the memory pointed to by "ptr", so that pointer
9684               should not be freed or used by the programmer after giving it
9685               to "sv_usepvn", and neither should any pointers from "behind"
9686               that pointer (e.g. ptr + 1) be used.
9687
9688               If "flags & SV_SMAGIC" is true, will call "SvSETMAGIC".  If
9689               "flags & SV_HAS_TRAILING_NUL" is true, then "ptr[len]" must be
9690               "NUL", and the realloc will be skipped (i.e. the buffer is
9691               actually at least 1 byte longer than "len", and already meets
9692               the requirements for storing in "SvPVX").
9693
9694                       void    sv_usepvn_flags(SV *const sv, char* ptr,
9695                                               const STRLEN len,
9696                                               const U32 flags)
9697
9698       SvUTF8  Returns a U32 value indicating the UTF-8 status of an SV.  If
9699               things are set-up properly, this indicates whether or not the
9700               SV contains UTF-8 encoded data.  You should use this after a
9701               call to "SvPV()" or one of its variants, in case any call to
9702               string overloading updates the internal flag.
9703
9704               If you want to take into account the bytes pragma, use
9705               "DO_UTF8" instead.
9706
9707                       U32     SvUTF8(SV* sv)
9708
9709       sv_utf8_decode
9710               If the PV of the SV is an octet sequence in Perl's extended
9711               UTF-8 and contains a multiple-byte character, the "SvUTF8" flag
9712               is turned on so that it looks like a character.  If the PV
9713               contains only single-byte characters, the "SvUTF8" flag stays
9714               off.  Scans PV for validity and returns FALSE if the PV is
9715               invalid UTF-8.
9716
9717                       bool    sv_utf8_decode(SV *const sv)
9718
9719       sv_utf8_downgrade
9720               Attempts to convert the PV of an SV from characters to bytes.
9721               If the PV contains a character that cannot fit in a byte, this
9722               conversion will fail; in this case, either returns false or, if
9723               "fail_ok" is not true, croaks.
9724
9725               This is not a general purpose Unicode to byte encoding
9726               interface: use the "Encode" extension for that.
9727
9728               This function process get magic on "sv".
9729
9730                       bool    sv_utf8_downgrade(SV *const sv,
9731                                                 const bool fail_ok)
9732
9733       sv_utf8_downgrade_flags
9734               Like "sv_utf8_downgrade", but with additional "flags".  If
9735               "flags" has "SV_GMAGIC" bit set, processes get magic on "sv".
9736
9737                       bool    sv_utf8_downgrade_flags(SV *const sv,
9738                                                       const bool fail_ok,
9739                                                       const U32 flags)
9740
9741       sv_utf8_downgrade_nomg
9742               Like "sv_utf8_downgrade", but does not process get magic on
9743               "sv".
9744
9745                       bool    sv_utf8_downgrade_nomg(SV *const sv,
9746                                                      const bool fail_ok)
9747
9748       sv_utf8_encode
9749               Converts the PV of an SV to UTF-8, but then turns the "SvUTF8"
9750               flag off so that it looks like octets again.
9751
9752                       void    sv_utf8_encode(SV *const sv)
9753
9754       sv_utf8_upgrade
9755               Converts the PV of an SV to its UTF-8-encoded form.  Forces the
9756               SV to string form if it is not already.  Will "mg_get" on "sv"
9757               if appropriate.  Always sets the "SvUTF8" flag to avoid future
9758               validity checks even if the whole string is the same in UTF-8
9759               as not.  Returns the number of bytes in the converted string
9760
9761               This is not a general purpose byte encoding to Unicode
9762               interface: use the Encode extension for that.
9763
9764                       STRLEN  sv_utf8_upgrade(SV *sv)
9765
9766       sv_utf8_upgrade_flags
9767               Converts the PV of an SV to its UTF-8-encoded form.  Forces the
9768               SV to string form if it is not already.  Always sets the SvUTF8
9769               flag to avoid future validity checks even if all the bytes are
9770               invariant in UTF-8.  If "flags" has "SV_GMAGIC" bit set, will
9771               "mg_get" on "sv" if appropriate, else not.
9772
9773               The "SV_FORCE_UTF8_UPGRADE" flag is now ignored.
9774
9775               Returns the number of bytes in the converted string.
9776
9777               This is not a general purpose byte encoding to Unicode
9778               interface: use the Encode extension for that.
9779
9780                       STRLEN  sv_utf8_upgrade_flags(SV *const sv,
9781                                                     const I32 flags)
9782
9783       sv_utf8_upgrade_flags_grow
9784               Like "sv_utf8_upgrade_flags", but has an additional parameter
9785               "extra", which is the number of unused bytes the string of "sv"
9786               is guaranteed to have free after it upon return.  This allows
9787               the caller to reserve extra space that it intends to fill, to
9788               avoid extra grows.
9789
9790               "sv_utf8_upgrade", "sv_utf8_upgrade_nomg", and
9791               "sv_utf8_upgrade_flags" are implemented in terms of this
9792               function.
9793
9794               Returns the number of bytes in the converted string (not
9795               including the spares).
9796
9797                       STRLEN  sv_utf8_upgrade_flags_grow(SV *const sv,
9798                                                          const I32 flags,
9799                                                          STRLEN extra)
9800
9801       sv_utf8_upgrade_nomg
9802               Like "sv_utf8_upgrade", but doesn't do magic on "sv".
9803
9804                       STRLEN  sv_utf8_upgrade_nomg(SV *sv)
9805
9806       SvUTF8_off
9807               Unsets the UTF-8 status of an SV (the data is not changed, just
9808               the flag).  Do not use frivolously.
9809
9810                       void    SvUTF8_off(SV *sv)
9811
9812       SvUTF8_on
9813               Turn on the UTF-8 status of an SV (the data is not changed,
9814               just the flag).  Do not use frivolously.
9815
9816                       void    SvUTF8_on(SV *sv)
9817
9818       SvUV    Coerces the given SV to UV and returns it.  The returned value
9819               in many circumstances will get stored in "sv"'s UV slot, but
9820               not in all cases.  (Use "sv_setuv" to make sure it does).
9821
9822               See "SvUVx" for a version which guarantees to evaluate "sv"
9823               only once.
9824
9825                       UV      SvUV(SV* sv)
9826
9827       SvUV_nomg
9828               Like "SvUV" but doesn't process magic.
9829
9830                       UV      SvUV_nomg(SV* sv)
9831
9832       SvUV_set
9833               Set the value of the UV pointer in "sv" to val.  See
9834               "SvIV_set".
9835
9836                       void    SvUV_set(SV* sv, UV val)
9837
9838       SvUVX   Returns the raw value in the SV's UV slot, without checks or
9839               conversions.  Only use when you are sure "SvIOK" is true.  See
9840               also "SvUV".
9841
9842                       UV      SvUVX(SV* sv)
9843
9844       SvUVx   Coerces the given SV to UV and returns it.  The returned value
9845               in many circumstances will get stored in "sv"'s UV slot, but
9846               not in all cases.  (Use "sv_setuv" to make sure it does).
9847
9848               This form guarantees to evaluate "sv" only once.  Only use this
9849               if "sv" is an expression with side effects, otherwise use the
9850               more efficient "SvUV".
9851
9852                       UV      SvUVx(SV* sv)
9853
9854       SvUVXx  DEPRECATED!  It is planned to remove this function from a
9855               future release of Perl.  Do not use it for new code; remove it
9856               from existing code.
9857
9858               This is an unnecessary synonym for "SvUVX"
9859
9860                       UV      SvUVXx(SV* sv)
9861
9862       sv_vcatpvf
9863               Processes its arguments like "sv_vcatpvfn" called with a non-
9864               null C-style variable argument list, and appends the formatted
9865               output to an SV.  Does not handle 'set' magic.  See
9866               "sv_vcatpvf_mg".
9867
9868               Usually used via its frontend "sv_catpvf".
9869
9870                       void    sv_vcatpvf(SV *const sv, const char *const pat,
9871                                          va_list *const args)
9872
9873       sv_vcatpvfn
9874                       void    sv_vcatpvfn(SV *const sv, const char *const pat,
9875                                           const STRLEN patlen,
9876                                           va_list *const args,
9877                                           SV **const svargs,
9878                                           const Size_t sv_count,
9879                                           bool *const maybe_tainted)
9880
9881       sv_vcatpvfn_flags
9882               Processes its arguments like "vsprintf" and appends the
9883               formatted output to an SV.  Uses an array of SVs if the C-style
9884               variable argument list is missing ("NULL"). Argument reordering
9885               (using format specifiers like "%2$d" or "%*2$d") is supported
9886               only when using an array of SVs; using a C-style "va_list"
9887               argument list with a format string that uses argument
9888               reordering will yield an exception.
9889
9890               When running with taint checks enabled, indicates via
9891               "maybe_tainted" if results are untrustworthy (often due to the
9892               use of locales).
9893
9894               If called as "sv_vcatpvfn" or flags has the "SV_GMAGIC" bit
9895               set, calls get magic.
9896
9897               It assumes that pat has the same utf8-ness as sv.  It's the
9898               caller's responsibility to ensure that this is so.
9899
9900               Usually used via one of its frontends "sv_vcatpvf" and
9901               "sv_vcatpvf_mg".
9902
9903                       void    sv_vcatpvfn_flags(SV *const sv,
9904                                                 const char *const pat,
9905                                                 const STRLEN patlen,
9906                                                 va_list *const args,
9907                                                 SV **const svargs,
9908                                                 const Size_t sv_count,
9909                                                 bool *const maybe_tainted,
9910                                                 const U32 flags)
9911
9912       sv_vcatpvf_mg
9913               Like "sv_vcatpvf", but also handles 'set' magic.
9914
9915               Usually used via its frontend "sv_catpvf_mg".
9916
9917                       void    sv_vcatpvf_mg(SV *const sv,
9918                                             const char *const pat,
9919                                             va_list *const args)
9920
9921       SvVOK   Returns a boolean indicating whether the SV contains a
9922               v-string.
9923
9924                       bool    SvVOK(SV* sv)
9925
9926       sv_vsetpvf
9927               Works like "sv_vcatpvf" but copies the text into the SV instead
9928               of appending it.  Does not handle 'set' magic.  See
9929               "sv_vsetpvf_mg".
9930
9931               Usually used via its frontend "sv_setpvf".
9932
9933                       void    sv_vsetpvf(SV *const sv, const char *const pat,
9934                                          va_list *const args)
9935
9936       sv_vsetpvfn
9937               Works like "sv_vcatpvfn" but copies the text into the SV
9938               instead of appending it.
9939
9940               Usually used via one of its frontends "sv_vsetpvf" and
9941               "sv_vsetpvf_mg".
9942
9943                       void    sv_vsetpvfn(SV *const sv, const char *const pat,
9944                                           const STRLEN patlen,
9945                                           va_list *const args,
9946                                           SV **const svargs,
9947                                           const Size_t sv_count,
9948                                           bool *const maybe_tainted)
9949
9950       sv_vsetpvf_mg
9951               Like "sv_vsetpvf", but also handles 'set' magic.
9952
9953               Usually used via its frontend "sv_setpvf_mg".
9954
9955                       void    sv_vsetpvf_mg(SV *const sv,
9956                                             const char *const pat,
9957                                             va_list *const args)
9958

Unicode Support

9960       "Unicode Support" in perlguts has an introduction to this API.
9961
9962       See also "Character classification", and "Character case changing".
9963       Various functions outside this section also work specially with
9964       Unicode.  Search for the string "utf8" in this document.
9965
9966       BOM_UTF8
9967               This is a macro that evaluates to a string constant of the
9968               UTF-8 bytes that define the Unicode BYTE ORDER MARK (U+FEFF)
9969               for the platform that perl is compiled on.  This allows code to
9970               use a mnemonic for this character that works on both ASCII and
9971               EBCDIC platforms.  "sizeof(BOM_UTF8) - 1" can be used to get
9972               its length in bytes.
9973
9974       bytes_cmp_utf8
9975               Compares the sequence of characters (stored as octets) in "b",
9976               "blen" with the sequence of characters (stored as UTF-8) in
9977               "u", "ulen".  Returns 0 if they are equal, -1 or -2 if the
9978               first string is less than the second string, +1 or +2 if the
9979               first string is greater than the second string.
9980
9981               -1 or +1 is returned if the shorter string was identical to the
9982               start of the longer string.  -2 or +2 is returned if there was
9983               a difference between characters within the strings.
9984
9985                       int     bytes_cmp_utf8(const U8 *b, STRLEN blen,
9986                                              const U8 *u, STRLEN ulen)
9987
9988       bytes_from_utf8
9989               NOTE: this function is experimental and may change or be
9990               removed without notice.
9991
9992               Converts a potentially UTF-8 encoded string "s" of length *lenp
9993               into native byte encoding.  On input, the boolean *is_utf8p
9994               gives whether or not "s" is actually encoded in UTF-8.
9995
9996               Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-
9997               destructive of the input string.
9998
9999               Do nothing if *is_utf8p is 0, or if there are code points in
10000               the string not expressible in native byte encoding.  In these
10001               cases, *is_utf8p and *lenp are unchanged, and the return value
10002               is the original "s".
10003
10004               Otherwise, *is_utf8p is set to 0, and the return value is a
10005               pointer to a newly created string containing a downgraded copy
10006               of "s", and whose length is returned in *lenp, updated.  The
10007               new string is "NUL"-terminated.  The caller is responsible for
10008               arranging for the memory used by this string to get freed.
10009
10010               Upon successful return, the number of variants in the string
10011               can be computed by having saved the value of *lenp before the
10012               call, and subtracting the after-call value of *lenp from it.
10013
10014                       U8*     bytes_from_utf8(const U8 *s, STRLEN *lenp,
10015                                               bool *is_utf8p)
10016
10017       bytes_to_utf8
10018               NOTE: this function is experimental and may change or be
10019               removed without notice.
10020
10021               Converts a string "s" of length *lenp bytes from the native
10022               encoding into UTF-8.  Returns a pointer to the newly-created
10023               string, and sets *lenp to reflect the new length in bytes.  The
10024               caller is responsible for arranging for the memory used by this
10025               string to get freed.
10026
10027               Upon successful return, the number of variants in the string
10028               can be computed by having saved the value of *lenp before the
10029               call, and subtracting it from the after-call value of *lenp.
10030
10031               A "NUL" character will be written after the end of the string.
10032
10033               If you want to convert to UTF-8 from encodings other than the
10034               native (Latin1 or EBCDIC), see "sv_recode_to_utf8"().
10035
10036                       U8*     bytes_to_utf8(const U8 *s, STRLEN *lenp)
10037
10038       DO_UTF8 Returns a bool giving whether or not the PV in "sv" is to be
10039               treated as being encoded in UTF-8.
10040
10041               You should use this after a call to "SvPV()" or one of its
10042               variants, in case any call to string overloading updates the
10043               internal UTF-8 encoding flag.
10044
10045                       bool    DO_UTF8(SV* sv)
10046
10047       foldEQ_utf8
10048               Returns true if the leading portions of the strings "s1" and
10049               "s2" (either or both of which may be in UTF-8) are the same
10050               case-insensitively; false otherwise.  How far into the strings
10051               to compare is determined by other input parameters.
10052
10053               If "u1" is true, the string "s1" is assumed to be in
10054               UTF-8-encoded Unicode; otherwise it is assumed to be in native
10055               8-bit encoding.  Correspondingly for "u2" with respect to "s2".
10056
10057               If the byte length "l1" is non-zero, it says how far into "s1"
10058               to check for fold equality.  In other words, "s1"+"l1" will be
10059               used as a goal to reach.  The scan will not be considered to be
10060               a match unless the goal is reached, and scanning won't continue
10061               past that goal.  Correspondingly for "l2" with respect to "s2".
10062
10063               If "pe1" is non-"NULL" and the pointer it points to is not
10064               "NULL", that pointer is considered an end pointer to the
10065               position 1 byte past the maximum point in "s1" beyond which
10066               scanning will not continue under any circumstances.  (This
10067               routine assumes that UTF-8 encoded input strings are not
10068               malformed; malformed input can cause it to read past "pe1").
10069               This means that if both "l1" and "pe1" are specified, and "pe1"
10070               is less than "s1"+"l1", the match will never be successful
10071               because it can never get as far as its goal (and in fact is
10072               asserted against).  Correspondingly for "pe2" with respect to
10073               "s2".
10074
10075               At least one of "s1" and "s2" must have a goal (at least one of
10076               "l1" and "l2" must be non-zero), and if both do, both have to
10077               be reached for a successful match.   Also, if the fold of a
10078               character is multiple characters, all of them must be matched
10079               (see tr21 reference below for 'folding').
10080
10081               Upon a successful match, if "pe1" is non-"NULL", it will be set
10082               to point to the beginning of the next character of "s1" beyond
10083               what was matched.  Correspondingly for "pe2" and "s2".
10084
10085               For case-insensitiveness, the "casefolding" of Unicode is used
10086               instead of upper/lowercasing both the characters, see
10087               <https://www.unicode.org/unicode/reports/tr21/> (Case
10088               Mappings).
10089
10090                       I32     foldEQ_utf8(const char *s1, char **pe1, UV l1,
10091                                           bool u1, const char *s2, char **pe2,
10092                                           UV l2, bool u2)
10093
10094       is_ascii_string
10095               This is a misleadingly-named synonym for
10096               "is_utf8_invariant_string".  On ASCII-ish platforms, the name
10097               isn't misleading: the ASCII-range characters are exactly the
10098               UTF-8 invariants.  But EBCDIC machines have more invariants
10099               than just the ASCII characters, so "is_utf8_invariant_string"
10100               is preferred.
10101
10102                       bool    is_ascii_string(const U8* const s, STRLEN len)
10103
10104       is_c9strict_utf8_string
10105               Returns TRUE if the first "len" bytes of string "s" form a
10106               valid UTF-8-encoded string that conforms to Unicode Corrigendum
10107               #9 <http://www.unicode.org/versions/corrigendum9.html>;
10108               otherwise it returns FALSE.  If "len" is 0, it will be
10109               calculated using strlen(s) (which means if you use this option,
10110               that "s" can't have embedded "NUL" characters and has to have a
10111               terminating "NUL" byte).  Note that all characters being ASCII
10112               constitute 'a valid UTF-8 string'.
10113
10114               This function returns FALSE for strings containing any code
10115               points above the Unicode max of 0x10FFFF or surrogate code
10116               points, but accepts non-character code points per Corrigendum
10117               #9 <http://www.unicode.org/versions/corrigendum9.html>.
10118
10119               See also "is_utf8_invariant_string",
10120               "is_utf8_invariant_string_loc", "is_utf8_string",
10121               "is_utf8_string_flags", "is_utf8_string_loc",
10122               "is_utf8_string_loc_flags", "is_utf8_string_loclen",
10123               "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
10124               "is_utf8_fixed_width_buf_loc_flags",
10125               "is_utf8_fixed_width_buf_loclen_flags",
10126               "is_strict_utf8_string", "is_strict_utf8_string_loc",
10127               "is_strict_utf8_string_loclen", "is_c9strict_utf8_string_loc",
10128               and "is_c9strict_utf8_string_loclen".
10129
10130                       bool    is_c9strict_utf8_string(const U8 *s, STRLEN len)
10131
10132       is_c9strict_utf8_string_loc
10133               Like "is_c9strict_utf8_string" but stores the location of the
10134               failure (in the case of "utf8ness failure") or the location
10135               "s"+"len" (in the case of "utf8ness success") in the "ep"
10136               pointer.
10137
10138               See also "is_c9strict_utf8_string_loclen".
10139
10140                       bool    is_c9strict_utf8_string_loc(const U8 *s,
10141                                                           STRLEN len,
10142                                                           const U8 **ep)
10143
10144       is_c9strict_utf8_string_loclen
10145               Like "is_c9strict_utf8_string" but stores the location of the
10146               failure (in the case of "utf8ness failure") or the location
10147               "s"+"len" (in the case of "utf8ness success") in the "ep"
10148               pointer, and the number of UTF-8 encoded characters in the "el"
10149               pointer.
10150
10151               See also "is_c9strict_utf8_string_loc".
10152
10153                       bool    is_c9strict_utf8_string_loclen(const U8 *s,
10154                                                              STRLEN len,
10155                                                              const U8 **ep,
10156                                                              STRLEN *el)
10157
10158       isC9_STRICT_UTF8_CHAR
10159               Evaluates to non-zero if the first few bytes of the string
10160               starting at "s" and looking no further than "e - 1" are well-
10161               formed UTF-8 that represents some Unicode non-surrogate code
10162               point; otherwise it evaluates to 0.  If non-zero, the value
10163               gives how many bytes starting at "s" comprise the code point's
10164               representation.  Any bytes remaining before "e", but beyond the
10165               ones needed to form the first code point in "s", are not
10166               examined.
10167
10168               The largest acceptable code point is the Unicode maximum
10169               0x10FFFF.  This differs from "isSTRICT_UTF8_CHAR" only in that
10170               it accepts non-character code points.  This corresponds to
10171               Unicode Corrigendum #9
10172               <http://www.unicode.org/versions/corrigendum9.html>.  which
10173               said that non-character code points are merely discouraged
10174               rather than completely forbidden in open interchange.  See
10175               "Noncharacter code points" in perlunicode.
10176
10177               Use "isUTF8_CHAR" to check for Perl's extended UTF-8; and
10178               "isUTF8_CHAR_flags" for a more customized definition.
10179
10180               Use "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc",
10181               and "is_c9strict_utf8_string_loclen" to check entire strings.
10182
10183                       Size_t  isC9_STRICT_UTF8_CHAR(const U8 * const s0,
10184                                                     const U8 * const e)
10185
10186       is_invariant_string
10187               This is a somewhat misleadingly-named synonym for
10188               "is_utf8_invariant_string".  "is_utf8_invariant_string" is
10189               preferred, as it indicates under what conditions the string is
10190               invariant.
10191
10192                       bool    is_invariant_string(const U8* const s,
10193                                                   STRLEN len)
10194
10195       isSTRICT_UTF8_CHAR
10196               Evaluates to non-zero if the first few bytes of the string
10197               starting at "s" and looking no further than "e - 1" are well-
10198               formed UTF-8 that represents some Unicode code point completely
10199               acceptable for open interchange between all applications;
10200               otherwise it evaluates to 0.  If non-zero, the value gives how
10201               many bytes starting at "s" comprise the code point's
10202               representation.  Any bytes remaining before "e", but beyond the
10203               ones needed to form the first code point in "s", are not
10204               examined.
10205
10206               The largest acceptable code point is the Unicode maximum
10207               0x10FFFF, and must not be a surrogate nor a non-character code
10208               point.  Thus this excludes any code point from Perl's extended
10209               UTF-8.
10210
10211               This is used to efficiently decide if the next few bytes in "s"
10212               is legal Unicode-acceptable UTF-8 for a single character.
10213
10214               Use "isC9_STRICT_UTF8_CHAR" to use the Unicode Corrigendum #9
10215               <http://www.unicode.org/versions/corrigendum9.html> definition
10216               of allowable code points; "isUTF8_CHAR" to check for Perl's
10217               extended UTF-8; and "isUTF8_CHAR_flags" for a more customized
10218               definition.
10219
10220               Use "is_strict_utf8_string", "is_strict_utf8_string_loc", and
10221               "is_strict_utf8_string_loclen" to check entire strings.
10222
10223                       Size_t  isSTRICT_UTF8_CHAR(const U8 * const s0,
10224                                                  const U8 * const e)
10225
10226       is_strict_utf8_string
10227               Returns TRUE if the first "len" bytes of string "s" form a
10228               valid UTF-8-encoded string that is fully interchangeable by any
10229               application using Unicode rules; otherwise it returns FALSE.
10230               If "len" is 0, it will be calculated using strlen(s) (which
10231               means if you use this option, that "s" can't have embedded
10232               "NUL" characters and has to have a terminating "NUL" byte).
10233               Note that all characters being ASCII constitute 'a valid UTF-8
10234               string'.
10235
10236               This function returns FALSE for strings containing any code
10237               points above the Unicode max of 0x10FFFF, surrogate code
10238               points, or non-character code points.
10239
10240               See also "is_utf8_invariant_string",
10241               "is_utf8_invariant_string_loc", "is_utf8_string",
10242               "is_utf8_string_flags", "is_utf8_string_loc",
10243               "is_utf8_string_loc_flags", "is_utf8_string_loclen",
10244               "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
10245               "is_utf8_fixed_width_buf_loc_flags",
10246               "is_utf8_fixed_width_buf_loclen_flags",
10247               "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
10248               "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
10249               "is_c9strict_utf8_string_loclen".
10250
10251                       bool    is_strict_utf8_string(const U8 *s, STRLEN len)
10252
10253       is_strict_utf8_string_loc
10254               Like "is_strict_utf8_string" but stores the location of the
10255               failure (in the case of "utf8ness failure") or the location
10256               "s"+"len" (in the case of "utf8ness success") in the "ep"
10257               pointer.
10258
10259               See also "is_strict_utf8_string_loclen".
10260
10261                       bool    is_strict_utf8_string_loc(const U8 *s,
10262                                                         STRLEN len,
10263                                                         const U8 **ep)
10264
10265       is_strict_utf8_string_loclen
10266               Like "is_strict_utf8_string" but stores the location of the
10267               failure (in the case of "utf8ness failure") or the location
10268               "s"+"len" (in the case of "utf8ness success") in the "ep"
10269               pointer, and the number of UTF-8 encoded characters in the "el"
10270               pointer.
10271
10272               See also "is_strict_utf8_string_loc".
10273
10274                       bool    is_strict_utf8_string_loclen(const U8 *s,
10275                                                            STRLEN len,
10276                                                            const U8 **ep,
10277                                                            STRLEN *el)
10278
10279       is_utf8_fixed_width_buf_flags
10280               Returns TRUE if the fixed-width buffer starting at "s" with
10281               length "len" is entirely valid UTF-8, subject to the
10282               restrictions given by "flags"; otherwise it returns FALSE.
10283
10284               If "flags" is 0, any well-formed UTF-8, as extended by Perl, is
10285               accepted without restriction.  If the final few bytes of the
10286               buffer do not form a complete code point, this will return TRUE
10287               anyway, provided that "is_utf8_valid_partial_char_flags"
10288               returns TRUE for them.
10289
10290               If "flags" in non-zero, it can be any combination of the
10291               "UTF8_DISALLOW_foo" flags accepted by "utf8n_to_uvchr", and
10292               with the same meanings.
10293
10294               This function differs from "is_utf8_string_flags" only in that
10295               the latter returns FALSE if the final few bytes of the string
10296               don't form a complete code point.
10297
10298                       bool    is_utf8_fixed_width_buf_flags(
10299                                   const U8 * const s, STRLEN len,
10300                                   const U32 flags
10301                               )
10302
10303       is_utf8_fixed_width_buf_loclen_flags
10304               Like "is_utf8_fixed_width_buf_loc_flags" but stores the number
10305               of complete, valid characters found in the "el" pointer.
10306
10307                       bool    is_utf8_fixed_width_buf_loclen_flags(
10308                                   const U8 * const s, STRLEN len,
10309                                   const U8 **ep, STRLEN *el, const U32 flags
10310                               )
10311
10312       is_utf8_fixed_width_buf_loc_flags
10313               Like "is_utf8_fixed_width_buf_flags" but stores the location of
10314               the failure in the "ep" pointer.  If the function returns TRUE,
10315               *ep will point to the beginning of any partial character at the
10316               end of the buffer; if there is no partial character *ep will
10317               contain "s"+"len".
10318
10319               See also "is_utf8_fixed_width_buf_loclen_flags".
10320
10321                       bool    is_utf8_fixed_width_buf_loc_flags(
10322                                   const U8 * const s, STRLEN len,
10323                                   const U8 **ep, const U32 flags
10324                               )
10325
10326       is_utf8_invariant_string
10327               Returns TRUE if the first "len" bytes of the string "s" are the
10328               same regardless of the UTF-8 encoding of the string (or UTF-
10329               EBCDIC encoding on EBCDIC machines); otherwise it returns
10330               FALSE.  That is, it returns TRUE if they are UTF-8 invariant.
10331               On ASCII-ish machines, all the ASCII characters and only the
10332               ASCII characters fit this definition.  On EBCDIC machines, the
10333               ASCII-range characters are invariant, but so also are the C1
10334               controls.
10335
10336               If "len" is 0, it will be calculated using strlen(s), (which
10337               means if you use this option, that "s" can't have embedded
10338               "NUL" characters and has to have a terminating "NUL" byte).
10339
10340               See also "is_utf8_string", "is_utf8_string_flags",
10341               "is_utf8_string_loc", "is_utf8_string_loc_flags",
10342               "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
10343               "is_utf8_fixed_width_buf_flags",
10344               "is_utf8_fixed_width_buf_loc_flags",
10345               "is_utf8_fixed_width_buf_loclen_flags",
10346               "is_strict_utf8_string", "is_strict_utf8_string_loc",
10347               "is_strict_utf8_string_loclen", "is_c9strict_utf8_string",
10348               "is_c9strict_utf8_string_loc", and
10349               "is_c9strict_utf8_string_loclen".
10350
10351                       bool    is_utf8_invariant_string(const U8* const s,
10352                                                        STRLEN len)
10353
10354       is_utf8_invariant_string_loc
10355               Like "is_utf8_invariant_string" but upon failure, stores the
10356               location of the first UTF-8 variant character in the "ep"
10357               pointer; if all characters are UTF-8 invariant, this function
10358               does not change the contents of *ep.
10359
10360                       bool    is_utf8_invariant_string_loc(const U8* const s,
10361                                                            STRLEN len,
10362                                                            const U8 ** ep)
10363
10364       is_utf8_string
10365               Returns TRUE if the first "len" bytes of string "s" form a
10366               valid Perl-extended-UTF-8 string; returns FALSE otherwise.  If
10367               "len" is 0, it will be calculated using strlen(s) (which means
10368               if you use this option, that "s" can't have embedded "NUL"
10369               characters and has to have a terminating "NUL" byte).  Note
10370               that all characters being ASCII constitute 'a valid UTF-8
10371               string'.
10372
10373               This function considers Perl's extended UTF-8 to be valid.
10374               That means that code points above Unicode, surrogates, and non-
10375               character code points are considered valid by this function.
10376               Use "is_strict_utf8_string", "is_c9strict_utf8_string", or
10377               "is_utf8_string_flags" to restrict what code points are
10378               considered valid.
10379
10380               See also "is_utf8_invariant_string",
10381               "is_utf8_invariant_string_loc", "is_utf8_string_loc",
10382               "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags",
10383               "is_utf8_fixed_width_buf_loc_flags",
10384               "is_utf8_fixed_width_buf_loclen_flags",
10385
10386                       bool    is_utf8_string(const U8 *s, STRLEN len)
10387
10388       is_utf8_string_flags
10389               Returns TRUE if the first "len" bytes of string "s" form a
10390               valid UTF-8 string, subject to the restrictions imposed by
10391               "flags"; returns FALSE otherwise.  If "len" is 0, it will be
10392               calculated using strlen(s) (which means if you use this option,
10393               that "s" can't have embedded "NUL" characters and has to have a
10394               terminating "NUL" byte).  Note that all characters being ASCII
10395               constitute 'a valid UTF-8 string'.
10396
10397               If "flags" is 0, this gives the same results as
10398               "is_utf8_string"; if "flags" is
10399               "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the same
10400               results as "is_strict_utf8_string"; and if "flags" is
10401               "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same
10402               results as "is_c9strict_utf8_string".  Otherwise "flags" may be
10403               any combination of the "UTF8_DISALLOW_foo" flags understood by
10404               "utf8n_to_uvchr", with the same meanings.
10405
10406               See also "is_utf8_invariant_string",
10407               "is_utf8_invariant_string_loc", "is_utf8_string",
10408               "is_utf8_string_loc", "is_utf8_string_loc_flags",
10409               "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
10410               "is_utf8_fixed_width_buf_flags",
10411               "is_utf8_fixed_width_buf_loc_flags",
10412               "is_utf8_fixed_width_buf_loclen_flags",
10413               "is_strict_utf8_string", "is_strict_utf8_string_loc",
10414               "is_strict_utf8_string_loclen", "is_c9strict_utf8_string",
10415               "is_c9strict_utf8_string_loc", and
10416               "is_c9strict_utf8_string_loclen".
10417
10418                       bool    is_utf8_string_flags(const U8 *s, STRLEN len,
10419                                                    const U32 flags)
10420
10421       is_utf8_string_loc
10422               Like "is_utf8_string" but stores the location of the failure
10423               (in the case of "utf8ness failure") or the location "s"+"len"
10424               (in the case of "utf8ness success") in the "ep" pointer.
10425
10426               See also "is_utf8_string_loclen".
10427
10428                       bool    is_utf8_string_loc(const U8 *s,
10429                                                  const STRLEN len,
10430                                                  const U8 **ep)
10431
10432       is_utf8_string_loclen
10433               Like "is_utf8_string" but stores the location of the failure
10434               (in the case of "utf8ness failure") or the location "s"+"len"
10435               (in the case of "utf8ness success") in the "ep" pointer, and
10436               the number of UTF-8 encoded characters in the "el" pointer.
10437
10438               See also "is_utf8_string_loc".
10439
10440                       bool    is_utf8_string_loclen(const U8 *s, STRLEN len,
10441                                                     const U8 **ep, STRLEN *el)
10442
10443       is_utf8_string_loclen_flags
10444               Like "is_utf8_string_flags" but stores the location of the
10445               failure (in the case of "utf8ness failure") or the location
10446               "s"+"len" (in the case of "utf8ness success") in the "ep"
10447               pointer, and the number of UTF-8 encoded characters in the "el"
10448               pointer.
10449
10450               See also "is_utf8_string_loc_flags".
10451
10452                       bool    is_utf8_string_loclen_flags(const U8 *s,
10453                                                           STRLEN len,
10454                                                           const U8 **ep,
10455                                                           STRLEN *el,
10456                                                           const U32 flags)
10457
10458       is_utf8_string_loc_flags
10459               Like "is_utf8_string_flags" but stores the location of the
10460               failure (in the case of "utf8ness failure") or the location
10461               "s"+"len" (in the case of "utf8ness success") in the "ep"
10462               pointer.
10463
10464               See also "is_utf8_string_loclen_flags".
10465
10466                       bool    is_utf8_string_loc_flags(const U8 *s,
10467                                                        STRLEN len,
10468                                                        const U8 **ep,
10469                                                        const U32 flags)
10470
10471       is_utf8_valid_partial_char
10472               Returns 0 if the sequence of bytes starting at "s" and looking
10473               no further than "e - 1" is the UTF-8 encoding, as extended by
10474               Perl, for one or more code points.  Otherwise, it returns 1 if
10475               there exists at least one non-empty sequence of bytes that when
10476               appended to sequence "s", starting at position "e" causes the
10477               entire sequence to be the well-formed UTF-8 of some code point;
10478               otherwise returns 0.
10479
10480               In other words this returns TRUE if "s" points to a partial
10481               UTF-8-encoded code point.
10482
10483               This is useful when a fixed-length buffer is being tested for
10484               being well-formed UTF-8, but the final few bytes in it don't
10485               comprise a full character; that is, it is split somewhere in
10486               the middle of the final code point's UTF-8 representation.
10487               (Presumably when the buffer is refreshed with the next chunk of
10488               data, the new first bytes will complete the partial code
10489               point.)   This function is used to verify that the final bytes
10490               in the current buffer are in fact the legal beginning of some
10491               code point, so that if they aren't, the failure can be
10492               signalled without having to wait for the next read.
10493
10494                       bool    is_utf8_valid_partial_char(const U8 * const s,
10495                                                          const U8 * const e)
10496
10497       is_utf8_valid_partial_char_flags
10498               Like "is_utf8_valid_partial_char", it returns a boolean giving
10499               whether or not the input is a valid UTF-8 encoded partial
10500               character, but it takes an extra parameter, "flags", which can
10501               further restrict which code points are considered valid.
10502
10503               If "flags" is 0, this behaves identically to
10504               "is_utf8_valid_partial_char".  Otherwise "flags" can be any
10505               combination of the "UTF8_DISALLOW_foo" flags accepted by
10506               "utf8n_to_uvchr".  If there is any sequence of bytes that can
10507               complete the input partial character in such a way that a non-
10508               prohibited character is formed, the function returns TRUE;
10509               otherwise FALSE.  Non character code points cannot be
10510               determined based on partial character input.  But many  of the
10511               other possible excluded types can be determined from just the
10512               first one or two bytes.
10513
10514                       bool    is_utf8_valid_partial_char_flags(
10515                                   const U8 * const s, const U8 * const e,
10516                                   const U32 flags
10517                               )
10518
10519       isUTF8_CHAR
10520               Evaluates to non-zero if the first few bytes of the string
10521               starting at "s" and looking no further than "e - 1" are well-
10522               formed UTF-8, as extended by Perl, that represents some code
10523               point; otherwise it evaluates to 0.  If non-zero, the value
10524               gives how many bytes starting at "s" comprise the code point's
10525               representation.  Any bytes remaining before "e", but beyond the
10526               ones needed to form the first code point in "s", are not
10527               examined.
10528
10529               The code point can be any that will fit in an IV on this
10530               machine, using Perl's extension to official UTF-8 to represent
10531               those higher than the Unicode maximum of 0x10FFFF.  That means
10532               that this macro is used to efficiently decide if the next few
10533               bytes in "s" is legal UTF-8 for a single character.
10534
10535               Use "isSTRICT_UTF8_CHAR" to restrict the acceptable code points
10536               to those defined by Unicode to be fully interchangeable across
10537               applications; "isC9_STRICT_UTF8_CHAR" to use the Unicode
10538               Corrigendum #9
10539               <http://www.unicode.org/versions/corrigendum9.html> definition
10540               of allowable code points; and "isUTF8_CHAR_flags" for a more
10541               customized definition.
10542
10543               Use "is_utf8_string", "is_utf8_string_loc", and
10544               "is_utf8_string_loclen" to check entire strings.
10545
10546               Note also that a UTF-8 "invariant" character (i.e. ASCII on
10547               non-EBCDIC machines) is a valid UTF-8 character.
10548
10549                       Size_t  isUTF8_CHAR(const U8 * const s0,
10550                                           const U8 * const e)
10551
10552       isUTF8_CHAR_flags
10553               Evaluates to non-zero if the first few bytes of the string
10554               starting at "s" and looking no further than "e - 1" are well-
10555               formed UTF-8, as extended by Perl, that represents some code
10556               point, subject to the restrictions given by "flags"; otherwise
10557               it evaluates to 0.  If non-zero, the value gives how many bytes
10558               starting at "s" comprise the code point's representation.  Any
10559               bytes remaining before "e", but beyond the ones needed to form
10560               the first code point in "s", are not examined.
10561
10562               If "flags" is 0, this gives the same results as "isUTF8_CHAR";
10563               if "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives
10564               the same results as "isSTRICT_UTF8_CHAR"; and if "flags" is
10565               "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same
10566               results as "isC9_STRICT_UTF8_CHAR".  Otherwise "flags" may be
10567               any combination of the "UTF8_DISALLOW_foo" flags understood by
10568               "utf8n_to_uvchr", with the same meanings.
10569
10570               The three alternative macros are for the most commonly needed
10571               validations; they are likely to run somewhat faster than this
10572               more general one, as they can be inlined into your code.
10573
10574               Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
10575               "is_utf8_string_loclen_flags" to check entire strings.
10576
10577                       STRLEN  isUTF8_CHAR_flags(const U8 *s, const U8 *e,
10578                                                 const U32 flags)
10579
10580       LATIN1_TO_NATIVE
10581               Returns the native  equivalent of the input Latin-1 code point
10582               (including ASCII and control characters) given by "ch".  Thus,
10583               "LATIN1_TO_NATIVE(66)" on EBCDIC platforms returns 194.  These
10584               each represent the character "B" on their respective platforms.
10585               On ASCII platforms no conversion is needed, so this macro
10586               expands to just its input, adding no time nor space
10587               requirements to the implementation.
10588
10589               For conversion of code points potentially larger than will fit
10590               in a character, use "UNI_TO_NATIVE".
10591
10592                       U8      LATIN1_TO_NATIVE(U8 ch)
10593
10594       NATIVE_TO_LATIN1
10595               Returns the Latin-1 (including ASCII and control characters)
10596               equivalent of the input native code point given by "ch".  Thus,
10597               "NATIVE_TO_LATIN1(193)" on EBCDIC platforms returns 65.  These
10598               each represent the character "A" on their respective platforms.
10599               On ASCII platforms no conversion is needed, so this macro
10600               expands to just its input, adding no time nor space
10601               requirements to the implementation.
10602
10603               For conversion of code points potentially larger than will fit
10604               in a character, use "NATIVE_TO_UNI".
10605
10606                       U8      NATIVE_TO_LATIN1(U8 ch)
10607
10608       NATIVE_TO_UNI
10609               Returns the Unicode  equivalent of the input native code point
10610               given by "ch".  Thus, "NATIVE_TO_UNI(195)" on EBCDIC platforms
10611               returns 67.  These each represent the character "C" on their
10612               respective platforms.  On ASCII platforms no conversion is
10613               needed, so this macro expands to just its input, adding no time
10614               nor space requirements to the implementation.
10615
10616                       UV      NATIVE_TO_UNI(UV ch)
10617
10618       pv_uni_display
10619               Build to the scalar "dsv" a displayable version of the UTF-8
10620               encoded string "spv", length "len", the displayable version
10621               being at most "pvlim" bytes long (if longer, the rest is
10622               truncated and "..." will be appended).
10623
10624               The "flags" argument can have "UNI_DISPLAY_ISPRINT" set to
10625               display "isPRINT()"able characters as themselves,
10626               "UNI_DISPLAY_BACKSLASH" to display the "\\[nrfta\\]" as the
10627               backslashed versions (like "\n") ("UNI_DISPLAY_BACKSLASH" is
10628               preferred over "UNI_DISPLAY_ISPRINT" for "\\").
10629               "UNI_DISPLAY_QQ" (and its alias "UNI_DISPLAY_REGEX") have both
10630               "UNI_DISPLAY_BACKSLASH" and "UNI_DISPLAY_ISPRINT" turned on.
10631
10632               Additionally, there is now "UNI_DISPLAY_BACKSPACE" which allows
10633               "\b" for a backspace, but only when "UNI_DISPLAY_BACKSLASH"
10634               also is set.
10635
10636               The pointer to the PV of the "dsv" is returned.
10637
10638               See also "sv_uni_display".
10639
10640                       char*   pv_uni_display(SV *dsv, const U8 *spv,
10641                                              STRLEN len, STRLEN pvlim,
10642                                              UV flags)
10643
10644       REPLACEMENT_CHARACTER_UTF8
10645               This is a macro that evaluates to a string constant of the
10646               UTF-8 bytes that define the Unicode REPLACEMENT CHARACTER
10647               (U+FFFD) for the platform that perl is compiled on.  This
10648               allows code to use a mnemonic for this character that works on
10649               both ASCII and EBCDIC platforms.
10650               "sizeof(REPLACEMENT_CHARACTER_UTF8) - 1" can be used to get its
10651               length in bytes.
10652
10653       sv_cat_decode
10654               "encoding" is assumed to be an "Encode" object, the PV of "ssv"
10655               is assumed to be octets in that encoding and decoding the input
10656               starts from the position which "(PV + *offset)" pointed to.
10657               "dsv" will be concatenated with the decoded UTF-8 string from
10658               "ssv".  Decoding will terminate when the string "tstr" appears
10659               in decoding output or the input ends on the PV of "ssv".  The
10660               value which "offset" points will be modified to the last input
10661               position on "ssv".
10662
10663               Returns TRUE if the terminator was found, else returns FALSE.
10664
10665                       bool    sv_cat_decode(SV* dsv, SV *encoding, SV *ssv,
10666                                             int *offset, char* tstr, int tlen)
10667
10668       sv_recode_to_utf8
10669               "encoding" is assumed to be an "Encode" object, on entry the PV
10670               of "sv" is assumed to be octets in that encoding, and "sv" will
10671               be converted into Unicode (and UTF-8).
10672
10673               If "sv" already is UTF-8 (or if it is not "POK"), or if
10674               "encoding" is not a reference, nothing is done to "sv".  If
10675               "encoding" is not an "Encode::XS" Encoding object, bad things
10676               will happen.  (See cpan/Encode/encoding.pm and Encode.)
10677
10678               The PV of "sv" is returned.
10679
10680                       char*   sv_recode_to_utf8(SV* sv, SV *encoding)
10681
10682       sv_uni_display
10683               Build to the scalar "dsv" a displayable version of the scalar
10684               "sv", the displayable version being at most "pvlim" bytes long
10685               (if longer, the rest is truncated and "..." will be appended).
10686
10687               The "flags" argument is as in "pv_uni_display"().
10688
10689               The pointer to the PV of the "dsv" is returned.
10690
10691                       char*   sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim,
10692                                              UV flags)
10693
10694       UNICODE_REPLACEMENT
10695               Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT
10696               CHARACTER
10697
10698       UNI_TO_NATIVE
10699               Returns the native  equivalent of the input Unicode code point
10700               given by "ch".  Thus, "UNI_TO_NATIVE(68)" on EBCDIC platforms
10701               returns 196.  These each represent the character "D" on their
10702               respective platforms.  On ASCII platforms no conversion is
10703               needed, so this macro expands to just its input, adding no time
10704               nor space requirements to the implementation.
10705
10706                       UV      UNI_TO_NATIVE(UV ch)
10707
10708       utf8n_to_uvchr
10709               THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
10710               CIRCUMSTANCES.  Most code should use "utf8_to_uvchr_buf"()
10711               rather than call this directly.
10712
10713               Bottom level UTF-8 decode routine.  Returns the native code
10714               point value of the first character in the string "s", which is
10715               assumed to be in UTF-8 (or UTF-EBCDIC) encoding, and no longer
10716               than "curlen" bytes; *retlen (if "retlen" isn't NULL) will be
10717               set to the length, in bytes, of that character.
10718
10719               The value of "flags" determines the behavior when "s" does not
10720               point to a well-formed UTF-8 character.  If "flags" is 0,
10721               encountering a malformation causes zero to be returned and
10722               *retlen is set so that ("s" + *retlen) is the next possible
10723               position in "s" that could begin a non-malformed character.
10724               Also, if UTF-8 warnings haven't been lexically disabled, a
10725               warning is raised.  Some UTF-8 input sequences may contain
10726               multiple malformations.  This function tries to find every
10727               possible one in each call, so multiple warnings can be raised
10728               for the same sequence.
10729
10730               Various ALLOW flags can be set in "flags" to allow (and not
10731               warn on) individual types of malformations, such as the
10732               sequence being overlong (that is, when there is a shorter
10733               sequence that can express the same code point; overlong
10734               sequences are expressly forbidden in the UTF-8 standard due to
10735               potential security issues).  Another malformation example is
10736               the first byte of a character not being a legal first byte.
10737               See utf8.h for the list of such flags.  Even if allowed, this
10738               function generally returns the Unicode REPLACEMENT CHARACTER
10739               when it encounters a malformation.  There are flags in utf8.h
10740               to override this behavior for the overlong malformations, but
10741               don't do that except for very specialized purposes.
10742
10743               The "UTF8_CHECK_ONLY" flag overrides the behavior when a non-
10744               allowed (by other flags) malformation is found.  If this flag
10745               is set, the routine assumes that the caller will raise a
10746               warning, and this function will silently just set "retlen" to
10747               "-1" (cast to "STRLEN") and return zero.
10748
10749               Note that this API requires disambiguation between successful
10750               decoding a "NUL" character, and an error return (unless the
10751               "UTF8_CHECK_ONLY" flag is set), as in both cases, 0 is
10752               returned, and, depending on the malformation, "retlen" may be
10753               set to 1.  To disambiguate, upon a zero return, see if the
10754               first byte of "s" is 0 as well.  If so, the input was a "NUL";
10755               if not, the input had an error.  Or you can use
10756               "utf8n_to_uvchr_error".
10757
10758               Certain code points are considered problematic.  These are
10759               Unicode surrogates, Unicode non-characters, and code points
10760               above the Unicode maximum of 0x10FFFF.  By default these are
10761               considered regular code points, but certain situations warrant
10762               special handling for them, which can be specified using the
10763               "flags" parameter.  If "flags" contains
10764               "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", all three classes are
10765               treated as malformations and handled as such.  The flags
10766               "UTF8_DISALLOW_SURROGATE", "UTF8_DISALLOW_NONCHAR", and
10767               "UTF8_DISALLOW_SUPER" (meaning above the legal Unicode maximum)
10768               can be set to disallow these categories individually.
10769               "UTF8_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed
10770               inputs to the strict UTF-8 traditionally defined by Unicode.
10771               Use "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE" to use the
10772               strictness definition given by Unicode Corrigendum #9
10773               <https://www.unicode.org/versions/corrigendum9.html>.  The
10774               difference between traditional strictness and C9 strictness is
10775               that the latter does not forbid non-character code points.
10776               (They are still discouraged, however.)  For more discussion see
10777               "Noncharacter code points" in perlunicode.
10778
10779               The flags "UTF8_WARN_ILLEGAL_INTERCHANGE",
10780               "UTF8_WARN_ILLEGAL_C9_INTERCHANGE", "UTF8_WARN_SURROGATE",
10781               "UTF8_WARN_NONCHAR", and "UTF8_WARN_SUPER" will cause warning
10782               messages to be raised for their respective categories, but
10783               otherwise the code points are considered valid (not
10784               malformations).  To get a category to both be treated as a
10785               malformation and raise a warning, specify both the WARN and
10786               DISALLOW flags.  (But note that warnings are not raised if
10787               lexically disabled nor if "UTF8_CHECK_ONLY" is also specified.)
10788
10789               Extremely high code points were never specified in any
10790               standard, and require an extension to UTF-8 to express, which
10791               Perl does.  It is likely that programs written in something
10792               other than Perl would not be able to read files that contain
10793               these; nor would Perl understand files written by something
10794               that uses a different extension.  For these reasons, there is a
10795               separate set of flags that can warn and/or disallow these
10796               extremely high code points, even if other above-Unicode ones
10797               are accepted.  They are the "UTF8_WARN_PERL_EXTENDED" and
10798               "UTF8_DISALLOW_PERL_EXTENDED" flags.  For more information see
10799               ""UTF8_GOT_PERL_EXTENDED"".  Of course "UTF8_DISALLOW_SUPER"
10800               will treat all above-Unicode code points, including these, as
10801               malformations.  (Note that the Unicode standard considers
10802               anything above 0x10FFFF to be illegal, but there are standards
10803               predating it that allow up to 0x7FFF_FFFF (2**31 -1))
10804
10805               A somewhat misleadingly named synonym for
10806               "UTF8_WARN_PERL_EXTENDED" is retained for backward
10807               compatibility: "UTF8_WARN_ABOVE_31_BIT".  Similarly,
10808               "UTF8_DISALLOW_ABOVE_31_BIT" is usable instead of the more
10809               accurately named "UTF8_DISALLOW_PERL_EXTENDED".  The names are
10810               misleading because these flags can apply to code points that
10811               actually do fit in 31 bits.  This happens on EBCDIC platforms,
10812               and sometimes when the overlong malformation is also present.
10813               The new names accurately describe the situation in all cases.
10814
10815               All other code points corresponding to Unicode characters,
10816               including private use and those yet to be assigned, are never
10817               considered malformed and never warn.
10818
10819                       UV      utf8n_to_uvchr(const U8 *s, STRLEN curlen,
10820                                              STRLEN *retlen, const U32 flags)
10821
10822       utf8n_to_uvchr_error
10823               THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
10824               CIRCUMSTANCES.  Most code should use "utf8_to_uvchr_buf"()
10825               rather than call this directly.
10826
10827               This function is for code that needs to know what the precise
10828               malformation(s) are when an error is found.  If you also need
10829               to know the generated warning messages, use
10830               "utf8n_to_uvchr_msgs"() instead.
10831
10832               It is like "utf8n_to_uvchr" but it takes an extra parameter
10833               placed after all the others, "errors".  If this parameter is 0,
10834               this function behaves identically to "utf8n_to_uvchr".
10835               Otherwise, "errors" should be a pointer to a "U32" variable,
10836               which this function sets to indicate any errors found.  Upon
10837               return, if *errors is 0, there were no errors found.
10838               Otherwise, *errors is the bit-wise "OR" of the bits described
10839               in the list below.  Some of these bits will be set if a
10840               malformation is found, even if the input "flags" parameter
10841               indicates that the given malformation is allowed; those
10842               exceptions are noted:
10843
10844               "UTF8_GOT_PERL_EXTENDED"
10845                   The input sequence is not standard UTF-8, but a Perl
10846                   extension.  This bit is set only if the input "flags"
10847                   parameter contains either the "UTF8_DISALLOW_PERL_EXTENDED"
10848                   or the "UTF8_WARN_PERL_EXTENDED" flags.
10849
10850                   Code points above 0x7FFF_FFFF (2**31 - 1) were never
10851                   specified in any standard, and so some extension must be
10852                   used to express them.  Perl uses a natural extension to
10853                   UTF-8 to represent the ones up to 2**36-1, and invented a
10854                   further extension to represent even higher ones, so that
10855                   any code point that fits in a 64-bit word can be
10856                   represented.  Text using these extensions is not likely to
10857                   be portable to non-Perl code.  We lump both of these
10858                   extensions together and refer to them as Perl extended
10859                   UTF-8.  There exist other extensions that people have
10860                   invented, incompatible with Perl's.
10861
10862                   On EBCDIC platforms starting in Perl v5.24, the Perl
10863                   extension for representing extremely high code points kicks
10864                   in at 0x3FFF_FFFF (2**30 -1), which is lower than on ASCII.
10865                   Prior to that, code points 2**31 and higher were simply
10866                   unrepresentable, and a different, incompatible method was
10867                   used to represent code points between 2**30 and 2**31 - 1.
10868
10869                   On both platforms, ASCII and EBCDIC,
10870                   "UTF8_GOT_PERL_EXTENDED" is set if Perl extended UTF-8 is
10871                   used.
10872
10873                   In earlier Perls, this bit was named
10874                   "UTF8_GOT_ABOVE_31_BIT", which you still may use for
10875                   backward compatibility.  That name is misleading, as this
10876                   flag may be set when the code point actually does fit in 31
10877                   bits.  This happens on EBCDIC platforms, and sometimes when
10878                   the overlong malformation is also present.  The new name
10879                   accurately describes the situation in all cases.
10880
10881               "UTF8_GOT_CONTINUATION"
10882                   The input sequence was malformed in that the first byte was
10883                   a UTF-8 continuation byte.
10884
10885               "UTF8_GOT_EMPTY"
10886                   The input "curlen" parameter was 0.
10887
10888               "UTF8_GOT_LONG"
10889                   The input sequence was malformed in that there is some
10890                   other sequence that evaluates to the same code point, but
10891                   that sequence is shorter than this one.
10892
10893                   Until Unicode 3.1, it was legal for programs to accept this
10894                   malformation, but it was discovered that this created
10895                   security issues.
10896
10897               "UTF8_GOT_NONCHAR"
10898                   The code point represented by the input UTF-8 sequence is
10899                   for a Unicode non-character code point.  This bit is set
10900                   only if the input "flags" parameter contains either the
10901                   "UTF8_DISALLOW_NONCHAR" or the "UTF8_WARN_NONCHAR" flags.
10902
10903               "UTF8_GOT_NON_CONTINUATION"
10904                   The input sequence was malformed in that a non-continuation
10905                   type byte was found in a position where only a continuation
10906                   type one should be.  See also ""UTF8_GOT_SHORT"".
10907
10908               "UTF8_GOT_OVERFLOW"
10909                   The input sequence was malformed in that it is for a code
10910                   point that is not representable in the number of bits
10911                   available in an IV on the current platform.
10912
10913               "UTF8_GOT_SHORT"
10914                   The input sequence was malformed in that "curlen" is
10915                   smaller than required for a complete sequence.  In other
10916                   words, the input is for a partial character sequence.
10917
10918                   "UTF8_GOT_SHORT" and "UTF8_GOT_NON_CONTINUATION" both
10919                   indicate a too short sequence.  The difference is that
10920                   "UTF8_GOT_NON_CONTINUATION" indicates always that there is
10921                   an error, while "UTF8_GOT_SHORT" means that an incomplete
10922                   sequence was looked at.   If no other flags are present, it
10923                   means that the sequence was valid as far as it went.
10924                   Depending on the application, this could mean one of three
10925                   things:
10926
10927                   ·   The "curlen" length parameter passed in was too small,
10928                       and the function was prevented from examining all the
10929                       necessary bytes.
10930
10931                   ·   The buffer being looked at is based on reading data,
10932                       and the data received so far stopped in the middle of a
10933                       character, so that the next read will read the
10934                       remainder of this character.  (It is up to the caller
10935                       to deal with the split bytes somehow.)
10936
10937                   ·   This is a real error, and the partial sequence is all
10938                       we're going to get.
10939
10940               "UTF8_GOT_SUPER"
10941                   The input sequence was malformed in that it is for a non-
10942                   Unicode code point; that is, one above the legal Unicode
10943                   maximum.  This bit is set only if the input "flags"
10944                   parameter contains either the "UTF8_DISALLOW_SUPER" or the
10945                   "UTF8_WARN_SUPER" flags.
10946
10947               "UTF8_GOT_SURROGATE"
10948                   The input sequence was malformed in that it is for a
10949                   -Unicode UTF-16 surrogate code point.  This bit is set only
10950                   if the input "flags" parameter contains either the
10951                   "UTF8_DISALLOW_SURROGATE" or the "UTF8_WARN_SURROGATE"
10952                   flags.
10953
10954               To do your own error handling, call this function with the
10955               "UTF8_CHECK_ONLY" flag to suppress any warnings, and then
10956               examine the *errors return.
10957
10958                       UV      utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
10959                                                    STRLEN *retlen,
10960                                                    const U32 flags,
10961                                                    U32 * errors)
10962
10963       utf8n_to_uvchr_msgs
10964               NOTE: this function is experimental and may change or be
10965               removed without notice.
10966
10967               THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
10968               CIRCUMSTANCES.  Most code should use "utf8_to_uvchr_buf"()
10969               rather than call this directly.
10970
10971               This function is for code that needs to know what the precise
10972               malformation(s) are when an error is found, and wants the
10973               corresponding warning and/or error messages to be returned to
10974               the caller rather than be displayed.  All messages that would
10975               have been displayed if all lexcial warnings are enabled will be
10976               returned.
10977
10978               It is just like "utf8n_to_uvchr_error" but it takes an extra
10979               parameter placed after all the others, "msgs".  If this
10980               parameter is 0, this function behaves identically to
10981               "utf8n_to_uvchr_error".  Otherwise, "msgs" should be a pointer
10982               to an "AV *" variable, in which this function creates a new AV
10983               to contain any appropriate messages.  The elements of the array
10984               are ordered so that the first message that would have been
10985               displayed is in the 0th element, and so on.  Each element is a
10986               hash with three key-value pairs, as follows:
10987
10988               "text"
10989                   The text of the message as a "SVpv".
10990
10991               "warn_categories"
10992                   The warning category (or categories) packed into a "SVuv".
10993
10994               "flag"
10995                   A single flag bit associated with this message, in a
10996                   "SVuv".  The bit corresponds to some bit in the *errors
10997                   return value, such as "UTF8_GOT_LONG".
10998
10999               It's important to note that specifying this parameter as non-
11000               null will cause any warnings this function would otherwise
11001               generate to be suppressed, and instead be placed in *msgs.  The
11002               caller can check the lexical warnings state (or not) when
11003               choosing what to do with the returned messages.
11004
11005               If the flag "UTF8_CHECK_ONLY" is passed, no warnings are
11006               generated, and hence no AV is created.
11007
11008               The caller, of course, is responsible for freeing any returned
11009               AV.
11010
11011                       UV      utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
11012                                                   STRLEN *retlen,
11013                                                   const U32 flags,
11014                                                   U32 * errors, AV ** msgs)
11015
11016       UTF8SKIP
11017               returns the number of bytes a non-malformed UTF-8 encoded
11018               character whose first (perhaps only) byte is pointed to by "s".
11019
11020               If there is a possibility of malformed input, use instead:
11021
11022               ""UTF8_SAFE_SKIP"" if you know the maximum ending pointer in
11023               the buffer pointed to by "s"; or
11024               ""UTF8_CHK_SKIP"" if you don't know it.
11025
11026               It is better to restructure your code so the end pointer is
11027               passed down so that you know what it actually is at the point
11028               of this call, but if that isn't possible, ""UTF8_CHK_SKIP"" can
11029               minimize the chance of accessing beyond the end of the input
11030               buffer.
11031
11032                       STRLEN  UTF8SKIP(char* s)
11033
11034       UTF8_CHK_SKIP
11035               This is a safer version of ""UTF8SKIP"", but still not as safe
11036               as ""UTF8_SAFE_SKIP"".  This version doesn't blindly assume
11037               that the input string pointed to by "s" is well-formed, but
11038               verifies that there isn't a NUL terminating character before
11039               the expected end of the next character in "s".  The length
11040               "UTF8_CHK_SKIP" returns stops just before any such NUL.
11041
11042               Perl tends to add NULs, as an insurance policy, after the end
11043               of strings in SV's, so it is likely that using this macro will
11044               prevent inadvertent reading beyond the end of the input buffer,
11045               even if it is malformed UTF-8.
11046
11047               This macro is intended to be used by XS modules where the
11048               inputs could be malformed, and it isn't feasible to restructure
11049               to use the safer ""UTF8_SAFE_SKIP"", for example when
11050               interfacing with a C library.
11051
11052                       STRLEN  UTF8_CHK_SKIP(char* s)
11053
11054       utf8_distance
11055               Returns the number of UTF-8 characters between the UTF-8
11056               pointers "a" and "b".
11057
11058               WARNING: use only if you *know* that the pointers point inside
11059               the same UTF-8 buffer.
11060
11061                       IV      utf8_distance(const U8 *a, const U8 *b)
11062
11063       utf8_hop
11064               Return the UTF-8 pointer "s" displaced by "off" characters,
11065               either forward or backward.
11066
11067               WARNING: do not use the following unless you *know* "off" is
11068               within the UTF-8 data pointed to by "s" *and* that on entry "s"
11069               is aligned on the first byte of character or just after the
11070               last byte of a character.
11071
11072                       U8*     utf8_hop(const U8 *s, SSize_t off)
11073
11074       utf8_hop_back
11075               Return the UTF-8 pointer "s" displaced by up to "off"
11076               characters, backward.
11077
11078               "off" must be non-positive.
11079
11080               "s" must be after or equal to "start".
11081
11082               When moving backward it will not move before "start".
11083
11084               Will not exceed this limit even if the string is not valid
11085               "UTF-8".
11086
11087                       U8*     utf8_hop_back(const U8 *s, SSize_t off,
11088                                             const U8 *start)
11089
11090       utf8_hop_forward
11091               Return the UTF-8 pointer "s" displaced by up to "off"
11092               characters, forward.
11093
11094               "off" must be non-negative.
11095
11096               "s" must be before or equal to "end".
11097
11098               When moving forward it will not move beyond "end".
11099
11100               Will not exceed this limit even if the string is not valid
11101               "UTF-8".
11102
11103                       U8*     utf8_hop_forward(const U8 *s, SSize_t off,
11104                                                const U8 *end)
11105
11106       utf8_hop_safe
11107               Return the UTF-8 pointer "s" displaced by up to "off"
11108               characters, either forward or backward.
11109
11110               When moving backward it will not move before "start".
11111
11112               When moving forward it will not move beyond "end".
11113
11114               Will not exceed those limits even if the string is not valid
11115               "UTF-8".
11116
11117                       U8*     utf8_hop_safe(const U8 *s, SSize_t off,
11118                                             const U8 *start, const U8 *end)
11119
11120       UTF8_IS_INVARIANT
11121               Evaluates to 1 if the byte "c" represents the same character
11122               when encoded in UTF-8 as when not; otherwise evaluates to 0.
11123               UTF-8 invariant characters can be copied as-is when converting
11124               to/from UTF-8, saving time.
11125
11126               In spite of the name, this macro gives the correct result if
11127               the input string from which "c" comes is not encoded in UTF-8.
11128
11129               See "UVCHR_IS_INVARIANT" for checking if a UV is invariant.
11130
11131                       bool    UTF8_IS_INVARIANT(char c)
11132
11133       UTF8_IS_NONCHAR
11134               Evaluates to non-zero if the first few bytes of the string
11135               starting at "s" and looking no further than "e - 1" are well-
11136               formed UTF-8 that represents one of the Unicode non-character
11137               code points; otherwise it evaluates to 0.  If non-zero, the
11138               value gives how many bytes starting at "s" comprise the code
11139               point's representation.
11140
11141                       bool    UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
11142
11143       UTF8_IS_SUPER
11144               Recall that Perl recognizes an extension to UTF-8 that can
11145               encode code points larger than the ones defined by Unicode,
11146               which are 0..0x10FFFF.
11147
11148               This macro evaluates to non-zero if the first few bytes of the
11149               string starting at "s" and looking no further than "e - 1" are
11150               from this UTF-8 extension; otherwise it evaluates to 0.  If
11151               non-zero, the value gives how many bytes starting at "s"
11152               comprise the code point's representation.
11153
11154               0 is returned if the bytes are not well-formed extended UTF-8,
11155               or if they represent a code point that cannot fit in a UV on
11156               the current platform.  Hence this macro can give different
11157               results when run on a 64-bit word machine than on one with a
11158               32-bit word size.
11159
11160               Note that it is illegal to have code points that are larger
11161               than what can fit in an IV on the current machine.
11162
11163                       bool    UTF8_IS_SUPER(const U8 *s, const U8 *e)
11164
11165       UTF8_IS_SURROGATE
11166               Evaluates to non-zero if the first few bytes of the string
11167               starting at "s" and looking no further than "e - 1" are well-
11168               formed UTF-8 that represents one of the Unicode surrogate code
11169               points; otherwise it evaluates to 0.  If non-zero, the value
11170               gives how many bytes starting at "s" comprise the code point's
11171               representation.
11172
11173                       bool    UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
11174
11175       utf8_length
11176               Returns the number of characters in the sequence of
11177               UTF-8-encoded bytes starting at "s" and ending at the byte just
11178               before "e".  If <s> and <e> point to the same place, it returns
11179               0 with no warning raised.
11180
11181               If "e < s" or if the scan would end up past "e", it raises a
11182               UTF8 warning and returns the number of valid characters.
11183
11184                       STRLEN  utf8_length(const U8* s, const U8 *e)
11185
11186       UTF8_MAXBYTES
11187               The maximum width of a single UTF-8 encoded character, in
11188               bytes.
11189
11190               NOTE: Strictly speaking Perl's UTF-8 should not be called UTF-8
11191               since UTF-8 is an encoding of Unicode, and Unicode's upper
11192               limit, 0x10FFFF, can be expressed with 4 bytes.  However, Perl
11193               thinks of UTF-8 as a way to encode non-negative integers in a
11194               binary format, even those above Unicode.
11195
11196       UTF8_MAXBYTES_CASE
11197               The maximum number of UTF-8 bytes a single Unicode character
11198               can uppercase/lowercase/titlecase/fold into.
11199
11200       UTF8_SAFE_SKIP
11201               returns 0 if "s >= e"; otherwise returns the number of bytes in
11202               the UTF-8 encoded character whose first  byte is pointed to by
11203               "s".  But it never returns beyond "e".  On DEBUGGING builds, it
11204               asserts that "s <= e".
11205
11206                       STRLEN  UTF8_SAFE_SKIP(char* s, char* e)
11207
11208       UTF8_SKIP
11209               This is a synonym for ""UTF8SKIP""
11210
11211                       STRLEN  UTF8_SKIP(char* s)
11212
11213       utf8_to_bytes
11214               NOTE: this function is experimental and may change or be
11215               removed without notice.
11216
11217               Converts a string "s" of length *lenp from UTF-8 into native
11218               byte encoding.  Unlike "bytes_to_utf8", this over-writes the
11219               original string, and updates *lenp to contain the new length.
11220               Returns zero on failure (leaving "s" unchanged) setting *lenp
11221               to -1.
11222
11223               Upon successful return, the number of variants in the string
11224               can be computed by having saved the value of *lenp before the
11225               call, and subtracting the after-call value of *lenp from it.
11226
11227               If you need a copy of the string, see "bytes_from_utf8".
11228
11229                       U8*     utf8_to_bytes(U8 *s, STRLEN *lenp)
11230
11231       utf8_to_uvchr_buf
11232               Returns the native code point of the first character in the
11233               string "s" which is assumed to be in UTF-8 encoding; "send"
11234               points to 1 beyond the end of "s".  *retlen will be set to the
11235               length, in bytes, of that character.
11236
11237               If "s" does not point to a well-formed UTF-8 character and UTF8
11238               warnings are enabled, zero is returned and *retlen is set (if
11239               "retlen" isn't "NULL") to -1.  If those warnings are off, the
11240               computed value, if well-defined (or the Unicode REPLACEMENT
11241               CHARACTER if not), is silently returned, and *retlen is set (if
11242               "retlen" isn't "NULL") so that ("s" + *retlen) is the next
11243               possible position in "s" that could begin a non-malformed
11244               character.  See "utf8n_to_uvchr" for details on when the
11245               REPLACEMENT CHARACTER is returned.
11246
11247                       UV      utf8_to_uvchr_buf(const U8 *s, const U8 *send,
11248                                                 STRLEN *retlen)
11249
11250       UVCHR_IS_INVARIANT
11251               Evaluates to 1 if the representation of code point "cp" is the
11252               same whether or not it is encoded in UTF-8; otherwise evaluates
11253               to 0.  UTF-8 invariant characters can be copied as-is when
11254               converting to/from UTF-8, saving time.  "cp" is Unicode if
11255               above 255; otherwise is platform-native.
11256
11257                       bool    UVCHR_IS_INVARIANT(UV cp)
11258
11259       UVCHR_SKIP
11260               returns the number of bytes required to represent the code
11261               point "cp" when encoded as UTF-8.  "cp" is a native (ASCII or
11262               EBCDIC) code point if less than 255; a Unicode code point
11263               otherwise.
11264
11265                       STRLEN  UVCHR_SKIP(UV cp)
11266
11267       uvchr_to_utf8
11268               Adds the UTF-8 representation of the native code point "uv" to
11269               the end of the string "d"; "d" should have at least
11270               "UVCHR_SKIP(uv)+1" (up to "UTF8_MAXBYTES+1") free bytes
11271               available.  The return value is the pointer to the byte after
11272               the end of the new character.  In other words,
11273
11274                   d = uvchr_to_utf8(d, uv);
11275
11276               is the recommended wide native character-aware way of saying
11277
11278                   *(d++) = uv;
11279
11280               This function accepts any code point from 0.."IV_MAX" as input.
11281               "IV_MAX" is typically 0x7FFF_FFFF in a 32-bit word.
11282
11283               It is possible to forbid or warn on non-Unicode code points, or
11284               those that may be problematic by using "uvchr_to_utf8_flags".
11285
11286                       U8*     uvchr_to_utf8(U8 *d, UV uv)
11287
11288       uvchr_to_utf8_flags
11289               Adds the UTF-8 representation of the native code point "uv" to
11290               the end of the string "d"; "d" should have at least
11291               "UVCHR_SKIP(uv)+1" (up to "UTF8_MAXBYTES+1") free bytes
11292               available.  The return value is the pointer to the byte after
11293               the end of the new character.  In other words,
11294
11295                   d = uvchr_to_utf8_flags(d, uv, flags);
11296
11297               or, in most cases,
11298
11299                   d = uvchr_to_utf8_flags(d, uv, 0);
11300
11301               This is the Unicode-aware way of saying
11302
11303                   *(d++) = uv;
11304
11305               If "flags" is 0, this function accepts any code point from
11306               0.."IV_MAX" as input.  "IV_MAX" is typically 0x7FFF_FFFF in a
11307               32-bit word.
11308
11309               Specifying "flags" can further restrict what is allowed and not
11310               warned on, as follows:
11311
11312               If "uv" is a Unicode surrogate code point and
11313               "UNICODE_WARN_SURROGATE" is set, the function will raise a
11314               warning, provided UTF8 warnings are enabled.  If instead
11315               "UNICODE_DISALLOW_SURROGATE" is set, the function will fail and
11316               return NULL.  If both flags are set, the function will both
11317               warn and return NULL.
11318
11319               Similarly, the "UNICODE_WARN_NONCHAR" and
11320               "UNICODE_DISALLOW_NONCHAR" flags affect how the function
11321               handles a Unicode non-character.
11322
11323               And likewise, the "UNICODE_WARN_SUPER" and
11324               "UNICODE_DISALLOW_SUPER" flags affect the handling of code
11325               points that are above the Unicode maximum of 0x10FFFF.
11326               Languages other than Perl may not be able to accept files that
11327               contain these.
11328
11329               The flag "UNICODE_WARN_ILLEGAL_INTERCHANGE" selects all three
11330               of the above WARN flags; and
11331               "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE" selects all three
11332               DISALLOW flags.  "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE"
11333               restricts the allowed inputs to the strict UTF-8 traditionally
11334               defined by Unicode.  Similarly,
11335               "UNICODE_WARN_ILLEGAL_C9_INTERCHANGE" and
11336               "UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE" are shortcuts to
11337               select the above-Unicode and surrogate flags, but not the non-
11338               character ones, as defined in Unicode Corrigendum #9
11339               <https://www.unicode.org/versions/corrigendum9.html>.  See
11340               "Noncharacter code points" in perlunicode.
11341
11342               Extremely high code points were never specified in any
11343               standard, and require an extension to UTF-8 to express, which
11344               Perl does.  It is likely that programs written in something
11345               other than Perl would not be able to read files that contain
11346               these; nor would Perl understand files written by something
11347               that uses a different extension.  For these reasons, there is a
11348               separate set of flags that can warn and/or disallow these
11349               extremely high code points, even if other above-Unicode ones
11350               are accepted.  They are the "UNICODE_WARN_PERL_EXTENDED" and
11351               "UNICODE_DISALLOW_PERL_EXTENDED" flags.  For more information
11352               see ""UTF8_GOT_PERL_EXTENDED"".  Of course
11353               "UNICODE_DISALLOW_SUPER" will treat all above-Unicode code
11354               points, including these, as malformations.  (Note that the
11355               Unicode standard considers anything above 0x10FFFF to be
11356               illegal, but there are standards predating it that allow up to
11357               0x7FFF_FFFF (2**31 -1))
11358
11359               A somewhat misleadingly named synonym for
11360               "UNICODE_WARN_PERL_EXTENDED" is retained for backward
11361               compatibility: "UNICODE_WARN_ABOVE_31_BIT".  Similarly,
11362               "UNICODE_DISALLOW_ABOVE_31_BIT" is usable instead of the more
11363               accurately named "UNICODE_DISALLOW_PERL_EXTENDED".  The names
11364               are misleading because on EBCDIC platforms,these flags can
11365               apply to code points that actually do fit in 31 bits.  The new
11366               names accurately describe the situation in all cases.
11367
11368                       U8*     uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
11369
11370       uvchr_to_utf8_flags_msgs
11371               NOTE: this function is experimental and may change or be
11372               removed without notice.
11373
11374               THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
11375               CIRCUMSTANCES.
11376
11377               Most code should use ""uvchr_to_utf8_flags"()" rather than call
11378               this directly.
11379
11380               This function is for code that wants any warning and/or error
11381               messages to be returned to the caller rather than be displayed.
11382               All messages that would have been displayed if all lexical
11383               warnings are enabled will be returned.
11384
11385               It is just like "uvchr_to_utf8_flags" but it takes an extra
11386               parameter placed after all the others, "msgs".  If this
11387               parameter is 0, this function behaves identically to
11388               "uvchr_to_utf8_flags".  Otherwise, "msgs" should be a pointer
11389               to an "HV *" variable, in which this function creates a new HV
11390               to contain any appropriate messages.  The hash has three key-
11391               value pairs, as follows:
11392
11393               "text"
11394                   The text of the message as a "SVpv".
11395
11396               "warn_categories"
11397                   The warning category (or categories) packed into a "SVuv".
11398
11399               "flag"
11400                   A single flag bit associated with this message, in a
11401                   "SVuv".  The bit corresponds to some bit in the *errors
11402                   return value, such as "UNICODE_GOT_SURROGATE".
11403
11404               It's important to note that specifying this parameter as non-
11405               null will cause any warnings this function would otherwise
11406               generate to be suppressed, and instead be placed in *msgs.  The
11407               caller can check the lexical warnings state (or not) when
11408               choosing what to do with the returned messages.
11409
11410               The caller, of course, is responsible for freeing any returned
11411               HV.
11412
11413                       U8*     uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags,
11414                                                        HV ** msgs)
11415

Variables created by "xsubpp" and "xsubpp" internal functions

11417       newXSproto
11418               Used by "xsubpp" to hook up XSUBs as Perl subs.  Adds Perl
11419               prototypes to the subs.
11420
11421       XS_APIVERSION_BOOTCHECK
11422               Macro to verify that the perl api version an XS module has been
11423               compiled against matches the api version of the perl
11424               interpreter it's being loaded into.
11425
11426                               XS_APIVERSION_BOOTCHECK;
11427
11428       XS_VERSION
11429               The version identifier for an XS module.  This is usually
11430               handled automatically by "ExtUtils::MakeMaker".  See
11431               "XS_VERSION_BOOTCHECK".
11432
11433       XS_VERSION_BOOTCHECK
11434               Macro to verify that a PM module's $VERSION variable matches
11435               the XS module's "XS_VERSION" variable.  This is usually handled
11436               automatically by "xsubpp".  See "The VERSIONCHECK: Keyword" in
11437               perlxs.
11438
11439                               XS_VERSION_BOOTCHECK;
11440

Warning and Dieing

11442       In all these calls, the "U32 wn" parameters are warning category
11443       constants.  You can see the ones currently available in "Category
11444       Hierarchy" in warnings, just capitalize all letters in the names and
11445       prefix them by "WARN_".  So, for example, the category "void" used in a
11446       perl program becomes "WARN_VOID" when used in XS code and passed to one
11447       of the calls below.
11448
11449       ckWARN  Returns a boolean as to whether or not warnings are enabled for
11450               the warning category "w".  If the category is by default
11451               enabled even if not within the scope of "use warnings", instead
11452               use the "ckWARN_d" macro.
11453
11454                       bool    ckWARN(U32 w)
11455
11456       ckWARN2 Like "ckWARN", but takes two warnings categories as input, and
11457               returns TRUE if either is enabled.  If either category is by
11458               default enabled even if not within the scope of "use warnings",
11459               instead use the "ckWARN2_d" macro.  The categories must be
11460               completely independent, one may not be subclassed from the
11461               other.
11462
11463                       bool    ckWARN2(U32 w1, U32 w2)
11464
11465       ckWARN3 Like "ckWARN2", but takes three warnings categories as input,
11466               and returns TRUE if any is enabled.  If any of the categories
11467               is by default enabled even if not within the scope of
11468               "use warnings", instead use the "ckWARN3_d" macro.  The
11469               categories must be completely independent, one may not be
11470               subclassed from any other.
11471
11472                       bool    ckWARN3(U32 w1, U32 w2, U32 w3)
11473
11474       ckWARN4 Like "ckWARN3", but takes four warnings categories as input,
11475               and returns TRUE if any is enabled.  If any of the categories
11476               is by default enabled even if not within the scope of
11477               "use warnings", instead use the "ckWARN4_d" macro.  The
11478               categories must be completely independent, one may not be
11479               subclassed from any other.
11480
11481                       bool    ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
11482
11483       ckWARN_d
11484               Like "ckWARN", but for use if and only if the warning category
11485               is by default enabled even if not within the scope of
11486               "use warnings".
11487
11488                       bool    ckWARN_d(U32 w)
11489
11490       ckWARN2_d
11491               Like "ckWARN2", but for use if and only if either warning
11492               category is by default enabled even if not within the scope of
11493               "use warnings".
11494
11495                       bool    ckWARN2_d(U32 w1, U32 w2)
11496
11497       ckWARN3_d
11498               Like "ckWARN3", but for use if and only if any of the warning
11499               categories is by default enabled even if not within the scope
11500               of "use warnings".
11501
11502                       bool    ckWARN3_d(U32 w1, U32 w2, U32 w3)
11503
11504       ckWARN4_d
11505               Like "ckWARN4", but for use if and only if any of the warning
11506               categories is by default enabled even if not within the scope
11507               of "use warnings".
11508
11509                       bool    ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
11510
11511       CLEAR_ERRSV
11512               Clear the contents of $@, setting it to the empty string.
11513
11514               This replaces any read-only SV with a fresh SV and removes any
11515               magic.
11516
11517                       void    CLEAR_ERRSV()
11518
11519       croak   This is an XS interface to Perl's "die" function.
11520
11521               Take a sprintf-style format pattern and argument list.  These
11522               are used to generate a string message.  If the message does not
11523               end with a newline, then it will be extended with some
11524               indication of the current location in the code, as described
11525               for "mess_sv".
11526
11527               The error message will be used as an exception, by default
11528               returning control to the nearest enclosing "eval", but subject
11529               to modification by a $SIG{__DIE__} handler.  In any case, the
11530               "croak" function never returns normally.
11531
11532               For historical reasons, if "pat" is null then the contents of
11533               "ERRSV" ($@) will be used as an error message or object instead
11534               of building an error message from arguments.  If you want to
11535               throw a non-string object, or build an error message in an SV
11536               yourself, it is preferable to use the "croak_sv" function,
11537               which does not involve clobbering "ERRSV".
11538
11539                       void    croak(const char* pat, ...)
11540
11541       croak_no_modify
11542               Exactly equivalent to "Perl_croak(aTHX_ "%s", PL_no_modify)",
11543               but generates terser object code than using "Perl_croak".  Less
11544               code used on exception code paths reduces CPU cache pressure.
11545
11546                       void    croak_no_modify()
11547
11548       croak_sv
11549               This is an XS interface to Perl's "die" function.
11550
11551               "baseex" is the error message or object.  If it is a reference,
11552               it will be used as-is.  Otherwise it is used as a string, and
11553               if it does not end with a newline then it will be extended with
11554               some indication of the current location in the code, as
11555               described for "mess_sv".
11556
11557               The error message or object will be used as an exception, by
11558               default returning control to the nearest enclosing "eval", but
11559               subject to modification by a $SIG{__DIE__} handler.  In any
11560               case, the "croak_sv" function never returns normally.
11561
11562               To die with a simple string message, the "croak" function may
11563               be more convenient.
11564
11565                       void    croak_sv(SV *baseex)
11566
11567       die     Behaves the same as "croak", except for the return type.  It
11568               should be used only where the "OP *" return type is required.
11569               The function never actually returns.
11570
11571                       OP*     die(const char* pat, ...)
11572
11573       die_sv  Behaves the same as "croak_sv", except for the return type.  It
11574               should be used only where the "OP *" return type is required.
11575               The function never actually returns.
11576
11577                       OP*     die_sv(SV *baseex)
11578
11579       ERRSV   Returns the SV for $@, creating it if needed.
11580
11581                       SV *    ERRSV
11582
11583       my_setenv
11584               A wrapper for the C library setenv(3).  Don't use the latter,
11585               as the perl version has desirable safeguards
11586
11587                       void    my_setenv(const char* nam, const char* val)
11588
11589       rsignal A wrapper for the C library signal(2).  Don't use the latter,
11590               as the Perl version knows things that interact with the rest of
11591               the perl interpreter.
11592
11593                       Sighandler_t rsignal(int i, Sighandler_t t)
11594
11595       SANE_ERRSV
11596               Clean up ERRSV so we can safely set it.
11597
11598               This replaces any read-only SV with a fresh writable copy and
11599               removes any magic.
11600
11601                       void    SANE_ERRSV()
11602
11603       vcroak  This is an XS interface to Perl's "die" function.
11604
11605               "pat" and "args" are a sprintf-style format pattern and
11606               encapsulated argument list.  These are used to generate a
11607               string message.  If the message does not end with a newline,
11608               then it will be extended with some indication of the current
11609               location in the code, as described for "mess_sv".
11610
11611               The error message will be used as an exception, by default
11612               returning control to the nearest enclosing "eval", but subject
11613               to modification by a $SIG{__DIE__} handler.  In any case, the
11614               "croak" function never returns normally.
11615
11616               For historical reasons, if "pat" is null then the contents of
11617               "ERRSV" ($@) will be used as an error message or object instead
11618               of building an error message from arguments.  If you want to
11619               throw a non-string object, or build an error message in an SV
11620               yourself, it is preferable to use the "croak_sv" function,
11621               which does not involve clobbering "ERRSV".
11622
11623                       void    vcroak(const char* pat, va_list* args)
11624
11625       vwarn   This is an XS interface to Perl's "warn" function.
11626
11627               "pat" and "args" are a sprintf-style format pattern and
11628               encapsulated argument list.  These are used to generate a
11629               string message.  If the message does not end with a newline,
11630               then it will be extended with some indication of the current
11631               location in the code, as described for "mess_sv".
11632
11633               The error message or object will by default be written to
11634               standard error, but this is subject to modification by a
11635               $SIG{__WARN__} handler.
11636
11637               Unlike with "vcroak", "pat" is not permitted to be null.
11638
11639                       void    vwarn(const char* pat, va_list* args)
11640
11641       warn    This is an XS interface to Perl's "warn" function.
11642
11643               Take a sprintf-style format pattern and argument list.  These
11644               are used to generate a string message.  If the message does not
11645               end with a newline, then it will be extended with some
11646               indication of the current location in the code, as described
11647               for "mess_sv".
11648
11649               The error message or object will by default be written to
11650               standard error, but this is subject to modification by a
11651               $SIG{__WARN__} handler.
11652
11653               Unlike with "croak", "pat" is not permitted to be null.
11654
11655                       void    warn(const char* pat, ...)
11656
11657       warn_sv This is an XS interface to Perl's "warn" function.
11658
11659               "baseex" is the error message or object.  If it is a reference,
11660               it will be used as-is.  Otherwise it is used as a string, and
11661               if it does not end with a newline then it will be extended with
11662               some indication of the current location in the code, as
11663               described for "mess_sv".
11664
11665               The error message or object will by default be written to
11666               standard error, but this is subject to modification by a
11667               $SIG{__WARN__} handler.
11668
11669               To warn with a simple string message, the "warn" function may
11670               be more convenient.
11671
11672                       void    warn_sv(SV *baseex)
11673

Undocumented functions

11675       The following functions have been flagged as part of the public API,
11676       but are currently undocumented.  Use them at your own risk, as the
11677       interfaces are subject to change.  Functions that are not listed in
11678       this document are not intended for public use, and should NOT be used
11679       under any circumstances.
11680
11681       If you feel you need to use one of these functions, first send email to
11682       perl5-porters@perl.org <mailto:perl5-porters@perl.org>.  It may be that
11683       there is a good reason for the function not being documented, and it
11684       should be removed from this list; or it may just be that no one has
11685       gotten around to documenting it.  In the latter case, you will be asked
11686       to submit a patch to document the function.  Once your patch is
11687       accepted, it will indicate that the interface is stable (unless it is
11688       explicitly marked otherwise) and usable by you.
11689
11690       CvDEPTH
11691       CvGV
11692       GetVars
11693       Gv_AMupdate
11694       PerlIO_close
11695       PerlIO_context_layers
11696       PerlIO_error
11697       PerlIO_fill
11698       PerlIO_flush
11699       PerlIO_get_bufsiz
11700       PerlIO_get_ptr
11701       PerlIO_read
11702       PerlIO_seek
11703       PerlIO_set_cnt
11704       PerlIO_setlinebuf
11705       PerlIO_stdout
11706       PerlIO_unread
11707       SvAMAGIC_off
11708       SvAMAGIC_on
11709       amagic_call
11710       amagic_deref_call
11711       any_dup
11712       atfork_lock
11713       atfork_unlock
11714       av_arylen_p
11715       av_iter_p
11716       block_gimme
11717       call_atexit
11718       call_list
11719       calloc
11720       cast_i32
11721       cast_iv
11722       cast_ulong
11723       cast_uv
11724       ck_warner
11725       ck_warner_d
11726       ckwarn
11727       ckwarn_d
11728       clear_defarray
11729       clone_params_del
11730       clone_params_new
11731       croak_nocontext
11732       csighandler
11733       csighandler1
11734       csighandler3
11735       cx_dump
11736       cx_dup
11737       cxinc
11738       deb
11739       deb_nocontext
11740       debop
11741       debprofdump
11742       debstack
11743       debstackptrs
11744       delimcpy
11745       despatch_signals
11746       die_nocontext
11747       dirp_dup
11748       do_aspawn
11749       do_close
11750       do_gv_dump
11751       do_gvgv_dump
11752       do_hv_dump
11753       do_join
11754       do_magic_dump
11755       do_op_dump
11756       do_open
11757       do_openn
11758       do_pmop_dump
11759       do_spawn
11760       do_spawn_nowait
11761       do_sprintf
11762       do_sv_dump
11763       doing_taint
11764       doref
11765       dounwind
11766       dowantarray
11767       dump_eval
11768       dump_form
11769       dump_indent
11770       dump_mstats
11771       dump_sub
11772       dump_vindent
11773       filter_del
11774       filter_read
11775       foldEQ_latin1
11776       form_nocontext
11777       fp_dup
11778       free_global_struct
11779       free_tmps
11780       get_context
11781       get_mstats
11782       get_op_descs
11783       get_op_names
11784       get_ppaddr
11785       get_vtbl
11786       gp_dup
11787       gp_free
11788       gp_ref
11789       gv_AVadd
11790       gv_HVadd
11791       gv_IOadd
11792       gv_SVadd
11793       gv_add_by_type
11794       gv_autoload4
11795       gv_autoload_pv
11796       gv_autoload_pvn
11797       gv_autoload_sv
11798       gv_check
11799       gv_dump
11800       gv_efullname3
11801       gv_efullname4
11802       gv_fetchfile
11803       gv_fetchfile_flags
11804       gv_fetchpv
11805       gv_fetchpvn_flags
11806       gv_fetchsv
11807       gv_fullname3
11808       gv_fullname4
11809       gv_handler
11810       gv_name_set
11811       he_dup
11812       hek_dup
11813       hv_common
11814       hv_common_key_len
11815       hv_delayfree_ent
11816       hv_eiter_p
11817       hv_eiter_set
11818       hv_free_ent
11819       hv_ksplit
11820       hv_name_set
11821       hv_placeholders_get
11822       hv_placeholders_set
11823       hv_rand_set
11824       hv_riter_p
11825       hv_riter_set
11826       ibcmp_utf8
11827       init_global_struct
11828       init_stacks
11829       init_tm
11830       is_lvalue_sub
11831       leave_scope
11832       load_module_nocontext
11833       magic_dump
11834       markstack_grow
11835       mess_nocontext
11836       mfree
11837       mg_dup
11838       mg_size
11839       mini_mktime
11840       moreswitches
11841       mro_get_from_name
11842       mro_set_mro
11843       mro_set_private_data
11844       my_atof
11845       my_chsize
11846       my_cxt_index
11847       my_cxt_init
11848       my_dirfd
11849       my_failure_exit
11850       my_fflush_all
11851       my_fork
11852       my_lstat
11853       my_pclose
11854       my_popen
11855       my_popen_list
11856       my_socketpair
11857       my_stat
11858       my_strftime
11859       newANONATTRSUB
11860       newANONHASH
11861       newANONLIST
11862       newANONSUB
11863       newATTRSUB
11864       newAVREF
11865       newCVREF
11866       newFORM
11867       newGVREF
11868       newGVgen
11869       newGVgen_flags
11870       newHVREF
11871       newHVhv
11872       newIO
11873       newMYSUB
11874       newPROG
11875       newRV
11876       newSUB
11877       newSVREF
11878       newSVpvf_nocontext
11879       newSVsv_flags
11880       new_stackinfo
11881       op_refcnt_lock
11882       op_refcnt_unlock
11883       parser_dup
11884       perl_alloc_using
11885       perl_clone_using
11886       perly_sighandler
11887       pmop_dump
11888       pop_scope
11889       pregcomp
11890       pregexec
11891       pregfree
11892       pregfree2
11893       ptr_table_fetch
11894       ptr_table_free
11895       ptr_table_new
11896       ptr_table_split
11897       ptr_table_store
11898       push_scope
11899       re_compile
11900       re_dup_guts
11901       reentrant_free
11902       reentrant_init
11903       reentrant_retry
11904       reentrant_size
11905       ref
11906       reg_named_buff_all
11907       reg_named_buff_exists
11908       reg_named_buff_fetch
11909       reg_named_buff_firstkey
11910       reg_named_buff_nextkey
11911       reg_named_buff_scalar
11912       regdump
11913       regdupe_internal
11914       regexec_flags
11915       regfree_internal
11916       reginitcolors
11917       regnext
11918       repeatcpy
11919       rsignal_state
11920       runops_debug
11921       runops_standard
11922       rvpv_dup
11923       safesyscalloc
11924       safesysfree
11925       safesysmalloc
11926       safesysrealloc
11927       save_I16
11928       save_I32
11929       save_I8
11930       save_adelete
11931       save_aelem
11932       save_aelem_flags
11933       save_alloc
11934       save_ary
11935       save_bool
11936       save_clearsv
11937       save_delete
11938       save_destructor
11939       save_destructor_x
11940       save_freeop
11941       save_freepv
11942       save_freesv
11943       save_generic_pvref
11944       save_generic_svref
11945       save_hdelete
11946       save_helem
11947       save_helem_flags
11948       save_hints
11949       save_hptr
11950       save_int
11951       save_item
11952       save_iv
11953       save_mortalizesv
11954       save_op
11955       save_padsv_and_mortalize
11956       save_pptr
11957       save_pushi32ptr
11958       save_pushptr
11959       save_pushptrptr
11960       save_re_context
11961       save_set_svflags
11962       save_shared_pvref
11963       save_sptr
11964       save_svref
11965       save_vptr
11966       savestack_grow
11967       savestack_grow_cnt
11968       scan_num
11969       scan_vstring
11970       seed
11971       set_context
11972       share_hek
11973       si_dup
11974       ss_dup
11975       stack_grow
11976       start_subparse
11977       str_to_version
11978       sv_2iv
11979       sv_2pv
11980       sv_2pvbyte_flags
11981       sv_2pvutf8_flags
11982       sv_2uv
11983       sv_catpvf_mg_nocontext
11984       sv_catpvf_nocontext
11985       sv_dup
11986       sv_dup_inc
11987       sv_peek
11988       sv_setpvf_mg_nocontext
11989       sv_setpvf_nocontext
11990       sys_init
11991       sys_init3
11992       sys_intern_clear
11993       sys_intern_dup
11994       sys_intern_init
11995       sys_term
11996       taint_env
11997       taint_proper
11998       unlnk
11999       unsharepvn
12000       vdeb
12001       vform
12002       vload_module
12003       vnewSVpvf
12004       vwarner
12005       warn_nocontext
12006       warner
12007       warner_nocontext
12008       whichsig
12009       whichsig_pv
12010       whichsig_pvn
12011       whichsig_sv
12012

AUTHORS

12014       Until May 1997, this document was maintained by Jeff Okamoto
12015       <okamoto@corp.hp.com>.  It is now maintained as part of Perl itself.
12016
12017       With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
12018       Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
12019       Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
12020       Stephen McCamant, and Gurusamy Sarathy.
12021
12022       API Listing originally by Dean Roehrich <roehrich@cray.com>.
12023
12024       Updated to be autogenerated from comments in the source by Benjamin
12025       Stuhl.
12026

SEE ALSO

12028       config.h perlapio perlcall perlclib perlfilter perlguts perlintern
12029       perlmroapi perlxs perlxstut warnings
12030
12031
12032
12033perl v5.32.1                      2021-03-31                        PERLAPI(1)
Impressum