1PERLAPI(1) Perl Programmers Reference Guide PERLAPI(1)
2
3
4
6 perlapi - autogenerated documentation for the perl public API
7
9 This file contains most of the documentation of the perl public API, as
10 generated by embed.pl. Specifically, it is a listing of functions,
11 macros, flags, and variables that may be used by extension writers.
12 Besides perlintern and config.h, some items are listed here as being
13 actually documented in another pod.
14
15 At the end is a list of functions which have yet to be documented.
16 Patches welcome! The interfaces of these are subject to change without
17 notice.
18
19 Some of the functions documented here are consolidated so that a single
20 entry serves for multiple functions which all do basically the same
21 thing, but have some slight differences. For example, one form might
22 process magic, while another doesn't. The name of each variation is
23 listed at the top of the single entry. But if all have the same
24 signature (arguments and return type) except for their names, only the
25 usage for the base form is shown. If any one of the forms has a
26 different signature (such as returning "const" or not) every function's
27 signature is explicitly displayed.
28
29 Anything not listed here or in the other mentioned pods is not part of
30 the public API, and should not be used by extension writers at all.
31 For these reasons, blindly using functions listed in proto.h is to be
32 avoided when writing extensions.
33
34 In Perl, unlike C, a string of characters may generally contain
35 embedded "NUL" characters. Sometimes in the documentation a Perl
36 string is referred to as a "buffer" to distinguish it from a C string,
37 but sometimes they are both just referred to as strings.
38
39 Note that all Perl API global variables must be referenced with the
40 "PL_" prefix. Again, those not listed here are not to be used by
41 extension writers, and can be changed or removed without notice; same
42 with macros. Some macros are provided for compatibility with the
43 older, unadorned names, but this support may be disabled in a future
44 release.
45
46 Perl was originally written to handle US-ASCII only (that is characters
47 whose ordinal numbers are in the range 0 - 127). And documentation and
48 comments may still use the term ASCII, when sometimes in fact the
49 entire range from 0 - 255 is meant.
50
51 The non-ASCII characters below 256 can have various meanings, depending
52 on various things. (See, most notably, perllocale.) But usually the
53 whole range can be referred to as ISO-8859-1. Often, the term
54 "Latin-1" (or "Latin1") is used as an equivalent for ISO-8859-1. But
55 some people treat "Latin1" as referring just to the characters in the
56 range 128 through 255, or sometimes from 160 through 255. This
57 documentation uses "Latin1" and "Latin-1" to refer to all 256
58 characters.
59
60 Note that Perl can be compiled and run under either ASCII or EBCDIC
61 (See perlebcdic). Most of the documentation (and even comments in the
62 code) ignore the EBCDIC possibility. For almost all purposes the
63 differences are transparent. As an example, under EBCDIC, instead of
64 UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so whenever
65 this documentation refers to "utf8" (and variants of that name,
66 including in function names), it also (essentially transparently) means
67 "UTF-EBCDIC". But the ordinals of characters differ between ASCII,
68 EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may
69 occupy a different number of bytes than in UTF-8.
70
71 The organization of this document is tentative and subject to change.
72 Suggestions and patches welcome perl5-porters@perl.org
73 <mailto:perl5-porters@perl.org>.
74
75 The sections in this document currently are
76
77 "AV Handling"
78 "Callback Functions"
79 "Casting"
80 "Character case changing"
81 "Character classification"
82 "Compiler and Preprocessor information"
83 "Compiler directives"
84 "Compile-time scope hooks"
85 "Concurrency"
86 "COP Hint Hashes"
87 "Custom Operators"
88 "CV Handling"
89 "Debugging"
90 "Display functions"
91 "Embedding and Interpreter Cloning"
92 "Errno"
93 "Exception Handling (simple) Macros"
94 "Filesystem configuration values"
95 "Floating point configuration values"
96 "Formats"
97 "General Configuration"
98 "Global Variables"
99 "GV Handling"
100 "Hook manipulation"
101 "HV Handling"
102 "Input/Output"
103 "Integer configuration values"
104 "Lexer interface"
105 "Locales"
106 "Magic"
107 "Memory Management"
108 "MRO"
109 "Multicall Functions"
110 "Numeric Functions"
111 "Optree construction"
112 "Optree Manipulation Functions"
113 "Pack and Unpack"
114 "Pad Data Structures"
115 "Password and Group access"
116 "Paths to system commands"
117 "Prototype information"
118 "REGEXP Functions"
119 "Signals"
120 "Site configuration"
121 "Sockets configuration values"
122 "Source Filters"
123 "Stack Manipulation Macros"
124 "String Handling"
125 "SV Flags"
126 "SV Handling"
127 "Time"
128 "Typedef names"
129 "Unicode Support"
130 "Utility Functions"
131 "Versioning"
132 "Warning and Dieing"
133 "XS"
134 "Undocumented elements"
135
136 The listing below is alphabetical, case insensitive.
137
139 "AV"
140 Described in perlguts.
141
142 "AvARRAY"
143 Returns a pointer to the AV's internal SV* array.
144
145 This is useful for doing pointer arithmetic on the array. If all
146 you need is to look up an array element, then prefer "av_fetch".
147
148 SV** AvARRAY(AV* av)
149
150 "av_clear"
151 Frees all the elements of an array, leaving it empty. The XS
152 equivalent of "@array = ()". See also "av_undef".
153
154 Note that it is possible that the actions of a destructor called
155 directly or indirectly by freeing an element of the array could
156 cause the reference count of the array itself to be reduced (e.g.
157 by deleting an entry in the symbol table). So it is a possibility
158 that the AV could have been freed (or even reallocated) on return
159 from the call unless you hold a reference to it.
160
161 void av_clear(AV *av)
162
163 "av_count"
164 Returns the number of elements in the array "av". This is the true
165 length of the array, including any undefined elements. It is
166 always the same as "av_top_index(av) + 1".
167
168 Size_t av_count(AV *av)
169
170 "av_create_and_push"
171 NOTE: "av_create_and_push" is experimental and may change or be
172 removed without notice.
173
174 Push an SV onto the end of the array, creating the array if
175 necessary. A small internal helper function to remove a commonly
176 duplicated idiom.
177
178 NOTE: "av_create_and_push" must be explicitly called as
179 "Perl_av_create_and_push" with an "aTHX_" parameter.
180
181 void Perl_av_create_and_push(pTHX_ AV **const avp,
182 SV *const val)
183
184 "av_create_and_unshift_one"
185 NOTE: "av_create_and_unshift_one" is experimental and may change or
186 be removed without notice.
187
188 Unshifts an SV onto the beginning of the array, creating the array
189 if necessary. A small internal helper function to remove a
190 commonly duplicated idiom.
191
192 NOTE: "av_create_and_unshift_one" must be explicitly called as
193 "Perl_av_create_and_unshift_one" with an "aTHX_" parameter.
194
195 SV** Perl_av_create_and_unshift_one(pTHX_ AV **const avp,
196 SV *const val)
197
198 "av_delete"
199 Deletes the element indexed by "key" from the array, makes the
200 element mortal, and returns it. If "flags" equals "G_DISCARD", the
201 element is freed and NULL is returned. NULL is also returned if
202 "key" is out of range.
203
204 Perl equivalent: "splice(@myarray, $key, 1, undef)" (with the
205 "splice" in void context if "G_DISCARD" is present).
206
207 SV* av_delete(AV *av, SSize_t key, I32 flags)
208
209 "av_exists"
210 Returns true if the element indexed by "key" has been initialized.
211
212 This relies on the fact that uninitialized array elements are set
213 to "NULL".
214
215 Perl equivalent: "exists($myarray[$key])".
216
217 bool av_exists(AV *av, SSize_t key)
218
219 "av_extend"
220 Pre-extend an array so that it is capable of storing values at
221 indexes "0..key". Thus "av_extend(av,99)" guarantees that the array
222 can store 100 elements, i.e. that "av_store(av, 0, sv)" through
223 "av_store(av, 99, sv)" on a plain array will work without any
224 further memory allocation.
225
226 If the av argument is a tied array then will call the "EXTEND" tied
227 array method with an argument of "(key+1)".
228
229 void av_extend(AV *av, SSize_t key)
230
231 "av_fetch"
232 Returns the SV at the specified index in the array. The "key" is
233 the index. If lval is true, you are guaranteed to get a real SV
234 back (in case it wasn't real before), which you can then modify.
235 Check that the return value is non-null before dereferencing it to
236 a "SV*".
237
238 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
239 for more information on how to use this function on tied arrays.
240
241 The rough perl equivalent is $myarray[$key].
242
243 SV** av_fetch(AV *av, SSize_t key, I32 lval)
244
245 "AvFILL"
246 Same as "av_top_index" or "av_tindex".
247
248 SSize_t AvFILL(AV* av)
249
250 "av_fill"
251 Set the highest index in the array to the given number, equivalent
252 to Perl's "$#array = $fill;".
253
254 The number of elements in the array will be "fill + 1" after
255 "av_fill()" returns. If the array was previously shorter, then the
256 additional elements appended are set to NULL. If the array was
257 longer, then the excess elements are freed. "av_fill(av, -1)" is
258 the same as "av_clear(av)".
259
260 void av_fill(AV *av, SSize_t fill)
261
262 "av_len"
263 Same as "av_top_index". Note that, unlike what the name implies,
264 it returns the maximum index in the array. This is unlike
265 "sv_len", which returns what you would expect.
266
267 To get the true number of elements in the array, instead use
268 "av_count".
269
270 SSize_t av_len(AV *av)
271
272 "av_make"
273 Creates a new AV and populates it with a list of SVs. The SVs are
274 copied into the array, so they may be freed after the call to
275 "av_make". The new AV will have a reference count of 1.
276
277 Perl equivalent: "my @new_array = ($scalar1, $scalar2,
278 $scalar3...);"
279
280 AV* av_make(SSize_t size, SV **strp)
281
282 "av_pop"
283 Removes one SV from the end of the array, reducing its size by one
284 and returning the SV (transferring control of one reference count)
285 to the caller. Returns &PL_sv_undef if the array is empty.
286
287 Perl equivalent: "pop(@myarray);"
288
289 SV* av_pop(AV *av)
290
291 "av_push"
292 Pushes an SV (transferring control of one reference count) onto the
293 end of the array. The array will grow automatically to accommodate
294 the addition.
295
296 Perl equivalent: "push @myarray, $val;".
297
298 void av_push(AV *av, SV *val)
299
300 "av_shift"
301 Removes one SV from the start of the array, reducing its size by
302 one and returning the SV (transferring control of one reference
303 count) to the caller. Returns &PL_sv_undef if the array is empty.
304
305 Perl equivalent: "shift(@myarray);"
306
307 SV* av_shift(AV *av)
308
309 "av_store"
310 Stores an SV in an array. The array index is specified as "key".
311 The return value will be "NULL" if the operation failed or if the
312 value did not need to be actually stored within the array (as in
313 the case of tied arrays). Otherwise, it can be dereferenced to get
314 the "SV*" that was stored there (= "val")).
315
316 Note that the caller is responsible for suitably incrementing the
317 reference count of "val" before the call, and decrementing it if
318 the function returned "NULL".
319
320 Approximate Perl equivalent: "splice(@myarray, $key, 1, $val)".
321
322 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
323 for more information on how to use this function on tied arrays.
324
325 SV** av_store(AV *av, SSize_t key, SV *val)
326
327 "av_tindex"
328 "av_top_index"
329 These behave identically. If the array "av" is empty, these return
330 -1; otherwise they return the maximum value of the indices of all
331 the array elements which are currently defined in "av".
332
333 They process 'get' magic.
334
335 The Perl equivalent for these is $#av.
336
337 Use "av_count" to get the number of elements in an array.
338
339 SSize_t av_tindex(AV *av)
340
341 "av_undef"
342 Undefines the array. The XS equivalent of "undef(@array)".
343
344 As well as freeing all the elements of the array (like
345 "av_clear()"), this also frees the memory used by the av to store
346 its list of scalars.
347
348 See "av_clear" for a note about the array possibly being invalid on
349 return.
350
351 void av_undef(AV *av)
352
353 "av_unshift"
354 Unshift the given number of "undef" values onto the beginning of
355 the array. The array will grow automatically to accommodate the
356 addition.
357
358 Perl equivalent: "unshift @myarray, ((undef) x $num);"
359
360 void av_unshift(AV *av, SSize_t num)
361
362 "get_av"
363 Returns the AV of the specified Perl global or package array with
364 the given name (so it won't work on lexical variables). "flags"
365 are passed to "gv_fetchpv". If "GV_ADD" is set and the Perl
366 variable does not exist then it will be created. If "flags" is
367 zero and the variable does not exist then NULL is returned.
368
369 Perl equivalent: "@{"$name"}".
370
371 NOTE: the "perl_get_av()" form is deprecated.
372
373 AV* get_av(const char *name, I32 flags)
374
375 "newAV"
376 Creates a new AV. The reference count is set to 1.
377
378 Perl equivalent: "my @array;".
379
380 AV* newAV()
381
382 "Nullav"
383 "DEPRECATED!" It is planned to remove "Nullav" from a future
384 release of Perl. Do not use it for new code; remove it from
385 existing code.
386
387 Null AV pointer.
388
389 (deprecated - use "(AV *)NULL" instead)
390
392 "call_argv"
393 Performs a callback to the specified named and package-scoped Perl
394 subroutine with "argv" (a "NULL"-terminated array of strings) as
395 arguments. See perlcall.
396
397 Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
398
399 NOTE: the "perl_call_argv()" form is deprecated.
400
401 I32 call_argv(const char* sub_name, I32 flags, char** argv)
402
403 "call_method"
404 Performs a callback to the specified Perl method. The blessed
405 object must be on the stack. See perlcall.
406
407 NOTE: the "perl_call_method()" form is deprecated.
408
409 I32 call_method(const char* methname, I32 flags)
410
411 "call_pv"
412 Performs a callback to the specified Perl sub. See perlcall.
413
414 NOTE: the "perl_call_pv()" form is deprecated.
415
416 I32 call_pv(const char* sub_name, I32 flags)
417
418 "call_sv"
419 Performs a callback to the Perl sub specified by the SV.
420
421 If neither the "G_METHOD" nor "G_METHOD_NAMED" flag is supplied,
422 the SV may be any of a CV, a GV, a reference to a CV, a reference
423 to a GV or "SvPV(sv)" will be used as the name of the sub to call.
424
425 If the "G_METHOD" flag is supplied, the SV may be a reference to a
426 CV or "SvPV(sv)" will be used as the name of the method to call.
427
428 If the "G_METHOD_NAMED" flag is supplied, "SvPV(sv)" will be used
429 as the name of the method to call.
430
431 Some other values are treated specially for internal use and should
432 not be depended on.
433
434 See perlcall.
435
436 NOTE: the "perl_call_sv()" form is deprecated.
437
438 I32 call_sv(SV* sv, volatile I32 flags)
439
440 "ENTER"
441 Opening bracket on a callback. See "LEAVE" and perlcall.
442
443 ENTER;
444
445 "ENTER_with_name"
446 Same as "ENTER", but when debugging is enabled it also associates
447 the given literal string with the new scope.
448
449 ENTER_with_name("name");
450
451 "eval_pv"
452 Tells Perl to "eval" the given string in scalar context and return
453 an SV* result.
454
455 NOTE: the "perl_eval_pv()" form is deprecated.
456
457 SV* eval_pv(const char* p, I32 croak_on_error)
458
459 "eval_sv"
460 Tells Perl to "eval" the string in the SV. It supports the same
461 flags as "call_sv", with the obvious exception of "G_EVAL". See
462 perlcall.
463
464 The "G_RETHROW" flag can be used if you only need eval_sv() to
465 execute code specified by a string, but not catch any errors.
466
467 NOTE: the "perl_eval_sv()" form is deprecated.
468
469 I32 eval_sv(SV* sv, I32 flags)
470
471 "FREETMPS"
472 Closing bracket for temporaries on a callback. See "SAVETMPS" and
473 perlcall.
474
475 FREETMPS;
476
477 "G_ARRAY"
478 Described in perlcall.
479
480 "G_DISCARD"
481 Described in perlcall.
482
483 "G_EVAL"
484 Described in perlcall.
485
486 "GIMME"
487 "DEPRECATED!" It is planned to remove "GIMME" from a future
488 release of Perl. Do not use it for new code; remove it from
489 existing code.
490
491 A backward-compatible version of "GIMME_V" which can only return
492 "G_SCALAR" or "G_ARRAY"; in a void context, it returns "G_SCALAR".
493 Deprecated. Use "GIMME_V" instead.
494
495 U32 GIMME
496
497 "GIMME_V"
498 The XSUB-writer's equivalent to Perl's "wantarray". Returns
499 "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list context,
500 respectively. See perlcall for a usage example.
501
502 U32 GIMME_V
503
504 "G_KEEPERR"
505 Described in perlcall.
506
507 "G_NOARGS"
508 Described in perlcall.
509
510 "G_SCALAR"
511 Described in perlcall.
512
513 "G_VOID"
514 Described in perlcall.
515
516 "LEAVE"
517 Closing bracket on a callback. See "ENTER" and perlcall.
518
519 LEAVE;
520
521 "LEAVE_with_name"
522 Same as "LEAVE", but when debugging is enabled it first checks that
523 the scope has the given name. "name" must be a literal string.
524
525 LEAVE_with_name("name");
526
527 "PL_errgv"
528 Described in perlcall.
529
530 "SAVETMPS"
531 Opening bracket for temporaries on a callback. See "FREETMPS" and
532 perlcall.
533
534 SAVETMPS;
535
537 "cBOOL"
538 Cast-to-bool. A simple "(bool) expr" cast may not do the right
539 thing: if "bool" is defined as "char", for example, then the cast
540 from "int" is implementation-defined.
541
542 "(bool)!!(cbool)" in a ternary triggers a bug in xlc on AIX
543
544 bool cBOOL(bool expr)
545
546 "I_32"
547 Cast an NV to I32 while avoiding undefined C behavior
548
549 I32 I_32(NV what)
550
551 "INT2PTR"
552 Described in perlguts.
553
554 type INT2PTR(type, int value)
555
556 "I_V"
557 Cast an NV to IV while avoiding undefined C behavior
558
559 IV I_V(NV what)
560
561 "Perl_cpeep_t"
562 Described in perlguts.
563
564 "PTR2IV"
565 Described in perlguts.
566
567 IV PTR2IV(void * ptr)
568
569 "PTR2nat"
570 Described in perlguts.
571
572 IV PTR2nat(void *)
573
574 "PTR2NV"
575 Described in perlguts.
576
577 NV PTR2NV(void * ptr)
578
579 "PTR2ul"
580 Described in perlguts.
581
582 unsigned long PTR2ul(void *)
583
584 "PTR2UV"
585 Described in perlguts.
586
587 UV PTR2UV(void * ptr)
588
589 "PTRV"
590 Described in perlguts.
591
592 "U_32"
593 Cast an NV to U32 while avoiding undefined C behavior
594
595 U32 U_32(NV what)
596
597 "U_V"
598 Cast an NV to UV while avoiding undefined C behavior
599
600 UV U_V(NV what)
601
602 "XOP"
603 Described in perlguts.
604
606 Perl uses "full" Unicode case mappings. This means that converting a
607 single character to another case may result in a sequence of more than
608 one character. For example, the uppercase of "ss" (LATIN SMALL LETTER
609 SHARP S) is the two character sequence "SS". This presents some
610 complications The lowercase of all characters in the range 0..255 is
611 a single character, and thus "toLOWER_L1" is furnished. But,
612 "toUPPER_L1" can't exist, as it couldn't return a valid result for all
613 legal inputs. Instead "toUPPER_uvchr" has an API that does allow every
614 possible legal result to be returned.) Likewise no other function that
615 is crippled by not being able to give the correct results for the full
616 range of possible inputs has been implemented here.
617
618 "toFOLD"
619 Converts the specified character to foldcase. If the input is
620 anything but an ASCII uppercase character, that input character
621 itself is returned. Variant "toFOLD_A" is equivalent. (There is
622 no equivalent "to_FOLD_L1" for the full Latin1 range, as the full
623 generality of "toFOLD_uvchr" is needed there.)
624
625 U8 toFOLD(U8 ch)
626
627 "toFOLD_utf8"
628 "toFOLD_utf8_safe"
629 Converts the first UTF-8 encoded character in the sequence starting
630 at "p" and extending no further than "e - 1" to its foldcase
631 version, and stores that in UTF-8 in "s", and its length in bytes
632 in "lenp". Note that the buffer pointed to by "s" needs to be at
633 least "UTF8_MAXBYTES_CASE+1" bytes since the foldcase version may
634 be longer than the original character.
635
636 The first code point of the foldcased version is returned (but
637 note, as explained at the top of this section, that there may be
638 more).
639
640 It will not attempt to read beyond "e - 1", provided that the
641 constraint "s < e" is true (this is asserted for in "-DDEBUGGING"
642 builds). If the UTF-8 for the input character is malformed in some
643 way, the program may croak, or the function may return the
644 REPLACEMENT CHARACTER, at the discretion of the implementation, and
645 subject to change in future releases.
646
647 "toFOLD_utf8_safe" is now just a different spelling of plain
648 "toFOLD_utf8"
649
650 UV toFOLD_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
651
652 "toFOLD_uvchr"
653 Converts the code point "cp" to its foldcase version, and stores
654 that in UTF-8 in "s", and its length in bytes in "lenp". The code
655 point is interpreted as native if less than 256; otherwise as
656 Unicode. Note that the buffer pointed to by "s" needs to be at
657 least "UTF8_MAXBYTES_CASE+1" bytes since the foldcase version may
658 be longer than the original character.
659
660 The first code point of the foldcased version is returned (but
661 note, as explained at the top of this section, that there may be
662 more).
663
664 UV toFOLD_uvchr(UV cp, U8* s, STRLEN* lenp)
665
666 "toLOWER"
667 "toLOWER_A"
668 "toLOWER_L1"
669 "toLOWER_LATIN1"
670 "toLOWER_LC"
671 "toLOWER_uvchr"
672 "toLOWER_utf8"
673 "toLOWER_utf8_safe"
674 These all return the lowercase of a character. The differences are
675 what domain they operate on, and whether the input is specified as
676 a code point (those forms with a "cp" parameter) or as a UTF-8
677 string (the others). In the latter case, the code point to use is
678 the first one in the buffer of UTF-8 encoded code points,
679 delineated by the arguments "p .. e - 1".
680
681 "toLOWER" and "toLOWER_A" are synonyms of each other. They return
682 the lowercase of any uppercase ASCII-range code point. All other
683 inputs are returned unchanged. Since these are macros, the input
684 type may be any integral one, and the output will occupy the same
685 number of bits as the input.
686
687 "toLOWER_L1" and "toLOWER_LATIN1" are synonyms of each other. They
688 behave identically as "toLOWER" for ASCII-range input. But
689 additionally will return the lowercase of any uppercase code point
690 in the entire 0..255 range, assuming a Latin-1 encoding (or the
691 EBCDIC equivalent on such platforms).
692
693 "toLOWER_LC" returns the lowercase of the input code point
694 according to the rules of the current POSIX locale. Input code
695 points outside the range 0..255 are returned unchanged.
696
697 "toLOWER_uvchr" returns the lowercase of any Unicode code point.
698 The return value is identical to that of "toLOWER_L1" for input
699 code points in the 0..255 range. The lowercase of the vast
700 majority of Unicode code points is the same as the code point
701 itself. For these, and for code points above the legal Unicode
702 maximum, this returns the input code point unchanged. It
703 additionally stores the UTF-8 of the result into the buffer
704 beginning at "s", and its length in bytes into *lenp. The caller
705 must have made "s" large enough to contain at least
706 "UTF8_MAXBYTES_CASE+1" bytes to avoid possible overflow.
707
708 NOTE: the lowercase of a code point may be more than one code
709 point. The return value of this function is only the first of
710 these. The entire lowercase is returned in "s". To determine if
711 the result is more than a single code point, you can do something
712 like this:
713
714 uc = toLOWER_uvchr(cp, s, &len);
715 if (len > UTF8SKIP(s)) { is multiple code points }
716 else { is a single code point }
717
718 "toLOWER_utf8" and "toLOWER_utf8_safe" are synonyms of each other.
719 The only difference between these and "toLOWER_uvchr" is that the
720 source for these is encoded in UTF-8, instead of being a code
721 point. It is passed as a buffer starting at "p", with "e" pointing
722 to one byte beyond its end. The "p" buffer may certainly contain
723 more than one code point; but only the first one (up through
724 "e - 1") is examined. If the UTF-8 for the input character is
725 malformed in some way, the program may croak, or the function may
726 return the REPLACEMENT CHARACTER, at the discretion of the
727 implementation, and subject to change in future releases.
728
729 UV toLOWER (UV cp)
730 UV toLOWER_A (UV cp)
731 UV toLOWER_L1 (UV cp)
732 UV toLOWER_LATIN1 (UV cp)
733 UV toLOWER_LC (UV cp)
734 UV toLOWER_uvchr (UV cp, U8* s, STRLEN* lenp)
735 UV toLOWER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
736 UV toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
737
738 "toTITLE"
739 Converts the specified character to titlecase. If the input is
740 anything but an ASCII lowercase character, that input character
741 itself is returned. Variant "toTITLE_A" is equivalent. (There is
742 no "toTITLE_L1" for the full Latin1 range, as the full generality
743 of "toTITLE_uvchr" is needed there. Titlecase is not a concept
744 used in locale handling, so there is no functionality for that.)
745
746 U8 toTITLE(U8 ch)
747
748 "toTITLE_utf8"
749 "toTITLE_utf8_safe"
750 Convert the first UTF-8 encoded character in the sequence starting
751 at "p" and extending no further than "e - 1" to its titlecase
752 version, and stores that in UTF-8 in "s", and its length in bytes
753 in "lenp". Note that the buffer pointed to by "s" needs to be at
754 least "UTF8_MAXBYTES_CASE+1" bytes since the titlecase version may
755 be longer than the original character.
756
757 The first code point of the titlecased version is returned (but
758 note, as explained at the top of this section, that there may be
759 more).
760
761 It will not attempt to read beyond "e - 1", provided that the
762 constraint "s < e" is true (this is asserted for in "-DDEBUGGING"
763 builds). If the UTF-8 for the input character is malformed in some
764 way, the program may croak, or the function may return the
765 REPLACEMENT CHARACTER, at the discretion of the implementation, and
766 subject to change in future releases.
767
768 "toTITLE_utf8_safe" is now just a different spelling of plain
769 "toTITLE_utf8"
770
771 UV toTITLE_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
772
773 "toTITLE_uvchr"
774 Converts the code point "cp" to its titlecase version, and stores
775 that in UTF-8 in "s", and its length in bytes in "lenp". The code
776 point is interpreted as native if less than 256; otherwise as
777 Unicode. Note that the buffer pointed to by "s" needs to be at
778 least "UTF8_MAXBYTES_CASE+1" bytes since the titlecase version may
779 be longer than the original character.
780
781 The first code point of the titlecased version is returned (but
782 note, as explained at the top of this section, that there may be
783 more).
784
785 UV toTITLE_uvchr(UV cp, U8* s, STRLEN* lenp)
786
787 "toUPPER"
788 Converts the specified character to uppercase. If the input is
789 anything but an ASCII lowercase character, that input character
790 itself is returned. Variant "toUPPER_A" is equivalent.
791
792 U8 toUPPER(int ch)
793
794 "toUPPER_utf8"
795 "toUPPER_utf8_safe"
796 Converts the first UTF-8 encoded character in the sequence starting
797 at "p" and extending no further than "e - 1" to its uppercase
798 version, and stores that in UTF-8 in "s", and its length in bytes
799 in "lenp". Note that the buffer pointed to by "s" needs to be at
800 least "UTF8_MAXBYTES_CASE+1" bytes since the uppercase version may
801 be longer than the original character.
802
803 The first code point of the uppercased version is returned (but
804 note, as explained at the top of this section, that there may be
805 more).
806
807 It will not attempt to read beyond "e - 1", provided that the
808 constraint "s < e" is true (this is asserted for in "-DDEBUGGING"
809 builds). If the UTF-8 for the input character is malformed in some
810 way, the program may croak, or the function may return the
811 REPLACEMENT CHARACTER, at the discretion of the implementation, and
812 subject to change in future releases.
813
814 "toUPPER_utf8_safe" is now just a different spelling of plain
815 "toUPPER_utf8"
816
817 UV toUPPER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
818
819 "toUPPER_uvchr"
820 Converts the code point "cp" to its uppercase version, and stores
821 that in UTF-8 in "s", and its length in bytes in "lenp". The code
822 point is interpreted as native if less than 256; otherwise as
823 Unicode. Note that the buffer pointed to by "s" needs to be at
824 least "UTF8_MAXBYTES_CASE+1" bytes since the uppercase version may
825 be longer than the original character.
826
827 The first code point of the uppercased version is returned (but
828 note, as explained at the top of this section, that there may be
829 more.)
830
831 UV toUPPER_uvchr(UV cp, U8* s, STRLEN* lenp)
832
834 This section is about functions (really macros) that classify
835 characters into types, such as punctuation versus alphabetic, etc.
836 Most of these are analogous to regular expression character classes.
837 (See "POSIX Character Classes" in perlrecharclass.) There are several
838 variants for each class. (Not all macros have all variants; each item
839 below lists the ones valid for it.) None are affected by "use bytes",
840 and only the ones with "LC" in the name are affected by the current
841 locale.
842
843 The base function, e.g., "isALPHA()", takes any signed or unsigned
844 value, treating it as a code point, and returns a boolean as to whether
845 or not the character represented by it is (or on non-ASCII platforms,
846 corresponds to) an ASCII character in the named class based on
847 platform, Unicode, and Perl rules. If the input is a number that
848 doesn't fit in an octet, FALSE is returned.
849
850 Variant "isFOO_A" (e.g., "isALPHA_A()") is identical to the base
851 function with no suffix "_A". This variant is used to emphasize by its
852 name that only ASCII-range characters can return TRUE.
853
854 Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivalent) character
855 set onto the platform. That is, the code points that are ASCII are
856 unaffected, since ASCII is a subset of Latin-1. But the non-ASCII code
857 points are treated as if they are Latin-1 characters. For example,
858 "isWORDCHAR_L1()" will return true when called with the code point
859 0xDF, which is a word character in both ASCII and EBCDIC (though it
860 represents different characters in each). If the input is a number
861 that doesn't fit in an octet, FALSE is returned. (Perl's documentation
862 uses a colloquial definition of Latin-1, to include all code points
863 below 256.)
864
865 Variant "isFOO_uvchr" is exactly like the "isFOO_L1" variant, for
866 inputs below 256, but if the code point is larger than 255, Unicode
867 rules are used to determine if it is in the character class. For
868 example, "isWORDCHAR_uvchr(0x100)" returns TRUE, since 0x100 is LATIN
869 CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.
870
871 Variants "isFOO_utf8" and "isFOO_utf8_safe" are like "isFOO_uvchr", but
872 are used for UTF-8 encoded strings. The two forms are different names
873 for the same thing. Each call to one of these classifies the first
874 character of the string starting at "p". The second parameter, "e",
875 points to anywhere in the string beyond the first character, up to one
876 byte past the end of the entire string. Although both variants are
877 identical, the suffix "_safe" in one name emphasizes that it will not
878 attempt to read beyond "e - 1", provided that the constraint "s < e" is
879 true (this is asserted for in "-DDEBUGGING" builds). If the UTF-8 for
880 the input character is malformed in some way, the program may croak, or
881 the function may return FALSE, at the discretion of the implementation,
882 and subject to change in future releases.
883
884 Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but
885 the result is based on the current locale, which is what "LC" in the
886 name stands for. If Perl can determine that the current locale is a
887 UTF-8 locale, it uses the published Unicode rules; otherwise, it uses
888 the C library function that gives the named classification. For
889 example, "isDIGIT_LC()" when not in a UTF-8 locale returns the result
890 of calling "isdigit()". FALSE is always returned if the input won't
891 fit into an octet. On some platforms where the C library function is
892 known to be defective, Perl changes its result to follow the POSIX
893 standard's rules.
894
895 Variant "isFOO_LC_uvchr" acts exactly like "isFOO_LC" for inputs less
896 than 256, but for larger ones it returns the Unicode classification of
897 the code point.
898
899 Variants "isFOO_LC_utf8" and "isFOO_LC_utf8_safe" are like
900 "isFOO_LC_uvchr", but are used for UTF-8 encoded strings. The two
901 forms are different names for the same thing. Each call to one of
902 these classifies the first character of the string starting at "p".
903 The second parameter, "e", points to anywhere in the string beyond the
904 first character, up to one byte past the end of the entire string.
905 Although both variants are identical, the suffix "_safe" in one name
906 emphasizes that it will not attempt to read beyond "e - 1", provided
907 that the constraint "s < e" is true (this is asserted for in
908 "-DDEBUGGING" builds). If the UTF-8 for the input character is
909 malformed in some way, the program may croak, or the function may
910 return FALSE, at the discretion of the implementation, and subject to
911 change in future releases.
912
913 "isALPHA"
914 "isALPHA_A"
915 "isALPHA_L1"
916 "isALPHA_uvchr"
917 "isALPHA_utf8_safe"
918 "isALPHA_utf8"
919 "isALPHA_LC"
920 "isALPHA_LC_uvchr"
921 "isALPHA_LC_utf8_safe"
922 Returns a boolean indicating whether the specified input is one of
923 "[A-Za-z]", analogous to "m/[[:alpha:]]/". See the top of this
924 section for an explanation of the variants.
925
926 bool isALPHA (UV ch)
927 bool isALPHA_A (UV ch)
928 bool isALPHA_L1 (UV ch)
929 bool isALPHA_uvchr (UV ch)
930 bool isALPHA_utf8_safe (U8 * s, U8 * end)
931 bool isALPHA_utf8 (U8 * s, U8 * end)
932 bool isALPHA_LC (UV ch)
933 bool isALPHA_LC_uvchr (UV ch)
934 bool isALPHA_LC_utf8_safe(U8 * s, U8 *end)
935
936 "isALPHANUMERIC"
937 "isALPHANUMERIC_A"
938 "isALPHANUMERIC_L1"
939 "isALPHANUMERIC_uvchr"
940 "isALPHANUMERIC_utf8_safe"
941 "isALPHANUMERIC_utf8"
942 "isALPHANUMERIC_LC"
943 "isALPHANUMERIC_LC_uvchr"
944 "isALPHANUMERIC_LC_utf8_safe"
945 "isALNUMC"
946 "isALNUMC_A"
947 "isALNUMC_L1"
948 "isALNUMC_LC"
949 "isALNUMC_LC_uvchr"
950 Returns a boolean indicating whether the specified character is one
951 of "[A-Za-z0-9]", analogous to "m/[[:alnum:]]/". See the top of
952 this section for an explanation of the variants.
953
954 A (discouraged from use) synonym is "isALNUMC" (where the "C"
955 suffix means this corresponds to the C language alphanumeric
956 definition). Also there are the variants "isALNUMC_A",
957 "isALNUMC_L1" "isALNUMC_LC", and "isALNUMC_LC_uvchr".
958
959 bool isALPHANUMERIC (UV ch)
960 bool isALPHANUMERIC_A (UV ch)
961 bool isALPHANUMERIC_L1 (UV ch)
962 bool isALPHANUMERIC_uvchr (UV ch)
963 bool isALPHANUMERIC_utf8_safe (U8 * s, U8 * end)
964 bool isALPHANUMERIC_utf8 (U8 * s, U8 * end)
965 bool isALPHANUMERIC_LC (UV ch)
966 bool isALPHANUMERIC_LC_uvchr (UV ch)
967 bool isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end)
968 bool isALNUMC (UV ch)
969 bool isALNUMC_A (UV ch)
970 bool isALNUMC_L1 (UV ch)
971 bool isALNUMC_LC (UV ch)
972 bool isALNUMC_LC_uvchr (UV ch)
973
974 "isASCII"
975 "isASCII_A"
976 "isASCII_L1"
977 "isASCII_uvchr"
978 "isASCII_utf8_safe"
979 "isASCII_utf8"
980 "isASCII_LC"
981 "isASCII_LC_uvchr"
982 "isASCII_LC_utf8_safe"
983 Returns a boolean indicating whether the specified character is one
984 of the 128 characters in the ASCII character set, analogous to
985 "m/[[:ascii:]]/". On non-ASCII platforms, it returns TRUE iff this
986 character corresponds to an ASCII character. Variants
987 "isASCII_A()" and "isASCII_L1()" are identical to "isASCII()". See
988 the top of this section for an explanation of the variants. Note,
989 however, that some platforms do not have the C library routine
990 "isascii()". In these cases, the variants whose names contain "LC"
991 are the same as the corresponding ones without.
992
993 Also note, that because all ASCII characters are UTF-8 invariant
994 (meaning they have the exact same representation (always a single
995 byte) whether encoded in UTF-8 or not), "isASCII" will give the
996 correct results when called with any byte in any string encoded or
997 not in UTF-8. And similarly "isASCII_utf8" and "isASCII_utf8_safe"
998 will work properly on any string encoded or not in UTF-8.
999
1000 bool isASCII (UV ch)
1001 bool isASCII_A (UV ch)
1002 bool isASCII_L1 (UV ch)
1003 bool isASCII_uvchr (UV ch)
1004 bool isASCII_utf8_safe (U8 * s, U8 * end)
1005 bool isASCII_utf8 (U8 * s, U8 * end)
1006 bool isASCII_LC (UV ch)
1007 bool isASCII_LC_uvchr (UV ch)
1008 bool isASCII_LC_utf8_safe(U8 * s, U8 *end)
1009
1010 "isBLANK"
1011 "isBLANK_A"
1012 "isBLANK_L1"
1013 "isBLANK_uvchr"
1014 "isBLANK_utf8_safe"
1015 "isBLANK_utf8"
1016 "isBLANK_LC"
1017 "isBLANK_LC_uvchr"
1018 "isBLANK_LC_utf8_safe"
1019 Returns a boolean indicating whether the specified character is a
1020 character considered to be a blank, analogous to "m/[[:blank:]]/".
1021 See the top of this section for an explanation of the variants.
1022 Note, however, that some platforms do not have the C library
1023 routine "isblank()". In these cases, the variants whose names
1024 contain "LC" are the same as the corresponding ones without.
1025
1026 bool isBLANK (UV ch)
1027 bool isBLANK_A (UV ch)
1028 bool isBLANK_L1 (UV ch)
1029 bool isBLANK_uvchr (UV ch)
1030 bool isBLANK_utf8_safe (U8 * s, U8 * end)
1031 bool isBLANK_utf8 (U8 * s, U8 * end)
1032 bool isBLANK_LC (UV ch)
1033 bool isBLANK_LC_uvchr (UV ch)
1034 bool isBLANK_LC_utf8_safe(U8 * s, U8 *end)
1035
1036 "isCNTRL"
1037 "isCNTRL_A"
1038 "isCNTRL_L1"
1039 "isCNTRL_uvchr"
1040 "isCNTRL_utf8_safe"
1041 "isCNTRL_utf8"
1042 "isCNTRL_LC"
1043 "isCNTRL_LC_uvchr"
1044 "isCNTRL_LC_utf8_safe"
1045 Returns a boolean indicating whether the specified character is a
1046 control character, analogous to "m/[[:cntrl:]]/". See the top of
1047 this section for an explanation of the variants. On EBCDIC
1048 platforms, you almost always want to use the "isCNTRL_L1" variant.
1049
1050 bool isCNTRL (UV ch)
1051 bool isCNTRL_A (UV ch)
1052 bool isCNTRL_L1 (UV ch)
1053 bool isCNTRL_uvchr (UV ch)
1054 bool isCNTRL_utf8_safe (U8 * s, U8 * end)
1055 bool isCNTRL_utf8 (U8 * s, U8 * end)
1056 bool isCNTRL_LC (UV ch)
1057 bool isCNTRL_LC_uvchr (UV ch)
1058 bool isCNTRL_LC_utf8_safe(U8 * s, U8 *end)
1059
1060 "isDIGIT"
1061 "isDIGIT_A"
1062 "isDIGIT_L1"
1063 "isDIGIT_uvchr"
1064 "isDIGIT_utf8_safe"
1065 "isDIGIT_utf8"
1066 "isDIGIT_LC"
1067 "isDIGIT_LC_uvchr"
1068 "isDIGIT_LC_utf8_safe"
1069 Returns a boolean indicating whether the specified character is a
1070 digit, analogous to "m/[[:digit:]]/". Variants "isDIGIT_A" and
1071 "isDIGIT_L1" are identical to "isDIGIT". See the top of this
1072 section for an explanation of the variants.
1073
1074 bool isDIGIT (UV ch)
1075 bool isDIGIT_A (UV ch)
1076 bool isDIGIT_L1 (UV ch)
1077 bool isDIGIT_uvchr (UV ch)
1078 bool isDIGIT_utf8_safe (U8 * s, U8 * end)
1079 bool isDIGIT_utf8 (U8 * s, U8 * end)
1080 bool isDIGIT_LC (UV ch)
1081 bool isDIGIT_LC_uvchr (UV ch)
1082 bool isDIGIT_LC_utf8_safe(U8 * s, U8 *end)
1083
1084 "isGRAPH"
1085 "isGRAPH_A"
1086 "isGRAPH_L1"
1087 "isGRAPH_uvchr"
1088 "isGRAPH_utf8_safe"
1089 "isGRAPH_utf8"
1090 "isGRAPH_LC"
1091 "isGRAPH_LC_uvchr"
1092 "isGRAPH_LC_utf8_safe"
1093 Returns a boolean indicating whether the specified character is a
1094 graphic character, analogous to "m/[[:graph:]]/". See the top of
1095 this section for an explanation of the variants.
1096
1097 bool isGRAPH (UV ch)
1098 bool isGRAPH_A (UV ch)
1099 bool isGRAPH_L1 (UV ch)
1100 bool isGRAPH_uvchr (UV ch)
1101 bool isGRAPH_utf8_safe (U8 * s, U8 * end)
1102 bool isGRAPH_utf8 (U8 * s, U8 * end)
1103 bool isGRAPH_LC (UV ch)
1104 bool isGRAPH_LC_uvchr (UV ch)
1105 bool isGRAPH_LC_utf8_safe(U8 * s, U8 *end)
1106
1107 "isIDCONT"
1108 "isIDCONT_A"
1109 "isIDCONT_L1"
1110 "isIDCONT_uvchr"
1111 "isIDCONT_utf8_safe"
1112 "isIDCONT_utf8"
1113 "isIDCONT_LC"
1114 "isIDCONT_LC_uvchr"
1115 "isIDCONT_LC_utf8_safe"
1116 Returns a boolean indicating whether the specified character can be
1117 the second or succeeding character of an identifier. This is very
1118 close to, but not quite the same as the official Unicode property
1119 "XID_Continue". The difference is that this returns true only if
1120 the input character also matches "isWORDCHAR". See the top of this
1121 section for an explanation of the variants.
1122
1123 bool isIDCONT (UV ch)
1124 bool isIDCONT_A (UV ch)
1125 bool isIDCONT_L1 (UV ch)
1126 bool isIDCONT_uvchr (UV ch)
1127 bool isIDCONT_utf8_safe (U8 * s, U8 * end)
1128 bool isIDCONT_utf8 (U8 * s, U8 * end)
1129 bool isIDCONT_LC (UV ch)
1130 bool isIDCONT_LC_uvchr (UV ch)
1131 bool isIDCONT_LC_utf8_safe(U8 * s, U8 *end)
1132
1133 "isIDFIRST"
1134 "isIDFIRST_A"
1135 "isIDFIRST_L1"
1136 "isIDFIRST_uvchr"
1137 "isIDFIRST_utf8_safe"
1138 "isIDFIRST_utf8"
1139 "isIDFIRST_LC"
1140 "isIDFIRST_LC_uvchr"
1141 "isIDFIRST_LC_utf8_safe"
1142 Returns a boolean indicating whether the specified character can be
1143 the first character of an identifier. This is very close to, but
1144 not quite the same as the official Unicode property "XID_Start".
1145 The difference is that this returns true only if the input
1146 character also matches "isWORDCHAR". See the top of this section
1147 for an explanation of the variants.
1148
1149 bool isIDFIRST (UV ch)
1150 bool isIDFIRST_A (UV ch)
1151 bool isIDFIRST_L1 (UV ch)
1152 bool isIDFIRST_uvchr (UV ch)
1153 bool isIDFIRST_utf8_safe (U8 * s, U8 * end)
1154 bool isIDFIRST_utf8 (U8 * s, U8 * end)
1155 bool isIDFIRST_LC (UV ch)
1156 bool isIDFIRST_LC_uvchr (UV ch)
1157 bool isIDFIRST_LC_utf8_safe(U8 * s, U8 *end)
1158
1159 "isLOWER"
1160 "isLOWER_A"
1161 "isLOWER_L1"
1162 "isLOWER_uvchr"
1163 "isLOWER_utf8_safe"
1164 "isLOWER_utf8"
1165 "isLOWER_LC"
1166 "isLOWER_LC_uvchr"
1167 "isLOWER_LC_utf8_safe"
1168 Returns a boolean indicating whether the specified character is a
1169 lowercase character, analogous to "m/[[:lower:]]/". See the top of
1170 this section for an explanation of the variants
1171
1172 bool isLOWER (UV ch)
1173 bool isLOWER_A (UV ch)
1174 bool isLOWER_L1 (UV ch)
1175 bool isLOWER_uvchr (UV ch)
1176 bool isLOWER_utf8_safe (U8 * s, U8 * end)
1177 bool isLOWER_utf8 (U8 * s, U8 * end)
1178 bool isLOWER_LC (UV ch)
1179 bool isLOWER_LC_uvchr (UV ch)
1180 bool isLOWER_LC_utf8_safe(U8 * s, U8 *end)
1181
1182 "isOCTAL"
1183 "isOCTAL_A"
1184 "isOCTAL_L1"
1185 Returns a boolean indicating whether the specified character is an
1186 octal digit, [0-7]. The only two variants are "isOCTAL_A" and
1187 "isOCTAL_L1"; each is identical to "isOCTAL".
1188
1189 bool isOCTAL(UV ch)
1190
1191 "isPRINT"
1192 "isPRINT_A"
1193 "isPRINT_L1"
1194 "isPRINT_uvchr"
1195 "isPRINT_utf8_safe"
1196 "isPRINT_utf8"
1197 "isPRINT_LC"
1198 "isPRINT_LC_uvchr"
1199 "isPRINT_LC_utf8_safe"
1200 Returns a boolean indicating whether the specified character is a
1201 printable character, analogous to "m/[[:print:]]/". See the top of
1202 this section for an explanation of the variants.
1203
1204 bool isPRINT (UV ch)
1205 bool isPRINT_A (UV ch)
1206 bool isPRINT_L1 (UV ch)
1207 bool isPRINT_uvchr (UV ch)
1208 bool isPRINT_utf8_safe (U8 * s, U8 * end)
1209 bool isPRINT_utf8 (U8 * s, U8 * end)
1210 bool isPRINT_LC (UV ch)
1211 bool isPRINT_LC_uvchr (UV ch)
1212 bool isPRINT_LC_utf8_safe(U8 * s, U8 *end)
1213
1214 "isPSXSPC"
1215 "isPSXSPC_A"
1216 "isPSXSPC_L1"
1217 "isPSXSPC_uvchr"
1218 "isPSXSPC_utf8_safe"
1219 "isPSXSPC_utf8"
1220 "isPSXSPC_LC"
1221 "isPSXSPC_LC_uvchr"
1222 "isPSXSPC_LC_utf8_safe"
1223 (short for Posix Space) Starting in 5.18, this is identical in all
1224 its forms to the corresponding "isSPACE()" macros. The locale
1225 forms of this macro are identical to their corresponding
1226 "isSPACE()" forms in all Perl releases. In releases prior to 5.18,
1227 the non-locale forms differ from their "isSPACE()" forms only in
1228 that the "isSPACE()" forms don't match a Vertical Tab, and the
1229 "isPSXSPC()" forms do. Otherwise they are identical. Thus this
1230 macro is analogous to what "m/[[:space:]]/" matches in a regular
1231 expression. See the top of this section for an explanation of the
1232 variants.
1233
1234 bool isPSXSPC (UV ch)
1235 bool isPSXSPC_A (UV ch)
1236 bool isPSXSPC_L1 (UV ch)
1237 bool isPSXSPC_uvchr (UV ch)
1238 bool isPSXSPC_utf8_safe (U8 * s, U8 * end)
1239 bool isPSXSPC_utf8 (U8 * s, U8 * end)
1240 bool isPSXSPC_LC (UV ch)
1241 bool isPSXSPC_LC_uvchr (UV ch)
1242 bool isPSXSPC_LC_utf8_safe(U8 * s, U8 *end)
1243
1244 "isPUNCT"
1245 "isPUNCT_A"
1246 "isPUNCT_L1"
1247 "isPUNCT_uvchr"
1248 "isPUNCT_utf8_safe"
1249 "isPUNCT_utf8"
1250 "isPUNCT_LC"
1251 "isPUNCT_LC_uvchr"
1252 "isPUNCT_LC_utf8_safe"
1253 Returns a boolean indicating whether the specified character is a
1254 punctuation character, analogous to "m/[[:punct:]]/". Note that
1255 the definition of what is punctuation isn't as straightforward as
1256 one might desire. See "POSIX Character Classes" in perlrecharclass
1257 for details. See the top of this section for an explanation of the
1258 variants.
1259
1260 bool isPUNCT (UV ch)
1261 bool isPUNCT_A (UV ch)
1262 bool isPUNCT_L1 (UV ch)
1263 bool isPUNCT_uvchr (UV ch)
1264 bool isPUNCT_utf8_safe (U8 * s, U8 * end)
1265 bool isPUNCT_utf8 (U8 * s, U8 * end)
1266 bool isPUNCT_LC (UV ch)
1267 bool isPUNCT_LC_uvchr (UV ch)
1268 bool isPUNCT_LC_utf8_safe(U8 * s, U8 *end)
1269
1270 "isSPACE"
1271 "isSPACE_A"
1272 "isSPACE_L1"
1273 "isSPACE_uvchr"
1274 "isSPACE_utf8_safe"
1275 "isSPACE_utf8"
1276 "isSPACE_LC"
1277 "isSPACE_LC_uvchr"
1278 "isSPACE_LC_utf8_safe"
1279 Returns a boolean indicating whether the specified character is a
1280 whitespace character. This is analogous to what "m/\s/" matches in
1281 a regular expression. Starting in Perl 5.18 this also matches what
1282 "m/[[:space:]]/" does. Prior to 5.18, only the locale forms of
1283 this macro (the ones with "LC" in their names) matched precisely
1284 what "m/[[:space:]]/" does. In those releases, the only
1285 difference, in the non-locale variants, was that "isSPACE()" did
1286 not match a vertical tab. (See "isPSXSPC" for a macro that matches
1287 a vertical tab in all releases.) See the top of this section for
1288 an explanation of the variants.
1289
1290 bool isSPACE (UV ch)
1291 bool isSPACE_A (UV ch)
1292 bool isSPACE_L1 (UV ch)
1293 bool isSPACE_uvchr (UV ch)
1294 bool isSPACE_utf8_safe (U8 * s, U8 * end)
1295 bool isSPACE_utf8 (U8 * s, U8 * end)
1296 bool isSPACE_LC (UV ch)
1297 bool isSPACE_LC_uvchr (UV ch)
1298 bool isSPACE_LC_utf8_safe(U8 * s, U8 *end)
1299
1300 "isUPPER"
1301 "isUPPER_A"
1302 "isUPPER_L1"
1303 "isUPPER_uvchr"
1304 "isUPPER_utf8_safe"
1305 "isUPPER_utf8"
1306 "isUPPER_LC"
1307 "isUPPER_LC_uvchr"
1308 "isUPPER_LC_utf8_safe"
1309 Returns a boolean indicating whether the specified character is an
1310 uppercase character, analogous to "m/[[:upper:]]/". See the top of
1311 this section for an explanation of the variants.
1312
1313 bool isUPPER (UV ch)
1314 bool isUPPER_A (UV ch)
1315 bool isUPPER_L1 (UV ch)
1316 bool isUPPER_uvchr (UV ch)
1317 bool isUPPER_utf8_safe (U8 * s, U8 * end)
1318 bool isUPPER_utf8 (U8 * s, U8 * end)
1319 bool isUPPER_LC (UV ch)
1320 bool isUPPER_LC_uvchr (UV ch)
1321 bool isUPPER_LC_utf8_safe(U8 * s, U8 *end)
1322
1323 "isWORDCHAR"
1324 "isWORDCHAR_A"
1325 "isWORDCHAR_L1"
1326 "isWORDCHAR_uvchr"
1327 "isWORDCHAR_utf8_safe"
1328 "isWORDCHAR_utf8"
1329 "isWORDCHAR_LC"
1330 "isWORDCHAR_LC_uvchr"
1331 "isWORDCHAR_LC_utf8_safe"
1332 "isALNUM"
1333 "isALNUM_A"
1334 "isALNUM_LC"
1335 "isALNUM_LC_uvchr"
1336 Returns a boolean indicating whether the specified character is a
1337 character that is a word character, analogous to what "m/\w/" and
1338 "m/[[:word:]]/" match in a regular expression. A word character is
1339 an alphabetic character, a decimal digit, a connecting punctuation
1340 character (such as an underscore), or a "mark" character that
1341 attaches to one of those (like some sort of accent). "isALNUM()"
1342 is a synonym provided for backward compatibility, even though a
1343 word character includes more than the standard C language meaning
1344 of alphanumeric. See the top of this section for an explanation of
1345 the variants. "isWORDCHAR_A", "isWORDCHAR_L1", "isWORDCHAR_uvchr",
1346 "isWORDCHAR_LC", "isWORDCHAR_LC_uvchr", "isWORDCHAR_LC_utf8", and
1347 "isWORDCHAR_LC_utf8_safe" are also as described there, but
1348 additionally include the platform's native underscore.
1349
1350 bool isWORDCHAR (UV ch)
1351 bool isWORDCHAR_A (UV ch)
1352 bool isWORDCHAR_L1 (UV ch)
1353 bool isWORDCHAR_uvchr (UV ch)
1354 bool isWORDCHAR_utf8_safe (U8 * s, U8 * end)
1355 bool isWORDCHAR_utf8 (U8 * s, U8 * end)
1356 bool isWORDCHAR_LC (UV ch)
1357 bool isWORDCHAR_LC_uvchr (UV ch)
1358 bool isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end)
1359 bool isALNUM (UV ch)
1360 bool isALNUM_A (UV ch)
1361 bool isALNUM_LC (UV ch)
1362 bool isALNUM_LC_uvchr (UV ch)
1363
1364 "isXDIGIT"
1365 "isXDIGIT_A"
1366 "isXDIGIT_L1"
1367 "isXDIGIT_uvchr"
1368 "isXDIGIT_utf8_safe"
1369 "isXDIGIT_utf8"
1370 "isXDIGIT_LC"
1371 "isXDIGIT_LC_uvchr"
1372 "isXDIGIT_LC_utf8_safe"
1373 Returns a boolean indicating whether the specified character is a
1374 hexadecimal digit. In the ASCII range these are "[0-9A-Fa-f]".
1375 Variants "isXDIGIT_A()" and "isXDIGIT_L1()" are identical to
1376 "isXDIGIT()". See the top of this section for an explanation of
1377 the variants.
1378
1379 bool isXDIGIT (UV ch)
1380 bool isXDIGIT_A (UV ch)
1381 bool isXDIGIT_L1 (UV ch)
1382 bool isXDIGIT_uvchr (UV ch)
1383 bool isXDIGIT_utf8_safe (U8 * s, U8 * end)
1384 bool isXDIGIT_utf8 (U8 * s, U8 * end)
1385 bool isXDIGIT_LC (UV ch)
1386 bool isXDIGIT_LC_uvchr (UV ch)
1387 bool isXDIGIT_LC_utf8_safe(U8 * s, U8 *end)
1388
1390 "CPPLAST"
1391 This symbol is intended to be used along with "CPPRUN" in the same
1392 manner symbol "CPPMINUS" is used with "CPPSTDIN". It contains
1393 either "-" or "".
1394
1395 "CPPMINUS"
1396 This symbol contains the second part of the string which will
1397 invoke the C preprocessor on the standard input and produce to
1398 standard output. This symbol will have the value "-" if "CPPSTDIN"
1399 needs a minus to specify standard input, otherwise the value is "".
1400
1401 "CPPRUN"
1402 This symbol contains the string which will invoke a C preprocessor
1403 on the standard input and produce to standard output. It needs to
1404 end with "CPPLAST", after all other preprocessor flags have been
1405 specified. The main difference with "CPPSTDIN" is that this
1406 program will never be a pointer to a shell wrapper, i.e. it will be
1407 empty if no preprocessor is available directly to the user. Note
1408 that it may well be different from the preprocessor used to compile
1409 the C program.
1410
1411 "CPPSTDIN"
1412 This symbol contains the first part of the string which will invoke
1413 the C preprocessor on the standard input and produce to standard
1414 output. Typical value of "cc -E" or "/lib/cpp", but it can also
1415 call a wrapper. See "CPPRUN".
1416
1417 "HASATTRIBUTE_ALWAYS_INLINE"
1418 Can we handle "GCC" attribute for functions that should always be
1419 inlined.
1420
1421 "HASATTRIBUTE_DEPRECATED"
1422 Can we handle "GCC" attribute for marking deprecated "APIs"
1423
1424 "HASATTRIBUTE_FORMAT"
1425 Can we handle "GCC" attribute for checking printf-style formats
1426
1427 "HASATTRIBUTE_NONNULL"
1428 Can we handle "GCC" attribute for nonnull function parms.
1429
1430 "HASATTRIBUTE_NORETURN"
1431 Can we handle "GCC" attribute for functions that do not return
1432
1433 "HASATTRIBUTE_PURE"
1434 Can we handle "GCC" attribute for pure functions
1435
1436 "HASATTRIBUTE_UNUSED"
1437 Can we handle "GCC" attribute for unused variables and arguments
1438
1439 "HASATTRIBUTE_WARN_UNUSED_RESULT"
1440 Can we handle "GCC" attribute for warning on unused results
1441
1442 "HAS_BUILTIN_ADD_OVERFLOW"
1443 This symbol, if defined, indicates that the compiler supports
1444 "__builtin_add_overflow" for adding integers with overflow checks.
1445
1446 "HAS_BUILTIN_CHOOSE_EXPR"
1447 Can we handle "GCC" builtin for compile-time ternary-like
1448 expressions
1449
1450 "HAS_BUILTIN_EXPECT"
1451 Can we handle "GCC" builtin for telling that certain values are
1452 more likely
1453
1454 "HAS_BUILTIN_MUL_OVERFLOW"
1455 This symbol, if defined, indicates that the compiler supports
1456 "__builtin_mul_overflow" for multiplying integers with overflow
1457 checks.
1458
1459 "HAS_BUILTIN_SUB_OVERFLOW"
1460 This symbol, if defined, indicates that the compiler supports
1461 "__builtin_sub_overflow" for subtracting integers with overflow
1462 checks.
1463
1464 "HAS_C99_VARIADIC_MACROS"
1465 If defined, the compiler supports C99 variadic macros.
1466
1467 "HAS_STATIC_INLINE"
1468 This symbol, if defined, indicates that the C compiler supports
1469 C99-style static inline. That is, the function can't be called
1470 from another translation unit.
1471
1472 "MEM_ALIGNBYTES"
1473 This symbol contains the number of bytes required to align a
1474 double, or a long double when applicable. Usual values are 2, 4 and
1475 8. The default is eight, for safety. For cross-compiling or
1476 multiarch support, Configure will set a minimum of 8.
1477
1478 "PERL_STATIC_INLINE"
1479 This symbol gives the best-guess incantation to use for static
1480 inline functions. If "HAS_STATIC_INLINE" is defined, this will
1481 give C99-style inline. If "HAS_STATIC_INLINE" is not defined, this
1482 will give a plain 'static'. It will always be defined to something
1483 that gives static linkage. Possibilities include
1484
1485 static inline (c99)
1486 static __inline__ (gcc -ansi)
1487 static __inline (MSVC)
1488 static _inline (older MSVC)
1489 static (c89 compilers)
1490
1491 "U32_ALIGNMENT_REQUIRED"
1492 This symbol, if defined, indicates that you must access character
1493 data through U32-aligned pointers.
1494
1496 "ASSUME"
1497 "ASSUME" is like "assert()", but it has a benefit in a release
1498 build. It is a hint to a compiler about a statement of fact in a
1499 function call free expression, which allows the compiler to
1500 generate better machine code. In a debug build, ASSUME(x) is a
1501 synonym for assert(x). ASSUME(0) means the control path is
1502 unreachable. In a for loop, "ASSUME" can be used to hint that a
1503 loop will run at least X times. "ASSUME" is based off MSVC's
1504 "__assume" intrinsic function, see its documents for more details.
1505
1506 ASSUME(bool expr)
1507
1508 "dNOOP"
1509 Declare nothing; typically used as a placeholder to replace
1510 something that used to declare something. Works on compilers that
1511 require declarations before any code.
1512
1513 dNOOP;
1514
1515 "END_EXTERN_C"
1516 When not compiling using C++, expands to nothing. Otherwise ends a
1517 section of code already begun by a "START_EXTERN_C".
1518
1519 END_EXTERN_C
1520
1521 "EXTERN_C"
1522 When not compiling using C++, expands to nothing. Otherwise is
1523 used in a declaration of a function to indicate the function should
1524 have external C linkage. This is required for things to work for
1525 just about all functions with external linkage compiled into perl.
1526 Often, you can use "START_EXTERN_C" ... "END_EXTERN_C" blocks
1527 surrounding all your code that you need to have this linkage.
1528
1529 Example usage:
1530
1531 EXTERN_C int flock(int fd, int op);
1532
1533 "LIKELY"
1534 Returns the input unchanged, but at the same time it gives a branch
1535 prediction hint to the compiler that this condition is likely to be
1536 true.
1537
1538 LIKELY(bool expr)
1539
1540 "NOOP"
1541 Do nothing; typically used as a placeholder to replace something
1542 that used to do something.
1543
1544 NOOP;
1545
1546 "PERL_UNUSED_ARG"
1547 This is used to suppress compiler warnings that a parameter to a
1548 function is not used. This situation can arise, for example, when
1549 a parameter is needed under some configuration conditions, but not
1550 others, so that C preprocessor conditional compilation causes it be
1551 used just some times.
1552
1553 PERL_UNUSED_ARG(void x);
1554
1555 "PERL_UNUSED_CONTEXT"
1556 This is used to suppress compiler warnings that the thread context
1557 parameter to a function is not used. This situation can arise, for
1558 example, when a C preprocessor conditional compilation causes it be
1559 used just some times.
1560
1561 PERL_UNUSED_CONTEXT;
1562
1563 "PERL_UNUSED_DECL"
1564 Tells the compiler that the parameter in the function prototype
1565 just before it is not necessarily expected to be used in the
1566 function. Not that many compilers understand this, so this should
1567 only be used in cases where "PERL_UNUSED_ARG" can't conveniently be
1568 used.
1569
1570 Example usage:
1571
1572 Signal_t
1573 Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
1574 void *uap PERL_UNUSED_DECL, bool safe)
1575
1576 "PERL_UNUSED_RESULT"
1577 This macro indicates to discard the return value of the function
1578 call inside it, e.g.,
1579
1580 PERL_UNUSED_RESULT(foo(a, b))
1581
1582 The main reason for this is that the combination of "gcc
1583 -Wunused-result" (part of "-Wall") and the
1584 "__attribute__((warn_unused_result))" cannot be silenced with
1585 casting to "void". This causes trouble when the system header
1586 files use the attribute.
1587
1588 Use "PERL_UNUSED_RESULT" sparingly, though, since usually the
1589 warning is there for a good reason: you might lose success/failure
1590 information, or leak resources, or changes in resources.
1591
1592 But sometimes you just want to ignore the return value, e.g., on
1593 codepaths soon ending up in abort, or in "best effort" attempts, or
1594 in situations where there is no good way to handle failures.
1595
1596 Sometimes "PERL_UNUSED_RESULT" might not be the most natural way:
1597 another possibility is that you can capture the return value and
1598 use "PERL_UNUSED_VAR" on that.
1599
1600 PERL_UNUSED_RESULT(void x)
1601
1602 "PERL_UNUSED_VAR"
1603 This is used to suppress compiler warnings that the variable x is
1604 not used. This situation can arise, for example, when a C
1605 preprocessor conditional compilation causes it be used just some
1606 times.
1607
1608 PERL_UNUSED_VAR(void x);
1609
1610 "PERL_USE_GCC_BRACE_GROUPS"
1611 This C pre-processor value, if defined, indicates that it is
1612 permissible to use the GCC brace groups extension. This extension,
1613 of the form
1614
1615 ({ statement ... })
1616
1617 turns the block consisting of statements ... into an expression
1618 with a value, unlike plain C language blocks. This can present
1619 optimization possibilities, BUT you generally need to specify an
1620 alternative in case this ability doesn't exist or has otherwise
1621 been forbidden.
1622
1623 Example usage:
1624
1625 #ifdef PERL_USE_GCC_BRACE_GROUPS
1626 ...
1627 #else
1628 ...
1629 #endif
1630
1631 "START_EXTERN_C"
1632 When not compiling using C++, expands to nothing. Otherwise begins
1633 a section of code in which every function will effectively have
1634 "EXTERN_C" applied to it, that is to have external C linkage. The
1635 section is ended by a "END_EXTERN_C".
1636
1637 START_EXTERN_C
1638
1639 "STATIC"
1640 Described in perlguts.
1641
1642 "STMT_START"
1643 "STMT_END"
1644 This allows a series of statements in a macro to be used as a
1645 single statement, as in
1646
1647 if (x) STMT_START { ... } STMT_END else ...
1648
1649 Note that you can't return a value out of them, which limits their
1650 utility. But see "PERL_USE_GCC_BRACE_GROUPS".
1651
1652 "UNLIKELY"
1653 Returns the input unchanged, but at the same time it gives a branch
1654 prediction hint to the compiler that this condition is likely to be
1655 false.
1656
1657 UNLIKELY(bool expr)
1658
1659 "__ASSERT_"
1660 This is a helper macro to avoid preprocessor issues, replaced by
1661 nothing unless under DEBUGGING, where it expands to an assert of
1662 its argument, followed by a comma (hence the comma operator). If
1663 we just used a straight assert(), we would get a comma with nothing
1664 before it when not DEBUGGING.
1665
1666 __ASSERT_(bool expr)
1667
1669 "BhkDISABLE"
1670 NOTE: "BhkDISABLE" is experimental and may change or be removed
1671 without notice.
1672
1673 Temporarily disable an entry in this BHK structure, by clearing the
1674 appropriate flag. "which" is a preprocessor token indicating which
1675 entry to disable.
1676
1677 void BhkDISABLE(BHK *hk, which)
1678
1679 "BhkENABLE"
1680 NOTE: "BhkENABLE" is experimental and may change or be removed
1681 without notice.
1682
1683 Re-enable an entry in this BHK structure, by setting the
1684 appropriate flag. "which" is a preprocessor token indicating which
1685 entry to enable. This will assert (under -DDEBUGGING) if the entry
1686 doesn't contain a valid pointer.
1687
1688 void BhkENABLE(BHK *hk, which)
1689
1690 "BhkENTRY_set"
1691 NOTE: "BhkENTRY_set" is experimental and may change or be removed
1692 without notice.
1693
1694 Set an entry in the BHK structure, and set the flags to indicate it
1695 is valid. "which" is a preprocessing token indicating which entry
1696 to set. The type of "ptr" depends on the entry.
1697
1698 void BhkENTRY_set(BHK *hk, which, void *ptr)
1699
1700 "blockhook_register"
1701 NOTE: "blockhook_register" is experimental and may change or be
1702 removed without notice.
1703
1704 Register a set of hooks to be called when the Perl lexical scope
1705 changes at compile time. See "Compile-time scope hooks" in
1706 perlguts.
1707
1708 NOTE: "blockhook_register" must be explicitly called as
1709 "Perl_blockhook_register" with an "aTHX_" parameter.
1710
1711 void Perl_blockhook_register(pTHX_ BHK *hk)
1712
1714 "aTHX"
1715 Described in perlguts.
1716
1717 "aTHX_"
1718 Described in perlguts.
1719
1720 "CPERLscope"
1721 "DEPRECATED!" It is planned to remove "CPERLscope" from a future
1722 release of Perl. Do not use it for new code; remove it from
1723 existing code.
1724
1725 Now a no-op.
1726
1727 void CPERLscope(void x)
1728
1729 "dTHR"
1730 Described in perlguts.
1731
1732 "dTHX"
1733 Described in perlguts.
1734
1735 "dTHXa"
1736 On threaded perls, set "pTHX" to "a"; on unthreaded perls, do
1737 nothing
1738
1739 "dTHXoa"
1740 Now a synonym for "dTHXa".
1741
1742 "dVAR"
1743 This is now a synonym for dNOOP: declare nothing
1744
1745 "GETENV_PRESERVES_OTHER_THREAD"
1746 This symbol, if defined, indicates that the getenv system call
1747 doesn't zap the static buffer of "getenv()" in a different thread.
1748 The typical "getenv()" implementation will return a pointer to the
1749 proper position in **environ. But some may instead copy them to a
1750 static buffer in "getenv()". If there is a per-thread instance of
1751 that buffer, or the return points to **environ, then a
1752 many-reader/1-writer mutex will work; otherwise an exclusive
1753 locking mutex is required to prevent races.
1754
1755 "HAS_PTHREAD_ATFORK"
1756 This symbol, if defined, indicates that the "pthread_atfork"
1757 routine is available to setup fork handlers.
1758
1759 "HAS_PTHREAD_ATTR_SETSCOPE"
1760 This symbol, if defined, indicates that the "pthread_attr_setscope"
1761 system call is available to set the contention scope attribute of a
1762 thread attribute object.
1763
1764 "HAS_PTHREAD_YIELD"
1765 This symbol, if defined, indicates that the "pthread_yield" routine
1766 is available to yield the execution of the current thread.
1767 "sched_yield" is preferable to "pthread_yield".
1768
1769 "HAS_SCHED_YIELD"
1770 This symbol, if defined, indicates that the "sched_yield" routine
1771 is available to yield the execution of the current thread.
1772 "sched_yield" is preferable to "pthread_yield".
1773
1774 "I_MACH_CTHREADS"
1775 This symbol, if defined, indicates to the C program that it should
1776 include mach/cthreads.h.
1777
1778 #ifdef I_MACH_CTHREADS
1779 #include <mach_cthreads.h>
1780 #endif
1781
1782 "I_PTHREAD"
1783 This symbol, if defined, indicates to the C program that it should
1784 include pthread.h.
1785
1786 #ifdef I_PTHREAD
1787 #include <pthread.h>
1788 #endif
1789
1790 "MULTIPLICITY"
1791 This symbol, if defined, indicates that Perl should be built to use
1792 multiplicity.
1793
1794 "OLD_PTHREADS_API"
1795 This symbol, if defined, indicates that Perl should be built to use
1796 the old draft "POSIX" threads "API".
1797
1798 "OLD_PTHREAD_CREATE_JOINABLE"
1799 This symbol, if defined, indicates how to create pthread in
1800 joinable (aka undetached) state. "NOTE": not defined if pthread.h
1801 already has defined "PTHREAD_CREATE_JOINABLE" (the new version of
1802 the constant). If defined, known values are
1803 "PTHREAD_CREATE_UNDETACHED" and "__UNDETACHED".
1804
1805 "pTHX"
1806 Described in perlguts.
1807
1808 "pTHX_"
1809 Described in perlguts.
1810
1811 "SCHED_YIELD"
1812 This symbol defines the way to yield the execution of the current
1813 thread. Known ways are "sched_yield", "pthread_yield", and
1814 "pthread_yield" with "NULL".
1815
1816 "SVf"
1817 Described in perlguts.
1818
1819 "SVfARG"
1820 Described in perlguts.
1821
1822 SVfARG(SV *sv)
1823
1825 "cop_fetch_label"
1826 NOTE: "cop_fetch_label" is experimental and may change or be
1827 removed without notice.
1828
1829 Returns the label attached to a cop, and stores its length in bytes
1830 into *len. Upon return, *flags will be set to either "SVf_UTF8" or
1831 0.
1832
1833 Alternatively, use the macro "CopLABEL_len_flags"; or if you don't
1834 need to know if the label is UTF-8 or not, the macro
1835 "CopLABEL_len"; or if you additionally dont need to know the
1836 length, "CopLABEL".
1837
1838 const char * cop_fetch_label(COP *const cop, STRLEN *len,
1839 U32 *flags)
1840
1841 "CopFILE"
1842 Returns the name of the file associated with the "COP" "c"
1843
1844 const char * CopFILE(const COP * c)
1845
1846 "CopFILEAV"
1847 Returns the AV associated with the "COP" "c"
1848
1849 AV * CopFILEAV(const COP * c)
1850
1851 "CopFILEGV"
1852 Returns the GV associated with the "COP" "c"
1853
1854 GV * CopFILEGV(const COP * c)
1855
1856 "CopFILEGV_set"
1857 Available only on unthreaded perls. Makes "pv" the name of the
1858 file associated with the "COP" "c"
1859
1860 void CopFILEGV_set(COP * c, GV * gv)
1861
1862 "CopFILE_set"
1863 Makes "pv" the name of the file associated with the "COP" "c"
1864
1865 void CopFILE_set(COP * c, const char * pv)
1866
1867 "CopFILESV"
1868 Returns the SV associated with the "COP" "c"
1869
1870 SV * CopFILESV(const COP * c)
1871
1872 "cophh_2hv"
1873 NOTE: "cophh_2hv" is experimental and may change or be removed
1874 without notice.
1875
1876 Generates and returns a standard Perl hash representing the full
1877 set of key/value pairs in the cop hints hash "cophh". "flags" is
1878 currently unused and must be zero.
1879
1880 HV * cophh_2hv(const COPHH *cophh, U32 flags)
1881
1882 "cophh_copy"
1883 NOTE: "cophh_copy" is experimental and may change or be removed
1884 without notice.
1885
1886 Make and return a complete copy of the cop hints hash "cophh".
1887
1888 COPHH * cophh_copy(COPHH *cophh)
1889
1890 "cophh_delete_pv"
1891 NOTE: "cophh_delete_pv" is experimental and may change or be
1892 removed without notice.
1893
1894 Like "cophh_delete_pvn", but takes a nul-terminated string instead
1895 of a string/length pair.
1896
1897 COPHH * cophh_delete_pv(COPHH *cophh, char *key, U32 hash,
1898 U32 flags)
1899
1900 "cophh_delete_pvn"
1901 NOTE: "cophh_delete_pvn" is experimental and may change or be
1902 removed without notice.
1903
1904 Delete a key and its associated value from the cop hints hash
1905 "cophh", and returns the modified hash. The returned hash pointer
1906 is in general not the same as the hash pointer that was passed in.
1907 The input hash is consumed by the function, and the pointer to it
1908 must not be subsequently used. Use "cophh_copy" if you need both
1909 hashes.
1910
1911 The key is specified by "keypv" and "keylen". If "flags" has the
1912 "COPHH_KEY_UTF8" bit set, the key octets are interpreted as UTF-8,
1913 otherwise they are interpreted as Latin-1. "hash" is a precomputed
1914 hash of the key string, or zero if it has not been precomputed.
1915
1916 COPHH * cophh_delete_pvn(COPHH *cophh, const char *keypv,
1917 STRLEN keylen, U32 hash, U32 flags)
1918
1919 "cophh_delete_pvs"
1920 NOTE: "cophh_delete_pvs" is experimental and may change or be
1921 removed without notice.
1922
1923 Like "cophh_delete_pvn", but takes a literal string instead of a
1924 string/length pair, and no precomputed hash.
1925
1926 COPHH * cophh_delete_pvs(COPHH *cophh, "key", U32 flags)
1927
1928 "cophh_delete_sv"
1929 NOTE: "cophh_delete_sv" is experimental and may change or be
1930 removed without notice.
1931
1932 Like "cophh_delete_pvn", but takes a Perl scalar instead of a
1933 string/length pair.
1934
1935 COPHH * cophh_delete_sv(COPHH *cophh, SV *key, U32 hash,
1936 U32 flags)
1937
1938 "cophh_exists_pv"
1939 NOTE: "cophh_exists_pv" is experimental and may change or be
1940 removed without notice.
1941
1942 Like "cophh_exists_pvn", but takes a nul-terminated string instead
1943 of a string/length pair.
1944
1945 bool cophh_exists_pv(const COPHH *cophh, const char *key,
1946 U32 hash, U32 flags)
1947
1948 "cophh_exists_pvn"
1949 NOTE: "cophh_exists_pvn" is experimental and may change or be
1950 removed without notice.
1951
1952 Look up the entry in the cop hints hash "cophh" with the key
1953 specified by "keypv" and "keylen". If "flags" has the
1954 "COPHH_KEY_UTF8" bit set, the key octets are interpreted as UTF-8,
1955 otherwise they are interpreted as Latin-1. "hash" is a precomputed
1956 hash of the key string, or zero if it has not been precomputed.
1957 Returns true if a value exists, and false otherwise.
1958
1959 bool cophh_exists_pvn(const COPHH *cophh, const char *keypv,
1960 STRLEN keylen, U32 hash, U32 flags)
1961
1962 "cophh_exists_pvs"
1963 NOTE: "cophh_exists_pvs" is experimental and may change or be
1964 removed without notice.
1965
1966 Like "cophh_exists_pvn", but takes a literal string instead of a
1967 string/length pair, and no precomputed hash.
1968
1969 bool cophh_exists_pvs(const COPHH *cophh, "key", U32 flags)
1970
1971 "cophh_exists_sv"
1972 NOTE: "cophh_exists_sv" is experimental and may change or be
1973 removed without notice.
1974
1975 Like "cophh_exists_pvn", but takes a Perl scalar instead of a
1976 string/length pair.
1977
1978 bool cophh_exists_sv(const COPHH *cophh, SV *key, U32 hash,
1979 U32 flags)
1980
1981 "cophh_fetch_pv"
1982 NOTE: "cophh_fetch_pv" is experimental and may change or be removed
1983 without notice.
1984
1985 Like "cophh_fetch_pvn", but takes a nul-terminated string instead
1986 of a string/length pair.
1987
1988 SV * cophh_fetch_pv(const COPHH *cophh, const char *key,
1989 U32 hash, U32 flags)
1990
1991 "cophh_fetch_pvn"
1992 NOTE: "cophh_fetch_pvn" is experimental and may change or be
1993 removed without notice.
1994
1995 Look up the entry in the cop hints hash "cophh" with the key
1996 specified by "keypv" and "keylen". If "flags" has the
1997 "COPHH_KEY_UTF8" bit set, the key octets are interpreted as UTF-8,
1998 otherwise they are interpreted as Latin-1. "hash" is a precomputed
1999 hash of the key string, or zero if it has not been precomputed.
2000 Returns a mortal scalar copy of the value associated with the key,
2001 or &PL_sv_placeholder if there is no value associated with the key.
2002
2003 SV * cophh_fetch_pvn(const COPHH *cophh, const char *keypv,
2004 STRLEN keylen, U32 hash, U32 flags)
2005
2006 "cophh_fetch_pvs"
2007 NOTE: "cophh_fetch_pvs" is experimental and may change or be
2008 removed without notice.
2009
2010 Like "cophh_fetch_pvn", but takes a literal string instead of a
2011 string/length pair, and no precomputed hash.
2012
2013 SV * cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags)
2014
2015 "cophh_fetch_sv"
2016 NOTE: "cophh_fetch_sv" is experimental and may change or be removed
2017 without notice.
2018
2019 Like "cophh_fetch_pvn", but takes a Perl scalar instead of a
2020 string/length pair.
2021
2022 SV * cophh_fetch_sv(const COPHH *cophh, SV *key, U32 hash,
2023 U32 flags)
2024
2025 "cophh_free"
2026 NOTE: "cophh_free" is experimental and may change or be removed
2027 without notice.
2028
2029 Discard the cop hints hash "cophh", freeing all resources
2030 associated with it.
2031
2032 void cophh_free(COPHH *cophh)
2033
2034 "cophh_new_empty"
2035 NOTE: "cophh_new_empty" is experimental and may change or be
2036 removed without notice.
2037
2038 Generate and return a fresh cop hints hash containing no entries.
2039
2040 COPHH * cophh_new_empty()
2041
2042 "cophh_store_pv"
2043 NOTE: "cophh_store_pv" is experimental and may change or be removed
2044 without notice.
2045
2046 Like "cophh_store_pvn", but takes a nul-terminated string instead
2047 of a string/length pair.
2048
2049 COPHH * cophh_store_pv(COPHH *cophh, const char *key, U32 hash,
2050 SV *value, U32 flags)
2051
2052 "cophh_store_pvn"
2053 NOTE: "cophh_store_pvn" is experimental and may change or be
2054 removed without notice.
2055
2056 Stores a value, associated with a key, in the cop hints hash
2057 "cophh", and returns the modified hash. The returned hash pointer
2058 is in general not the same as the hash pointer that was passed in.
2059 The input hash is consumed by the function, and the pointer to it
2060 must not be subsequently used. Use "cophh_copy" if you need both
2061 hashes.
2062
2063 The key is specified by "keypv" and "keylen". If "flags" has the
2064 "COPHH_KEY_UTF8" bit set, the key octets are interpreted as UTF-8,
2065 otherwise they are interpreted as Latin-1. "hash" is a precomputed
2066 hash of the key string, or zero if it has not been precomputed.
2067
2068 "value" is the scalar value to store for this key. "value" is
2069 copied by this function, which thus does not take ownership of any
2070 reference to it, and later changes to the scalar will not be
2071 reflected in the value visible in the cop hints hash. Complex
2072 types of scalar will not be stored with referential integrity, but
2073 will be coerced to strings.
2074
2075 COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
2076 STRLEN keylen, U32 hash, SV *value,
2077 U32 flags)
2078
2079 "cophh_store_pvs"
2080 NOTE: "cophh_store_pvs" is experimental and may change or be
2081 removed without notice.
2082
2083 Like "cophh_store_pvn", but takes a literal string instead of a
2084 string/length pair, and no precomputed hash.
2085
2086 COPHH * cophh_store_pvs(COPHH *cophh, "key", SV *value,
2087 U32 flags)
2088
2089 "cophh_store_sv"
2090 NOTE: "cophh_store_sv" is experimental and may change or be removed
2091 without notice.
2092
2093 Like "cophh_store_pvn", but takes a Perl scalar instead of a
2094 string/length pair.
2095
2096 COPHH * cophh_store_sv(COPHH *cophh, SV *key, U32 hash,
2097 SV *value, U32 flags)
2098
2099 "cop_hints_2hv"
2100 Generates and returns a standard Perl hash representing the full
2101 set of hint entries in the cop "cop". "flags" is currently unused
2102 and must be zero.
2103
2104 HV * cop_hints_2hv(const COP *cop, U32 flags)
2105
2106 "cop_hints_exists_pv"
2107 Like "cop_hints_exists_pvn", but takes a nul-terminated string
2108 instead of a string/length pair.
2109
2110 bool cop_hints_exists_pv(const COP *cop, const char *key,
2111 U32 hash, U32 flags)
2112
2113 "cop_hints_exists_pvn"
2114 Look up the hint entry in the cop "cop" with the key specified by
2115 "keypv" and "keylen". If "flags" has the "COPHH_KEY_UTF8" bit set,
2116 the key octets are interpreted as UTF-8, otherwise they are
2117 interpreted as Latin-1. "hash" is a precomputed hash of the key
2118 string, or zero if it has not been precomputed. Returns true if a
2119 value exists, and false otherwise.
2120
2121 bool cop_hints_exists_pvn(const COP *cop, const char *keypv,
2122 STRLEN keylen, U32 hash, U32 flags)
2123
2124 "cop_hints_exists_pvs"
2125 Like "cop_hints_exists_pvn", but takes a literal string instead of
2126 a string/length pair, and no precomputed hash.
2127
2128 bool cop_hints_exists_pvs(const COP *cop, "key", U32 flags)
2129
2130 "cop_hints_exists_sv"
2131 Like "cop_hints_exists_pvn", but takes a Perl scalar instead of a
2132 string/length pair.
2133
2134 bool cop_hints_exists_sv(const COP *cop, SV *key, U32 hash,
2135 U32 flags)
2136
2137 "cop_hints_fetch_pv"
2138 Like "cop_hints_fetch_pvn", but takes a nul-terminated string
2139 instead of a string/length pair.
2140
2141 SV * cop_hints_fetch_pv(const COP *cop, const char *key,
2142 U32 hash, U32 flags)
2143
2144 "cop_hints_fetch_pvn"
2145 Look up the hint entry in the cop "cop" with the key specified by
2146 "keypv" and "keylen". If "flags" has the "COPHH_KEY_UTF8" bit set,
2147 the key octets are interpreted as UTF-8, otherwise they are
2148 interpreted as Latin-1. "hash" is a precomputed hash of the key
2149 string, or zero if it has not been precomputed. Returns a mortal
2150 scalar copy of the value associated with the key, or
2151 &PL_sv_placeholder if there is no value associated with the key.
2152
2153 SV * cop_hints_fetch_pvn(const COP *cop, const char *keypv,
2154 STRLEN keylen, U32 hash, U32 flags)
2155
2156 "cop_hints_fetch_pvs"
2157 Like "cop_hints_fetch_pvn", but takes a literal string instead of a
2158 string/length pair, and no precomputed hash.
2159
2160 SV * cop_hints_fetch_pvs(const COP *cop, "key", U32 flags)
2161
2162 "cop_hints_fetch_sv"
2163 Like "cop_hints_fetch_pvn", but takes a Perl scalar instead of a
2164 string/length pair.
2165
2166 SV * cop_hints_fetch_sv(const COP *cop, SV *key, U32 hash,
2167 U32 flags)
2168
2169 "CopLABEL"
2170 Returns the label attached to a cop.
2171
2172 const char * CopLABEL(COP *const cop)
2173
2174 "CopLABEL_len"
2175 Returns the label attached to a cop, and stores its length in bytes
2176 into *len.
2177
2178 const char * CopLABEL_len(COP *const cop, STRLEN *len)
2179
2180 "CopLABEL_len_flags"
2181 Returns the label attached to a cop, and stores its length in bytes
2182 into *len. Upon return, *flags will be set to either "SVf_UTF8" or
2183 0.
2184
2185 const char * CopLABEL_len_flags(COP *const cop, STRLEN *len,
2186 U32 *flags)
2187
2188 "CopLINE"
2189 Returns the line number in the source code associated with the
2190 "COP" "c"
2191
2192 STRLEN CopLINE(const COP * c)
2193
2194 "CopSTASH"
2195 Returns the stash associated with "c".
2196
2197 HV * CopSTASH(const COP * c)
2198
2199 "CopSTASH_eq"
2200 Returns a boolean as to whether or not "hv" is the stash associated
2201 with "c".
2202
2203 bool CopSTASH_eq(const COP * c, const HV * hv)
2204
2205 "CopSTASHPV"
2206 Returns the package name of the stash associated with "c", or
2207 "NULL" if no associated stash
2208
2209 char * CopSTASHPV(const COP * c)
2210
2211 "CopSTASHPV_set"
2212 Set the package name of the stash associated with "c", to the NUL-
2213 terminated C string "p", creating the package if necessary.
2214
2215 void CopSTASHPV_set(COP * c, const char * pv)
2216
2217 "CopSTASH_set"
2218 Set the stash associated with "c" to "hv".
2219
2220 bool CopSTASH_set(COP * c, HV * hv)
2221
2222 "cop_store_label"
2223 NOTE: "cop_store_label" is experimental and may change or be
2224 removed without notice.
2225
2226 Save a label into a "cop_hints_hash". You need to set flags to
2227 "SVf_UTF8" for a UTF-8 label. Any other flag is ignored.
2228
2229 void cop_store_label(COP *const cop, const char *label,
2230 STRLEN len, U32 flags)
2231
2232 "PERL_SI"
2233 Use this typedef to declare variables that are to hold "struct
2234 stackinfo".
2235
2237 "custom_op_desc"
2238 "DEPRECATED!" It is planned to remove "custom_op_desc" from a
2239 future release of Perl. Do not use it for new code; remove it from
2240 existing code.
2241
2242 Return the description of a given custom op. This was once used by
2243 the "OP_DESC" macro, but is no longer: it has only been kept for
2244 compatibility, and should not be used.
2245
2246 const char * custom_op_desc(const OP *o)
2247
2248 "custom_op_name"
2249 "DEPRECATED!" It is planned to remove "custom_op_name" from a
2250 future release of Perl. Do not use it for new code; remove it from
2251 existing code.
2252
2253 Return the name for a given custom op. This was once used by the
2254 "OP_NAME" macro, but is no longer: it has only been kept for
2255 compatibility, and should not be used.
2256
2257 const char * custom_op_name(const OP *o)
2258
2259 "custom_op_register"
2260 Register a custom op. See "Custom Operators" in perlguts.
2261
2262 NOTE: "custom_op_register" must be explicitly called as
2263 "Perl_custom_op_register" with an "aTHX_" parameter.
2264
2265 void Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr,
2266 const XOP *xop)
2267
2268 "Perl_custom_op_xop"
2269 Return the XOP structure for a given custom op. This macro should
2270 be considered internal to "OP_NAME" and the other access macros:
2271 use them instead. This macro does call a function. Prior to
2272 5.19.6, this was implemented as a function.
2273
2274 const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
2275
2276 "XopDISABLE"
2277 Temporarily disable a member of the XOP, by clearing the
2278 appropriate flag.
2279
2280 void XopDISABLE(XOP *xop, which)
2281
2282 "XopENABLE"
2283 Reenable a member of the XOP which has been disabled.
2284
2285 void XopENABLE(XOP *xop, which)
2286
2287 "XopENTRY"
2288 Return a member of the XOP structure. "which" is a cpp token
2289 indicating which entry to return. If the member is not set this
2290 will return a default value. The return type depends on "which".
2291 This macro evaluates its arguments more than once. If you are
2292 using "Perl_custom_op_xop" to retrieve a "XOP *" from a "OP *", use
2293 the more efficient "XopENTRYCUSTOM" instead.
2294
2295 XopENTRY(XOP *xop, which)
2296
2297 "XopENTRYCUSTOM"
2298 Exactly like "XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o),
2299 which)" but more efficient. The "which" parameter is identical to
2300 "XopENTRY".
2301
2302 XopENTRYCUSTOM(const OP *o, which)
2303
2304 "XopENTRY_set"
2305 Set a member of the XOP structure. "which" is a cpp token
2306 indicating which entry to set. See "Custom Operators" in perlguts
2307 for details about the available members and how they are used.
2308 This macro evaluates its argument more than once.
2309
2310 void XopENTRY_set(XOP *xop, which, value)
2311
2312 "XopFLAGS"
2313 Return the XOP's flags.
2314
2315 U32 XopFLAGS(XOP *xop)
2316
2318 This section documents functions to manipulate CVs which are code-
2319 values, meaning subroutines. For more information, see perlguts.
2320
2321 "caller_cx"
2322 The XSUB-writer's equivalent of caller(). The returned
2323 "PERL_CONTEXT" structure can be interrogated to find all the
2324 information returned to Perl by "caller". Note that XSUBs don't
2325 get a stack frame, so "caller_cx(0, NULL)" will return information
2326 for the immediately-surrounding Perl code.
2327
2328 This function skips over the automatic calls to &DB::sub made on
2329 the behalf of the debugger. If the stack frame requested was a sub
2330 called by "DB::sub", the return value will be the frame for the
2331 call to "DB::sub", since that has the correct line number/etc. for
2332 the call site. If dbcxp is non-"NULL", it will be set to a pointer
2333 to the frame for the sub call itself.
2334
2335 const PERL_CONTEXT * caller_cx(I32 level,
2336 const PERL_CONTEXT **dbcxp)
2337
2338 "CvGV"
2339 Returns the GV associated with the CV "sv", reifying it if
2340 necessary.
2341
2342 GV * CvGV(CV *sv)
2343
2344 "CvSTASH"
2345 Returns the stash of the CV. A stash is the symbol table hash,
2346 containing the package-scoped variables in the package where the
2347 subroutine was defined. For more information, see perlguts.
2348
2349 This also has a special use with XS AUTOLOAD subs. See
2350 "Autoloading with XSUBs" in perlguts.
2351
2352 HV* CvSTASH(CV* cv)
2353
2354 "find_runcv"
2355 Locate the CV corresponding to the currently executing sub or eval.
2356 If "db_seqp" is non_null, skip CVs that are in the DB package and
2357 populate *db_seqp with the cop sequence number at the point that
2358 the DB:: code was entered. (This allows debuggers to eval in the
2359 scope of the breakpoint rather than in the scope of the debugger
2360 itself.)
2361
2362 CV* find_runcv(U32 *db_seqp)
2363
2364 "get_cv"
2365 "get_cvs"
2366 "get_cvn_flags"
2367 These return the CV of the specified Perl subroutine. "flags" are
2368 passed to "gv_fetchpvn_flags". If "GV_ADD" is set and the Perl
2369 subroutine does not exist then it will be declared (which has the
2370 same effect as saying "sub name;"). If "GV_ADD" is not set and the
2371 subroutine does not exist, then NULL is returned.
2372
2373 The forms differ only in how the subroutine is specified.. With
2374 "get_cvs", the name is a literal C string, enclosed in double
2375 quotes. With "get_cv", the name is given by the "name" parameter,
2376 which must be a NUL-terminated C string. With "get_cvn_flags", the
2377 name is also given by the "name" parameter, but it is a Perl string
2378 (possibly containing embedded NUL bytes), and its length in bytes
2379 is contained in the "len" parameter.
2380
2381 NOTE: the "perl_get_cv()" form is deprecated.
2382
2383 NOTE: the "perl_get_cvs()" form is deprecated.
2384
2385 NOTE: the "perl_get_cvn_flags()" form is deprecated.
2386
2387 CV* get_cv (const char* name, I32 flags)
2388 CV * get_cvs ("string", I32 flags)
2389 CV* get_cvn_flags(const char* name, STRLEN len, I32 flags)
2390
2391 "Nullcv"
2392 "DEPRECATED!" It is planned to remove "Nullcv" from a future
2393 release of Perl. Do not use it for new code; remove it from
2394 existing code.
2395
2396 Null CV pointer.
2397
2398 (deprecated - use "(CV *)NULL" instead)
2399
2401 "dump_all"
2402 Dumps the entire optree of the current program starting at
2403 "PL_main_root" to "STDERR". Also dumps the optrees for all visible
2404 subroutines in "PL_defstash".
2405
2406 void dump_all()
2407
2408 "dump_c_backtrace"
2409 Dumps the C backtrace to the given "fp".
2410
2411 Returns true if a backtrace could be retrieved, false if not.
2412
2413 bool dump_c_backtrace(PerlIO* fp, int max_depth, int skip)
2414
2415 "dump_packsubs"
2416 Dumps the optrees for all visible subroutines in "stash".
2417
2418 void dump_packsubs(const HV* stash)
2419
2420 "get_c_backtrace_dump"
2421 Returns a SV containing a dump of "depth" frames of the call stack,
2422 skipping the "skip" innermost ones. "depth" of 20 is usually
2423 enough.
2424
2425 The appended output looks like:
2426
2427 ...
2428 1 10e004812:0082 Perl_croak util.c:1716 /usr/bin/perl
2429 2 10df8d6d2:1d72 perl_parse perl.c:3975 /usr/bin/perl
2430 ...
2431
2432 The fields are tab-separated. The first column is the depth (zero
2433 being the innermost non-skipped frame). In the hex:offset, the hex
2434 is where the program counter was in "S_parse_body", and the :offset
2435 (might be missing) tells how much inside the "S_parse_body" the
2436 program counter was.
2437
2438 The "util.c:1716" is the source code file and line number.
2439
2440 The /usr/bin/perl is obvious (hopefully).
2441
2442 Unknowns are "-". Unknowns can happen unfortunately quite easily:
2443 if the platform doesn't support retrieving the information; if the
2444 binary is missing the debug information; if the optimizer has
2445 transformed the code by for example inlining.
2446
2447 SV* get_c_backtrace_dump(int max_depth, int skip)
2448
2449 "HAS_BACKTRACE"
2450 This symbol, if defined, indicates that the "backtrace()" routine
2451 is available to get a stack trace. The execinfo.h header must be
2452 included to use this routine.
2453
2454 "op_class"
2455 Given an op, determine what type of struct it has been allocated
2456 as. Returns one of the OPclass enums, such as OPclass_LISTOP.
2457
2458 OPclass op_class(const OP *o)
2459
2460 "op_dump"
2461 Dumps the optree starting at OP "o" to "STDERR".
2462
2463 void op_dump(const OP *o)
2464
2465 "sv_dump"
2466 Dumps the contents of an SV to the "STDERR" filehandle.
2467
2468 For an example of its output, see Devel::Peek.
2469
2470 void sv_dump(SV* sv)
2471
2473 "form"
2474 "form_nocontext"
2475 These take a sprintf-style format pattern and conventional (non-SV)
2476 arguments and return the formatted string.
2477
2478 (char *) Perl_form(pTHX_ const char* pat, ...)
2479
2480 can be used any place a string (char *) is required:
2481
2482 char * s = Perl_form("%d.%d",major,minor);
2483
2484 They use a single (per-thread) private buffer so if you want to
2485 format several strings you must explicitly copy the earlier strings
2486 away (and free the copies when you are done).
2487
2488 The two forms differ only in that "form_nocontext" does not take a
2489 thread context ("aTHX") parameter, so is used in situations where
2490 the caller doesn't already have the thread context.
2491
2492 NOTE: "form" must be explicitly called as "Perl_form" with an
2493 "aTHX_" parameter.
2494
2495 char* Perl_form (pTHX_ const char* pat, ...)
2496 char* form_nocontext(const char* pat, ...)
2497
2498 "mess"
2499 "mess_nocontext"
2500 These take a sprintf-style format pattern and argument list, which
2501 are used to generate a string message. If the message does not end
2502 with a newline, then it will be extended with some indication of
2503 the current location in the code, as described for "mess_sv".
2504
2505 Normally, the resulting message is returned in a new mortal SV.
2506 But during global destruction a single SV may be shared between
2507 uses of this function.
2508
2509 The two forms differ only in that "mess_nocontext" does not take a
2510 thread context ("aTHX") parameter, so is used in situations where
2511 the caller doesn't already have the thread context.
2512
2513 NOTE: "mess" must be explicitly called as "Perl_mess" with an
2514 "aTHX_" parameter.
2515
2516 SV* Perl_mess (pTHX_ const char* pat, ...)
2517 SV* mess_nocontext(const char* pat, ...)
2518
2519 "mess_sv"
2520 Expands a message, intended for the user, to include an indication
2521 of the current location in the code, if the message does not
2522 already appear to be complete.
2523
2524 "basemsg" is the initial message or object. If it is a reference,
2525 it will be used as-is and will be the result of this function.
2526 Otherwise it is used as a string, and if it already ends with a
2527 newline, it is taken to be complete, and the result of this
2528 function will be the same string. If the message does not end with
2529 a newline, then a segment such as "at foo.pl line 37" will be
2530 appended, and possibly other clauses indicating the current state
2531 of execution. The resulting message will end with a dot and a
2532 newline.
2533
2534 Normally, the resulting message is returned in a new mortal SV.
2535 During global destruction a single SV may be shared between uses of
2536 this function. If "consume" is true, then the function is
2537 permitted (but not required) to modify and return "basemsg" instead
2538 of allocating a new SV.
2539
2540 SV* mess_sv(SV* basemsg, bool consume)
2541
2542 "pv_display"
2543 Similar to
2544
2545 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
2546
2547 except that an additional "\0" will be appended to the string when
2548 len > cur and pv[cur] is "\0".
2549
2550 Note that the final string may be up to 7 chars longer than pvlim.
2551
2552 char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len,
2553 STRLEN pvlim)
2554
2555 "pv_escape"
2556 Escapes at most the first "count" chars of "pv" and puts the
2557 results into "dsv" such that the size of the escaped string will
2558 not exceed "max" chars and will not contain any incomplete escape
2559 sequences. The number of bytes escaped will be returned in the
2560 "STRLEN *escaped" parameter if it is not null. When the "dsv"
2561 parameter is null no escaping actually occurs, but the number of
2562 bytes that would be escaped were it not null will be calculated.
2563
2564 If flags contains "PERL_PV_ESCAPE_QUOTE" then any double quotes in
2565 the string will also be escaped.
2566
2567 Normally the SV will be cleared before the escaped string is
2568 prepared, but when "PERL_PV_ESCAPE_NOCLEAR" is set this will not
2569 occur.
2570
2571 If "PERL_PV_ESCAPE_UNI" is set then the input string is treated as
2572 UTF-8 if "PERL_PV_ESCAPE_UNI_DETECT" is set then the input string
2573 is scanned using "is_utf8_string()" to determine if it is UTF-8.
2574
2575 If "PERL_PV_ESCAPE_ALL" is set then all input chars will be output
2576 using "\x01F1" style escapes, otherwise if
2577 "PERL_PV_ESCAPE_NONASCII" is set, only non-ASCII chars will be
2578 escaped using this style; otherwise, only chars above 255 will be
2579 so escaped; other non printable chars will use octal or common
2580 escaped patterns like "\n". Otherwise, if
2581 "PERL_PV_ESCAPE_NOBACKSLASH" then all chars below 255 will be
2582 treated as printable and will be output as literals.
2583
2584 If "PERL_PV_ESCAPE_FIRSTCHAR" is set then only the first char of
2585 the string will be escaped, regardless of max. If the output is to
2586 be in hex, then it will be returned as a plain hex sequence. Thus
2587 the output will either be a single char, an octal escape sequence,
2588 a special escape like "\n" or a hex value.
2589
2590 If "PERL_PV_ESCAPE_RE" is set then the escape char used will be a
2591 "%" and not a "\\". This is because regexes very often contain
2592 backslashed sequences, whereas "%" is not a particularly common
2593 character in patterns.
2594
2595 Returns a pointer to the escaped text as held by "dsv".
2596
2597 char* pv_escape(SV *dsv, char const * const str,
2598 const STRLEN count, const STRLEN max,
2599 STRLEN * const escaped, const U32 flags)
2600
2601 "pv_pretty"
2602 Converts a string into something presentable, handling escaping via
2603 "pv_escape()" and supporting quoting and ellipses.
2604
2605 If the "PERL_PV_PRETTY_QUOTE" flag is set then the result will be
2606 double quoted with any double quotes in the string escaped.
2607 Otherwise if the "PERL_PV_PRETTY_LTGT" flag is set then the result
2608 be wrapped in angle brackets.
2609
2610 If the "PERL_PV_PRETTY_ELLIPSES" flag is set and not all characters
2611 in string were output then an ellipsis "..." will be appended to
2612 the string. Note that this happens AFTER it has been quoted.
2613
2614 If "start_color" is non-null then it will be inserted after the
2615 opening quote (if there is one) but before the escaped text. If
2616 "end_color" is non-null then it will be inserted after the escaped
2617 text but before any quotes or ellipses.
2618
2619 Returns a pointer to the prettified text as held by "dsv".
2620
2621 char* pv_pretty(SV *dsv, char const * const str,
2622 const STRLEN count, const STRLEN max,
2623 char const * const start_color,
2624 char const * const end_color, const U32 flags)
2625
2626 "vform"
2627 Like "form" but but the arguments are an encapsulated argument
2628 list.
2629
2630 char* vform(const char* pat, va_list* args)
2631
2632 "vmess"
2633 "pat" and "args" are a sprintf-style format pattern and
2634 encapsulated argument list, respectively. These are used to
2635 generate a string message. If the message does not end with a
2636 newline, then it will be extended with some indication of the
2637 current location in the code, as described for "mess_sv".
2638
2639 Normally, the resulting message is returned in a new mortal SV.
2640 During global destruction a single SV may be shared between uses of
2641 this function.
2642
2643 SV* vmess(const char* pat, va_list* args)
2644
2646 "cv_clone"
2647 Clone a CV, making a lexical closure. "proto" supplies the
2648 prototype of the function: its code, pad structure, and other
2649 attributes. The prototype is combined with a capture of outer
2650 lexicals to which the code refers, which are taken from the
2651 currently-executing instance of the immediately surrounding code.
2652
2653 CV* cv_clone(CV* proto)
2654
2655 "cv_name"
2656 Returns an SV containing the name of the CV, mainly for use in
2657 error reporting. The CV may actually be a GV instead, in which
2658 case the returned SV holds the GV's name. Anything other than a GV
2659 or CV is treated as a string already holding the sub name, but this
2660 could change in the future.
2661
2662 An SV may be passed as a second argument. If so, the name will be
2663 assigned to it and it will be returned. Otherwise the returned SV
2664 will be a new mortal.
2665
2666 If "flags" has the "CV_NAME_NOTQUAL" bit set, then the package name
2667 will not be included. If the first argument is neither a CV nor a
2668 GV, this flag is ignored (subject to change).
2669
2670 SV * cv_name(CV *cv, SV *sv, U32 flags)
2671
2672 "cv_undef"
2673 Clear out all the active components of a CV. This can happen
2674 either by an explicit "undef &foo", or by the reference count going
2675 to zero. In the former case, we keep the "CvOUTSIDE" pointer, so
2676 that any anonymous children can still follow the full lexical scope
2677 chain.
2678
2679 void cv_undef(CV* cv)
2680
2681 "find_rundefsv"
2682 Returns the global variable $_.
2683
2684 SV* find_rundefsv()
2685
2686 "find_rundefsvoffset"
2687 "DEPRECATED!" It is planned to remove "find_rundefsvoffset" from a
2688 future release of Perl. Do not use it for new code; remove it from
2689 existing code.
2690
2691 Until the lexical $_ feature was removed, this function would find
2692 the position of the lexical $_ in the pad of the currently-
2693 executing function and return the offset in the current pad, or
2694 "NOT_IN_PAD".
2695
2696 Now it always returns "NOT_IN_PAD".
2697
2698 PADOFFSET find_rundefsvoffset()
2699
2700 "intro_my"
2701 "Introduce" "my" variables to visible status. This is called
2702 during parsing at the end of each statement to make lexical
2703 variables visible to subsequent statements.
2704
2705 U32 intro_my()
2706
2707 "load_module"
2708 Loads the module whose name is pointed to by the string part of
2709 "name". Note that the actual module name, not its filename, should
2710 be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver, if
2711 specified and not NULL, provides version semantics similar to "use
2712 Foo::Bar VERSION". The optional trailing arguments can be used to
2713 specify arguments to the module's "import()" method, similar to
2714 "use Foo::Bar VERSION LIST"; their precise handling depends on the
2715 flags. The flags argument is a bitwise-ORed collection of any of
2716 "PERL_LOADMOD_DENY", "PERL_LOADMOD_NOIMPORT", or
2717 "PERL_LOADMOD_IMPORT_OPS" (or 0 for no flags).
2718
2719 If "PERL_LOADMOD_NOIMPORT" is set, the module is loaded as if with
2720 an empty import list, as in "use Foo::Bar ()"; this is the only
2721 circumstance in which the trailing optional arguments may be
2722 omitted entirely. Otherwise, if "PERL_LOADMOD_IMPORT_OPS" is set,
2723 the trailing arguments must consist of exactly one "OP*",
2724 containing the op tree that produces the relevant import arguments.
2725 Otherwise, the trailing arguments must all be "SV*" values that
2726 will be used as import arguments; and the list must be terminated
2727 with "(SV*) NULL". If neither "PERL_LOADMOD_NOIMPORT" nor
2728 "PERL_LOADMOD_IMPORT_OPS" is set, the trailing "NULL" pointer is
2729 needed even if no import arguments are desired. The reference count
2730 for each specified "SV*" argument is decremented. In addition, the
2731 "name" argument is modified.
2732
2733 If "PERL_LOADMOD_DENY" is set, the module is loaded as if with "no"
2734 rather than "use".
2735
2736 void load_module(U32 flags, SV* name, SV* ver, ...)
2737
2738 "load_module_nocontext"
2739 Like "load_module" but does not take a thread context ("aTHX")
2740 parameter, so is used in situations where the caller doesn't
2741 already have the thread context.
2742
2743 void load_module_nocontext(U32 flags, SV* name, SV* ver, ...)
2744
2745 "my_exit"
2746 A wrapper for the C library exit(3), honoring what "PL_exit_flags"
2747 in perlapi say to do.
2748
2749 void my_exit(U32 status)
2750
2751 "newPADNAMELIST"
2752 NOTE: "newPADNAMELIST" is experimental and may change or be removed
2753 without notice.
2754
2755 Creates a new pad name list. "max" is the highest index for which
2756 space is allocated.
2757
2758 PADNAMELIST * newPADNAMELIST(size_t max)
2759
2760 "newPADNAMEouter"
2761 NOTE: "newPADNAMEouter" is experimental and may change or be
2762 removed without notice.
2763
2764 Constructs and returns a new pad name. Only use this function for
2765 names that refer to outer lexicals. (See also "newPADNAMEpvn".)
2766 "outer" is the outer pad name that this one mirrors. The returned
2767 pad name has the "PADNAMEt_OUTER" flag already set.
2768
2769 PADNAME * newPADNAMEouter(PADNAME *outer)
2770
2771 "newPADNAMEpvn"
2772 NOTE: "newPADNAMEpvn" is experimental and may change or be removed
2773 without notice.
2774
2775 Constructs and returns a new pad name. "s" must be a UTF-8 string.
2776 Do not use this for pad names that point to outer lexicals. See
2777 "newPADNAMEouter".
2778
2779 PADNAME * newPADNAMEpvn(const char *s, STRLEN len)
2780
2781 "nothreadhook"
2782 Stub that provides thread hook for perl_destruct when there are no
2783 threads.
2784
2785 int nothreadhook()
2786
2787 "pad_add_anon"
2788 Allocates a place in the currently-compiling pad (via "pad_alloc")
2789 for an anonymous function that is lexically scoped inside the
2790 currently-compiling function. The function "func" is linked into
2791 the pad, and its "CvOUTSIDE" link to the outer scope is weakened to
2792 avoid a reference loop.
2793
2794 One reference count is stolen, so you may need to do
2795 "SvREFCNT_inc(func)".
2796
2797 "optype" should be an opcode indicating the type of operation that
2798 the pad entry is to support. This doesn't affect operational
2799 semantics, but is used for debugging.
2800
2801 PADOFFSET pad_add_anon(CV* func, I32 optype)
2802
2803 "pad_add_name_pv"
2804 Exactly like "pad_add_name_pvn", but takes a nul-terminated string
2805 instead of a string/length pair.
2806
2807 PADOFFSET pad_add_name_pv(const char *name, const U32 flags,
2808 HV *typestash, HV *ourstash)
2809
2810 "pad_add_name_pvn"
2811 Allocates a place in the currently-compiling pad for a named
2812 lexical variable. Stores the name and other metadata in the name
2813 part of the pad, and makes preparations to manage the variable's
2814 lexical scoping. Returns the offset of the allocated pad slot.
2815
2816 "namepv"/"namelen" specify the variable's name, including leading
2817 sigil. If "typestash" is non-null, the name is for a typed
2818 lexical, and this identifies the type. If "ourstash" is non-null,
2819 it's a lexical reference to a package variable, and this identifies
2820 the package. The following flags can be OR'ed together:
2821
2822 padadd_OUR redundantly specifies if it's a package var
2823 padadd_STATE variable will retain value persistently
2824 padadd_NO_DUP_CHECK skip check for lexical shadowing
2825
2826 PADOFFSET pad_add_name_pvn(const char *namepv, STRLEN namelen,
2827 U32 flags, HV *typestash,
2828 HV *ourstash)
2829
2830 "pad_add_name_sv"
2831 Exactly like "pad_add_name_pvn", but takes the name string in the
2832 form of an SV instead of a string/length pair.
2833
2834 PADOFFSET pad_add_name_sv(SV *name, U32 flags, HV *typestash,
2835 HV *ourstash)
2836
2837 "pad_alloc"
2838 NOTE: "pad_alloc" is experimental and may change or be removed
2839 without notice.
2840
2841 Allocates a place in the currently-compiling pad, returning the
2842 offset of the allocated pad slot. No name is initially attached to
2843 the pad slot. "tmptype" is a set of flags indicating the kind of
2844 pad entry required, which will be set in the value SV for the
2845 allocated pad entry:
2846
2847 SVs_PADMY named lexical variable ("my", "our", "state")
2848 SVs_PADTMP unnamed temporary store
2849 SVf_READONLY constant shared between recursion levels
2850
2851 "SVf_READONLY" has been supported here only since perl 5.20. To
2852 work with earlier versions as well, use "SVf_READONLY|SVs_PADTMP".
2853 "SVf_READONLY" does not cause the SV in the pad slot to be marked
2854 read-only, but simply tells "pad_alloc" that it will be made read-
2855 only (by the caller), or at least should be treated as such.
2856
2857 "optype" should be an opcode indicating the type of operation that
2858 the pad entry is to support. This doesn't affect operational
2859 semantics, but is used for debugging.
2860
2861 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
2862
2863 "pad_findmy_pv"
2864 Exactly like "pad_findmy_pvn", but takes a nul-terminated string
2865 instead of a string/length pair.
2866
2867 PADOFFSET pad_findmy_pv(const char* name, U32 flags)
2868
2869 "pad_findmy_pvn"
2870 Given the name of a lexical variable, find its position in the
2871 currently-compiling pad. "namepv"/"namelen" specify the variable's
2872 name, including leading sigil. "flags" is reserved and must be
2873 zero. If it is not in the current pad but appears in the pad of
2874 any lexically enclosing scope, then a pseudo-entry for it is added
2875 in the current pad. Returns the offset in the current pad, or
2876 "NOT_IN_PAD" if no such lexical is in scope.
2877
2878 PADOFFSET pad_findmy_pvn(const char* namepv, STRLEN namelen,
2879 U32 flags)
2880
2881 "pad_findmy_sv"
2882 Exactly like "pad_findmy_pvn", but takes the name string in the
2883 form of an SV instead of a string/length pair.
2884
2885 PADOFFSET pad_findmy_sv(SV* name, U32 flags)
2886
2887 "padnamelist_fetch"
2888 NOTE: "padnamelist_fetch" is experimental and may change or be
2889 removed without notice.
2890
2891 Fetches the pad name from the given index.
2892
2893 PADNAME * padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
2894
2895 "padnamelist_store"
2896 NOTE: "padnamelist_store" is experimental and may change or be
2897 removed without notice.
2898
2899 Stores the pad name (which may be null) at the given index, freeing
2900 any existing pad name in that slot.
2901
2902 PADNAME ** padnamelist_store(PADNAMELIST *pnl, SSize_t key,
2903 PADNAME *val)
2904
2905 "pad_tidy"
2906 NOTE: "pad_tidy" is experimental and may change or be removed
2907 without notice.
2908
2909 Tidy up a pad at the end of compilation of the code to which it
2910 belongs. Jobs performed here are: remove most stuff from the pads
2911 of anonsub prototypes; give it a @_; mark temporaries as such.
2912 "type" indicates the kind of subroutine:
2913
2914 padtidy_SUB ordinary subroutine
2915 padtidy_SUBCLONE prototype for lexical closure
2916 padtidy_FORMAT format
2917
2918 void pad_tidy(padtidy_type type)
2919
2920 "perl_alloc"
2921 Allocates a new Perl interpreter. See perlembed.
2922
2923 PerlInterpreter* perl_alloc()
2924
2925 "PERL_ASYNC_CHECK"
2926 Described in perlinterp.
2927
2928 void PERL_ASYNC_CHECK()
2929
2930 "perl_clone"
2931 Create and return a new interpreter by cloning the current one.
2932
2933 "perl_clone" takes these flags as parameters:
2934
2935 "CLONEf_COPY_STACKS" - is used to, well, copy the stacks also,
2936 without it we only clone the data and zero the stacks, with it we
2937 copy the stacks and the new perl interpreter is ready to run at the
2938 exact same point as the previous one. The pseudo-fork code uses
2939 "COPY_STACKS" while the threads->create doesn't.
2940
2941 "CLONEf_KEEP_PTR_TABLE" - "perl_clone" keeps a ptr_table with the
2942 pointer of the old variable as a key and the new variable as a
2943 value, this allows it to check if something has been cloned and not
2944 clone it again, but rather just use the value and increase the
2945 refcount. If "KEEP_PTR_TABLE" is not set then "perl_clone" will
2946 kill the ptr_table using the function
2947 "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;". A reason to
2948 keep it around is if you want to dup some of your own variables
2949 which are outside the graph that perl scans.
2950
2951 "CLONEf_CLONE_HOST" - This is a win32 thing, it is ignored on unix,
2952 it tells perl's win32host code (which is c++) to clone itself, this
2953 is needed on win32 if you want to run two threads at the same time,
2954 if you just want to do some stuff in a separate perl interpreter
2955 and then throw it away and return to the original one, you don't
2956 need to do anything.
2957
2958 PerlInterpreter* perl_clone(PerlInterpreter *proto_perl,
2959 UV flags)
2960
2961 "perl_construct"
2962 Initializes a new Perl interpreter. See perlembed.
2963
2964 void perl_construct(PerlInterpreter *my_perl)
2965
2966 "perl_destruct"
2967 Shuts down a Perl interpreter. See perlembed for a tutorial.
2968
2969 "my_perl" points to the Perl interpreter. It must have been
2970 previously created through the use of "perl_alloc" and
2971 "perl_construct". It may have been initialised through
2972 "perl_parse", and may have been used through "perl_run" and other
2973 means. This function should be called for any Perl interpreter
2974 that has been constructed with "perl_construct", even if subsequent
2975 operations on it failed, for example if "perl_parse" returned a
2976 non-zero value.
2977
2978 If the interpreter's "PL_exit_flags" word has the
2979 "PERL_EXIT_DESTRUCT_END" flag set, then this function will execute
2980 code in "END" blocks before performing the rest of destruction. If
2981 it is desired to make any use of the interpreter between
2982 "perl_parse" and "perl_destruct" other than just calling
2983 "perl_run", then this flag should be set early on. This matters if
2984 "perl_run" will not be called, or if anything else will be done in
2985 addition to calling "perl_run".
2986
2987 Returns a value be a suitable value to pass to the C library
2988 function "exit" (or to return from "main"), to serve as an exit
2989 code indicating the nature of the way the interpreter terminated.
2990 This takes into account any failure of "perl_parse" and any early
2991 exit from "perl_run". The exit code is of the type required by the
2992 host operating system, so because of differing exit code
2993 conventions it is not portable to interpret specific numeric values
2994 as having specific meanings.
2995
2996 int perl_destruct(PerlInterpreter *my_perl)
2997
2998 "perl_free"
2999 Releases a Perl interpreter. See perlembed.
3000
3001 void perl_free(PerlInterpreter *my_perl)
3002
3003 "perl_parse"
3004 Tells a Perl interpreter to parse a Perl script. This performs
3005 most of the initialisation of a Perl interpreter. See perlembed
3006 for a tutorial.
3007
3008 "my_perl" points to the Perl interpreter that is to parse the
3009 script. It must have been previously created through the use of
3010 "perl_alloc" and "perl_construct". "xsinit" points to a callback
3011 function that will be called to set up the ability for this Perl
3012 interpreter to load XS extensions, or may be null to perform no
3013 such setup.
3014
3015 "argc" and "argv" supply a set of command-line arguments to the
3016 Perl interpreter, as would normally be passed to the "main"
3017 function of a C program. "argv[argc]" must be null. These
3018 arguments are where the script to parse is specified, either by
3019 naming a script file or by providing a script in a "-e" option. If
3020 $0 will be written to in the Perl interpreter, then the argument
3021 strings must be in writable memory, and so mustn't just be string
3022 constants.
3023
3024 "env" specifies a set of environment variables that will be used by
3025 this Perl interpreter. If non-null, it must point to a null-
3026 terminated array of environment strings. If null, the Perl
3027 interpreter will use the environment supplied by the "environ"
3028 global variable.
3029
3030 This function initialises the interpreter, and parses and compiles
3031 the script specified by the command-line arguments. This includes
3032 executing code in "BEGIN", "UNITCHECK", and "CHECK" blocks. It
3033 does not execute "INIT" blocks or the main program.
3034
3035 Returns an integer of slightly tricky interpretation. The correct
3036 use of the return value is as a truth value indicating whether
3037 there was a failure in initialisation. If zero is returned, this
3038 indicates that initialisation was successful, and it is safe to
3039 proceed to call "perl_run" and make other use of it. If a non-zero
3040 value is returned, this indicates some problem that means the
3041 interpreter wants to terminate. The interpreter should not be just
3042 abandoned upon such failure; the caller should proceed to shut the
3043 interpreter down cleanly with "perl_destruct" and free it with
3044 "perl_free".
3045
3046 For historical reasons, the non-zero return value also attempts to
3047 be a suitable value to pass to the C library function "exit" (or to
3048 return from "main"), to serve as an exit code indicating the nature
3049 of the way initialisation terminated. However, this isn't
3050 portable, due to differing exit code conventions. A historical bug
3051 is preserved for the time being: if the Perl built-in "exit" is
3052 called during this function's execution, with a type of exit
3053 entailing a zero exit code under the host operating system's
3054 conventions, then this function returns zero rather than a non-zero
3055 value. This bug, [perl #2754], leads to "perl_run" being called
3056 (and therefore "INIT" blocks and the main program running) despite
3057 a call to "exit". It has been preserved because a popular module-
3058 installing module has come to rely on it and needs time to be
3059 fixed. This issue is [perl #132577], and the original bug is due
3060 to be fixed in Perl 5.30.
3061
3062 int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit,
3063 int argc, char** argv, char** env)
3064
3065 "perl_run"
3066 Tells a Perl interpreter to run its main program. See perlembed
3067 for a tutorial.
3068
3069 "my_perl" points to the Perl interpreter. It must have been
3070 previously created through the use of "perl_alloc" and
3071 "perl_construct", and initialised through "perl_parse". This
3072 function should not be called if "perl_parse" returned a non-zero
3073 value, indicating a failure in initialisation or compilation.
3074
3075 This function executes code in "INIT" blocks, and then executes the
3076 main program. The code to be executed is that established by the
3077 prior call to "perl_parse". If the interpreter's "PL_exit_flags"
3078 word does not have the "PERL_EXIT_DESTRUCT_END" flag set, then this
3079 function will also execute code in "END" blocks. If it is desired
3080 to make any further use of the interpreter after calling this
3081 function, then "END" blocks should be postponed to "perl_destruct"
3082 time by setting that flag.
3083
3084 Returns an integer of slightly tricky interpretation. The correct
3085 use of the return value is as a truth value indicating whether the
3086 program terminated non-locally. If zero is returned, this
3087 indicates that the program ran to completion, and it is safe to
3088 make other use of the interpreter (provided that the
3089 "PERL_EXIT_DESTRUCT_END" flag was set as described above). If a
3090 non-zero value is returned, this indicates that the interpreter
3091 wants to terminate early. The interpreter should not be just
3092 abandoned because of this desire to terminate; the caller should
3093 proceed to shut the interpreter down cleanly with "perl_destruct"
3094 and free it with "perl_free".
3095
3096 For historical reasons, the non-zero return value also attempts to
3097 be a suitable value to pass to the C library function "exit" (or to
3098 return from "main"), to serve as an exit code indicating the nature
3099 of the way the program terminated. However, this isn't portable,
3100 due to differing exit code conventions. An attempt is made to
3101 return an exit code of the type required by the host operating
3102 system, but because it is constrained to be non-zero, it is not
3103 necessarily possible to indicate every type of exit. It is only
3104 reliable on Unix, where a zero exit code can be augmented with a
3105 set bit that will be ignored. In any case, this function is not
3106 the correct place to acquire an exit code: one should get that from
3107 "perl_destruct".
3108
3109 int perl_run(PerlInterpreter *my_perl)
3110
3111 "PERL_SYS_INIT"
3112 Provides system-specific tune up of the C runtime environment
3113 necessary to run Perl interpreters. This should be called only
3114 once, before creating any Perl interpreters.
3115
3116 void PERL_SYS_INIT(int *argc, char*** argv)
3117
3118 "PERL_SYS_INIT3"
3119 Provides system-specific tune up of the C runtime environment
3120 necessary to run Perl interpreters. This should be called only
3121 once, before creating any Perl interpreters.
3122
3123 void PERL_SYS_INIT3(int *argc, char*** argv, char*** env)
3124
3125 "PERL_SYS_TERM"
3126 Provides system-specific clean up of the C runtime environment
3127 after running Perl interpreters. This should be called only once,
3128 after freeing any remaining Perl interpreters.
3129
3130 void PERL_SYS_TERM()
3131
3132 "PL_exit_flags"
3133 Contains flags controlling perl's behaviour on exit():
3134
3135 • "PERL_EXIT_DESTRUCT_END"
3136
3137 If set, END blocks are executed when the interpreter is
3138 destroyed. This is normally set by perl itself after the
3139 interpreter is constructed.
3140
3141 • "PERL_EXIT_ABORT"
3142
3143 Call "abort()" on exit. This is used internally by perl itself
3144 to abort if exit is called while processing exit.
3145
3146 • "PERL_EXIT_WARN"
3147
3148 Warn on exit.
3149
3150 • "PERL_EXIT_EXPECTED"
3151
3152 Set by the "exit" in perlfunc operator.
3153
3154 U8 PL_exit_flags
3155
3156 "PL_perl_destruct_level"
3157 This value may be set when embedding for full cleanup.
3158
3159 Possible values:
3160
3161 • 0 - none
3162
3163 • 1 - full
3164
3165 • 2 or greater - full with checks.
3166
3167 If $ENV{PERL_DESTRUCT_LEVEL} is set to an integer greater than the
3168 value of "PL_perl_destruct_level" its value is used instead.
3169
3170 On threaded perls, each thread has an independent copy of this
3171 variable; each initialized at creation time with the current value
3172 of the creating thread's copy.
3173
3174 signed char PL_perl_destruct_level
3175
3176 "require_pv"
3177 Tells Perl to "require" the file named by the string argument. It
3178 is analogous to the Perl code "eval "require '$file'"". It's even
3179 implemented that way; consider using load_module instead.
3180
3181 NOTE: the "perl_require_pv()" form is deprecated.
3182
3183 void require_pv(const char* pv)
3184
3185 "UVf"
3186 "DEPRECATED!" It is planned to remove "UVf" from a future release
3187 of Perl. Do not use it for new code; remove it from existing code.
3188
3189 Obsolete form of "UVuf", which you should convert to instead use
3190
3191 const char * UVf
3192
3193 "vload_module"
3194 Like "load_module" but the arguments are an encapsulated argument
3195 list.
3196
3197 void vload_module(U32 flags, SV* name, SV* ver, va_list* args)
3198
3200 "sv_string_from_errnum"
3201 Generates the message string describing an OS error and returns it
3202 as an SV. "errnum" must be a value that "errno" could take,
3203 identifying the type of error.
3204
3205 If "tgtsv" is non-null then the string will be written into that SV
3206 (overwriting existing content) and it will be returned. If "tgtsv"
3207 is a null pointer then the string will be written into a new mortal
3208 SV which will be returned.
3209
3210 The message will be taken from whatever locale would be used by $!,
3211 and will be encoded in the SV in whatever manner would be used by
3212 $!. The details of this process are subject to future change.
3213 Currently, the message is taken from the C locale by default
3214 (usually producing an English message), and from the currently
3215 selected locale when in the scope of the "use locale" pragma. A
3216 heuristic attempt is made to decode the message from the locale's
3217 character encoding, but it will only be decoded as either UTF-8 or
3218 ISO-8859-1. It is always correctly decoded in a UTF-8 locale,
3219 usually in an ISO-8859-1 locale, and never in any other locale.
3220
3221 The SV is always returned containing an actual string, and with no
3222 other OK bits set. Unlike $!, a message is even yielded for
3223 "errnum" zero (meaning success), and if no useful message is
3224 available then a useless string (currently empty) is returned.
3225
3226 SV* sv_string_from_errnum(int errnum, SV* tgtsv)
3227
3229 "dXCPT"
3230 Set up necessary local variables for exception handling. See
3231 "Exception Handling" in perlguts.
3232
3233 dXCPT;
3234
3235 "JMPENV_JUMP"
3236 Described in perlinterp.
3237
3238 void JMPENV_JUMP(int v)
3239
3240 "JMPENV_PUSH"
3241 Described in perlinterp.
3242
3243 void JMPENV_PUSH(int v)
3244
3245 "PL_restartop"
3246 Described in perlinterp.
3247
3248 "XCPT_CATCH"
3249 Introduces a catch block. See "Exception Handling" in perlguts.
3250
3251 "XCPT_RETHROW"
3252 Rethrows a previously caught exception. See "Exception Handling"
3253 in perlguts.
3254
3255 XCPT_RETHROW;
3256
3257 "XCPT_TRY_END"
3258 Ends a try block. See "Exception Handling" in perlguts.
3259
3260 "XCPT_TRY_START"
3261 Starts a try block. See "Exception Handling" in perlguts.
3262
3264 Also see "List of capability HAS_foo symbols".
3265
3266 "DIRNAMLEN"
3267 This symbol, if defined, indicates to the C program that the length
3268 of directory entry names is provided by a "d_namlen" field.
3269 Otherwise you need to do "strlen()" on the "d_name" field.
3270
3271 "DOSUID"
3272 This symbol, if defined, indicates that the C program should check
3273 the script that it is executing for setuid/setgid bits, and attempt
3274 to emulate setuid/setgid on systems that have disabled setuid #!
3275 scripts because the kernel can't do it securely. It is up to the
3276 package designer to make sure that this emulation is done securely.
3277 Among other things, it should do an fstat on the script it just
3278 opened to make sure it really is a setuid/setgid script, it should
3279 make sure the arguments passed correspond exactly to the argument
3280 on the #! line, and it should not trust any subprocesses to which
3281 it must pass the filename rather than the file descriptor of the
3282 script to be executed.
3283
3284 "EOF_NONBLOCK"
3285 This symbol, if defined, indicates to the C program that a "read()"
3286 on a non-blocking file descriptor will return 0 on "EOF", and not
3287 the value held in "RD_NODATA" (-1 usually, in that case!).
3288
3289 "FCNTL_CAN_LOCK"
3290 This symbol, if defined, indicates that "fcntl()" can be used for
3291 file locking. Normally on Unix systems this is defined. It may be
3292 undefined on "VMS".
3293
3294 "FFLUSH_ALL"
3295 This symbol, if defined, tells that to flush all pending stdio
3296 output one must loop through all the stdio file handles stored in
3297 an array and fflush them. Note that if "fflushNULL" is defined,
3298 fflushall will not even be probed for and will be left undefined.
3299
3300 "FFLUSH_NULL"
3301 This symbol, if defined, tells that "fflush(NULL)" correctly
3302 flushes all pending stdio output without side effects. In
3303 particular, on some platforms calling "fflush(NULL)" *still*
3304 corrupts "STDIN" if it is a pipe.
3305
3306 "FILE_base"
3307 This macro is used to access the "_base" field (or equivalent) of
3308 the "FILE" structure pointed to by its argument. This macro will
3309 always be defined if "USE_STDIO_BASE" is defined.
3310
3311 void * FILE_base(FILE * f)
3312
3313 "FILE_bufsiz"
3314 This macro is used to determine the number of bytes in the I/O
3315 buffer pointed to by "_base" field (or equivalent) of the "FILE"
3316 structure pointed to its argument. This macro will always be
3317 defined if "USE_STDIO_BASE" is defined.
3318
3319 Size_t FILE_bufsiz(FILE *f)
3320
3321 "FILE_cnt"
3322 This macro is used to access the "_cnt" field (or equivalent) of
3323 the "FILE" structure pointed to by its argument. This macro will
3324 always be defined if "USE_STDIO_PTR" is defined.
3325
3326 Size_t FILE_cnt(FILE * f)
3327
3328 "FILE_ptr"
3329 This macro is used to access the "_ptr" field (or equivalent) of
3330 the "FILE" structure pointed to by its argument. This macro will
3331 always be defined if "USE_STDIO_PTR" is defined.
3332
3333 void * FILE_ptr(FILE * f)
3334
3335 "FLEXFILENAMES"
3336 This symbol, if defined, indicates that the system supports
3337 filenames longer than 14 characters.
3338
3339 "HAS_DIR_DD_FD"
3340 This symbol, if defined, indicates that the the "DIR"* dirstream
3341 structure contains a member variable named "dd_fd".
3342
3343 "HAS_DUP2"
3344 This symbol, if defined, indicates that the "dup2" routine is
3345 available to duplicate file descriptors.
3346
3347 "HAS_DUP3"
3348 This symbol, if defined, indicates that the "dup3" routine is
3349 available to duplicate file descriptors.
3350
3351 "HAS_FAST_STDIO"
3352 This symbol, if defined, indicates that the "fast stdio" is
3353 available to manipulate the stdio buffers directly.
3354
3355 "HAS_FCHDIR"
3356 This symbol, if defined, indicates that the "fchdir" routine is
3357 available to change directory using a file descriptor.
3358
3359 "HAS_FCNTL"
3360 This symbol, if defined, indicates to the C program that the
3361 "fcntl()" function exists.
3362
3363 "HAS_FDCLOSE"
3364 This symbol, if defined, indicates that the "fdclose" routine is
3365 available to free a "FILE" structure without closing the underlying
3366 file descriptor. This function appeared in "FreeBSD" 10.2.
3367
3368 "HAS_FPATHCONF"
3369 This symbol, if defined, indicates that "pathconf()" is available
3370 to determine file-system related limits and options associated with
3371 a given open file descriptor.
3372
3373 "HAS_FPOS64_T"
3374 This symbol will be defined if the C compiler supports "fpos64_t".
3375
3376 "HAS_FSTATFS"
3377 This symbol, if defined, indicates that the "fstatfs" routine is
3378 available to stat filesystems by file descriptors.
3379
3380 "HAS_FSTATVFS"
3381 This symbol, if defined, indicates that the "fstatvfs" routine is
3382 available to stat filesystems by file descriptors.
3383
3384 "HAS_GETFSSTAT"
3385 This symbol, if defined, indicates that the "getfsstat" routine is
3386 available to stat filesystems in bulk.
3387
3388 "HAS_GETMNT"
3389 This symbol, if defined, indicates that the "getmnt" routine is
3390 available to get filesystem mount info by filename.
3391
3392 "HAS_GETMNTENT"
3393 This symbol, if defined, indicates that the "getmntent" routine is
3394 available to iterate through mounted file systems to get their
3395 info.
3396
3397 "HAS_HASMNTOPT"
3398 This symbol, if defined, indicates that the "hasmntopt" routine is
3399 available to query the mount options of file systems.
3400
3401 "HAS_LSEEK_PROTO"
3402 This symbol, if defined, indicates that the system provides a
3403 prototype for the "lseek()" function. Otherwise, it is up to the
3404 program to supply one. A good guess is
3405
3406 extern off_t lseek(int, off_t, int);
3407
3408 "HAS_MKDIR"
3409 This symbol, if defined, indicates that the "mkdir" routine is
3410 available to create directories. Otherwise you should fork off a
3411 new process to exec /bin/mkdir.
3412
3413 "HAS_OFF64_T"
3414 This symbol will be defined if the C compiler supports "off64_t".
3415
3416 "HAS_OPEN3"
3417 This manifest constant lets the C program know that the three
3418 argument form of open(2) is available.
3419
3420 "HAS_OPENAT"
3421 This symbol is defined if the "openat()" routine is available.
3422
3423 "HAS_POLL"
3424 This symbol, if defined, indicates that the "poll" routine is
3425 available to "poll" active file descriptors. Please check "I_POLL"
3426 and "I_SYS_POLL" to know which header should be included as well.
3427
3428 "HAS_READDIR"
3429 This symbol, if defined, indicates that the "readdir" routine is
3430 available to read directory entries. You may have to include
3431 dirent.h. See "I_DIRENT".
3432
3433 "HAS_READDIR64_R"
3434 This symbol, if defined, indicates that the "readdir64_r" routine
3435 is available to readdir64 re-entrantly.
3436
3437 "HAS_REWINDDIR"
3438 This symbol, if defined, indicates that the "rewinddir" routine is
3439 available. You may have to include dirent.h. See "I_DIRENT".
3440
3441 "HAS_RMDIR"
3442 This symbol, if defined, indicates that the "rmdir" routine is
3443 available to remove directories. Otherwise you should fork off a
3444 new process to exec /bin/rmdir.
3445
3446 "HAS_SEEKDIR"
3447 This symbol, if defined, indicates that the "seekdir" routine is
3448 available. You may have to include dirent.h. See "I_DIRENT".
3449
3450 "HAS_SELECT"
3451 This symbol, if defined, indicates that the "select" routine is
3452 available to "select" active file descriptors. If the timeout field
3453 is used, sys/time.h may need to be included.
3454
3455 "HAS_SETVBUF"
3456 This symbol, if defined, indicates that the "setvbuf" routine is
3457 available to change buffering on an open stdio stream. to a line-
3458 buffered mode.
3459
3460 "HAS_STDIO_STREAM_ARRAY"
3461 This symbol, if defined, tells that there is an array holding the
3462 stdio streams.
3463
3464 "HAS_STRUCT_FS_DATA"
3465 This symbol, if defined, indicates that the "struct fs_data" to do
3466 "statfs()" is supported.
3467
3468 "HAS_STRUCT_STATFS"
3469 This symbol, if defined, indicates that the "struct statfs" to do
3470 "statfs()" is supported.
3471
3472 "HAS_STRUCT_STATFS_F_FLAGS"
3473 This symbol, if defined, indicates that the "struct statfs" does
3474 have the "f_flags" member containing the mount flags of the
3475 filesystem containing the file. This kind of "struct statfs" is
3476 coming from sys/mount.h ("BSD" 4.3), not from sys/statfs.h
3477 ("SYSV"). Older "BSDs" (like Ultrix) do not have "statfs()" and
3478 "struct statfs", they have "ustat()" and "getmnt()" with "struct
3479 ustat" and "struct fs_data".
3480
3481 "HAS_TELLDIR"
3482 This symbol, if defined, indicates that the "telldir" routine is
3483 available. You may have to include dirent.h. See "I_DIRENT".
3484
3485 "HAS_USTAT"
3486 This symbol, if defined, indicates that the "ustat" system call is
3487 available to query file system statistics by "dev_t".
3488
3489 "I_FCNTL"
3490 This manifest constant tells the C program to include fcntl.h.
3491
3492 #ifdef I_FCNTL
3493 #include <fcntl.h>
3494 #endif
3495
3496 "I_SYS_DIR"
3497 This symbol, if defined, indicates to the C program that it should
3498 include sys/dir.h.
3499
3500 #ifdef I_SYS_DIR
3501 #include <sys_dir.h>
3502 #endif
3503
3504 "I_SYS_FILE"
3505 This symbol, if defined, indicates to the C program that it should
3506 include sys/file.h to get definition of "R_OK" and friends.
3507
3508 #ifdef I_SYS_FILE
3509 #include <sys_file.h>
3510 #endif
3511
3512 "I_SYS_NDIR"
3513 This symbol, if defined, indicates to the C program that it should
3514 include sys/ndir.h.
3515
3516 #ifdef I_SYS_NDIR
3517 #include <sys_ndir.h>
3518 #endif
3519
3520 "I_SYS_STATFS"
3521 This symbol, if defined, indicates that sys/statfs.h exists.
3522
3523 #ifdef I_SYS_STATFS
3524 #include <sys_statfs.h>
3525 #endif
3526
3527 "LSEEKSIZE"
3528 This symbol holds the number of bytes used by the "Off_t".
3529
3530 "RD_NODATA"
3531 This symbol holds the return code from "read()" when no data is
3532 present on the non-blocking file descriptor. Be careful! If
3533 "EOF_NONBLOCK" is not defined, then you can't distinguish between
3534 no data and "EOF" by issuing a "read()". You'll have to find
3535 another way to tell for sure!
3536
3537 "READDIR64_R_PROTO"
3538 This symbol encodes the prototype of "readdir64_r". It is zero if
3539 "d_readdir64_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
3540 macros of reentr.h if "d_readdir64_r" is defined.
3541
3542 "STDCHAR"
3543 This symbol is defined to be the type of char used in stdio.h. It
3544 has the values "unsigned char" or "char".
3545
3546 "STDIO_CNT_LVALUE"
3547 This symbol is defined if the "FILE_cnt" macro can be used as an
3548 lvalue.
3549
3550 "STDIO_PTR_LVALUE"
3551 This symbol is defined if the "FILE_ptr" macro can be used as an
3552 lvalue.
3553
3554 "STDIO_PTR_LVAL_NOCHANGE_CNT"
3555 This symbol is defined if using the "FILE_ptr" macro as an lvalue
3556 to increase the pointer by n leaves "File_cnt(fp)" unchanged.
3557
3558 "STDIO_PTR_LVAL_SETS_CNT"
3559 This symbol is defined if using the "FILE_ptr" macro as an lvalue
3560 to increase the pointer by n has the side effect of decreasing the
3561 value of "File_cnt(fp)" by n.
3562
3563 "STDIO_STREAM_ARRAY"
3564 This symbol tells the name of the array holding the stdio streams.
3565 Usual values include "_iob", "__iob", and "__sF".
3566
3567 "ST_INO_SIGN"
3568 This symbol holds the signedness of "struct stat"'s "st_ino". 1
3569 for unsigned, -1 for signed.
3570
3571 "ST_INO_SIZE"
3572 This variable contains the size of "struct stat"'s "st_ino" in
3573 bytes.
3574
3575 "VAL_EAGAIN"
3576 This symbol holds the errno error code set by "read()" when no data
3577 was present on the non-blocking file descriptor.
3578
3579 "VAL_O_NONBLOCK"
3580 This symbol is to be used during "open()" or "fcntl(F_SETFL)" to
3581 turn on non-blocking I/O for the file descriptor. Note that there
3582 is no way back, i.e. you cannot turn it blocking again this way. If
3583 you wish to alternatively switch between blocking and non-blocking,
3584 use the "ioctl(FIOSNBIO)" call instead, but that is not supported
3585 by all devices.
3586
3587 "VOID_CLOSEDIR"
3588 This symbol, if defined, indicates that the "closedir()" routine
3589 does not return a value.
3590
3592 Also "List of capability HAS_foo symbols" lists capabilities that arent
3593 in this section. For example "HAS_ASINH", for the hyperbolic sine
3594 function.
3595
3596 "CASTFLAGS"
3597 This symbol contains flags that say what difficulties the compiler
3598 has casting odd floating values to unsigned long:
3599
3600 0 = ok
3601 1 = couldn't cast < 0
3602 2 = couldn't cast >= 0x80000000
3603 4 = couldn't cast in argument expression list
3604
3605 "CASTNEGFLOAT"
3606 This symbol is defined if the C compiler can cast negative numbers
3607 to unsigned longs, ints and shorts.
3608
3609 "DOUBLE_HAS_INF"
3610 This symbol, if defined, indicates that the double has the
3611 infinity.
3612
3613 "DOUBLE_HAS_NAN"
3614 This symbol, if defined, indicates that the double has the not-a-
3615 number.
3616
3617 "DOUBLE_HAS_NEGATIVE_ZERO"
3618 This symbol, if defined, indicates that the double has the
3619 "negative_zero".
3620
3621 "DOUBLE_HAS_SUBNORMALS"
3622 This symbol, if defined, indicates that the double has the
3623 subnormals (denormals).
3624
3625 "DOUBLEINFBYTES"
3626 This symbol, if defined, is a comma-separated list of hexadecimal
3627 bytes for the double precision infinity.
3628
3629 "DOUBLEKIND"
3630 "DOUBLEKIND" will be one of
3631 "DOUBLE_IS_IEEE_754_32_BIT_LITTLE_ENDIAN"
3632 "DOUBLE_IS_IEEE_754_32_BIT_BIG_ENDIAN"
3633 "DOUBLE_IS_IEEE_754_64_BIT_LITTLE_ENDIAN"
3634 "DOUBLE_IS_IEEE_754_64_BIT_BIG_ENDIAN"
3635 "DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN"
3636 "DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN"
3637 "DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_LE_BE"
3638 "DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_BE_LE"
3639 "DOUBLE_IS_VAX_F_FLOAT" "DOUBLE_IS_VAX_D_FLOAT"
3640 "DOUBLE_IS_VAX_G_FLOAT" "DOUBLE_IS_IBM_SINGLE_32_BIT"
3641 "DOUBLE_IS_IBM_DOUBLE_64_BIT" "DOUBLE_IS_CRAY_SINGLE_64_BIT"
3642 "DOUBLE_IS_UNKNOWN_FORMAT"
3643
3644 "DOUBLEMANTBITS"
3645 This symbol, if defined, tells how many mantissa bits there are in
3646 double precision floating point format. Note that this is usually
3647 "DBL_MANT_DIG" minus one, since with the standard "IEEE" 754
3648 formats "DBL_MANT_DIG" includes the implicit bit, which doesn't
3649 really exist.
3650
3651 "DOUBLENANBYTES"
3652 This symbol, if defined, is a comma-separated list of hexadecimal
3653 bytes (0xHH) for the double precision not-a-number.
3654
3655 "DOUBLESIZE"
3656 This symbol contains the size of a double, so that the C
3657 preprocessor can make decisions based on it.
3658
3659 "DOUBLE_STYLE_CRAY"
3660 This symbol, if defined, indicates that the double is the 64-bit
3661 "CRAY" mainframe format.
3662
3663 "DOUBLE_STYLE_IBM"
3664 This symbol, if defined, indicates that the double is the 64-bit
3665 "IBM" mainframe format.
3666
3667 "DOUBLE_STYLE_IEEE"
3668 This symbol, if defined, indicates that the double is the 64-bit
3669 "IEEE" 754.
3670
3671 "DOUBLE_STYLE_VAX"
3672 This symbol, if defined, indicates that the double is the 64-bit
3673 "VAX" format D or G.
3674
3675 "HAS_ATOLF"
3676 This symbol, if defined, indicates that the "atolf" routine is
3677 available to convert strings into long doubles.
3678
3679 "HAS_CLASS"
3680 This symbol, if defined, indicates that the "class" routine is
3681 available to classify doubles. Available for example in "AIX".
3682 The returned values are defined in float.h and are:
3683
3684 FP_PLUS_NORM Positive normalized, nonzero
3685 FP_MINUS_NORM Negative normalized, nonzero
3686 FP_PLUS_DENORM Positive denormalized, nonzero
3687 FP_MINUS_DENORM Negative denormalized, nonzero
3688 FP_PLUS_ZERO +0.0
3689 FP_MINUS_ZERO -0.0
3690 FP_PLUS_INF +INF
3691 FP_MINUS_INF -INF
3692 FP_NANS Signaling Not a Number (NaNS)
3693 FP_NANQ Quiet Not a Number (NaNQ)
3694
3695 "HAS_FINITE"
3696 This symbol, if defined, indicates that the "finite" routine is
3697 available to check whether a double is "finite" (non-infinity non-
3698 NaN).
3699
3700 "HAS_FINITEL"
3701 This symbol, if defined, indicates that the "finitel" routine is
3702 available to check whether a long double is finite (non-infinity
3703 non-NaN).
3704
3705 "HAS_FPCLASS"
3706 This symbol, if defined, indicates that the "fpclass" routine is
3707 available to classify doubles. Available for example in
3708 Solaris/"SVR4". The returned values are defined in ieeefp.h and
3709 are:
3710
3711 FP_SNAN signaling NaN
3712 FP_QNAN quiet NaN
3713 FP_NINF negative infinity
3714 FP_PINF positive infinity
3715 FP_NDENORM negative denormalized non-zero
3716 FP_PDENORM positive denormalized non-zero
3717 FP_NZERO negative zero
3718 FP_PZERO positive zero
3719 FP_NNORM negative normalized non-zero
3720 FP_PNORM positive normalized non-zero
3721
3722 "HAS_FPCLASSIFY"
3723 This symbol, if defined, indicates that the "fpclassify" routine is
3724 available to classify doubles. Available for example in HP-UX.
3725 The returned values are defined in math.h and are
3726
3727 FP_NORMAL Normalized
3728 FP_ZERO Zero
3729 FP_INFINITE Infinity
3730 FP_SUBNORMAL Denormalized
3731 FP_NAN NaN
3732
3733 "HAS_FPCLASSL"
3734 This symbol, if defined, indicates that the "fpclassl" routine is
3735 available to classify long doubles. Available for example in
3736 "IRIX". The returned values are defined in ieeefp.h and are:
3737
3738 FP_SNAN signaling NaN
3739 FP_QNAN quiet NaN
3740 FP_NINF negative infinity
3741 FP_PINF positive infinity
3742 FP_NDENORM negative denormalized non-zero
3743 FP_PDENORM positive denormalized non-zero
3744 FP_NZERO negative zero
3745 FP_PZERO positive zero
3746 FP_NNORM negative normalized non-zero
3747 FP_PNORM positive normalized non-zero
3748
3749 "HAS_FPGETROUND"
3750 This symbol, if defined, indicates that the "fpgetround" routine is
3751 available to get the floating point rounding mode.
3752
3753 "HAS_FP_CLASS"
3754 This symbol, if defined, indicates that the "fp_class" routine is
3755 available to classify doubles. Available for example in Digital
3756 "UNIX". The returned values are defined in math.h and are:
3757
3758 FP_SNAN Signaling NaN (Not-a-Number)
3759 FP_QNAN Quiet NaN (Not-a-Number)
3760 FP_POS_INF +infinity
3761 FP_NEG_INF -infinity
3762 FP_POS_NORM Positive normalized
3763 FP_NEG_NORM Negative normalized
3764 FP_POS_DENORM Positive denormalized
3765 FP_NEG_DENORM Negative denormalized
3766 FP_POS_ZERO +0.0 (positive zero)
3767 FP_NEG_ZERO -0.0 (negative zero)
3768
3769 "HAS_FP_CLASSIFY"
3770 This symbol, if defined, indicates that the "fp_classify" routine
3771 is available to classify doubles. The values are defined in math.h
3772
3773 FP_NORMAL Normalized
3774 FP_ZERO Zero
3775 FP_INFINITE Infinity
3776 FP_SUBNORMAL Denormalized
3777 FP_NAN NaN
3778
3779 "HAS_FP_CLASSL"
3780 This symbol, if defined, indicates that the "fp_classl" routine is
3781 available to classify long doubles. Available for example in
3782 Digital "UNIX". See for possible values "HAS_FP_CLASS".
3783
3784 "HAS_FREXPL"
3785 This symbol, if defined, indicates that the "frexpl" routine is
3786 available to break a long double floating-point number into a
3787 normalized fraction and an integral power of 2.
3788
3789 "HAS_ILOGB"
3790 This symbol, if defined, indicates that the "ilogb" routine is
3791 available to get integer exponent of a floating-point value.
3792
3793 "HAS_ISFINITE"
3794 This symbol, if defined, indicates that the "isfinite" routine is
3795 available to check whether a double is finite (non-infinity non-
3796 NaN).
3797
3798 "HAS_ISFINITEL"
3799 This symbol, if defined, indicates that the "isfinitel" routine is
3800 available to check whether a long double is finite. (non-infinity
3801 non-NaN).
3802
3803 "HAS_ISINF"
3804 This symbol, if defined, indicates that the "isinf" routine is
3805 available to check whether a double is an infinity.
3806
3807 "HAS_ISINFL"
3808 This symbol, if defined, indicates that the "isinfl" routine is
3809 available to check whether a long double is an infinity.
3810
3811 "HAS_ISNAN"
3812 This symbol, if defined, indicates that the "isnan" routine is
3813 available to check whether a double is a NaN.
3814
3815 "HAS_ISNANL"
3816 This symbol, if defined, indicates that the "isnanl" routine is
3817 available to check whether a long double is a NaN.
3818
3819 "HAS_ISNORMAL"
3820 This symbol, if defined, indicates that the "isnormal" routine is
3821 available to check whether a double is normal (non-zero
3822 normalized).
3823
3824 "HAS_J0"
3825 This symbol, if defined, indicates to the C program that the "j0()"
3826 function is available for Bessel functions of the first kind of the
3827 order zero, for doubles.
3828
3829 "HAS_J0L"
3830 This symbol, if defined, indicates to the C program that the
3831 "j0l()" function is available for Bessel functions of the first
3832 kind of the order zero, for long doubles.
3833
3834 "HAS_LDBL_DIG"
3835 This symbol, if defined, indicates that this system's float.h or
3836 limits.h defines the symbol "LDBL_DIG", which is the number of
3837 significant digits in a long double precision number. Unlike for
3838 "DBL_DIG", there's no good guess for "LDBL_DIG" if it is undefined.
3839
3840 "HAS_LDEXPL"
3841 This symbol, if defined, indicates that the "ldexpl" routine is
3842 available to shift a long double floating-point number by an
3843 integral power of 2.
3844
3845 "HAS_LLRINT"
3846 This symbol, if defined, indicates that the "llrint" routine is
3847 available to return the long long value closest to a double
3848 (according to the current rounding mode).
3849
3850 "HAS_LLRINTL"
3851 This symbol, if defined, indicates that the "llrintl" routine is
3852 available to return the long long value closest to a long double
3853 (according to the current rounding mode).
3854
3855 "HAS_LLROUNDL"
3856 This symbol, if defined, indicates that the "llroundl" routine is
3857 available to return the nearest long long value away from zero of
3858 the long double argument value.
3859
3860 "HAS_LONG_DOUBLE"
3861 This symbol will be defined if the C compiler supports long
3862 doubles.
3863
3864 "HAS_LRINT"
3865 This symbol, if defined, indicates that the "lrint" routine is
3866 available to return the integral value closest to a double
3867 (according to the current rounding mode).
3868
3869 "HAS_LRINTL"
3870 This symbol, if defined, indicates that the "lrintl" routine is
3871 available to return the integral value closest to a long double
3872 (according to the current rounding mode).
3873
3874 "HAS_LROUNDL"
3875 This symbol, if defined, indicates that the "lroundl" routine is
3876 available to return the nearest integral value away from zero of
3877 the long double argument value.
3878
3879 "HAS_MODFL"
3880 This symbol, if defined, indicates that the "modfl" routine is
3881 available to split a long double x into a fractional part f and an
3882 integer part i such that |f| < 1.0 and (f + i) = x.
3883
3884 "HAS_NAN"
3885 This symbol, if defined, indicates that the "nan" routine is
3886 available to generate NaN.
3887
3888 "HAS_NEXTTOWARD"
3889 This symbol, if defined, indicates that the "nexttoward" routine is
3890 available to return the next machine representable long double from
3891 x in direction y.
3892
3893 "HAS_REMAINDER"
3894 This symbol, if defined, indicates that the "remainder" routine is
3895 available to return the floating-point "remainder".
3896
3897 "HAS_SCALBN"
3898 This symbol, if defined, indicates that the "scalbn" routine is
3899 available to multiply floating-point number by integral power of
3900 radix.
3901
3902 "HAS_SIGNBIT"
3903 This symbol, if defined, indicates that the "signbit" routine is
3904 available to check if the given number has the sign bit set. This
3905 should include correct testing of -0.0. This will only be set if
3906 the "signbit()" routine is safe to use with the NV type used
3907 internally in perl. Users should call "Perl_signbit()", which will
3908 be #defined to the system's "signbit()" function or macro if this
3909 symbol is defined.
3910
3911 "HAS_SQRTL"
3912 This symbol, if defined, indicates that the "sqrtl" routine is
3913 available to do long double square roots.
3914
3915 "HAS_STRTOD_L"
3916 This symbol, if defined, indicates that the "strtod_l" routine is
3917 available to convert strings to long doubles.
3918
3919 "HAS_STRTOLD"
3920 This symbol, if defined, indicates that the "strtold" routine is
3921 available to convert strings to long doubles.
3922
3923 "HAS_STRTOLD_L"
3924 This symbol, if defined, indicates that the "strtold_l" routine is
3925 available to convert strings to long doubles.
3926
3927 "HAS_TRUNC"
3928 This symbol, if defined, indicates that the "trunc" routine is
3929 available to round doubles towards zero.
3930
3931 "HAS_UNORDERED"
3932 This symbol, if defined, indicates that the "unordered" routine is
3933 available to check whether two doubles are "unordered"
3934 (effectively: whether either of them is NaN)
3935
3936 "I_FENV"
3937 This symbol, if defined, indicates to the C program that it should
3938 include fenv.h to get the floating point environment definitions.
3939
3940 #ifdef I_FENV
3941 #include <fenv.h>
3942 #endif
3943
3944 "I_QUADMATH"
3945 This symbol, if defined, indicates that quadmath.h exists and
3946 should be included.
3947
3948 #ifdef I_QUADMATH
3949 #include <quadmath.h>
3950 #endif
3951
3952 "LONGDBLINFBYTES"
3953 This symbol, if defined, is a comma-separated list of hexadecimal
3954 bytes for the long double precision infinity.
3955
3956 "LONGDBLMANTBITS"
3957 This symbol, if defined, tells how many mantissa bits there are in
3958 long double precision floating point format. Note that this can be
3959 "LDBL_MANT_DIG" minus one, since "LDBL_MANT_DIG" can include the
3960 "IEEE" 754 implicit bit. The common x86-style 80-bit long double
3961 does not have an implicit bit.
3962
3963 "LONGDBLNANBYTES"
3964 This symbol, if defined, is a comma-separated list of hexadecimal
3965 bytes (0xHH) for the long double precision not-a-number.
3966
3967 "LONG_DOUBLEKIND"
3968 "LONG_DOUBLEKIND" will be one of "LONG_DOUBLE_IS_DOUBLE"
3969 "LONG_DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN"
3970 "LONG_DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN"
3971 "LONG_DOUBLE_IS_X86_80_BIT_LITTLE_ENDIAN"
3972 "LONG_DOUBLE_IS_X86_80_BIT_BIG_ENDIAN"
3973 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_LE"
3974 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_BE"
3975 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_BE"
3976 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_LE"
3977 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LITTLE_ENDIAN"
3978 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BIG_ENDIAN"
3979 "LONG_DOUBLE_IS_VAX_H_FLOAT" "LONG_DOUBLE_IS_UNKNOWN_FORMAT" It is
3980 only defined if the system supports long doubles.
3981
3982 "LONG_DOUBLESIZE"
3983 This symbol contains the size of a long double, so that the C
3984 preprocessor can make decisions based on it. It is only defined if
3985 the system supports long doubles. Note that this is "sizeof(long
3986 double)", which may include unused bytes.
3987
3988 "LONG_DOUBLE_STYLE_IEEE"
3989 This symbol, if defined, indicates that the long double is any of
3990 the "IEEE" 754 style long doubles: "LONG_DOUBLE_STYLE_IEEE_STD",
3991 "LONG_DOUBLE_STYLE_IEEE_EXTENDED",
3992 "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE".
3993
3994 "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
3995 This symbol, if defined, indicates that the long double is the
3996 128-bit double-double.
3997
3998 "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
3999 This symbol, if defined, indicates that the long double is the
4000 80-bit "IEEE" 754. Note that despite the 'extended' this is less
4001 than the 'std', since this is an extension of the double precision.
4002
4003 "LONG_DOUBLE_STYLE_IEEE_STD"
4004 This symbol, if defined, indicates that the long double is the
4005 128-bit "IEEE" 754.
4006
4007 "LONG_DOUBLE_STYLE_VAX"
4008 This symbol, if defined, indicates that the long double is the
4009 128-bit "VAX" format H.
4010
4011 "NVMANTBITS"
4012 This symbol, if defined, tells how many mantissa bits (not
4013 including implicit bit) there are in a Perl NV. This depends on
4014 which floating point type was chosen.
4015
4016 "NV_OVERFLOWS_INTEGERS_AT"
4017 This symbol gives the largest integer value that NVs can hold. This
4018 value + 1.0 cannot be stored accurately. It is expressed as
4019 constant floating point expression to reduce the chance of
4020 decimal/binary conversion issues. If it can not be determined, the
4021 value 0 is given.
4022
4023 "NV_PRESERVES_UV"
4024 This symbol, if defined, indicates that a variable of type "NVTYPE"
4025 can preserve all the bits of a variable of type "UVTYPE".
4026
4027 "NV_PRESERVES_UV_BITS"
4028 This symbol contains the number of bits a variable of type "NVTYPE"
4029 can preserve of a variable of type "UVTYPE".
4030
4031 "NVSIZE"
4032 This symbol contains the "sizeof(NV)". Note that some floating
4033 point formats have unused bytes. The most notable example is the
4034 x86* 80-bit extended precision which comes in byte sizes of 12 and
4035 16 (for 32 and 64 bit platforms, respectively), but which only uses
4036 10 bytes. Perl compiled with "-Duselongdouble" on x86* is like
4037 this.
4038
4039 "NVTYPE"
4040 This symbol defines the C type used for Perl's NV.
4041
4042 "NV_ZERO_IS_ALLBITS_ZERO"
4043 This symbol, if defined, indicates that a variable of type "NVTYPE"
4044 stores 0.0 in memory as all bits zero.
4045
4047 These are used for formatting the corresponding type For example,
4048 instead of saying
4049
4050 Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\n", iv);
4051
4052 use
4053
4054 Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\n", iv);
4055
4056 This keeps you from having to know if, say an IV, needs to be printed
4057 as %d, %ld, or something else.
4058
4059 "IVdf"
4060 This symbol defines the format string used for printing a Perl IV
4061 as a signed decimal integer.
4062
4063 "NVef"
4064 This symbol defines the format string used for printing a Perl NV
4065 using %e-ish floating point format.
4066
4067 "NVff"
4068 This symbol defines the format string used for printing a Perl NV
4069 using %f-ish floating point format.
4070
4071 "NVgf"
4072 This symbol defines the format string used for printing a Perl NV
4073 using %g-ish floating point format.
4074
4075 "PERL_PRIeldbl"
4076 This symbol, if defined, contains the string used by stdio to
4077 format long doubles (format 'e') for output.
4078
4079 "PERL_PRIfldbl"
4080 This symbol, if defined, contains the string used by stdio to
4081 format long doubles (format 'f') for output.
4082
4083 "PERL_PRIgldbl"
4084 This symbol, if defined, contains the string used by stdio to
4085 format long doubles (format 'g') for output.
4086
4087 "PERL_SCNfldbl"
4088 This symbol, if defined, contains the string used by stdio to
4089 format long doubles (format 'f') for input.
4090
4091 "PRINTF_FORMAT_NULL_OK"
4092 Allows "__printf__" format to be null when checking printf-style
4093
4094 "UTF8f"
4095 Described in perlguts.
4096
4097 "UTF8fARG"
4098 Described in perlguts.
4099
4100 UTF8fARG(bool is_utf8, Size_t byte_len, char *str)
4101
4102 "UVof"
4103 This symbol defines the format string used for printing a Perl UV
4104 as an unsigned octal integer.
4105
4106 "UVuf"
4107 This symbol defines the format string used for printing a Perl UV
4108 as an unsigned decimal integer.
4109
4110 "UVXf"
4111 This symbol defines the format string used for printing a Perl UV
4112 as an unsigned hexadecimal integer in uppercase "ABCDEF".
4113
4114 "UVxf"
4115 This symbol defines the format string used for printing a Perl UV
4116 as an unsigned hexadecimal integer in lowercase abcdef.
4117
4119 This section contains configuration information not otherwise found in
4120 the more specialized sections of this document. At the end is a list
4121 of "#defines" whose name should be enough to tell you what they do, and
4122 a list of #defines which tell you if you need to "#include" files to
4123 get the corresponding functionality.
4124
4125 "BYTEORDER"
4126 This symbol holds the hexadecimal constant defined in byteorder, in
4127 a UV, i.e. 0x1234 or 0x4321 or 0x12345678, etc... If the compiler
4128 supports cross-compiling or multiple-architecture binaries, use
4129 compiler-defined macros to determine the byte order.
4130
4131 "CHARBITS"
4132 This symbol contains the size of a char, so that the C preprocessor
4133 can make decisions based on it.
4134
4135 "DB_VERSION_MAJOR_CFG"
4136 This symbol, if defined, defines the major version number of
4137 Berkeley DB found in the db.h header when Perl was configured.
4138
4139 "DB_VERSION_MINOR_CFG"
4140 This symbol, if defined, defines the minor version number of
4141 Berkeley DB found in the db.h header when Perl was configured. For
4142 DB version 1 this is always 0.
4143
4144 "DB_VERSION_PATCH_CFG"
4145 This symbol, if defined, defines the patch version number of
4146 Berkeley DB found in the db.h header when Perl was configured. For
4147 DB version 1 this is always 0.
4148
4149 "DEFAULT_INC_EXCLUDES_DOT"
4150 This symbol, if defined, removes the legacy default behavior of
4151 including '.' at the end of @"INC".
4152
4153 "DLSYM_NEEDS_UNDERSCORE"
4154 This symbol, if defined, indicates that we need to prepend an
4155 underscore to the symbol name before calling "dlsym()". This only
4156 makes sense if you *have* dlsym, which we will presume is the case
4157 if you're using dl_dlopen.xs.
4158
4159 "EBCDIC"
4160 This symbol, if defined, indicates that this system uses "EBCDIC"
4161 encoding.
4162
4163 "HAS_CSH"
4164 This symbol, if defined, indicates that the C-shell exists.
4165
4166 "HAS_GETHOSTNAME"
4167 This symbol, if defined, indicates that the C program may use the
4168 "gethostname()" routine to derive the host name. See also
4169 "HAS_UNAME" and "PHOSTNAME".
4170
4171 "HAS_GNULIBC"
4172 This symbol, if defined, indicates to the C program that the "GNU"
4173 C library is being used. A better check is to use the "__GLIBC__"
4174 and "__GLIBC_MINOR__" symbols supplied with glibc.
4175
4176 "HAS_LGAMMA"
4177 This symbol, if defined, indicates that the "lgamma" routine is
4178 available to do the log gamma function. See also "HAS_TGAMMA" and
4179 "HAS_LGAMMA_R".
4180
4181 "HAS_LGAMMA_R"
4182 This symbol, if defined, indicates that the "lgamma_r" routine is
4183 available to do the log gamma function without using the global
4184 signgam variable.
4185
4186 "HAS_PRCTL_SET_NAME"
4187 This symbol, if defined, indicates that the prctl routine is
4188 available to set process title and supports "PR_SET_NAME".
4189
4190 "HAS_PROCSELFEXE"
4191 This symbol is defined if "PROCSELFEXE_PATH" is a symlink to the
4192 absolute pathname of the executing program.
4193
4194 "HAS_PSEUDOFORK"
4195 This symbol, if defined, indicates that an emulation of the fork
4196 routine is available.
4197
4198 "HAS_REGCOMP"
4199 This symbol, if defined, indicates that the "regcomp()" routine is
4200 available to do some regular pattern matching (usually on "POSIX".2
4201 conforming systems).
4202
4203 "HAS_SETPGID"
4204 This symbol, if defined, indicates that the "setpgid(pid, gpid)"
4205 routine is available to set process group ID.
4206
4207 "HAS_SIGSETJMP"
4208 This variable indicates to the C program that the "sigsetjmp()"
4209 routine is available to save the calling process's registers and
4210 stack environment for later use by "siglongjmp()", and to
4211 optionally save the process's signal mask. See "Sigjmp_buf",
4212 "Sigsetjmp", and "Siglongjmp".
4213
4214 "HAS_STRUCT_CMSGHDR"
4215 This symbol, if defined, indicates that the "struct cmsghdr" is
4216 supported.
4217
4218 "HAS_STRUCT_MSGHDR"
4219 This symbol, if defined, indicates that the "struct msghdr" is
4220 supported.
4221
4222 "HAS_TGAMMA"
4223 This symbol, if defined, indicates that the "tgamma" routine is
4224 available to do the gamma function. See also "HAS_LGAMMA".
4225
4226 "HAS_UNAME"
4227 This symbol, if defined, indicates that the C program may use the
4228 "uname()" routine to derive the host name. See also
4229 "HAS_GETHOSTNAME" and "PHOSTNAME".
4230
4231 "HAS_UNION_SEMUN"
4232 This symbol, if defined, indicates that the "union semun" is
4233 defined by including sys/sem.h. If not, the user code probably
4234 needs to define it as:
4235
4236 union semun {
4237 int val;
4238 struct semid_ds *buf;
4239 unsigned short *array;
4240 }
4241
4242 "I_DIRENT"
4243 This symbol, if defined, indicates to the C program that it should
4244 include dirent.h. Using this symbol also triggers the definition of
4245 the "Direntry_t" define which ends up being '"struct dirent"' or
4246 '"struct direct"' depending on the availability of dirent.h.
4247
4248 #ifdef I_DIRENT
4249 #include <dirent.h>
4250 #endif
4251
4252 "I_POLL"
4253 This symbol, if defined, indicates that poll.h exists and should be
4254 included. (see also "HAS_POLL")
4255
4256 #ifdef I_POLL
4257 #include <poll.h>
4258 #endif
4259
4260 "I_SYS_RESOURCE"
4261 This symbol, if defined, indicates to the C program that it should
4262 include sys/resource.h.
4263
4264 #ifdef I_SYS_RESOURCE
4265 #include <sys_resource.h>
4266 #endif
4267
4268 "LIBM_LIB_VERSION"
4269 This symbol, if defined, indicates that libm exports "_LIB_VERSION"
4270 and that math.h defines the enum to manipulate it.
4271
4272 "NEED_VA_COPY"
4273 This symbol, if defined, indicates that the system stores the
4274 variable argument list datatype, "va_list", in a format that cannot
4275 be copied by simple assignment, so that some other means must be
4276 used when copying is required. As such systems vary in their
4277 provision (or non-provision) of copying mechanisms, handy.h defines
4278 a platform- independent macro, "Perl_va_copy(src, dst)", to do the
4279 job.
4280
4281 "OSNAME"
4282 This symbol contains the name of the operating system, as
4283 determined by Configure. You shouldn't rely on it too much; the
4284 specific feature tests from Configure are generally more reliable.
4285
4286 "OSVERS"
4287 This symbol contains the version of the operating system, as
4288 determined by Configure. You shouldn't rely on it too much; the
4289 specific feature tests from Configure are generally more reliable.
4290
4291 "PHOSTNAME"
4292 This symbol, if defined, indicates the command to feed to the
4293 "popen()" routine to derive the host name. See also
4294 "HAS_GETHOSTNAME" and "HAS_UNAME". Note that the command uses a
4295 fully qualified path, so that it is safe even if used by a process
4296 with super-user privileges.
4297
4298 "PROCSELFEXE_PATH"
4299 If "HAS_PROCSELFEXE" is defined this symbol is the filename of the
4300 symbolic link pointing to the absolute pathname of the executing
4301 program.
4302
4303 "PTRSIZE"
4304 This symbol contains the size of a pointer, so that the C
4305 preprocessor can make decisions based on it. It will be
4306 "sizeof(void *)" if the compiler supports (void *); otherwise it
4307 will be "sizeof(char *)".
4308
4309 "RANDBITS"
4310 This symbol indicates how many bits are produced by the function
4311 used to generate normalized random numbers. Values include 15, 16,
4312 31, and 48.
4313
4314 "SELECT_MIN_BITS"
4315 This symbol holds the minimum number of bits operated by select.
4316 That is, if you do "select(n, ...)", how many bits at least will be
4317 cleared in the masks if some activity is detected. Usually this is
4318 either n or 32*"ceil(n/32)", especially many little-endians do the
4319 latter. This is only useful if you have "select()", naturally.
4320
4321 "SETUID_SCRIPTS_ARE_SECURE_NOW"
4322 This symbol, if defined, indicates that the bug that prevents
4323 setuid scripts from being secure is not present in this kernel.
4324
4325 List of capability "HAS_foo" symbols
4326 This is a list of those symbols that dont appear elsewhere in ths
4327 document that indicate if the current platform has a certain
4328 capability. Their names all begin with "HAS_". Only those symbols
4329 whose capability is directly derived from the name are listed here.
4330 All others have their meaning expanded out elsewhere in this document.
4331 This (relatively) compact list is because we think that the expansion
4332 would add little or no value and take up a lot of space (because there
4333 are so many). If you think certain ones should be expanded, send email
4334 to perl5-porters@perl.org <mailto:perl5-porters@perl.org>.
4335
4336 Each symbol here will be "#define"d if and only if the platform has the
4337 capability. If you need more detail, see the corresponding entry in
4338 config.h. For convenience, the list is split so that the ones that
4339 indicate there is a reentrant version of a capability are listed
4340 separately
4341
4342 "HAS_ACCEPT4", "HAS_ACCESS", "HAS_ACCESSX", "HAS_ACOSH",
4343 "HAS_AINTL", "HAS_ALARM", "HAS_ASINH", "HAS_ATANH", "HAS_ATOLL",
4344 "HAS_CBRT", "HAS_CHOWN", "HAS_CHROOT", "HAS_CHSIZE",
4345 "HAS_CLEARENV", "HAS_COPYSIGN", "HAS_COPYSIGNL", "HAS_CRYPT",
4346 "HAS_CTERMID", "HAS_CUSERID", "HAS_DIRFD", "HAS_DLADDR",
4347 "HAS_DLERROR", "HAS_EACCESS", "HAS_ENDHOSTENT", "HAS_ENDNETENT",
4348 "HAS_ENDPROTOENT", "HAS_ENDSERVENT", "HAS_ERF", "HAS_ERFC",
4349 "HAS_EXP2", "HAS_EXPM1", "HAS_FCHMOD", "HAS_FCHMODAT",
4350 "HAS_FCHOWN", "HAS_FDIM", "HAS_FD_SET", "HAS_FEGETROUND",
4351 "HAS_FGETPOS", "HAS_FLOCK", "HAS_FMA", "HAS_FMAX", "HAS_FMIN",
4352 "HAS_FORK", "HAS_FSEEKO", "HAS_FSETPOS", "HAS_FSYNC",
4353 "HAS_FTELLO", "HAS_GAI_STRERROR", "HAS_GETADDRINFO", "HAS_GETCWD",
4354 "HAS_GETESPWNAM", "HAS_GETGROUPS", "HAS_GETHOSTBYADDR",
4355 "HAS_GETHOSTBYNAME", "HAS_GETHOSTENT", "HAS_GETLOGIN",
4356 "HAS_GETNAMEINFO", "HAS_GETNETBYADDR", "HAS_GETNETBYNAME",
4357 "HAS_GETNETENT", "HAS_GETPAGESIZE", "HAS_GETPGID", "HAS_GETPGRP",
4358 "HAS_GETPGRP2", "HAS_GETPPID", "HAS_GETPRIORITY",
4359 "HAS_GETPROTOBYNAME", "HAS_GETPROTOBYNUMBER", "HAS_GETPROTOENT",
4360 "HAS_GETPRPWNAM", "HAS_GETSERVBYNAME", "HAS_GETSERVBYPORT",
4361 "HAS_GETSERVENT", "HAS_GETSPNAM", "HAS_HTONL", "HAS_HTONS",
4362 "HAS_HYPOT", "HAS_ILOGBL", "HAS_INETNTOP", "HAS_INETPTON",
4363 "HAS_INET_ATON", "HAS_IPV6_MREQ", "HAS_IPV6_MREQ_SOURCE",
4364 "HAS_IP_MREQ", "HAS_IP_MREQ_SOURCE", "HAS_ISASCII", "HAS_ISBLANK",
4365 "HAS_ISLESS", "HAS_KILLPG", "HAS_LCHOWN", "HAS_LINK",
4366 "HAS_LINKAT", "HAS_LLROUND", "HAS_LOCKF", "HAS_LOG1P", "HAS_LOG2",
4367 "HAS_LOGB", "HAS_LROUND", "HAS_LSTAT", "HAS_MADVISE", "HAS_MBLEN",
4368 "HAS_MBRLEN", "HAS_MBRTOWC", "HAS_MBSTOWCS", "HAS_MBTOWC",
4369 "HAS_MEMMEM", "HAS_MEMRCHR", "HAS_MKDTEMP", "HAS_MKFIFO",
4370 "HAS_MKOSTEMP", "HAS_MKSTEMP", "HAS_MKSTEMPS", "HAS_MMAP",
4371 "HAS_MPROTECT", "HAS_MSG", "HAS_MSYNC", "HAS_MUNMAP",
4372 "HAS_NEARBYINT", "HAS_NEXTAFTER", "HAS_NICE", "HAS_NTOHL",
4373 "HAS_NTOHS", "HAS_PATHCONF", "HAS_PAUSE", "HAS_PHOSTNAME",
4374 "HAS_PIPE", "HAS_PIPE2", "HAS_PRCTL", "HAS_PTRDIFF_T",
4375 "HAS_READLINK", "HAS_READV", "HAS_RECVMSG", "HAS_REMQUO",
4376 "HAS_RENAME", "HAS_RENAMEAT", "HAS_RINT", "HAS_ROUND",
4377 "HAS_SCALBNL", "HAS_SEM", "HAS_SENDMSG", "HAS_SETEGID",
4378 "HAS_SETEUID", "HAS_SETGROUPS", "HAS_SETHOSTENT", "HAS_SETLINEBUF",
4379 "HAS_SETNETENT", "HAS_SETPGRP", "HAS_SETPGRP2", "HAS_SETPRIORITY",
4380 "HAS_SETPROCTITLE", "HAS_SETPROTOENT", "HAS_SETREGID",
4381 "HAS_SETRESGID", "HAS_SETRESUID", "HAS_SETREUID", "HAS_SETRGID",
4382 "HAS_SETRUID", "HAS_SETSERVENT", "HAS_SETSID", "HAS_SHM",
4383 "HAS_SIGACTION", "HAS_SIGPROCMASK", "HAS_SIN6_SCOPE_ID",
4384 "HAS_SNPRINTF", "HAS_STAT", "HAS_STRCOLL", "HAS_STRERROR_L",
4385 "HAS_STRLCAT", "HAS_STRLCPY", "HAS_STRNLEN", "HAS_STRTOD",
4386 "HAS_STRTOL", "HAS_STRTOLL", "HAS_STRTOQ", "HAS_STRTOUL",
4387 "HAS_STRTOULL", "HAS_STRTOUQ", "HAS_STRXFRM", "HAS_SYMLINK",
4388 "HAS_SYSCALL", "HAS_SYSCONF", "HAS_SYSTEM", "HAS_SYS_ERRLIST",
4389 "HAS_TCGETPGRP", "HAS_TCSETPGRP", "HAS_TOWLOWER", "HAS_TOWUPPER",
4390 "HAS_TRUNCATE", "HAS_TRUNCL", "HAS_UALARM", "HAS_UMASK",
4391 "HAS_UNLINKAT", "HAS_UNSETENV", "HAS_VFORK", "HAS_VSNPRINTF",
4392 "HAS_WAIT4", "HAS_WAITPID", "HAS_WCRTOMB", "HAS_WCSCMP",
4393 "HAS_WCSTOMBS", "HAS_WCSXFRM", "HAS_WCTOMB", "HAS_WRITEV",
4394 "HAS__FWALK"
4395
4396 And, the reentrant capabilities:
4397
4398 "HAS_CRYPT_R", "HAS_CTERMID_R", "HAS_DRAND48_R",
4399 "HAS_ENDHOSTENT_R", "HAS_ENDNETENT_R", "HAS_ENDPROTOENT_R",
4400 "HAS_ENDSERVENT_R", "HAS_GETGRGID_R", "HAS_GETGRNAM_R",
4401 "HAS_GETHOSTBYADDR_R", "HAS_GETHOSTBYNAME_R", "HAS_GETHOSTENT_R",
4402 "HAS_GETLOGIN_R", "HAS_GETNETBYADDR_R", "HAS_GETNETBYNAME_R",
4403 "HAS_GETNETENT_R", "HAS_GETPROTOBYNAME_R", "HAS_GETPROTOBYNUMBER_R",
4404 "HAS_GETPROTOENT_R", "HAS_GETPWNAM_R", "HAS_GETPWUID_R",
4405 "HAS_GETSERVBYNAME_R", "HAS_GETSERVBYPORT_R", "HAS_GETSERVENT_R",
4406 "HAS_GETSPNAM_R", "HAS_RANDOM_R", "HAS_READDIR_R",
4407 "HAS_SETHOSTENT_R", "HAS_SETNETENT_R", "HAS_SETPROTOENT_R",
4408 "HAS_SETSERVENT_R", "HAS_SRAND48_R", "HAS_SRANDOM_R",
4409 "HAS_STRERROR_R", "HAS_TMPNAM_R", "HAS_TTYNAME_R"
4410
4411 Example usage:
4412
4413 #ifdef HAS_STRNLEN
4414 use strnlen()
4415 #else
4416 use an alternative implementation
4417 #endif
4418
4419 List of "#include" needed symbols
4420 This list contains symbols that indicate if certain "#include" files
4421 are present on the platform. If your code accesses the functionality
4422 that one of these is for, you will need to "#include" it if the symbol
4423 on this list is "#define"d. For more detail, see the corresponding
4424 entry in config.h.
4425
4426 "I_ARPA_INET", "I_BFD", "I_CRYPT", "I_DBM", "I_DLFCN",
4427 "I_EXECINFO", "I_FP", "I_FP_CLASS", "I_GDBM", "I_GDBMNDBM",
4428 "I_GDBM_NDBM", "I_GRP", "I_IEEEFP", "I_INTTYPES", "I_LIBUTIL",
4429 "I_MNTENT", "I_NDBM", "I_NETDB", "I_NETINET_IN", "I_NETINET_TCP",
4430 "I_NET_ERRNO", "I_PROT", "I_PWD", "I_RPCSVC_DBM", "I_SGTTY",
4431 "I_SHADOW", "I_STDBOOL", "I_STDINT", "I_SUNMATH", "I_SYSLOG",
4432 "I_SYSMODE", "I_SYSUIO", "I_SYSUTSNAME", "I_SYS_ACCESS",
4433 "I_SYS_IOCTL", "I_SYS_MOUNT", "I_SYS_PARAM", "I_SYS_POLL",
4434 "I_SYS_SECURITY", "I_SYS_SELECT", "I_SYS_STAT", "I_SYS_STATVFS",
4435 "I_SYS_TIME", "I_SYS_TIMES", "I_SYS_TIME_KERNEL", "I_SYS_TYPES",
4436 "I_SYS_UN", "I_SYS_VFS", "I_SYS_WAIT", "I_TERMIO", "I_TERMIOS",
4437 "I_UNISTD", "I_USTAT", "I_VFORK", "I_WCHAR", "I_WCTYPE"
4438
4439 Example usage:
4440
4441 #ifdef I_WCHAR
4442 #include <wchar.h>
4443 #endif
4444
4446 These variables are global to an entire process. They are shared
4447 between all interpreters and all threads in a process. Any variables
4448 not documented here may be changed or removed without notice, so don't
4449 use them! If you feel you really do need to use an unlisted variable,
4450 first send email to perl5-porters@perl.org
4451 <mailto:perl5-porters@perl.org>. It may be that someone there will
4452 point out a way to accomplish what you need without using an internal
4453 variable. But if not, you should get a go-ahead to document and then
4454 use the variable.
4455
4456 "PL_check"
4457 Array, indexed by opcode, of functions that will be called for the
4458 "check" phase of optree building during compilation of Perl code.
4459 For most (but not all) types of op, once the op has been initially
4460 built and populated with child ops it will be filtered through the
4461 check function referenced by the appropriate element of this array.
4462 The new op is passed in as the sole argument to the check function,
4463 and the check function returns the completed op. The check
4464 function may (as the name suggests) check the op for validity and
4465 signal errors. It may also initialise or modify parts of the ops,
4466 or perform more radical surgery such as adding or removing child
4467 ops, or even throw the op away and return a different op in its
4468 place.
4469
4470 This array of function pointers is a convenient place to hook into
4471 the compilation process. An XS module can put its own custom check
4472 function in place of any of the standard ones, to influence the
4473 compilation of a particular type of op. However, a custom check
4474 function must never fully replace a standard check function (or
4475 even a custom check function from another module). A module
4476 modifying checking must instead wrap the preexisting check
4477 function. A custom check function must be selective about when to
4478 apply its custom behaviour. In the usual case where it decides not
4479 to do anything special with an op, it must chain the preexisting op
4480 function. Check functions are thus linked in a chain, with the
4481 core's base checker at the end.
4482
4483 For thread safety, modules should not write directly to this array.
4484 Instead, use the function "wrap_op_checker".
4485
4486 "PL_keyword_plugin"
4487 NOTE: "PL_keyword_plugin" is experimental and may change or be
4488 removed without notice.
4489
4490 Function pointer, pointing at a function used to handle extended
4491 keywords. The function should be declared as
4492
4493 int keyword_plugin_function(pTHX_
4494 char *keyword_ptr, STRLEN keyword_len,
4495 OP **op_ptr)
4496
4497 The function is called from the tokeniser, whenever a possible
4498 keyword is seen. "keyword_ptr" points at the word in the parser's
4499 input buffer, and "keyword_len" gives its length; it is not null-
4500 terminated. The function is expected to examine the word, and
4501 possibly other state such as %^H, to decide whether it wants to
4502 handle it as an extended keyword. If it does not, the function
4503 should return "KEYWORD_PLUGIN_DECLINE", and the normal parser
4504 process will continue.
4505
4506 If the function wants to handle the keyword, it first must parse
4507 anything following the keyword that is part of the syntax
4508 introduced by the keyword. See "Lexer interface" for details.
4509
4510 When a keyword is being handled, the plugin function must build a
4511 tree of "OP" structures, representing the code that was parsed.
4512 The root of the tree must be stored in *op_ptr. The function then
4513 returns a constant indicating the syntactic role of the construct
4514 that it has parsed: "KEYWORD_PLUGIN_STMT" if it is a complete
4515 statement, or "KEYWORD_PLUGIN_EXPR" if it is an expression. Note
4516 that a statement construct cannot be used inside an expression
4517 (except via "do BLOCK" and similar), and an expression is not a
4518 complete statement (it requires at least a terminating semicolon).
4519
4520 When a keyword is handled, the plugin function may also have
4521 (compile-time) side effects. It may modify "%^H", define
4522 functions, and so on. Typically, if side effects are the main
4523 purpose of a handler, it does not wish to generate any ops to be
4524 included in the normal compilation. In this case it is still
4525 required to supply an op tree, but it suffices to generate a single
4526 null op.
4527
4528 That's how the *PL_keyword_plugin function needs to behave overall.
4529 Conventionally, however, one does not completely replace the
4530 existing handler function. Instead, take a copy of
4531 "PL_keyword_plugin" before assigning your own function pointer to
4532 it. Your handler function should look for keywords that it is
4533 interested in and handle those. Where it is not interested, it
4534 should call the saved plugin function, passing on the arguments it
4535 received. Thus "PL_keyword_plugin" actually points at a chain of
4536 handler functions, all of which have an opportunity to handle
4537 keywords, and only the last function in the chain (built into the
4538 Perl core) will normally return "KEYWORD_PLUGIN_DECLINE".
4539
4540 For thread safety, modules should not set this variable directly.
4541 Instead, use the function "wrap_keyword_plugin".
4542
4543 "PL_phase"
4544 A value that indicates the current Perl interpreter's phase.
4545 Possible values include "PERL_PHASE_CONSTRUCT", "PERL_PHASE_START",
4546 "PERL_PHASE_CHECK", "PERL_PHASE_INIT", "PERL_PHASE_RUN",
4547 "PERL_PHASE_END", and "PERL_PHASE_DESTRUCT".
4548
4549 For example, the following determines whether the interpreter is in
4550 global destruction:
4551
4552 if (PL_phase == PERL_PHASE_DESTRUCT) {
4553 // we are in global destruction
4554 }
4555
4556 "PL_phase" was introduced in Perl 5.14; in prior perls you can use
4557 "PL_dirty" (boolean) to determine whether the interpreter is in
4558 global destruction. (Use of "PL_dirty" is discouraged since 5.14.)
4559
4560 enum perl_phase PL_phase
4561
4563 A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
4564 It is a structure that holds a pointer to a scalar, an array, a hash
4565 etc, corresponding to $foo, @foo, %foo.
4566
4567 GVs are usually found as values in stashes (symbol table hashes) where
4568 Perl stores its global variables.
4569
4570 "gv_autoload4"
4571 Equivalent to "gv_autoload_pvn".
4572
4573 GV* gv_autoload4(HV* stash, const char* name, STRLEN len,
4574 I32 method)
4575
4576 "GvAV"
4577 Return the AV from the GV.
4578
4579 AV* GvAV(GV* gv)
4580
4581 "gv_const_sv"
4582 If "gv" is a typeglob whose subroutine entry is a constant sub
4583 eligible for inlining, or "gv" is a placeholder reference that
4584 would be promoted to such a typeglob, then returns the value
4585 returned by the sub. Otherwise, returns "NULL".
4586
4587 SV* gv_const_sv(GV* gv)
4588
4589 "GvCV"
4590 Return the CV from the GV.
4591
4592 CV* GvCV(GV* gv)
4593
4594 "gv_fetchfile"
4595 "gv_fetchfile_flags"
4596 These return the debugger glob for the file (compiled by Perl)
4597 whose name is given by the "name" parameter.
4598
4599 There are currently exactly two differences between these
4600 functions.
4601
4602 The "name" parameter to "gv_fetchfile" is a C string, meaning it is
4603 "NUL"-terminated; whereas the "name" parameter to
4604 "gv_fetchfile_flags" is a Perl string, whose length (in bytes) is
4605 passed in via the "namelen" parameter This means the name may
4606 contain embedded "NUL" characters. "namelen" doesn't exist in
4607 plain "gv_fetchfile").
4608
4609 The other difference is that "gv_fetchfile_flags" has an extra
4610 "flags" parameter, which is currently completely ignored, but
4611 allows for possible future extensions.
4612
4613 GV* gv_fetchfile (const char* name)
4614 GV* gv_fetchfile_flags(const char *const name, const STRLEN len,
4615 const U32 flags)
4616
4617 "gv_fetchmeth"
4618 Like "gv_fetchmeth_pvn", but lacks a flags parameter.
4619
4620 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len,
4621 I32 level)
4622
4623 "gv_fetchmethod"
4624 See "gv_fetchmethod_autoload".
4625
4626 GV* gv_fetchmethod(HV* stash, const char* name)
4627
4628 "gv_fetchmethod_autoload"
4629 Returns the glob which contains the subroutine to call to invoke
4630 the method on the "stash". In fact in the presence of autoloading
4631 this may be the glob for "AUTOLOAD". In this case the
4632 corresponding variable $AUTOLOAD is already setup.
4633
4634 The third parameter of "gv_fetchmethod_autoload" determines whether
4635 AUTOLOAD lookup is performed if the given method is not present:
4636 non-zero means yes, look for AUTOLOAD; zero means no, don't look
4637 for AUTOLOAD. Calling "gv_fetchmethod" is equivalent to calling
4638 "gv_fetchmethod_autoload" with a non-zero "autoload" parameter.
4639
4640 These functions grant "SUPER" token as a prefix of the method name.
4641 Note that if you want to keep the returned glob for a long time,
4642 you need to check for it being "AUTOLOAD", since at the later time
4643 the call may load a different subroutine due to $AUTOLOAD changing
4644 its value. Use the glob created as a side effect to do this.
4645
4646 These functions have the same side-effects as "gv_fetchmeth" with
4647 "level==0". The warning against passing the GV returned by
4648 "gv_fetchmeth" to "call_sv" applies equally to these functions.
4649
4650 GV* gv_fetchmethod_autoload(HV* stash, const char* name,
4651 I32 autoload)
4652
4653 "gv_fetchmeth_autoload"
4654 This is the old form of "gv_fetchmeth_pvn_autoload", which has no
4655 flags parameter.
4656
4657 GV* gv_fetchmeth_autoload(HV* stash, const char* name,
4658 STRLEN len, I32 level)
4659
4660 "gv_fetchmeth_pv"
4661 Exactly like "gv_fetchmeth_pvn", but takes a nul-terminated string
4662 instead of a string/length pair.
4663
4664 GV* gv_fetchmeth_pv(HV* stash, const char* name, I32 level,
4665 U32 flags)
4666
4667 "gv_fetchmeth_pvn"
4668 Returns the glob with the given "name" and a defined subroutine or
4669 "NULL". The glob lives in the given "stash", or in the stashes
4670 accessible via @ISA and "UNIVERSAL::".
4671
4672 The argument "level" should be either 0 or -1. If "level==0", as a
4673 side-effect creates a glob with the given "name" in the given
4674 "stash" which in the case of success contains an alias for the
4675 subroutine, and sets up caching info for this glob.
4676
4677 The only significant values for "flags" are "GV_SUPER",
4678 "GV_NOUNIVERSAL", and "SVf_UTF8".
4679
4680 "GV_SUPER" indicates that we want to look up the method in the
4681 superclasses of the "stash".
4682
4683 "GV_NOUNIVERSAL" indicates that we do not want to look up the
4684 method in the stash accessible by "UNIVERSAL::".
4685
4686 The GV returned from "gv_fetchmeth" may be a method cache entry,
4687 which is not visible to Perl code. So when calling "call_sv", you
4688 should not use the GV directly; instead, you should use the
4689 method's CV, which can be obtained from the GV with the "GvCV"
4690 macro.
4691
4692 GV* gv_fetchmeth_pvn(HV* stash, const char* name, STRLEN len,
4693 I32 level, U32 flags)
4694
4695 "gv_fetchmeth_pvn_autoload"
4696 Same as "gv_fetchmeth_pvn()", but looks for autoloaded subroutines
4697 too. Returns a glob for the subroutine.
4698
4699 For an autoloaded subroutine without a GV, will create a GV even if
4700 "level < 0". For an autoloaded subroutine without a stub, "GvCV()"
4701 of the result may be zero.
4702
4703 Currently, the only significant value for "flags" is "SVf_UTF8".
4704
4705 GV* gv_fetchmeth_pvn_autoload(HV* stash, const char* name,
4706 STRLEN len, I32 level, U32 flags)
4707
4708 "gv_fetchmeth_pv_autoload"
4709 Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-
4710 terminated string instead of a string/length pair.
4711
4712 GV* gv_fetchmeth_pv_autoload(HV* stash, const char* name,
4713 I32 level, U32 flags)
4714
4715 "gv_fetchmeth_sv"
4716 Exactly like "gv_fetchmeth_pvn", but takes the name string in the
4717 form of an SV instead of a string/length pair.
4718
4719 GV* gv_fetchmeth_sv(HV* stash, SV* namesv, I32 level, U32 flags)
4720
4721 "gv_fetchmeth_sv_autoload"
4722 Exactly like "gv_fetchmeth_pvn_autoload", but takes the name string
4723 in the form of an SV instead of a string/length pair.
4724
4725 GV* gv_fetchmeth_sv_autoload(HV* stash, SV* namesv, I32 level,
4726 U32 flags)
4727
4728 "gv_fetchpv"
4729 "gv_fetchpvn"
4730 "gv_fetchpvn_flags"
4731 "gv_fetchpvs"
4732 "gv_fetchsv"
4733 "gv_fetchsv_nomg"
4734 These all return the GV of type "sv_type" whose name is given by
4735 the inputs, or NULL if no GV of that name and type could be found.
4736 See "Stashes and Globs" in perlguts.
4737
4738 The only differences are how the input name is specified, and if
4739 'get' magic is normally used in getting that name.
4740
4741 Don't be fooled by the fact that only one form has "flags" in its
4742 name. They all have a "flags" parameter in fact, and all the flag
4743 bits have the same meanings for all
4744
4745 If any of the flags "GV_ADD", "GV_ADDMG", "GV_ADDWARN",
4746 "GV_ADDMULTI", or "GV_NOINIT" is set, a GV is created if none
4747 already exists for the input name and type. However, "GV_ADDMG"
4748 will only do the creation for magical GV's. For all of these flags
4749 except "GV_NOINIT", "gv_init_pvn" is called after the addition.
4750 "GV_ADDWARN" is used when the caller expects that adding won't be
4751 necessary because the symbol should already exist; but if not, add
4752 it anyway, with a warning that it was unexpectedly absent. The
4753 "GV_ADDMULTI" flag means to pretend that the GV has been seen
4754 before (i.e., suppress "Used once" warnings).
4755
4756 The flag "GV_NOADD_NOINIT" causes "gv_init_pvn" not be to called if
4757 the GV existed but isn't PVGV.
4758
4759 If the "SVf_UTF8" bit is set, the name is treated as being encoded
4760 in UTF-8; otherwise the name won't be considered to be UTF-8 in the
4761 "pv"-named forms, and the UTF-8ness of the underlying SVs will be
4762 used in the "sv" forms.
4763
4764 If the flag "GV_NOTQUAL" is set, the caller warrants that the input
4765 name is a plain symbol name, not qualified with a package,
4766 otherwise the name is checked for being a qualified one.
4767
4768 In "gv_fetchpv", "nambeg" is a C string, NUL-terminated with no
4769 intermediate NULs.
4770
4771 In "gv_fetchpvs", "name" is a literal C string, hence is enclosed
4772 in double quotes.
4773
4774 "gv_fetchpvn" and "gv_fetchpvn_flags" are identical. In these,
4775 <nambeg> is a Perl string whose byte length is given by "full_len",
4776 and may contain embedded NULs.
4777
4778 In "gv_fetchsv" and "gv_fetchsv_nomg", the name is extracted from
4779 the PV of the input "name" SV. The only difference between these
4780 two forms is that 'get' magic is normally done on "name" in
4781 "gv_fetchsv", and always skipped with "gv_fetchsv_nomg". Including
4782 "GV_NO_SVGMAGIC" in the "flags" parameter to "gv_fetchsv" makes it
4783 behave identically to "gv_fetchsv_nomg".
4784
4785 GV* gv_fetchpv (const char *nambeg, I32 flags,
4786 const svtype sv_type)
4787 GV * gv_fetchpvn (const char * nambeg, STRLEN full_len,
4788 I32 flags, const svtype sv_type)
4789 GV* gv_fetchpvn_flags(const char* name, STRLEN len, I32 flags,
4790 const svtype sv_type)
4791 GV * gv_fetchpvs ("name", I32 flags, const svtype sv_type)
4792 GV* gv_fetchsv (SV *name, I32 flags, const svtype sv_type)
4793 GV * gv_fetchsv_nomg (SV *name, I32 flags, const svtype sv_type)
4794
4795 "GvHV"
4796 Return the HV from the GV.
4797
4798 HV* GvHV(GV* gv)
4799
4800 "gv_init"
4801 The old form of "gv_init_pvn()". It does not work with UTF-8
4802 strings, as it has no flags parameter. If the "multi" parameter is
4803 set, the "GV_ADDMULTI" flag will be passed to "gv_init_pvn()".
4804
4805 void gv_init(GV* gv, HV* stash, const char* name, STRLEN len,
4806 int multi)
4807
4808 "gv_init_pv"
4809 Same as "gv_init_pvn()", but takes a nul-terminated string for the
4810 name instead of separate char * and length parameters.
4811
4812 void gv_init_pv(GV* gv, HV* stash, const char* name, U32 flags)
4813
4814 "gv_init_pvn"
4815 Converts a scalar into a typeglob. This is an incoercible
4816 typeglob; assigning a reference to it will assign to one of its
4817 slots, instead of overwriting it as happens with typeglobs created
4818 by "SvSetSV". Converting any scalar that is "SvOK()" may produce
4819 unpredictable results and is reserved for perl's internal use.
4820
4821 "gv" is the scalar to be converted.
4822
4823 "stash" is the parent stash/package, if any.
4824
4825 "name" and "len" give the name. The name must be unqualified; that
4826 is, it must not include the package name. If "gv" is a stash
4827 element, it is the caller's responsibility to ensure that the name
4828 passed to this function matches the name of the element. If it
4829 does not match, perl's internal bookkeeping will get out of sync.
4830
4831 "flags" can be set to "SVf_UTF8" if "name" is a UTF-8 string, or
4832 the return value of SvUTF8(sv). It can also take the "GV_ADDMULTI"
4833 flag, which means to pretend that the GV has been seen before
4834 (i.e., suppress "Used once" warnings).
4835
4836 void gv_init_pvn(GV* gv, HV* stash, const char* name, STRLEN len,
4837 U32 flags)
4838
4839 "gv_init_sv"
4840 Same as "gv_init_pvn()", but takes an SV * for the name instead of
4841 separate char * and length parameters. "flags" is currently
4842 unused.
4843
4844 void gv_init_sv(GV* gv, HV* stash, SV* namesv, U32 flags)
4845
4846 "gv_stashpv"
4847 Returns a pointer to the stash for a specified package. Uses
4848 "strlen" to determine the length of "name", then calls
4849 "gv_stashpvn()".
4850
4851 HV* gv_stashpv(const char* name, I32 flags)
4852
4853 "gv_stashpvn"
4854 Returns a pointer to the stash for a specified package. The
4855 "namelen" parameter indicates the length of the "name", in bytes.
4856 "flags" is passed to "gv_fetchpvn_flags()", so if set to "GV_ADD"
4857 then the package will be created if it does not already exist. If
4858 the package does not exist and "flags" is 0 (or any other setting
4859 that does not create packages) then "NULL" is returned.
4860
4861 Flags may be one of:
4862
4863 GV_ADD Create and initialize the package if doesn't
4864 already exist
4865 GV_NOADD_NOINIT Don't create the package,
4866 GV_ADDMG GV_ADD iff the GV is magical
4867 GV_NOINIT GV_ADD, but don't initialize
4868 GV_NOEXPAND Don't expand SvOK() entries to PVGV
4869 SVf_UTF8 The name is in UTF-8
4870
4871 The most important of which are probably "GV_ADD" and "SVf_UTF8".
4872
4873 Note, use of "gv_stashsv" instead of "gv_stashpvn" where possible
4874 is strongly recommended for performance reasons.
4875
4876 HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
4877
4878 "gv_stashpvs"
4879 Like "gv_stashpvn", but takes a literal string instead of a
4880 string/length pair.
4881
4882 HV* gv_stashpvs("name", I32 create)
4883
4884 "gv_stashsv"
4885 Returns a pointer to the stash for a specified package. See
4886 "gv_stashpvn".
4887
4888 Note this interface is strongly preferred over "gv_stashpvn" for
4889 performance reasons.
4890
4891 HV* gv_stashsv(SV* sv, I32 flags)
4892
4893 "GvSV"
4894 Return the SV from the GV.
4895
4896 Prior to Perl v5.9.3, this would add a scalar if none existed.
4897 Nowadays, use "GvSVn" for that, or compile perl with
4898 "-DPERL_CREATE_GVSV". See perl5100delta.
4899
4900 SV* GvSV(GV* gv)
4901
4902 "GvSVn"
4903 Like "GvSV", but creates an empty scalar if none already exists.
4904
4905 SV* GvSVn(GV* gv)
4906
4907 "save_gp"
4908 Saves the current GP of gv on the save stack to be restored on
4909 scope exit.
4910
4911 If empty is true, replace the GP with a new GP.
4912
4913 If empty is false, mark gv with GVf_INTRO so the next reference
4914 assigned is localized, which is how " local *foo = $someref; "
4915 works.
4916
4917 void save_gp(GV* gv, I32 empty)
4918
4919 "setdefout"
4920 Sets "PL_defoutgv", the default file handle for output, to the
4921 passed in typeglob. As "PL_defoutgv" "owns" a reference on its
4922 typeglob, the reference count of the passed in typeglob is
4923 increased by one, and the reference count of the typeglob that
4924 "PL_defoutgv" points to is decreased by one.
4925
4926 void setdefout(GV* gv)
4927
4929 These functions provide convenient and thread-safe means of
4930 manipulating hook variables.
4931
4932 "wrap_op_checker"
4933 Puts a C function into the chain of check functions for a specified
4934 op type. This is the preferred way to manipulate the "PL_check"
4935 array. "opcode" specifies which type of op is to be affected.
4936 "new_checker" is a pointer to the C function that is to be added to
4937 that opcode's check chain, and "old_checker_p" points to the
4938 storage location where a pointer to the next function in the chain
4939 will be stored. The value of "new_checker" is written into the
4940 "PL_check" array, while the value previously stored there is
4941 written to *old_checker_p.
4942
4943 "PL_check" is global to an entire process, and a module wishing to
4944 hook op checking may find itself invoked more than once per
4945 process, typically in different threads. To handle that situation,
4946 this function is idempotent. The location *old_checker_p must
4947 initially (once per process) contain a null pointer. A C variable
4948 of static duration (declared at file scope, typically also marked
4949 "static" to give it internal linkage) will be implicitly
4950 initialised appropriately, if it does not have an explicit
4951 initialiser. This function will only actually modify the check
4952 chain if it finds *old_checker_p to be null. This function is also
4953 thread safe on the small scale. It uses appropriate locking to
4954 avoid race conditions in accessing "PL_check".
4955
4956 When this function is called, the function referenced by
4957 "new_checker" must be ready to be called, except for *old_checker_p
4958 being unfilled. In a threading situation, "new_checker" may be
4959 called immediately, even before this function has returned.
4960 *old_checker_p will always be appropriately set before
4961 "new_checker" is called. If "new_checker" decides not to do
4962 anything special with an op that it is given (which is the usual
4963 case for most uses of op check hooking), it must chain the check
4964 function referenced by *old_checker_p.
4965
4966 Taken all together, XS code to hook an op checker should typically
4967 look something like this:
4968
4969 static Perl_check_t nxck_frob;
4970 static OP *myck_frob(pTHX_ OP *op) {
4971 ...
4972 op = nxck_frob(aTHX_ op);
4973 ...
4974 return op;
4975 }
4976 BOOT:
4977 wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
4978
4979 If you want to influence compilation of calls to a specific
4980 subroutine, then use "cv_set_call_checker_flags" rather than
4981 hooking checking of all "entersub" ops.
4982
4983 void wrap_op_checker(Optype opcode, Perl_check_t new_checker,
4984 Perl_check_t *old_checker_p)
4985
4987 A HV structure represents a Perl hash. It consists mainly of an array
4988 of pointers, each of which points to a linked list of HE structures.
4989 The array is indexed by the hash function of the key, so each linked
4990 list represents all the hash entries with the same hash value. Each HE
4991 contains a pointer to the actual value, plus a pointer to a HEK
4992 structure which holds the key and hash value.
4993
4994 "get_hv"
4995 Returns the HV of the specified Perl hash. "flags" are passed to
4996 "gv_fetchpv". If "GV_ADD" is set and the Perl variable does not
4997 exist then it will be created. If "flags" is zero and the variable
4998 does not exist then "NULL" is returned.
4999
5000 NOTE: the "perl_get_hv()" form is deprecated.
5001
5002 HV* get_hv(const char *name, I32 flags)
5003
5004 "HEf_SVKEY"
5005 This flag, used in the length slot of hash entries and magic
5006 structures, specifies the structure contains an "SV*" pointer where
5007 a "char*" pointer is to be expected. (For information only--not to
5008 be used).
5009
5010 "HeHASH"
5011 Returns the computed hash stored in the hash entry.
5012
5013 U32 HeHASH(HE* he)
5014
5015 "HeKEY"
5016 Returns the actual pointer stored in the key slot of the hash
5017 entry. The pointer may be either "char*" or "SV*", depending on
5018 the value of "HeKLEN()". Can be assigned to. The "HePV()" or
5019 "HeSVKEY()" macros are usually preferable for finding the value of
5020 a key.
5021
5022 void* HeKEY(HE* he)
5023
5024 "HeKLEN"
5025 If this is negative, and amounts to "HEf_SVKEY", it indicates the
5026 entry holds an "SV*" key. Otherwise, holds the actual length of
5027 the key. Can be assigned to. The "HePV()" macro is usually
5028 preferable for finding key lengths.
5029
5030 STRLEN HeKLEN(HE* he)
5031
5032 "HePV"
5033 Returns the key slot of the hash entry as a "char*" value, doing
5034 any necessary dereferencing of possibly "SV*" keys. The length of
5035 the string is placed in "len" (this is a macro, so do not use
5036 &len). If you do not care about what the length of the key is, you
5037 may use the global variable "PL_na", though this is rather less
5038 efficient than using a local variable. Remember though, that hash
5039 keys in perl are free to contain embedded nulls, so using
5040 "strlen()" or similar is not a good way to find the length of hash
5041 keys. This is very similar to the "SvPV()" macro described
5042 elsewhere in this document. See also "HeUTF8".
5043
5044 If you are using "HePV" to get values to pass to "newSVpvn()" to
5045 create a new SV, you should consider using
5046 "newSVhek(HeKEY_hek(he))" as it is more efficient.
5047
5048 char* HePV(HE* he, STRLEN len)
5049
5050 "HeSVKEY"
5051 Returns the key as an "SV*", or "NULL" if the hash entry does not
5052 contain an "SV*" key.
5053
5054 SV* HeSVKEY(HE* he)
5055
5056 "HeSVKEY_force"
5057 Returns the key as an "SV*". Will create and return a temporary
5058 mortal "SV*" if the hash entry contains only a "char*" key.
5059
5060 SV* HeSVKEY_force(HE* he)
5061
5062 "HeSVKEY_set"
5063 Sets the key to a given "SV*", taking care to set the appropriate
5064 flags to indicate the presence of an "SV*" key, and returns the
5065 same "SV*".
5066
5067 SV* HeSVKEY_set(HE* he, SV* sv)
5068
5069 "HeUTF8"
5070 Returns whether the "char *" value returned by "HePV" is encoded in
5071 UTF-8, doing any necessary dereferencing of possibly "SV*" keys.
5072 The value returned will be 0 or non-0, not necessarily 1 (or even a
5073 value with any low bits set), so do not blindly assign this to a
5074 "bool" variable, as "bool" may be a typedef for "char".
5075
5076 U32 HeUTF8(HE* he)
5077
5078 "HeVAL"
5079 Returns the value slot (type "SV*") stored in the hash entry. Can
5080 be assigned to.
5081
5082 SV *foo= HeVAL(hv);
5083 HeVAL(hv)= sv;
5084
5085 SV* HeVAL(HE* he)
5086
5087 "HV"
5088 Described in perlguts.
5089
5090 "hv_assert"
5091 Check that a hash is in an internally consistent state.
5092
5093 NOTE: "hv_assert" must be explicitly called as "Perl_hv_assert"
5094 with an "aTHX_" parameter.
5095
5096 void Perl_hv_assert(pTHX_ HV *hv)
5097
5098 "hv_bucket_ratio"
5099 NOTE: "hv_bucket_ratio" is experimental and may change or be
5100 removed without notice.
5101
5102 If the hash is tied dispatches through to the SCALAR tied method,
5103 otherwise if the hash contains no keys returns 0, otherwise returns
5104 a mortal sv containing a string specifying the number of used
5105 buckets, followed by a slash, followed by the number of available
5106 buckets.
5107
5108 This function is expensive, it must scan all of the buckets to
5109 determine which are used, and the count is NOT cached. In a large
5110 hash this could be a lot of buckets.
5111
5112 SV* hv_bucket_ratio(HV *hv)
5113
5114 "hv_clear"
5115 Frees all the elements of a hash, leaving it empty. The XS
5116 equivalent of "%hash = ()". See also "hv_undef".
5117
5118 See "av_clear" for a note about the hash possibly being invalid on
5119 return.
5120
5121 void hv_clear(HV *hv)
5122
5123 "hv_clear_placeholders"
5124 Clears any placeholders from a hash. If a restricted hash has any
5125 of its keys marked as readonly and the key is subsequently deleted,
5126 the key is not actually deleted but is marked by assigning it a
5127 value of &PL_sv_placeholder. This tags it so it will be ignored by
5128 future operations such as iterating over the hash, but will still
5129 allow the hash to have a value reassigned to the key at some future
5130 point. This function clears any such placeholder keys from the
5131 hash. See "Hash::Util::lock_keys()" for an example of its use.
5132
5133 void hv_clear_placeholders(HV *hv)
5134
5135 "hv_copy_hints_hv"
5136 A specialised version of "newHVhv" for copying "%^H". "ohv" must
5137 be a pointer to a hash (which may have "%^H" magic, but should be
5138 generally non-magical), or "NULL" (interpreted as an empty hash).
5139 The content of "ohv" is copied to a new hash, which has the
5140 "%^H"-specific magic added to it. A pointer to the new hash is
5141 returned.
5142
5143 HV * hv_copy_hints_hv(HV *const ohv)
5144
5145 "hv_delete"
5146 Deletes a key/value pair in the hash. The value's SV is removed
5147 from the hash, made mortal, and returned to the caller. The
5148 absolute value of "klen" is the length of the key. If "klen" is
5149 negative the key is assumed to be in UTF-8-encoded Unicode. The
5150 "flags" value will normally be zero; if set to "G_DISCARD" then
5151 "NULL" will be returned. "NULL" will also be returned if the key
5152 is not found.
5153
5154 SV* hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
5155
5156 "hv_delete_ent"
5157 Deletes a key/value pair in the hash. The value SV is removed from
5158 the hash, made mortal, and returned to the caller. The "flags"
5159 value will normally be zero; if set to "G_DISCARD" then "NULL" will
5160 be returned. "NULL" will also be returned if the key is not found.
5161 "hash" can be a valid precomputed hash value, or 0 to ask for it to
5162 be computed.
5163
5164 SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
5165
5166 "HvENAME"
5167 Returns the effective name of a stash, or NULL if there is none.
5168 The effective name represents a location in the symbol table where
5169 this stash resides. It is updated automatically when packages are
5170 aliased or deleted. A stash that is no longer in the symbol table
5171 has no effective name. This name is preferable to "HvNAME" for use
5172 in MRO linearisations and isa caches.
5173
5174 char* HvENAME(HV* stash)
5175
5176 "HvENAMELEN"
5177 Returns the length of the stash's effective name.
5178
5179 STRLEN HvENAMELEN(HV *stash)
5180
5181 "HvENAMEUTF8"
5182 Returns true if the effective name is in UTF-8 encoding.
5183
5184 unsigned char HvENAMEUTF8(HV *stash)
5185
5186 "hv_exists"
5187 Returns a boolean indicating whether the specified hash key exists.
5188 The absolute value of "klen" is the length of the key. If "klen"
5189 is negative the key is assumed to be in UTF-8-encoded Unicode.
5190
5191 bool hv_exists(HV *hv, const char *key, I32 klen)
5192
5193 "hv_exists_ent"
5194 Returns a boolean indicating whether the specified hash key exists.
5195 "hash" can be a valid precomputed hash value, or 0 to ask for it to
5196 be computed.
5197
5198 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
5199
5200 "hv_fetch"
5201 Returns the SV which corresponds to the specified key in the hash.
5202 The absolute value of "klen" is the length of the key. If "klen"
5203 is negative the key is assumed to be in UTF-8-encoded Unicode. If
5204 "lval" is set then the fetch will be part of a store. This means
5205 that if there is no value in the hash associated with the given
5206 key, then one is created and a pointer to it is returned. The
5207 "SV*" it points to can be assigned to. But always check that the
5208 return value is non-null before dereferencing it to an "SV*".
5209
5210 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5211 for more information on how to use this function on tied hashes.
5212
5213 SV** hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
5214
5215 "hv_fetchs"
5216 Like "hv_fetch", but takes a literal string instead of a
5217 string/length pair.
5218
5219 SV** hv_fetchs(HV* tb, "key", I32 lval)
5220
5221 "hv_fetch_ent"
5222 Returns the hash entry which corresponds to the specified key in
5223 the hash. "hash" must be a valid precomputed hash number for the
5224 given "key", or 0 if you want the function to compute it. IF
5225 "lval" is set then the fetch will be part of a store. Make sure
5226 the return value is non-null before accessing it. The return value
5227 when "hv" is a tied hash is a pointer to a static location, so be
5228 sure to make a copy of the structure if you need to store it
5229 somewhere.
5230
5231 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5232 for more information on how to use this function on tied hashes.
5233
5234 HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
5235
5236 "HvFILL"
5237 See "hv_fill".
5238
5239 STRLEN HvFILL(HV *const hv)
5240
5241 "hv_fill"
5242 Returns the number of hash buckets that happen to be in use.
5243
5244 This function is wrapped by the macro "HvFILL".
5245
5246 As of perl 5.25 this function is used only for debugging purposes,
5247 and the number of used hash buckets is not in any way cached, thus
5248 this function can be costly to execute as it must iterate over all
5249 the buckets in the hash.
5250
5251 NOTE: "hv_fill" must be explicitly called as "Perl_hv_fill" with an
5252 "aTHX_" parameter.
5253
5254 STRLEN Perl_hv_fill(pTHX_ HV *const hv)
5255
5256 "hv_iterinit"
5257 Prepares a starting point to traverse a hash table. Returns the
5258 number of keys in the hash, including placeholders (i.e. the same
5259 as "HvTOTALKEYS(hv)"). The return value is currently only
5260 meaningful for hashes without tie magic.
5261
5262 NOTE: Before version 5.004_65, "hv_iterinit" used to return the
5263 number of hash buckets that happen to be in use. If you still need
5264 that esoteric value, you can get it through the macro "HvFILL(hv)".
5265
5266 I32 hv_iterinit(HV *hv)
5267
5268 "hv_iterkey"
5269 Returns the key from the current position of the hash iterator.
5270 See "hv_iterinit".
5271
5272 char* hv_iterkey(HE* entry, I32* retlen)
5273
5274 "hv_iterkeysv"
5275 Returns the key as an "SV*" from the current position of the hash
5276 iterator. The return value will always be a mortal copy of the
5277 key. Also see "hv_iterinit".
5278
5279 SV* hv_iterkeysv(HE* entry)
5280
5281 "hv_iternext"
5282 Returns entries from a hash iterator. See "hv_iterinit".
5283
5284 You may call "hv_delete" or "hv_delete_ent" on the hash entry that
5285 the iterator currently points to, without losing your place or
5286 invalidating your iterator. Note that in this case the current
5287 entry is deleted from the hash with your iterator holding the last
5288 reference to it. Your iterator is flagged to free the entry on the
5289 next call to "hv_iternext", so you must not discard your iterator
5290 immediately else the entry will leak - call "hv_iternext" to
5291 trigger the resource deallocation.
5292
5293 HE* hv_iternext(HV *hv)
5294
5295 "hv_iternextsv"
5296 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in one
5297 operation.
5298
5299 SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
5300
5301 "hv_iternext_flags"
5302 NOTE: "hv_iternext_flags" is experimental and may change or be
5303 removed without notice.
5304
5305 Returns entries from a hash iterator. See "hv_iterinit" and
5306 "hv_iternext". The "flags" value will normally be zero; if
5307 "HV_ITERNEXT_WANTPLACEHOLDERS" is set the placeholders keys (for
5308 restricted hashes) will be returned in addition to normal keys. By
5309 default placeholders are automatically skipped over. Currently a
5310 placeholder is implemented with a value that is &PL_sv_placeholder.
5311 Note that the implementation of placeholders and restricted hashes
5312 may change, and the implementation currently is insufficiently
5313 abstracted for any change to be tidy.
5314
5315 HE* hv_iternext_flags(HV *hv, I32 flags)
5316
5317 "hv_iterval"
5318 Returns the value from the current position of the hash iterator.
5319 See "hv_iterkey".
5320
5321 SV* hv_iterval(HV *hv, HE *entry)
5322
5323 "hv_magic"
5324 Adds magic to a hash. See "sv_magic".
5325
5326 void hv_magic(HV *hv, GV *gv, int how)
5327
5328 "HvNAME"
5329 Returns the package name of a stash, or "NULL" if "stash" isn't a
5330 stash. See "SvSTASH", "CvSTASH".
5331
5332 char* HvNAME(HV* stash)
5333
5334 "HvNAMELEN"
5335 Returns the length of the stash's name.
5336
5337 Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them
5338
5339 STRLEN HvNAMELEN(HV *stash)
5340
5341 "HvNAMEUTF8"
5342 Returns true if the name is in UTF-8 encoding.
5343
5344 unsigned char HvNAMEUTF8(HV *stash)
5345
5346 "hv_scalar"
5347 Evaluates the hash in scalar context and returns the result.
5348
5349 When the hash is tied dispatches through to the SCALAR method,
5350 otherwise returns a mortal SV containing the number of keys in the
5351 hash.
5352
5353 Note, prior to 5.25 this function returned what is now returned by
5354 the hv_bucket_ratio() function.
5355
5356 SV* hv_scalar(HV *hv)
5357
5358 "hv_store"
5359 Stores an SV in a hash. The hash key is specified as "key" and the
5360 absolute value of "klen" is the length of the key. If "klen" is
5361 negative the key is assumed to be in UTF-8-encoded Unicode. The
5362 "hash" parameter is the precomputed hash value; if it is zero then
5363 Perl will compute it.
5364
5365 The return value will be "NULL" if the operation failed or if the
5366 value did not need to be actually stored within the hash (as in the
5367 case of tied hashes). Otherwise it can be dereferenced to get the
5368 original "SV*". Note that the caller is responsible for suitably
5369 incrementing the reference count of "val" before the call, and
5370 decrementing it if the function returned "NULL". Effectively a
5371 successful "hv_store" takes ownership of one reference to "val".
5372 This is usually what you want; a newly created SV has a reference
5373 count of one, so if all your code does is create SVs then store
5374 them in a hash, "hv_store" will own the only reference to the new
5375 SV, and your code doesn't need to do anything further to tidy up.
5376 "hv_store" is not implemented as a call to "hv_store_ent", and does
5377 not create a temporary SV for the key, so if your key data is not
5378 already in SV form then use "hv_store" in preference to
5379 "hv_store_ent".
5380
5381 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5382 for more information on how to use this function on tied hashes.
5383
5384 SV** hv_store(HV *hv, const char *key, I32 klen, SV *val,
5385 U32 hash)
5386
5387 "hv_stores"
5388 Like "hv_store", but takes a literal string instead of a
5389 string/length pair and omits the hash parameter.
5390
5391 SV** hv_stores(HV* tb, "key", SV* val)
5392
5393 "hv_store_ent"
5394 Stores "val" in a hash. The hash key is specified as "key". The
5395 "hash" parameter is the precomputed hash value; if it is zero then
5396 Perl will compute it. The return value is the new hash entry so
5397 created. It will be "NULL" if the operation failed or if the value
5398 did not need to be actually stored within the hash (as in the case
5399 of tied hashes). Otherwise the contents of the return value can be
5400 accessed using the "He?" macros described here. Note that the
5401 caller is responsible for suitably incrementing the reference count
5402 of "val" before the call, and decrementing it if the function
5403 returned NULL. Effectively a successful "hv_store_ent" takes
5404 ownership of one reference to "val". This is usually what you
5405 want; a newly created SV has a reference count of one, so if all
5406 your code does is create SVs then store them in a hash, "hv_store"
5407 will own the only reference to the new SV, and your code doesn't
5408 need to do anything further to tidy up. Note that "hv_store_ent"
5409 only reads the "key"; unlike "val" it does not take ownership of
5410 it, so maintaining the correct reference count on "key" is entirely
5411 the caller's responsibility. The reason it does not take
5412 ownership, is that "key" is not used after this function returns,
5413 and so can be freed immediately. "hv_store" is not implemented as
5414 a call to "hv_store_ent", and does not create a temporary SV for
5415 the key, so if your key data is not already in SV form then use
5416 "hv_store" in preference to "hv_store_ent".
5417
5418 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5419 for more information on how to use this function on tied hashes.
5420
5421 HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
5422
5423 "hv_undef"
5424 Undefines the hash. The XS equivalent of "undef(%hash)".
5425
5426 As well as freeing all the elements of the hash (like
5427 "hv_clear()"), this also frees any auxiliary data and storage
5428 associated with the hash.
5429
5430 See "av_clear" for a note about the hash possibly being invalid on
5431 return.
5432
5433 void hv_undef(HV *hv)
5434
5435 "MGVTBL"
5436 Described in perlguts.
5437
5438 "newHV"
5439 Creates a new HV. The reference count is set to 1.
5440
5441 HV* newHV()
5442
5443 "Nullhv"
5444 "DEPRECATED!" It is planned to remove "Nullhv" from a future
5445 release of Perl. Do not use it for new code; remove it from
5446 existing code.
5447
5448 Null HV pointer.
5449
5450 (deprecated - use "(HV *)NULL" instead)
5451
5452 "PERL_HASH"
5453 Described in perlguts.
5454
5455 void PERL_HASH(U32 hash, char *key, STRLEN klen)
5456
5457 "PERL_MAGIC_arylen"
5458 "PERL_MAGIC_arylen_p"
5459 "PERL_MAGIC_backref"
5460 "PERL_MAGIC_bm"
5461 "PERL_MAGIC_checkcall"
5462 "PERL_MAGIC_collxfrm"
5463 "PERL_MAGIC_dbfile"
5464 "PERL_MAGIC_dbline"
5465 "PERL_MAGIC_debugvar"
5466 "PERL_MAGIC_defelem"
5467 "PERL_MAGIC_env"
5468 "PERL_MAGIC_envelem"
5469 "PERL_MAGIC_ext"
5470 "PERL_MAGIC_fm"
5471 "PERL_MAGIC_hints"
5472 "PERL_MAGIC_hintselem"
5473 "PERL_MAGIC_isa"
5474 "PERL_MAGIC_isaelem"
5475 "PERL_MAGIC_lvref"
5476 "PERL_MAGIC_nkeys"
5477 "PERL_MAGIC_nonelem"
5478 "PERL_MAGIC_overload_table"
5479 "PERL_MAGIC_pos"
5480 "PERL_MAGIC_qr"
5481 "PERL_MAGIC_regdata"
5482 "PERL_MAGIC_regdatum"
5483 "PERL_MAGIC_regex_global"
5484 "PERL_MAGIC_rhash"
5485 "PERL_MAGIC_shared"
5486 "PERL_MAGIC_shared_scalar"
5487 "PERL_MAGIC_sig"
5488 "PERL_MAGIC_sigelem"
5489 "PERL_MAGIC_substr"
5490 "PERL_MAGIC_sv"
5491 "PERL_MAGIC_symtab"
5492 "PERL_MAGIC_taint"
5493 "PERL_MAGIC_tied"
5494 "PERL_MAGIC_tiedelem"
5495 "PERL_MAGIC_tiedscalar"
5496 "PERL_MAGIC_utf8"
5497 "PERL_MAGIC_uvar"
5498 "PERL_MAGIC_uvar_elem"
5499 "PERL_MAGIC_vec"
5500 "PERL_MAGIC_vstring"
5501 Described in perlguts.
5502
5503 "PL_modglobal"
5504 "PL_modglobal" is a general purpose, interpreter global HV for use
5505 by extensions that need to keep information on a per-interpreter
5506 basis. In a pinch, it can also be used as a symbol table for
5507 extensions to share data among each other. It is a good idea to
5508 use keys prefixed by the package name of the extension that owns
5509 the data.
5510
5511 On threaded perls, each thread has an independent copy of this
5512 variable; each initialized at creation time with the current value
5513 of the creating thread's copy.
5514
5515 HV* PL_modglobal
5516
5518 "PerlIO_apply_layers"
5519 Described in perlapio.
5520
5521 int PerlIO_apply_layers(PerlIO *f, const char *mode,
5522 const char *layers)
5523
5524 "PerlIO_binmode"
5525 Described in perlapio.
5526
5527 int PerlIO_binmode(PerlIO *f, int ptype, int imode,
5528 const char *layers)
5529
5530 "PerlIO_canset_cnt"
5531 Described in perlapio.
5532
5533 int PerlIO_canset_cnt(PerlIO *f)
5534
5535 "PerlIO_clearerr"
5536 Described in perlapio.
5537
5538 void PerlIO_clearerr(PerlIO *f)
5539
5540 "PerlIO_close"
5541 Described in perlapio.
5542
5543 int PerlIO_close(PerlIO *f)
5544
5545 "PerlIO_debug"
5546 Described in perlapio.
5547
5548 void PerlIO_debug(const char *fmt, ...)
5549
5550 "PerlIO_eof"
5551 Described in perlapio.
5552
5553 int PerlIO_eof(PerlIO *f)
5554
5555 "PerlIO_error"
5556 Described in perlapio.
5557
5558 int PerlIO_error(PerlIO *f)
5559
5560 "PerlIO_exportFILE"
5561 Described in perlapio.
5562
5563 FILE * PerlIO_exportFILE(PerlIO *f, const char *mode)
5564
5565 "PerlIO_fast_gets"
5566 Described in perlapio.
5567
5568 int PerlIO_fast_gets(PerlIO *f)
5569
5570 "PerlIO_fdopen"
5571 Described in perlapio.
5572
5573 PerlIO* PerlIO_fdopen(int fd, const char *mode)
5574
5575 "PerlIO_fileno"
5576 Described in perlapio.
5577
5578 int PerlIO_fileno(PerlIO *f)
5579
5580 "PerlIO_findFILE"
5581 Described in perlapio.
5582
5583 FILE * PerlIO_findFILE(PerlIO *f)
5584
5585 "PerlIO_flush"
5586 Described in perlapio.
5587
5588 int PerlIO_flush(PerlIO *f)
5589
5590 "PERLIO_F_APPEND"
5591 "PERLIO_F_CANREAD"
5592 "PERLIO_F_CANWRITE"
5593 "PERLIO_F_CRLF"
5594 "PERLIO_F_EOF"
5595 "PERLIO_F_ERROR"
5596 "PERLIO_F_FASTGETS"
5597 "PERLIO_F_LINEBUF"
5598 "PERLIO_F_OPEN"
5599 "PERLIO_F_RDBUF"
5600 "PERLIO_F_TEMP"
5601 "PERLIO_F_TRUNCATE"
5602 "PERLIO_F_UNBUF"
5603 "PERLIO_F_UTF8"
5604 "PERLIO_F_WRBUF"
5605 Described in perliol.
5606
5607 "PerlIO_getc"
5608 Described in perlapio.
5609
5610 int PerlIO_getc(PerlIO *d)
5611
5612 "PerlIO_getpos"
5613 Described in perlapio.
5614
5615 int PerlIO_getpos(PerlIO *f, SV *save)
5616
5617 "PerlIO_get_base"
5618 Described in perlapio.
5619
5620 STDCHAR * PerlIO_get_base(PerlIO *f)
5621
5622 "PerlIO_get_bufsiz"
5623 Described in perlapio.
5624
5625 SSize_t PerlIO_get_bufsiz(PerlIO *f)
5626
5627 "PerlIO_get_cnt"
5628 Described in perlapio.
5629
5630 SSize_t PerlIO_get_cnt(PerlIO *f)
5631
5632 "PerlIO_get_ptr"
5633 Described in perlapio.
5634
5635 STDCHAR * PerlIO_get_ptr(PerlIO *f)
5636
5637 "PerlIO_has_base"
5638 Described in perlapio.
5639
5640 int PerlIO_has_base(PerlIO *f)
5641
5642 "PerlIO_has_cntptr"
5643 Described in perlapio.
5644
5645 int PerlIO_has_cntptr(PerlIO *f)
5646
5647 "PerlIO_importFILE"
5648 Described in perlapio.
5649
5650 PerlIO* PerlIO_importFILE(FILE *stdio, const char *mode)
5651
5652 "PERLIO_K_BUFFERED"
5653 "PERLIO_K_CANCRLF"
5654 "PERLIO_K_FASTGETS"
5655 "PERLIO_K_MULTIARG"
5656 "PERLIO_K_RAW"
5657 Described in perliol.
5658
5659 "PerlIO_open"
5660 Described in perlapio.
5661
5662 PerlIO* PerlIO_open(const char *path, const char *mode)
5663
5664 "PerlIO_printf"
5665 Described in perlapio.
5666
5667 int PerlIO_printf(PerlIO *f, const char *fmt, ...)
5668
5669 "PerlIO_putc"
5670 Described in perlapio.
5671
5672 int PerlIO_putc(PerlIO *f, int ch)
5673
5674 "PerlIO_puts"
5675 Described in perlapio.
5676
5677 int PerlIO_puts(PerlIO *f, const char *string)
5678
5679 "PerlIO_read"
5680 Described in perlapio.
5681
5682 SSize_t PerlIO_read(PerlIO *f, void *vbuf, Size_t count)
5683
5684 "PerlIO_releaseFILE"
5685 Described in perlapio.
5686
5687 void PerlIO_releaseFILE(PerlIO *f, FILE *stdio)
5688
5689 "PerlIO_reopen"
5690 Described in perlapio.
5691
5692 PerlIO * PerlIO_reopen(const char *path, const char *mode,
5693 PerlIO *old)
5694
5695 "PerlIO_rewind"
5696 Described in perlapio.
5697
5698 void PerlIO_rewind(PerlIO *f)
5699
5700 "PerlIO_seek"
5701 Described in perlapio.
5702
5703 int PerlIO_seek(PerlIO *f, Off_t offset, int whence)
5704
5705 "PerlIO_setlinebuf"
5706 Described in perlapio.
5707
5708 void PerlIO_setlinebuf(PerlIO *f)
5709
5710 "PerlIO_setpos"
5711 Described in perlapio.
5712
5713 int PerlIO_setpos(PerlIO *f, SV *saved)
5714
5715 "PerlIO_set_cnt"
5716 Described in perlapio.
5717
5718 void PerlIO_set_cnt(PerlIO *f, SSize_t cnt)
5719
5720 "PerlIO_set_ptrcnt"
5721 Described in perlapio.
5722
5723 void PerlIO_set_ptrcnt(PerlIO *f, STDCHAR *ptr, SSize_t cnt)
5724
5725 "PerlIO_stderr"
5726 Described in perlapio.
5727
5728 PerlIO * PerlIO_stderr()
5729
5730 "PerlIO_stdin"
5731 Described in perlapio.
5732
5733 PerlIO * PerlIO_stdin()
5734
5735 "PerlIO_stdout"
5736 Described in perlapio.
5737
5738 PerlIO * PerlIO_stdout()
5739
5740 "PerlIO_stdoutf"
5741 Described in perlapio.
5742
5743 int PerlIO_stdoutf(const char *fmt, ...)
5744
5745 "PerlIO_tell"
5746 Described in perlapio.
5747
5748 Off_t PerlIO_tell(PerlIO *f)
5749
5750 "PerlIO_ungetc"
5751 Described in perlapio.
5752
5753 int PerlIO_ungetc(PerlIO *f, int ch)
5754
5755 "PerlIO_vprintf"
5756 Described in perlapio.
5757
5758 int PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args)
5759
5760 "PerlIO_write"
5761 Described in perlapio.
5762
5763 SSize_t PerlIO_write(PerlIO *f, const void *vbuf, Size_t count)
5764
5765 "PL_maxsysfd"
5766 Described in perliol.
5767
5769 "CASTI32"
5770 This symbol is defined if the C compiler can cast negative or large
5771 floating point numbers to 32-bit ints.
5772
5773 "HAS_INT64_T"
5774 This symbol will defined if the C compiler supports "int64_t".
5775 Usually the inttypes.h needs to be included, but sometimes
5776 sys/types.h is enough.
5777
5778 "HAS_LONG_LONG"
5779 This symbol will be defined if the C compiler supports long long.
5780
5781 "HAS_QUAD"
5782 This symbol, if defined, tells that there's a 64-bit integer type,
5783 "Quad_t", and its unsigned counterpart, "Uquad_t". "QUADKIND" will
5784 be one of "QUAD_IS_INT", "QUAD_IS_LONG", "QUAD_IS_LONG_LONG",
5785 "QUAD_IS_INT64_T", or "QUAD_IS___INT64".
5786
5787 "HE"
5788 Described in perlguts.
5789
5790 "I8"
5791 "I16"
5792 "I32"
5793 "I64"
5794 "IV"
5795 Described in perlguts.
5796
5797 "I32SIZE"
5798 This symbol contains the "sizeof(I32)".
5799
5800 "I32TYPE"
5801 This symbol defines the C type used for Perl's I32.
5802
5803 "I64SIZE"
5804 This symbol contains the "sizeof(I64)".
5805
5806 "I64TYPE"
5807 This symbol defines the C type used for Perl's I64.
5808
5809 "I16SIZE"
5810 This symbol contains the "sizeof(I16)".
5811
5812 "I16TYPE"
5813 This symbol defines the C type used for Perl's I16.
5814
5815 "INT16_C"
5816 "INT32_C"
5817 "INT64_C"
5818 Returns a token the C compiler recognizes for the constant "number"
5819 of the corresponding integer type on the machine.
5820
5821 If the machine does not have a 64-bit type, "INT64_C" is undefined.
5822 Use "INTMAX_C" to get the largest type available on the platform.
5823
5824 I16 INT16_C(number)
5825 I32 INT32_C(number)
5826 I64 INT64_C(number)
5827
5828 "INTMAX_C"
5829 Returns a token the C compiler recognizes for the constant "number"
5830 of the widest integer type on the machine. For example, if the
5831 machine has "long long"s, "INTMAX_C(-1)" would yield
5832
5833 -1LL
5834
5835 See also, for example, "INT32_C".
5836
5837 Use "IV" to declare variables of the maximum usable size on this
5838 platform.
5839
5840 INTMAX_C(number)
5841
5842 "INTSIZE"
5843 This symbol contains the value of "sizeof(int)" so that the C
5844 preprocessor can make decisions based on it.
5845
5846 "I8SIZE"
5847 This symbol contains the "sizeof(I8)".
5848
5849 "I8TYPE"
5850 This symbol defines the C type used for Perl's I8.
5851
5852 "IV_MAX"
5853 The largest signed integer that fits in an IV on this platform.
5854
5855 IV IV_MAX
5856
5857 "IV_MIN"
5858 The negative signed integer furthest away from 0 that fits in an IV
5859 on this platform.
5860
5861 IV IV_MIN
5862
5863 "IVSIZE"
5864 This symbol contains the "sizeof(IV)".
5865
5866 "IVTYPE"
5867 This symbol defines the C type used for Perl's IV.
5868
5869 "line_t"
5870 The typedef to use to declare variables that are to hold line
5871 numbers.
5872
5873 "LONGLONGSIZE"
5874 This symbol contains the size of a long long, so that the C
5875 preprocessor can make decisions based on it. It is only defined if
5876 the system supports long long.
5877
5878 "LONGSIZE"
5879 This symbol contains the value of "sizeof(long)" so that the C
5880 preprocessor can make decisions based on it.
5881
5882 "memzero"
5883 Set the "l" bytes starting at *d to all zeroes.
5884
5885 void memzero(void * d, Size_t l)
5886
5887 "NV"
5888 Described in perlguts.
5889
5890 "PERL_INT_FAST8_T"
5891 "PERL_INT_FAST16_T"
5892 "PERL_UINT_FAST8_T"
5893 "PERL_UINT_FAST16_T"
5894 These are equivalent to the correspondingly-named C99 typedefs on
5895 platforms that have those; they evaluate to "int" and "unsigned
5896 int" on platforms that don't, so that you can portably take
5897 advantage of this C99 feature.
5898
5899 "PERL_INT_MAX"
5900 "PERL_INT_MIN"
5901 "PERL_LONG_MAX"
5902 "PERL_LONG_MIN"
5903 "PERL_SHORT_MAX"
5904 "PERL_SHORT_MIN"
5905 "PERL_UCHAR_MAX"
5906 "PERL_UCHAR_MIN"
5907 "PERL_UINT_MAX"
5908 "PERL_UINT_MIN"
5909 "PERL_ULONG_MAX"
5910 "PERL_ULONG_MIN"
5911 "PERL_USHORT_MAX"
5912 "PERL_USHORT_MIN"
5913 "PERL_QUAD_MAX"
5914 "PERL_QUAD_MIN"
5915 "PERL_UQUAD_MAX"
5916 "PERL_UQUAD_MIN"
5917 These give the largest and smallest number representable in the
5918 current platform in variables of the corresponding types.
5919
5920 For signed types, the smallest representable number is the most
5921 negative number, the one furthest away from zero.
5922
5923 For C99 and later compilers, these correspond to things like
5924 "INT_MAX", which are available to the C code. But these constants,
5925 furnished by Perl, allow code compiled on earlier compilers to
5926 portably have access to the same constants.
5927
5928 "SHORTSIZE"
5929 This symbol contains the value of "sizeof(short)" so that the C
5930 preprocessor can make decisions based on it.
5931
5932 "STRLEN"
5933 Described in perlguts.
5934
5935 "U8"
5936 "U16"
5937 "U32"
5938 "U64"
5939 "UV"
5940 Described in perlguts.
5941
5942 "U32SIZE"
5943 This symbol contains the "sizeof(U32)".
5944
5945 "U32TYPE"
5946 This symbol defines the C type used for Perl's U32.
5947
5948 "U64SIZE"
5949 This symbol contains the "sizeof(U64)".
5950
5951 "U64TYPE"
5952 This symbol defines the C type used for Perl's U64.
5953
5954 "U16SIZE"
5955 This symbol contains the "sizeof(U16)".
5956
5957 "U16TYPE"
5958 This symbol defines the C type used for Perl's U16.
5959
5960 "UINT16_C"
5961 "UINT32_C"
5962 "UINT64_C"
5963 Returns a token the C compiler recognizes for the constant "number"
5964 of the corresponding unsigned integer type on the machine.
5965
5966 If the machine does not have a 64-bit type, "UINT64_C" is
5967 undefined. Use "UINTMAX_C" to get the largest type available on
5968 the platform.
5969
5970 U16 UINT16_C(number)
5971 U32 UINT32_C(number)
5972 U64 UINT64_C(number)
5973
5974 "UINTMAX_C"
5975 Returns a token the C compiler recognizes for the constant "number"
5976 of the widest unsigned integer type on the machine. For example,
5977 if the machine has "long"s, UINTMAX_C(1) would yield
5978
5979 1UL
5980
5981 See also, for example, "UINT32_C".
5982
5983 Use "UV" to declare variables of the maximum usable size on this
5984 platform.
5985
5986 UINTMAX_C(number)
5987
5988 "U8SIZE"
5989 This symbol contains the "sizeof(U8)".
5990
5991 "U8TYPE"
5992 This symbol defines the C type used for Perl's U8.
5993
5994 "UV_MAX"
5995 The largest unsigned integer that fits in a UV on this platform.
5996
5997 UV UV_MAX
5998
5999 "UV_MIN"
6000 The smallest unsigned integer that fits in a UV on this platform.
6001 It should equal zero.
6002
6003 UV UV_MIN
6004
6005 "UVSIZE"
6006 This symbol contains the "sizeof(UV)".
6007
6008 "UVTYPE"
6009 This symbol defines the C type used for Perl's UV.
6010
6011 "WIDEST_UTYPE"
6012 Yields the widest unsigned integer type on the platform, currently
6013 either "U32" or "U64". This can be used in declarations such as
6014
6015 WIDEST_UTYPE my_uv;
6016
6017 or casts
6018
6019 my_uv = (WIDEST_UTYPE) val;
6020
6022 This is the lower layer of the Perl parser, managing characters and
6023 tokens.
6024
6025 "lex_bufutf8"
6026 NOTE: "lex_bufutf8" is experimental and may change or be removed
6027 without notice.
6028
6029 Indicates whether the octets in the lexer buffer
6030 ("PL_parser->linestr") should be interpreted as the UTF-8 encoding
6031 of Unicode characters. If not, they should be interpreted as
6032 Latin-1 characters. This is analogous to the "SvUTF8" flag for
6033 scalars.
6034
6035 In UTF-8 mode, it is not guaranteed that the lexer buffer actually
6036 contains valid UTF-8. Lexing code must be robust in the face of
6037 invalid encoding.
6038
6039 The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
6040 significant, but not the whole story regarding the input character
6041 encoding. Normally, when a file is being read, the scalar contains
6042 octets and its "SvUTF8" flag is off, but the octets should be
6043 interpreted as UTF-8 if the "use utf8" pragma is in effect. During
6044 a string eval, however, the scalar may have the "SvUTF8" flag on,
6045 and in this case its octets should be interpreted as UTF-8 unless
6046 the "use bytes" pragma is in effect. This logic may change in the
6047 future; use this function instead of implementing the logic
6048 yourself.
6049
6050 bool lex_bufutf8()
6051
6052 "lex_discard_to"
6053 NOTE: "lex_discard_to" is experimental and may change or be removed
6054 without notice.
6055
6056 Discards the first part of the "PL_parser->linestr" buffer, up to
6057 "ptr". The remaining content of the buffer will be moved, and all
6058 pointers into the buffer updated appropriately. "ptr" must not be
6059 later in the buffer than the position of "PL_parser->bufptr": it is
6060 not permitted to discard text that has yet to be lexed.
6061
6062 Normally it is not necessarily to do this directly, because it
6063 suffices to use the implicit discarding behaviour of
6064 "lex_next_chunk" and things based on it. However, if a token
6065 stretches across multiple lines, and the lexing code has kept
6066 multiple lines of text in the buffer for that purpose, then after
6067 completion of the token it would be wise to explicitly discard the
6068 now-unneeded earlier lines, to avoid future multi-line tokens
6069 growing the buffer without bound.
6070
6071 void lex_discard_to(char* ptr)
6072
6073 "lex_grow_linestr"
6074 NOTE: "lex_grow_linestr" is experimental and may change or be
6075 removed without notice.
6076
6077 Reallocates the lexer buffer ("PL_parser->linestr") to accommodate
6078 at least "len" octets (including terminating "NUL"). Returns a
6079 pointer to the reallocated buffer. This is necessary before making
6080 any direct modification of the buffer that would increase its
6081 length. "lex_stuff_pvn" provides a more convenient way to insert
6082 text into the buffer.
6083
6084 Do not use "SvGROW" or "sv_grow" directly on "PL_parser->linestr";
6085 this function updates all of the lexer's variables that point
6086 directly into the buffer.
6087
6088 char* lex_grow_linestr(STRLEN len)
6089
6090 "lex_next_chunk"
6091 NOTE: "lex_next_chunk" is experimental and may change or be removed
6092 without notice.
6093
6094 Reads in the next chunk of text to be lexed, appending it to
6095 "PL_parser->linestr". This should be called when lexing code has
6096 looked to the end of the current chunk and wants to know more. It
6097 is usual, but not necessary, for lexing to have consumed the
6098 entirety of the current chunk at this time.
6099
6100 If "PL_parser->bufptr" is pointing to the very end of the current
6101 chunk (i.e., the current chunk has been entirely consumed),
6102 normally the current chunk will be discarded at the same time that
6103 the new chunk is read in. If "flags" has the "LEX_KEEP_PREVIOUS"
6104 bit set, the current chunk will not be discarded. If the current
6105 chunk has not been entirely consumed, then it will not be discarded
6106 regardless of the flag.
6107
6108 Returns true if some new text was added to the buffer, or false if
6109 the buffer has reached the end of the input text.
6110
6111 bool lex_next_chunk(U32 flags)
6112
6113 "lex_peek_unichar"
6114 NOTE: "lex_peek_unichar" is experimental and may change or be
6115 removed without notice.
6116
6117 Looks ahead one (Unicode) character in the text currently being
6118 lexed. Returns the codepoint (unsigned integer value) of the next
6119 character, or -1 if lexing has reached the end of the input text.
6120 To consume the peeked character, use "lex_read_unichar".
6121
6122 If the next character is in (or extends into) the next chunk of
6123 input text, the next chunk will be read in. Normally the current
6124 chunk will be discarded at the same time, but if "flags" has the
6125 "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
6126 discarded.
6127
6128 If the input is being interpreted as UTF-8 and a UTF-8 encoding
6129 error is encountered, an exception is generated.
6130
6131 I32 lex_peek_unichar(U32 flags)
6132
6133 "lex_read_space"
6134 NOTE: "lex_read_space" is experimental and may change or be removed
6135 without notice.
6136
6137 Reads optional spaces, in Perl style, in the text currently being
6138 lexed. The spaces may include ordinary whitespace characters and
6139 Perl-style comments. "#line" directives are processed if
6140 encountered. "PL_parser->bufptr" is moved past the spaces, so that
6141 it points at a non-space character (or the end of the input text).
6142
6143 If spaces extend into the next chunk of input text, the next chunk
6144 will be read in. Normally the current chunk will be discarded at
6145 the same time, but if "flags" has the "LEX_KEEP_PREVIOUS" bit set,
6146 then the current chunk will not be discarded.
6147
6148 void lex_read_space(U32 flags)
6149
6150 "lex_read_to"
6151 NOTE: "lex_read_to" is experimental and may change or be removed
6152 without notice.
6153
6154 Consume text in the lexer buffer, from "PL_parser->bufptr" up to
6155 "ptr". This advances "PL_parser->bufptr" to match "ptr",
6156 performing the correct bookkeeping whenever a newline character is
6157 passed. This is the normal way to consume lexed text.
6158
6159 Interpretation of the buffer's octets can be abstracted out by
6160 using the slightly higher-level functions "lex_peek_unichar" and
6161 "lex_read_unichar".
6162
6163 void lex_read_to(char* ptr)
6164
6165 "lex_read_unichar"
6166 NOTE: "lex_read_unichar" is experimental and may change or be
6167 removed without notice.
6168
6169 Reads the next (Unicode) character in the text currently being
6170 lexed. Returns the codepoint (unsigned integer value) of the
6171 character read, and moves "PL_parser->bufptr" past the character,
6172 or returns -1 if lexing has reached the end of the input text. To
6173 non-destructively examine the next character, use
6174 "lex_peek_unichar" instead.
6175
6176 If the next character is in (or extends into) the next chunk of
6177 input text, the next chunk will be read in. Normally the current
6178 chunk will be discarded at the same time, but if "flags" has the
6179 "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
6180 discarded.
6181
6182 If the input is being interpreted as UTF-8 and a UTF-8 encoding
6183 error is encountered, an exception is generated.
6184
6185 I32 lex_read_unichar(U32 flags)
6186
6187 "lex_start"
6188 NOTE: "lex_start" is experimental and may change or be removed
6189 without notice.
6190
6191 Creates and initialises a new lexer/parser state object, supplying
6192 a context in which to lex and parse from a new source of Perl code.
6193 A pointer to the new state object is placed in "PL_parser". An
6194 entry is made on the save stack so that upon unwinding, the new
6195 state object will be destroyed and the former value of "PL_parser"
6196 will be restored. Nothing else need be done to clean up the
6197 parsing context.
6198
6199 The code to be parsed comes from "line" and "rsfp". "line", if
6200 non-null, provides a string (in SV form) containing code to be
6201 parsed. A copy of the string is made, so subsequent modification
6202 of "line" does not affect parsing. "rsfp", if non-null, provides
6203 an input stream from which code will be read to be parsed. If both
6204 are non-null, the code in "line" comes first and must consist of
6205 complete lines of input, and "rsfp" supplies the remainder of the
6206 source.
6207
6208 The "flags" parameter is reserved for future use. Currently it is
6209 only used by perl internally, so extensions should always pass
6210 zero.
6211
6212 void lex_start(SV* line, PerlIO *rsfp, U32 flags)
6213
6214 "lex_stuff_pv"
6215 NOTE: "lex_stuff_pv" is experimental and may change or be removed
6216 without notice.
6217
6218 Insert characters into the lexer buffer ("PL_parser->linestr"),
6219 immediately after the current lexing point ("PL_parser->bufptr"),
6220 reallocating the buffer if necessary. This means that lexing code
6221 that runs later will see the characters as if they had appeared in
6222 the input. It is not recommended to do this as part of normal
6223 parsing, and most uses of this facility run the risk of the
6224 inserted characters being interpreted in an unintended manner.
6225
6226 The string to be inserted is represented by octets starting at "pv"
6227 and continuing to the first nul. These octets are interpreted as
6228 either UTF-8 or Latin-1, according to whether the "LEX_STUFF_UTF8"
6229 flag is set in "flags". The characters are recoded for the lexer
6230 buffer, according to how the buffer is currently being interpreted
6231 ("lex_bufutf8"). If it is not convenient to nul-terminate a string
6232 to be inserted, the "lex_stuff_pvn" function is more appropriate.
6233
6234 void lex_stuff_pv(const char* pv, U32 flags)
6235
6236 "lex_stuff_pvn"
6237 NOTE: "lex_stuff_pvn" is experimental and may change or be removed
6238 without notice.
6239
6240 Insert characters into the lexer buffer ("PL_parser->linestr"),
6241 immediately after the current lexing point ("PL_parser->bufptr"),
6242 reallocating the buffer if necessary. This means that lexing code
6243 that runs later will see the characters as if they had appeared in
6244 the input. It is not recommended to do this as part of normal
6245 parsing, and most uses of this facility run the risk of the
6246 inserted characters being interpreted in an unintended manner.
6247
6248 The string to be inserted is represented by "len" octets starting
6249 at "pv". These octets are interpreted as either UTF-8 or Latin-1,
6250 according to whether the "LEX_STUFF_UTF8" flag is set in "flags".
6251 The characters are recoded for the lexer buffer, according to how
6252 the buffer is currently being interpreted ("lex_bufutf8"). If a
6253 string to be inserted is available as a Perl scalar, the
6254 "lex_stuff_sv" function is more convenient.
6255
6256 void lex_stuff_pvn(const char* pv, STRLEN len, U32 flags)
6257
6258 "lex_stuff_pvs"
6259 NOTE: "lex_stuff_pvs" is experimental and may change or be removed
6260 without notice.
6261
6262 Like "lex_stuff_pvn", but takes a literal string instead of a
6263 string/length pair.
6264
6265 void lex_stuff_pvs("pv", U32 flags)
6266
6267 "lex_stuff_sv"
6268 NOTE: "lex_stuff_sv" is experimental and may change or be removed
6269 without notice.
6270
6271 Insert characters into the lexer buffer ("PL_parser->linestr"),
6272 immediately after the current lexing point ("PL_parser->bufptr"),
6273 reallocating the buffer if necessary. This means that lexing code
6274 that runs later will see the characters as if they had appeared in
6275 the input. It is not recommended to do this as part of normal
6276 parsing, and most uses of this facility run the risk of the
6277 inserted characters being interpreted in an unintended manner.
6278
6279 The string to be inserted is the string value of "sv". The
6280 characters are recoded for the lexer buffer, according to how the
6281 buffer is currently being interpreted ("lex_bufutf8"). If a string
6282 to be inserted is not already a Perl scalar, the "lex_stuff_pvn"
6283 function avoids the need to construct a scalar.
6284
6285 void lex_stuff_sv(SV* sv, U32 flags)
6286
6287 "lex_unstuff"
6288 NOTE: "lex_unstuff" is experimental and may change or be removed
6289 without notice.
6290
6291 Discards text about to be lexed, from "PL_parser->bufptr" up to
6292 "ptr". Text following "ptr" will be moved, and the buffer
6293 shortened. This hides the discarded text from any lexing code that
6294 runs later, as if the text had never appeared.
6295
6296 This is not the normal way to consume lexed text. For that, use
6297 "lex_read_to".
6298
6299 void lex_unstuff(char* ptr)
6300
6301 "parse_arithexpr"
6302 NOTE: "parse_arithexpr" is experimental and may change or be
6303 removed without notice.
6304
6305 Parse a Perl arithmetic expression. This may contain operators of
6306 precedence down to the bit shift operators. The expression must be
6307 followed (and thus terminated) either by a comparison or lower-
6308 precedence operator or by something that would normally terminate
6309 an expression such as semicolon. If "flags" has the
6310 "PARSE_OPTIONAL" bit set, then the expression is optional,
6311 otherwise it is mandatory. It is up to the caller to ensure that
6312 the dynamic parser state ("PL_parser" et al) is correctly set to
6313 reflect the source of the code to be parsed and the lexical context
6314 for the expression.
6315
6316 The op tree representing the expression is returned. If an
6317 optional expression is absent, a null pointer is returned,
6318 otherwise the pointer will be non-null.
6319
6320 If an error occurs in parsing or compilation, in most cases a valid
6321 op tree is returned anyway. The error is reflected in the parser
6322 state, normally resulting in a single exception at the top level of
6323 parsing which covers all the compilation errors that occurred.
6324 Some compilation errors, however, will throw an exception
6325 immediately.
6326
6327 OP* parse_arithexpr(U32 flags)
6328
6329 "parse_barestmt"
6330 NOTE: "parse_barestmt" is experimental and may change or be removed
6331 without notice.
6332
6333 Parse a single unadorned Perl statement. This may be a normal
6334 imperative statement or a declaration that has compile-time effect.
6335 It does not include any label or other affixture. It is up to the
6336 caller to ensure that the dynamic parser state ("PL_parser" et al)
6337 is correctly set to reflect the source of the code to be parsed and
6338 the lexical context for the statement.
6339
6340 The op tree representing the statement is returned. This may be a
6341 null pointer if the statement is null, for example if it was
6342 actually a subroutine definition (which has compile-time side
6343 effects). If not null, it will be ops directly implementing the
6344 statement, suitable to pass to "newSTATEOP". It will not normally
6345 include a "nextstate" or equivalent op (except for those embedded
6346 in a scope contained entirely within the statement).
6347
6348 If an error occurs in parsing or compilation, in most cases a valid
6349 op tree (most likely null) is returned anyway. The error is
6350 reflected in the parser state, normally resulting in a single
6351 exception at the top level of parsing which covers all the
6352 compilation errors that occurred. Some compilation errors,
6353 however, will throw an exception immediately.
6354
6355 The "flags" parameter is reserved for future use, and must always
6356 be zero.
6357
6358 OP* parse_barestmt(U32 flags)
6359
6360 "parse_block"
6361 NOTE: "parse_block" is experimental and may change or be removed
6362 without notice.
6363
6364 Parse a single complete Perl code block. This consists of an
6365 opening brace, a sequence of statements, and a closing brace. The
6366 block constitutes a lexical scope, so "my" variables and various
6367 compile-time effects can be contained within it. It is up to the
6368 caller to ensure that the dynamic parser state ("PL_parser" et al)
6369 is correctly set to reflect the source of the code to be parsed and
6370 the lexical context for the statement.
6371
6372 The op tree representing the code block is returned. This is
6373 always a real op, never a null pointer. It will normally be a
6374 "lineseq" list, including "nextstate" or equivalent ops. No ops to
6375 construct any kind of runtime scope are included by virtue of it
6376 being a block.
6377
6378 If an error occurs in parsing or compilation, in most cases a valid
6379 op tree (most likely null) is returned anyway. The error is
6380 reflected in the parser state, normally resulting in a single
6381 exception at the top level of parsing which covers all the
6382 compilation errors that occurred. Some compilation errors,
6383 however, will throw an exception immediately.
6384
6385 The "flags" parameter is reserved for future use, and must always
6386 be zero.
6387
6388 OP* parse_block(U32 flags)
6389
6390 "parse_fullexpr"
6391 NOTE: "parse_fullexpr" is experimental and may change or be removed
6392 without notice.
6393
6394 Parse a single complete Perl expression. This allows the full
6395 expression grammar, including the lowest-precedence operators such
6396 as "or". The expression must be followed (and thus terminated) by
6397 a token that an expression would normally be terminated by: end-of-
6398 file, closing bracketing punctuation, semicolon, or one of the
6399 keywords that signals a postfix expression-statement modifier. If
6400 "flags" has the "PARSE_OPTIONAL" bit set, then the expression is
6401 optional, otherwise it is mandatory. It is up to the caller to
6402 ensure that the dynamic parser state ("PL_parser" et al) is
6403 correctly set to reflect the source of the code to be parsed and
6404 the lexical context for the expression.
6405
6406 The op tree representing the expression is returned. If an
6407 optional expression is absent, a null pointer is returned,
6408 otherwise the pointer will be non-null.
6409
6410 If an error occurs in parsing or compilation, in most cases a valid
6411 op tree is returned anyway. The error is reflected in the parser
6412 state, normally resulting in a single exception at the top level of
6413 parsing which covers all the compilation errors that occurred.
6414 Some compilation errors, however, will throw an exception
6415 immediately.
6416
6417 OP* parse_fullexpr(U32 flags)
6418
6419 "parse_fullstmt"
6420 NOTE: "parse_fullstmt" is experimental and may change or be removed
6421 without notice.
6422
6423 Parse a single complete Perl statement. This may be a normal
6424 imperative statement or a declaration that has compile-time effect,
6425 and may include optional labels. It is up to the caller to ensure
6426 that the dynamic parser state ("PL_parser" et al) is correctly set
6427 to reflect the source of the code to be parsed and the lexical
6428 context for the statement.
6429
6430 The op tree representing the statement is returned. This may be a
6431 null pointer if the statement is null, for example if it was
6432 actually a subroutine definition (which has compile-time side
6433 effects). If not null, it will be the result of a "newSTATEOP"
6434 call, normally including a "nextstate" or equivalent op.
6435
6436 If an error occurs in parsing or compilation, in most cases a valid
6437 op tree (most likely null) is returned anyway. The error is
6438 reflected in the parser state, normally resulting in a single
6439 exception at the top level of parsing which covers all the
6440 compilation errors that occurred. Some compilation errors,
6441 however, will throw an exception immediately.
6442
6443 The "flags" parameter is reserved for future use, and must always
6444 be zero.
6445
6446 OP* parse_fullstmt(U32 flags)
6447
6448 "parse_label"
6449 NOTE: "parse_label" is experimental and may change or be removed
6450 without notice.
6451
6452 Parse a single label, possibly optional, of the type that may
6453 prefix a Perl statement. It is up to the caller to ensure that the
6454 dynamic parser state ("PL_parser" et al) is correctly set to
6455 reflect the source of the code to be parsed. If "flags" has the
6456 "PARSE_OPTIONAL" bit set, then the label is optional, otherwise it
6457 is mandatory.
6458
6459 The name of the label is returned in the form of a fresh scalar.
6460 If an optional label is absent, a null pointer is returned.
6461
6462 If an error occurs in parsing, which can only occur if the label is
6463 mandatory, a valid label is returned anyway. The error is
6464 reflected in the parser state, normally resulting in a single
6465 exception at the top level of parsing which covers all the
6466 compilation errors that occurred.
6467
6468 SV* parse_label(U32 flags)
6469
6470 "parse_listexpr"
6471 NOTE: "parse_listexpr" is experimental and may change or be removed
6472 without notice.
6473
6474 Parse a Perl list expression. This may contain operators of
6475 precedence down to the comma operator. The expression must be
6476 followed (and thus terminated) either by a low-precedence logic
6477 operator such as "or" or by something that would normally terminate
6478 an expression such as semicolon. If "flags" has the
6479 "PARSE_OPTIONAL" bit set, then the expression is optional,
6480 otherwise it is mandatory. It is up to the caller to ensure that
6481 the dynamic parser state ("PL_parser" et al) is correctly set to
6482 reflect the source of the code to be parsed and the lexical context
6483 for the expression.
6484
6485 The op tree representing the expression is returned. If an
6486 optional expression is absent, a null pointer is returned,
6487 otherwise the pointer will be non-null.
6488
6489 If an error occurs in parsing or compilation, in most cases a valid
6490 op tree is returned anyway. The error is reflected in the parser
6491 state, normally resulting in a single exception at the top level of
6492 parsing which covers all the compilation errors that occurred.
6493 Some compilation errors, however, will throw an exception
6494 immediately.
6495
6496 OP* parse_listexpr(U32 flags)
6497
6498 "parse_stmtseq"
6499 NOTE: "parse_stmtseq" is experimental and may change or be removed
6500 without notice.
6501
6502 Parse a sequence of zero or more Perl statements. These may be
6503 normal imperative statements, including optional labels, or
6504 declarations that have compile-time effect, or any mixture thereof.
6505 The statement sequence ends when a closing brace or end-of-file is
6506 encountered in a place where a new statement could have validly
6507 started. It is up to the caller to ensure that the dynamic parser
6508 state ("PL_parser" et al) is correctly set to reflect the source of
6509 the code to be parsed and the lexical context for the statements.
6510
6511 The op tree representing the statement sequence is returned. This
6512 may be a null pointer if the statements were all null, for example
6513 if there were no statements or if there were only subroutine
6514 definitions (which have compile-time side effects). If not null,
6515 it will be a "lineseq" list, normally including "nextstate" or
6516 equivalent ops.
6517
6518 If an error occurs in parsing or compilation, in most cases a valid
6519 op tree is returned anyway. The error is reflected in the parser
6520 state, normally resulting in a single exception at the top level of
6521 parsing which covers all the compilation errors that occurred.
6522 Some compilation errors, however, will throw an exception
6523 immediately.
6524
6525 The "flags" parameter is reserved for future use, and must always
6526 be zero.
6527
6528 OP* parse_stmtseq(U32 flags)
6529
6530 "parse_subsignature"
6531 NOTE: "parse_subsignature" is experimental and may change or be
6532 removed without notice.
6533
6534 Parse a subroutine signature declaration. This is the contents of
6535 the parentheses following a named or anonymous subroutine
6536 declaration when the "signatures" feature is enabled. Note that
6537 this function neither expects nor consumes the opening and closing
6538 parentheses around the signature; it is the caller's job to handle
6539 these.
6540
6541 This function must only be called during parsing of a subroutine;
6542 after "start_subparse" has been called. It might allocate lexical
6543 variables on the pad for the current subroutine.
6544
6545 The op tree to unpack the arguments from the stack at runtime is
6546 returned. This op tree should appear at the beginning of the
6547 compiled function. The caller may wish to use "op_append_list" to
6548 build their function body after it, or splice it together with the
6549 body before calling "newATTRSUB".
6550
6551 The "flags" parameter is reserved for future use, and must always
6552 be zero.
6553
6554 OP* parse_subsignature(U32 flags)
6555
6556 "parse_termexpr"
6557 NOTE: "parse_termexpr" is experimental and may change or be removed
6558 without notice.
6559
6560 Parse a Perl term expression. This may contain operators of
6561 precedence down to the assignment operators. The expression must
6562 be followed (and thus terminated) either by a comma or lower-
6563 precedence operator or by something that would normally terminate
6564 an expression such as semicolon. If "flags" has the
6565 "PARSE_OPTIONAL" bit set, then the expression is optional,
6566 otherwise it is mandatory. It is up to the caller to ensure that
6567 the dynamic parser state ("PL_parser" et al) is correctly set to
6568 reflect the source of the code to be parsed and the lexical context
6569 for the expression.
6570
6571 The op tree representing the expression is returned. If an
6572 optional expression is absent, a null pointer is returned,
6573 otherwise the pointer will be non-null.
6574
6575 If an error occurs in parsing or compilation, in most cases a valid
6576 op tree is returned anyway. The error is reflected in the parser
6577 state, normally resulting in a single exception at the top level of
6578 parsing which covers all the compilation errors that occurred.
6579 Some compilation errors, however, will throw an exception
6580 immediately.
6581
6582 OP* parse_termexpr(U32 flags)
6583
6584 "PL_parser"
6585 Pointer to a structure encapsulating the state of the parsing
6586 operation currently in progress. The pointer can be locally
6587 changed to perform a nested parse without interfering with the
6588 state of an outer parse. Individual members of "PL_parser" have
6589 their own documentation.
6590
6591 "PL_parser->bufend"
6592 NOTE: "PL_parser->bufend" is experimental and may change or be
6593 removed without notice.
6594
6595 Direct pointer to the end of the chunk of text currently being
6596 lexed, the end of the lexer buffer. This is equal to
6597 "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)". A "NUL"
6598 character (zero octet) is always located at the end of the buffer,
6599 and does not count as part of the buffer's contents.
6600
6601 "PL_parser->bufptr"
6602 NOTE: "PL_parser->bufptr" is experimental and may change or be
6603 removed without notice.
6604
6605 Points to the current position of lexing inside the lexer buffer.
6606 Characters around this point may be freely examined, within the
6607 range delimited by "SvPVX("PL_parser->linestr")" and
6608 "PL_parser->bufend". The octets of the buffer may be intended to
6609 be interpreted as either UTF-8 or Latin-1, as indicated by
6610 "lex_bufutf8".
6611
6612 Lexing code (whether in the Perl core or not) moves this pointer
6613 past the characters that it consumes. It is also expected to
6614 perform some bookkeeping whenever a newline character is consumed.
6615 This movement can be more conveniently performed by the function
6616 "lex_read_to", which handles newlines appropriately.
6617
6618 Interpretation of the buffer's octets can be abstracted out by
6619 using the slightly higher-level functions "lex_peek_unichar" and
6620 "lex_read_unichar".
6621
6622 "PL_parser->linestart"
6623 NOTE: "PL_parser->linestart" is experimental and may change or be
6624 removed without notice.
6625
6626 Points to the start of the current line inside the lexer buffer.
6627 This is useful for indicating at which column an error occurred,
6628 and not much else. This must be updated by any lexing code that
6629 consumes a newline; the function "lex_read_to" handles this detail.
6630
6631 "PL_parser->linestr"
6632 NOTE: "PL_parser->linestr" is experimental and may change or be
6633 removed without notice.
6634
6635 Buffer scalar containing the chunk currently under consideration of
6636 the text currently being lexed. This is always a plain string
6637 scalar (for which "SvPOK" is true). It is not intended to be used
6638 as a scalar by normal scalar means; instead refer to the buffer
6639 directly by the pointer variables described below.
6640
6641 The lexer maintains various "char*" pointers to things in the
6642 "PL_parser->linestr" buffer. If "PL_parser->linestr" is ever
6643 reallocated, all of these pointers must be updated. Don't attempt
6644 to do this manually, but rather use "lex_grow_linestr" if you need
6645 to reallocate the buffer.
6646
6647 The content of the text chunk in the buffer is commonly exactly one
6648 complete line of input, up to and including a newline terminator,
6649 but there are situations where it is otherwise. The octets of the
6650 buffer may be intended to be interpreted as either UTF-8 or
6651 Latin-1. The function "lex_bufutf8" tells you which. Do not use
6652 the "SvUTF8" flag on this scalar, which may disagree with it.
6653
6654 For direct examination of the buffer, the variable
6655 "PL_parser->bufend" points to the end of the buffer. The current
6656 lexing position is pointed to by "PL_parser->bufptr". Direct use
6657 of these pointers is usually preferable to examination of the
6658 scalar through normal scalar means.
6659
6660 "wrap_keyword_plugin"
6661 NOTE: "wrap_keyword_plugin" is experimental and may change or be
6662 removed without notice.
6663
6664 Puts a C function into the chain of keyword plugins. This is the
6665 preferred way to manipulate the "PL_keyword_plugin" variable.
6666 "new_plugin" is a pointer to the C function that is to be added to
6667 the keyword plugin chain, and "old_plugin_p" points to the storage
6668 location where a pointer to the next function in the chain will be
6669 stored. The value of "new_plugin" is written into the
6670 "PL_keyword_plugin" variable, while the value previously stored
6671 there is written to *old_plugin_p.
6672
6673 "PL_keyword_plugin" is global to an entire process, and a module
6674 wishing to hook keyword parsing may find itself invoked more than
6675 once per process, typically in different threads. To handle that
6676 situation, this function is idempotent. The location *old_plugin_p
6677 must initially (once per process) contain a null pointer. A C
6678 variable of static duration (declared at file scope, typically also
6679 marked "static" to give it internal linkage) will be implicitly
6680 initialised appropriately, if it does not have an explicit
6681 initialiser. This function will only actually modify the plugin
6682 chain if it finds *old_plugin_p to be null. This function is also
6683 thread safe on the small scale. It uses appropriate locking to
6684 avoid race conditions in accessing "PL_keyword_plugin".
6685
6686 When this function is called, the function referenced by
6687 "new_plugin" must be ready to be called, except for *old_plugin_p
6688 being unfilled. In a threading situation, "new_plugin" may be
6689 called immediately, even before this function has returned.
6690 *old_plugin_p will always be appropriately set before "new_plugin"
6691 is called. If "new_plugin" decides not to do anything special with
6692 the identifier that it is given (which is the usual case for most
6693 calls to a keyword plugin), it must chain the plugin function
6694 referenced by *old_plugin_p.
6695
6696 Taken all together, XS code to install a keyword plugin should
6697 typically look something like this:
6698
6699 static Perl_keyword_plugin_t next_keyword_plugin;
6700 static OP *my_keyword_plugin(pTHX_
6701 char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
6702 {
6703 if (memEQs(keyword_ptr, keyword_len,
6704 "my_new_keyword")) {
6705 ...
6706 } else {
6707 return next_keyword_plugin(aTHX_
6708 keyword_ptr, keyword_len, op_ptr);
6709 }
6710 }
6711 BOOT:
6712 wrap_keyword_plugin(my_keyword_plugin,
6713 &next_keyword_plugin);
6714
6715 Direct access to "PL_keyword_plugin" should be avoided.
6716
6717 void wrap_keyword_plugin(Perl_keyword_plugin_t new_plugin,
6718 Perl_keyword_plugin_t *old_plugin_p)
6719
6721 "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
6722 This macro should be used as a statement. It declares a private
6723 variable (whose name begins with an underscore) that is needed by
6724 the other macros in this section. Failing to include this
6725 correctly should lead to a syntax error. For compatibility with
6726 C89 C compilers it should be placed in a block before any
6727 executable statements.
6728
6729 void DECLARATION_FOR_LC_NUMERIC_MANIPULATION
6730
6731 "foldEQ_locale"
6732 Returns true if the leading "len" bytes of the strings "s1" and
6733 "s2" are the same case-insensitively in the current locale; false
6734 otherwise.
6735
6736 I32 foldEQ_locale(const char* a, const char* b, I32 len)
6737
6738 "HAS_DUPLOCALE"
6739 This symbol, if defined, indicates that the "duplocale" routine is
6740 available to duplicate a locale object.
6741
6742 "HAS_FREELOCALE"
6743 This symbol, if defined, indicates that the "freelocale" routine is
6744 available to deallocates the resources associated with a locale
6745 object.
6746
6747 "HAS_LC_MONETARY_2008"
6748 This symbol, if defined, indicates that the localeconv routine is
6749 available and has the additional members added in "POSIX"
6750 1003.1-2008.
6751
6752 "HAS_LOCALECONV"
6753 This symbol, if defined, indicates that the "localeconv" routine is
6754 available for numeric and monetary formatting conventions.
6755
6756 "HAS_LOCALECONV_L"
6757 This symbol, if defined, indicates that the "localeconv_l" routine
6758 is available to query certain information about a locale.
6759
6760 "HAS_NEWLOCALE"
6761 This symbol, if defined, indicates that the "newlocale" routine is
6762 available to return a new locale object or modify an existing
6763 locale object.
6764
6765 "HAS_NL_LANGINFO"
6766 This symbol, if defined, indicates that the "nl_langinfo" routine
6767 is available to return local data. You will also need langinfo.h
6768 and therefore "I_LANGINFO".
6769
6770 "HAS_QUERYLOCALE"
6771 This symbol, if defined, indicates that the "querylocale" routine
6772 is available to return the name of the locale for a category mask.
6773
6774 "HAS_SETLOCALE"
6775 This symbol, if defined, indicates that the "setlocale" routine is
6776 available to handle locale-specific ctype implementations.
6777
6778 "HAS_SETLOCALE_R"
6779 This symbol, if defined, indicates that the "setlocale_r" routine
6780 is available to setlocale re-entrantly.
6781
6782 "HAS_THREAD_SAFE_NL_LANGINFO_L"
6783 This symbol, when defined, indicates presence of the
6784 "nl_langinfo_l()" function, and that it is thread-safe.
6785
6786 "HAS_USELOCALE"
6787 This symbol, if defined, indicates that the "uselocale" routine is
6788 available to set the current locale for the calling thread.
6789
6790 "I_LANGINFO"
6791 This symbol, if defined, indicates that langinfo.h exists and
6792 should be included.
6793
6794 #ifdef I_LANGINFO
6795 #include <langinfo.h>
6796 #endif
6797
6798 "I_LOCALE"
6799 This symbol, if defined, indicates to the C program that it should
6800 include locale.h.
6801
6802 #ifdef I_LOCALE
6803 #include <locale.h>
6804 #endif
6805
6806 "IN_LOCALE"
6807 Evaluates to TRUE if the plain locale pragma without a parameter
6808 ("use locale") is in effect.
6809
6810 bool IN_LOCALE
6811
6812 "IN_LOCALE_COMPILETIME"
6813 Evaluates to TRUE if, when compiling a perl program (including an
6814 "eval") if the plain locale pragma without a parameter
6815 ("use locale") is in effect.
6816
6817 bool IN_LOCALE_COMPILETIME
6818
6819 "IN_LOCALE_RUNTIME"
6820 Evaluates to TRUE if, when executing a perl program (including an
6821 "eval") if the plain locale pragma without a parameter
6822 ("use locale") is in effect.
6823
6824 bool IN_LOCALE_RUNTIME
6825
6826 "I_XLOCALE"
6827 This symbol, if defined, indicates to the C program that it should
6828 include xlocale.h to get "uselocale()" and its friends.
6829
6830 #ifdef I_XLOCALE
6831 #include <xlocale.h>
6832 #endif
6833
6834 "Perl_langinfo"
6835 This is an (almost) drop-in replacement for the system
6836 nl_langinfo(3), taking the same "item" parameter values, and
6837 returning the same information. But it is more thread-safe than
6838 regular "nl_langinfo()", and hides the quirks of Perl's locale
6839 handling from your code, and can be used on systems that lack a
6840 native "nl_langinfo".
6841
6842 Expanding on these:
6843
6844 • The reason it isn't quite a drop-in replacement is actually an
6845 advantage. The only difference is that it returns
6846 "const char *", whereas plain "nl_langinfo()" returns "char *",
6847 but you are (only by documentation) forbidden to write into the
6848 buffer. By declaring this "const", the compiler enforces this
6849 restriction, so if it is violated, you know at compilation
6850 time, rather than getting segfaults at runtime.
6851
6852 • It delivers the correct results for the "RADIXCHAR" and
6853 "THOUSEP" items, without you having to write extra code. The
6854 reason for the extra code would be because these are from the
6855 "LC_NUMERIC" locale category, which is normally kept set by
6856 Perl so that the radix is a dot, and the separator is the empty
6857 string, no matter what the underlying locale is supposed to be,
6858 and so to get the expected results, you have to temporarily
6859 toggle into the underlying locale, and later toggle back. (You
6860 could use plain "nl_langinfo" and
6861 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" for this but then you
6862 wouldn't get the other advantages of "Perl_langinfo()"; not
6863 keeping "LC_NUMERIC" in the C (or equivalent) locale would
6864 break a lot of CPAN, which is expecting the radix (decimal
6865 point) character to be a dot.)
6866
6867 • The system function it replaces can have its static return
6868 buffer trashed, not only by a subsequent call to that function,
6869 but by a "freelocale", "setlocale", or other locale change.
6870 The returned buffer of this function is not changed until the
6871 next call to it, so the buffer is never in a trashed state.
6872
6873 • Its return buffer is per-thread, so it also is never
6874 overwritten by a call to this function from another thread;
6875 unlike the function it replaces.
6876
6877 • But most importantly, it works on systems that don't have
6878 "nl_langinfo", such as Windows, hence makes your code more
6879 portable. Of the fifty-some possible items specified by the
6880 POSIX 2008 standard,
6881 <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
6882 only one is completely unimplemented, though on non-Windows
6883 platforms, another significant one is also not implemented).
6884 It uses various techniques to recover the other items,
6885 including calling localeconv(3), and strftime(3), both of which
6886 are specified in C89, so should be always be available. Later
6887 "strftime()" versions have additional capabilities; "" is
6888 returned for those not available on your system.
6889
6890 It is important to note that when called with an item that is
6891 recovered by using "localeconv", the buffer from any previous
6892 explicit call to "localeconv" will be overwritten. This means
6893 you must save that buffer's contents if you need to access them
6894 after a call to this function. (But note that you might not
6895 want to be using "localeconv()" directly anyway, because of
6896 issues like the ones listed in the second item of this list
6897 (above) for "RADIXCHAR" and "THOUSEP". You can use the methods
6898 given in perlcall to call "localeconv" in POSIX and avoid all
6899 the issues, but then you have a hash to unpack).
6900
6901 The details for those items which may deviate from what this
6902 emulation returns and what a native "nl_langinfo()" would
6903 return are specified in I18N::Langinfo.
6904
6905 When using "Perl_langinfo" on systems that don't have a native
6906 "nl_langinfo()", you must
6907
6908 #include "perl_langinfo.h"
6909
6910 before the "perl.h" "#include". You can replace your "langinfo.h"
6911 "#include" with this one. (Doing it this way keeps out the symbols
6912 that plain "langinfo.h" would try to import into the namespace for
6913 code that doesn't need it.)
6914
6915 The original impetus for "Perl_langinfo()" was so that code that
6916 needs to find out the current currency symbol, floating point radix
6917 character, or digit grouping separator can use, on all systems, the
6918 simpler and more thread-friendly "nl_langinfo" API instead of
6919 localeconv(3) which is a pain to make thread-friendly. For other
6920 fields returned by "localeconv", it is better to use the methods
6921 given in perlcall to call "POSIX::localeconv()", which is thread-
6922 friendly.
6923
6924 const char* Perl_langinfo(const nl_item item)
6925
6926 "Perl_setlocale"
6927 This is an (almost) drop-in replacement for the system
6928 setlocale(3), taking the same parameters, and returning the same
6929 information, except that it returns the correct underlying
6930 "LC_NUMERIC" locale. Regular "setlocale" will instead return "C"
6931 if the underlying locale has a non-dot decimal point character, or
6932 a non-empty thousands separator for displaying floating point
6933 numbers. This is because perl keeps that locale category such that
6934 it has a dot and empty separator, changing the locale briefly
6935 during the operations where the underlying one is required.
6936 "Perl_setlocale" knows about this, and compensates; regular
6937 "setlocale" doesn't.
6938
6939 Another reason it isn't completely a drop-in replacement is that it
6940 is declared to return "const char *", whereas the system setlocale
6941 omits the "const" (presumably because its API was specified long
6942 ago, and can't be updated; it is illegal to change the information
6943 "setlocale" returns; doing so leads to segfaults.)
6944
6945 Finally, "Perl_setlocale" works under all circumstances, whereas
6946 plain "setlocale" can be completely ineffective on some platforms
6947 under some configurations.
6948
6949 "Perl_setlocale" should not be used to change the locale except on
6950 systems where the predefined variable "${^SAFE_LOCALES}" is 1. On
6951 some such systems, the system "setlocale()" is ineffective,
6952 returning the wrong information, and failing to actually change the
6953 locale. "Perl_setlocale", however works properly in all
6954 circumstances.
6955
6956 The return points to a per-thread static buffer, which is
6957 overwritten the next time "Perl_setlocale" is called from the same
6958 thread.
6959
6960 const char* Perl_setlocale(const int category,
6961 const char* locale)
6962
6963 "RESTORE_LC_NUMERIC"
6964 This is used in conjunction with one of the macros
6965 "STORE_LC_NUMERIC_SET_TO_NEEDED" and
6966 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
6967 "LC_NUMERIC" state.
6968
6969 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
6970 made to declare at compile time a private variable used by this
6971 macro and the two "STORE" ones. This macro should be called as a
6972 single statement, not an expression, but with an empty argument
6973 list, like this:
6974
6975 {
6976 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
6977 ...
6978 RESTORE_LC_NUMERIC();
6979 ...
6980 }
6981
6982 void RESTORE_LC_NUMERIC()
6983
6984 "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
6985 This symbol, if defined, indicates that the setlocale routine is
6986 available and it accepts any input locale name as valid.
6987
6988 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
6989 This is used by XS code that is "LC_NUMERIC" locale-aware to force
6990 the locale for category "LC_NUMERIC" to be what perl thinks is the
6991 current underlying locale. (The perl interpreter could be wrong
6992 about what the underlying locale actually is if some C or XS code
6993 has called the C library function setlocale(3) behind its back;
6994 calling "sync_locale" before calling this macro will update perl's
6995 records.)
6996
6997 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
6998 made to declare at compile time a private variable used by this
6999 macro. This macro should be called as a single statement, not an
7000 expression, but with an empty argument list, like this:
7001
7002 {
7003 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7004 ...
7005 STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
7006 ...
7007 RESTORE_LC_NUMERIC();
7008 ...
7009 }
7010
7011 The private variable is used to save the current locale state, so
7012 that the requisite matching call to "RESTORE_LC_NUMERIC" can
7013 restore it.
7014
7015 On threaded perls not operating with thread-safe functionality,
7016 this macro uses a mutex to force a critical section. Therefore the
7017 matching RESTORE should be close by, and guaranteed to be called.
7018
7019 void STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
7020
7021 "STORE_LC_NUMERIC_SET_TO_NEEDED"
7022 This is used to help wrap XS or C code that is "LC_NUMERIC" locale-
7023 aware. This locale category is generally kept set to a locale
7024 where the decimal radix character is a dot, and the separator
7025 between groups of digits is empty. This is because most XS code
7026 that reads floating point numbers is expecting them to have this
7027 syntax.
7028
7029 This macro makes sure the current "LC_NUMERIC" state is set
7030 properly, to be aware of locale if the call to the XS or C code
7031 from the Perl program is from within the scope of a "use locale";
7032 or to ignore locale if the call is instead from outside such scope.
7033
7034 This macro is the start of wrapping the C or XS code; the wrap
7035 ending is done by calling the "RESTORE_LC_NUMERIC" macro after the
7036 operation. Otherwise the state can be changed that will adversely
7037 affect other XS code.
7038
7039 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
7040 made to declare at compile time a private variable used by this
7041 macro. This macro should be called as a single statement, not an
7042 expression, but with an empty argument list, like this:
7043
7044 {
7045 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7046 ...
7047 STORE_LC_NUMERIC_SET_TO_NEEDED();
7048 ...
7049 RESTORE_LC_NUMERIC();
7050 ...
7051 }
7052
7053 On threaded perls not operating with thread-safe functionality,
7054 this macro uses a mutex to force a critical section. Therefore the
7055 matching RESTORE should be close by, and guaranteed to be called;
7056 see "WITH_LC_NUMERIC_SET_TO_NEEDED" for a more contained way to
7057 ensure that.
7058
7059 void STORE_LC_NUMERIC_SET_TO_NEEDED()
7060
7061 "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
7062 Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
7063 provided as the precalculated value of "IN_LC(LC_NUMERIC)". It is
7064 the caller's responsibility to ensure that the status of
7065 "PL_compiling" and "PL_hints" cannot have changed since the
7066 precalculation.
7067
7068 void STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric)
7069
7070 "switch_to_global_locale"
7071 On systems without locale support, or on typical single-threaded
7072 builds, or on platforms that do not support per-thread locale
7073 operations, this function does nothing. On such systems that do
7074 have locale support, only a locale global to the whole program is
7075 available.
7076
7077 On multi-threaded builds on systems that do have per-thread locale
7078 operations, this function converts the thread it is running in to
7079 use the global locale. This is for code that has not yet or cannot
7080 be updated to handle multi-threaded locale operation. As long as
7081 only a single thread is so-converted, everything works fine, as all
7082 the other threads continue to ignore the global one, so only this
7083 thread looks at it.
7084
7085 However, on Windows systems this isn't quite true prior to Visual
7086 Studio 15, at which point Microsoft fixed a bug. A race can occur
7087 if you use the following operations on earlier Windows platforms:
7088
7089 POSIX::localeconv
7090 I18N::Langinfo, items "CRNCYSTR" and "THOUSEP"
7091 "Perl_langinfo" in perlapi, items "CRNCYSTR" and "THOUSEP"
7092
7093 The first item is not fixable (except by upgrading to a later
7094 Visual Studio release), but it would be possible to work around the
7095 latter two items by using the Windows API functions
7096 "GetNumberFormat" and "GetCurrencyFormat"; patches welcome.
7097
7098 Without this function call, threads that use the setlocale(3)
7099 system function will not work properly, as all the locale-sensitive
7100 functions will look at the per-thread locale, and "setlocale" will
7101 have no effect on this thread.
7102
7103 Perl code should convert to either call "Perl_setlocale" (which is
7104 a drop-in for the system "setlocale") or use the methods given in
7105 perlcall to call "POSIX::setlocale". Either one will transparently
7106 properly handle all cases of single- vs multi-thread, POSIX
7107 2008-supported or not.
7108
7109 Non-Perl libraries, such as "gtk", that call the system "setlocale"
7110 can continue to work if this function is called before transferring
7111 control to the library.
7112
7113 Upon return from the code that needs to use the global locale,
7114 "sync_locale()" should be called to restore the safe multi-thread
7115 operation.
7116
7117 void switch_to_global_locale()
7118
7119 "sync_locale"
7120 "Perl_setlocale" can be used at any time to query or change the
7121 locale (though changing the locale is antisocial and dangerous on
7122 multi-threaded systems that don't have multi-thread safe locale
7123 operations. (See "Multi-threaded operation" in perllocale). Using
7124 the system setlocale(3) should be avoided. Nevertheless, certain
7125 non-Perl libraries called from XS, such as "Gtk" do so, and this
7126 can't be changed. When the locale is changed by XS code that
7127 didn't use "Perl_setlocale", Perl needs to be told that the locale
7128 has changed. Use this function to do so, before returning to Perl.
7129
7130 The return value is a boolean: TRUE if the global locale at the
7131 time of call was in effect; and FALSE if a per-thread locale was in
7132 effect. This can be used by the caller that needs to restore
7133 things as-they-were to decide whether or not to call
7134 "Perl_switch_to_global_locale".
7135
7136 bool sync_locale()
7137
7138 "WITH_LC_NUMERIC_SET_TO_NEEDED"
7139 This macro invokes the supplied statement or block within the
7140 context of a "STORE_LC_NUMERIC_SET_TO_NEEDED" ..
7141 "RESTORE_LC_NUMERIC" pair if required, so eg:
7142
7143 WITH_LC_NUMERIC_SET_TO_NEEDED(
7144 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
7145 );
7146
7147 is equivalent to:
7148
7149 {
7150 #ifdef USE_LOCALE_NUMERIC
7151 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7152 STORE_LC_NUMERIC_SET_TO_NEEDED();
7153 #endif
7154 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
7155 #ifdef USE_LOCALE_NUMERIC
7156 RESTORE_LC_NUMERIC();
7157 #endif
7158 }
7159
7160 void WITH_LC_NUMERIC_SET_TO_NEEDED(block)
7161
7162 "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
7163 Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
7164 as the precalculated value of "IN_LC(LC_NUMERIC)". It is the
7165 caller's responsibility to ensure that the status of "PL_compiling"
7166 and "PL_hints" cannot have changed since the precalculation.
7167
7168 void WITH_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric, block)
7169
7171 "Magic" is special data attached to SV structures in order to give them
7172 "magical" properties. When any Perl code tries to read from, or assign
7173 to, an SV marked as magical, it calls the 'get' or 'set' function
7174 associated with that SV's magic. A get is called prior to reading an
7175 SV, in order to give it a chance to update its internal value (get on
7176 $. writes the line number of the last read filehandle into the SV's IV
7177 slot), while set is called after an SV has been written to, in order to
7178 allow it to make use of its changed value (set on $/ copies the SV's
7179 new value to the PL_rs global variable).
7180
7181 Magic is implemented as a linked list of MAGIC structures attached to
7182 the SV. Each MAGIC struct holds the type of the magic, a pointer to an
7183 array of functions that implement the get(), set(), length() etc
7184 functions, plus space for some flags and pointers. For example, a tied
7185 variable has a MAGIC structure that contains a pointer to the object
7186 associated with the tie.
7187
7188 "mg_clear"
7189 Clear something magical that the SV represents. See "sv_magic".
7190
7191 int mg_clear(SV* sv)
7192
7193 "mg_copy"
7194 Copies the magic from one SV to another. See "sv_magic".
7195
7196 int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
7197
7198 "mg_find"
7199 Finds the magic pointer for "type" matching the SV. See
7200 "sv_magic".
7201
7202 MAGIC* mg_find(const SV* sv, int type)
7203
7204 "mg_findext"
7205 Finds the magic pointer of "type" with the given "vtbl" for the
7206 "SV". See "sv_magicext".
7207
7208 MAGIC* mg_findext(const SV* sv, int type, const MGVTBL *vtbl)
7209
7210 "mg_free"
7211 Free any magic storage used by the SV. See "sv_magic".
7212
7213 int mg_free(SV* sv)
7214
7215 "mg_freeext"
7216 Remove any magic of type "how" using virtual table "vtbl" from the
7217 SV "sv". See "sv_magic".
7218
7219 "mg_freeext(sv, how, NULL)" is equivalent to "mg_free_type(sv,
7220 how)".
7221
7222 void mg_freeext(SV* sv, int how, const MGVTBL *vtbl)
7223
7224 "mg_free_type"
7225 Remove any magic of type "how" from the SV "sv". See "sv_magic".
7226
7227 void mg_free_type(SV* sv, int how)
7228
7229 "mg_get"
7230 Do magic before a value is retrieved from the SV. The type of SV
7231 must be >= "SVt_PVMG". See "sv_magic".
7232
7233 int mg_get(SV* sv)
7234
7235 "mg_length"
7236 "DEPRECATED!" It is planned to remove "mg_length" from a future
7237 release of Perl. Do not use it for new code; remove it from
7238 existing code.
7239
7240 Reports on the SV's length in bytes, calling length magic if
7241 available, but does not set the UTF8 flag on "sv". It will fall
7242 back to 'get' magic if there is no 'length' magic, but with no
7243 indication as to whether it called 'get' magic. It assumes "sv" is
7244 a "PVMG" or higher. Use "sv_len()" instead.
7245
7246 U32 mg_length(SV* sv)
7247
7248 "mg_magical"
7249 Turns on the magical status of an SV. See "sv_magic".
7250
7251 void mg_magical(SV* sv)
7252
7253 "mg_set"
7254 Do magic after a value is assigned to the SV. See "sv_magic".
7255
7256 int mg_set(SV* sv)
7257
7258 "SvTIED_obj"
7259 Described in perlinterp.
7260
7261 SvTIED_obj(SV *sv, MAGIC *mg)
7262
7264 "HASATTRIBUTE_MALLOC"
7265 Can we handle "GCC" attribute for malloc-style functions.
7266
7267 "HAS_MALLOC_GOOD_SIZE"
7268 This symbol, if defined, indicates that the "malloc_good_size"
7269 routine is available for use.
7270
7271 "HAS_MALLOC_SIZE"
7272 This symbol, if defined, indicates that the "malloc_size" routine
7273 is available for use.
7274
7275 "I_MALLOCMALLOC"
7276 This symbol, if defined, indicates to the C program that it should
7277 include malloc/malloc.h.
7278
7279 #ifdef I_MALLOCMALLOC
7280 #include <mallocmalloc.h>
7281 #endif
7282
7283 "MYMALLOC"
7284 This symbol, if defined, indicates that we're using our own malloc.
7285
7286 "Newx"
7287 The XSUB-writer's interface to the C "malloc" function.
7288
7289 Memory obtained by this should ONLY be freed with "Safefree".
7290
7291 In 5.9.3, Newx() and friends replace the older New() API, and drops
7292 the first parameter, x, a debug aid which allowed callers to
7293 identify themselves. This aid has been superseded by a new build
7294 option, PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhacktips). The
7295 older API is still there for use in XS modules supporting older
7296 perls.
7297
7298 void Newx(void* ptr, int nitems, type)
7299
7300 "Newxc"
7301 The XSUB-writer's interface to the C "malloc" function, with cast.
7302 See also "Newx".
7303
7304 Memory obtained by this should ONLY be freed with "Safefree".
7305
7306 void Newxc(void* ptr, int nitems, type, cast)
7307
7308 "Newxz"
7309 The XSUB-writer's interface to the C "malloc" function. The
7310 allocated memory is zeroed with "memzero". See also "Newx".
7311
7312 Memory obtained by this should ONLY be freed with "Safefree".
7313
7314 void Newxz(void* ptr, int nitems, type)
7315
7316 "PERL_MALLOC_WRAP"
7317 This symbol, if defined, indicates that we'd like malloc wrap
7318 checks.
7319
7320 "Renew"
7321 The XSUB-writer's interface to the C "realloc" function.
7322
7323 Memory obtained by this should ONLY be freed with "Safefree".
7324
7325 void Renew(void* ptr, int nitems, type)
7326
7327 "Renewc"
7328 The XSUB-writer's interface to the C "realloc" function, with cast.
7329
7330 Memory obtained by this should ONLY be freed with "Safefree".
7331
7332 void Renewc(void* ptr, int nitems, type, cast)
7333
7334 "Safefree"
7335 The XSUB-writer's interface to the C "free" function.
7336
7337 This should ONLY be used on memory obtained using "Newx" and
7338 friends.
7339
7340 void Safefree(void* ptr)
7341
7342 "safesyscalloc"
7343 Safe version of system's calloc()
7344
7345 Malloc_t safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
7346
7347 "safesysfree"
7348 Safe version of system's free()
7349
7350 Free_t safesysfree(Malloc_t where)
7351
7352 "safesysmalloc"
7353 Paranoid version of system's malloc()
7354
7355 Malloc_t safesysmalloc(MEM_SIZE nbytes)
7356
7357 "safesysrealloc"
7358 Paranoid version of system's realloc()
7359
7360 Malloc_t safesysrealloc(Malloc_t where, MEM_SIZE nbytes)
7361
7363 These functions are related to the method resolution order of perl
7364 classes Also see perlmroapi.
7365
7366 "HvMROMETA"
7367 Described in perlmroapi.
7368
7369 struct mro_meta * HvMROMETA(HV *hv)
7370
7371 "mro_get_linear_isa"
7372 Returns the mro linearisation for the given stash. By default,
7373 this will be whatever "mro_get_linear_isa_dfs" returns unless some
7374 other MRO is in effect for the stash. The return value is a read-
7375 only AV*.
7376
7377 You are responsible for "SvREFCNT_inc()" on the return value if you
7378 plan to store it anywhere semi-permanently (otherwise it might be
7379 deleted out from under you the next time the cache is invalidated).
7380
7381 AV* mro_get_linear_isa(HV* stash)
7382
7383 "MRO_GET_PRIVATE_DATA"
7384 Described in perlmroapi.
7385
7386 SV* MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta,
7387 const struct mro_alg *const which)
7388
7389 "mro_method_changed_in"
7390 Invalidates method caching on any child classes of the given stash,
7391 so that they might notice the changes in this one.
7392
7393 Ideally, all instances of "PL_sub_generation++" in perl source
7394 outside of mro.c should be replaced by calls to this.
7395
7396 Perl automatically handles most of the common ways a method might
7397 be redefined. However, there are a few ways you could change a
7398 method in a stash without the cache code noticing, in which case
7399 you need to call this method afterwards:
7400
7401 1) Directly manipulating the stash HV entries from XS code.
7402
7403 2) Assigning a reference to a readonly scalar constant into a stash
7404 entry in order to create a constant subroutine (like constant.pm
7405 does).
7406
7407 This same method is available from pure perl via,
7408 "mro::method_changed_in(classname)".
7409
7410 void mro_method_changed_in(HV* stash)
7411
7412 "mro_register"
7413 Registers a custom mro plugin. See perlmroapi for details on this
7414 and other mro functions.
7415
7416 NOTE: "mro_register" must be explicitly called as
7417 "Perl_mro_register" with an "aTHX_" parameter.
7418
7419 void Perl_mro_register(pTHX_ const struct mro_alg *mro)
7420
7421 "mro_set_private_data"
7422 Described in perlmroapi.
7423
7424 NOTE: "mro_set_private_data" must be explicitly called as
7425 "Perl_mro_set_private_data" with an "aTHX_" parameter.
7426
7427 SV* Perl_mro_set_private_data(pTHX_
7428 struct mro_meta *const smeta,
7429 const struct mro_alg *const which,
7430 SV *const data)
7431
7433 "dMULTICALL"
7434 Declare local variables for a multicall. See "LIGHTWEIGHT
7435 CALLBACKS" in perlcall.
7436
7437 dMULTICALL;
7438
7439 "MULTICALL"
7440 Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in
7441 perlcall.
7442
7443 MULTICALL;
7444
7445 "POP_MULTICALL"
7446 Closing bracket for a lightweight callback. See "LIGHTWEIGHT
7447 CALLBACKS" in perlcall.
7448
7449 POP_MULTICALL;
7450
7451 "PUSH_MULTICALL"
7452 Opening bracket for a lightweight callback. See "LIGHTWEIGHT
7453 CALLBACKS" in perlcall.
7454
7455 PUSH_MULTICALL(CV* the_cv);
7456
7458 "Drand01"
7459 This macro is to be used to generate uniformly distributed random
7460 numbers over the range [0., 1.[. You may have to supply an 'extern
7461 double "drand48()";' in your program since SunOS 4.1.3 doesn't
7462 provide you with anything relevant in its headers. See
7463 "HAS_DRAND48_PROTO".
7464
7465 double Drand01()
7466
7467 "Gconvert"
7468 This preprocessor macro is defined to convert a floating point
7469 number to a string without a trailing decimal point. This emulates
7470 the behavior of "sprintf("%g")", but is sometimes much more
7471 efficient. If "gconvert()" is not available, but "gcvt()" drops
7472 the trailing decimal point, then "gcvt()" is used. If all else
7473 fails, a macro using "sprintf("%g")" is used. Arguments for the
7474 Gconvert macro are: value, number of digits, whether trailing zeros
7475 should be retained, and the output buffer. The usual values are:
7476
7477 d_Gconvert='gconvert((x),(n),(t),(b))'
7478 d_Gconvert='gcvt((x),(n),(b))'
7479 d_Gconvert='sprintf((b),"%.*g",(n),(x))'
7480
7481 The last two assume trailing zeros should not be kept.
7482
7483 char * Gconvert(double x, Size_t n, bool t, char * b)
7484
7485 "grok_bin"
7486 converts a string representing a binary number to numeric form.
7487
7488 On entry "start" and *len_p give the string to scan, *flags gives
7489 conversion flags, and "result" should be "NULL" or a pointer to an
7490 NV. The scan stops at the end of the string, or at just before the
7491 first invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
7492 in *flags, encountering an invalid character (except NUL) will also
7493 trigger a warning. On return *len_p is set to the length of the
7494 scanned string, and *flags gives output flags.
7495
7496 If the value is <= "UV_MAX" it is returned as a UV, the output
7497 flags are clear, and nothing is written to *result. If the value
7498 is > "UV_MAX", "grok_bin" returns "UV_MAX", sets
7499 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
7500 approximation of the correct value into *result (which is an NV; or
7501 the approximation is discarded if "result" is NULL).
7502
7503 The binary number may optionally be prefixed with "0b" or "b"
7504 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
7505
7506 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
7507 pairs of digits may be separated from each other by a single
7508 underscore; also a single leading underscore is accepted.
7509
7510 UV grok_bin(const char* start, STRLEN* len_p, I32* flags,
7511 NV *result)
7512
7513 "grok_hex"
7514 converts a string representing a hex number to numeric form.
7515
7516 On entry "start" and *len_p give the string to scan, *flags gives
7517 conversion flags, and "result" should be "NULL" or a pointer to an
7518 NV. The scan stops at the end of the string, or at just before the
7519 first invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
7520 in *flags, encountering an invalid character (except NUL) will also
7521 trigger a warning. On return *len_p is set to the length of the
7522 scanned string, and *flags gives output flags.
7523
7524 If the value is <= "UV_MAX" it is returned as a UV, the output
7525 flags are clear, and nothing is written to *result. If the value
7526 is > "UV_MAX", "grok_hex" returns "UV_MAX", sets
7527 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
7528 approximation of the correct value into *result (which is an NV; or
7529 the approximation is discarded if "result" is NULL).
7530
7531 The hex number may optionally be prefixed with "0x" or "x" unless
7532 "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
7533
7534 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
7535 pairs of digits may be separated from each other by a single
7536 underscore; also a single leading underscore is accepted.
7537
7538 UV grok_hex(const char* start, STRLEN* len_p, I32* flags,
7539 NV *result)
7540
7541 "grok_infnan"
7542 Helper for "grok_number()", accepts various ways of spelling
7543 "infinity" or "not a number", and returns one of the following flag
7544 combinations:
7545
7546 IS_NUMBER_INFINITY
7547 IS_NUMBER_NAN
7548 IS_NUMBER_INFINITY | IS_NUMBER_NEG
7549 IS_NUMBER_NAN | IS_NUMBER_NEG
7550 0
7551
7552 possibly |-ed with "IS_NUMBER_TRAILING".
7553
7554 If an infinity or a not-a-number is recognized, *sp will point to
7555 one byte past the end of the recognized string. If the recognition
7556 fails, zero is returned, and *sp will not move.
7557
7558 int grok_infnan(const char** sp, const char *send)
7559
7560 "grok_number"
7561 Identical to "grok_number_flags()" with "flags" set to zero.
7562
7563 int grok_number(const char *pv, STRLEN len, UV *valuep)
7564
7565 "grok_number_flags"
7566 Recognise (or not) a number. The type of the number is returned (0
7567 if unrecognised), otherwise it is a bit-ORed combination of
7568 "IS_NUMBER_IN_UV", "IS_NUMBER_GREATER_THAN_UV_MAX",
7569 "IS_NUMBER_NOT_INT", "IS_NUMBER_NEG", "IS_NUMBER_INFINITY",
7570 "IS_NUMBER_NAN" (defined in perl.h).
7571
7572 If the value of the number can fit in a UV, it is returned in
7573 *valuep. "IS_NUMBER_IN_UV" will be set to indicate that *valuep is
7574 valid, "IS_NUMBER_IN_UV" will never be set unless *valuep is valid,
7575 but *valuep may have been assigned to during processing even though
7576 "IS_NUMBER_IN_UV" is not set on return. If "valuep" is "NULL",
7577 "IS_NUMBER_IN_UV" will be set for the same cases as when "valuep"
7578 is non-"NULL", but no actual assignment (or SEGV) will occur.
7579
7580 "IS_NUMBER_NOT_INT" will be set with "IS_NUMBER_IN_UV" if trailing
7581 decimals were seen (in which case *valuep gives the true value
7582 truncated to an integer), and "IS_NUMBER_NEG" if the number is
7583 negative (in which case *valuep holds the absolute value).
7584 "IS_NUMBER_IN_UV" is not set if "e" notation was used or the number
7585 is larger than a UV.
7586
7587 "flags" allows only "PERL_SCAN_TRAILING", which allows for trailing
7588 non-numeric text on an otherwise successful grok, setting
7589 "IS_NUMBER_TRAILING" on the result.
7590
7591 int grok_number_flags(const char *pv, STRLEN len, UV *valuep,
7592 U32 flags)
7593
7594 "GROK_NUMERIC_RADIX"
7595 A synonym for "grok_numeric_radix"
7596
7597 bool GROK_NUMERIC_RADIX(NN const char **sp, NN const char *send)
7598
7599 "grok_numeric_radix"
7600 Scan and skip for a numeric decimal separator (radix).
7601
7602 bool grok_numeric_radix(const char **sp, const char *send)
7603
7604 "grok_oct"
7605 converts a string representing an octal number to numeric form.
7606
7607 On entry "start" and *len_p give the string to scan, *flags gives
7608 conversion flags, and "result" should be "NULL" or a pointer to an
7609 NV. The scan stops at the end of the string, or at just before the
7610 first invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
7611 in *flags, encountering an invalid character (except NUL) will also
7612 trigger a warning. On return *len_p is set to the length of the
7613 scanned string, and *flags gives output flags.
7614
7615 If the value is <= "UV_MAX" it is returned as a UV, the output
7616 flags are clear, and nothing is written to *result. If the value
7617 is > "UV_MAX", "grok_oct" returns "UV_MAX", sets
7618 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
7619 approximation of the correct value into *result (which is an NV; or
7620 the approximation is discarded if "result" is NULL).
7621
7622 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
7623 pairs of digits may be separated from each other by a single
7624 underscore; also a single leading underscore is accepted.
7625
7626 The "PERL_SCAN_DISALLOW_PREFIX" flag is always treated as being set
7627 for this function.
7628
7629 UV grok_oct(const char* start, STRLEN* len_p, I32* flags,
7630 NV *result)
7631
7632 "isinfnan"
7633 "Perl_isinfnan()" is a utility function that returns true if the NV
7634 argument is either an infinity or a "NaN", false otherwise. To
7635 test in more detail, use "Perl_isinf()" and "Perl_isnan()".
7636
7637 This is also the logical inverse of Perl_isfinite().
7638
7639 bool isinfnan(NV nv)
7640
7641 "my_atof"
7642 "atof"(3), but properly works with Perl locale handling, accepting
7643 a dot radix character always, but also the current locale's radix
7644 character if and only if called from within the lexical scope of a
7645 Perl "use locale" statement.
7646
7647 N.B. "s" must be NUL terminated.
7648
7649 NV my_atof(const char *s)
7650
7651 "my_strtod"
7652 This function is equivalent to the libc strtod() function, and is
7653 available even on platforms that lack plain strtod(). Its return
7654 value is the best available precision depending on platform
7655 capabilities and Configure options.
7656
7657 It properly handles the locale radix character, meaning it expects
7658 a dot except when called from within the scope of "use locale", in
7659 which case the radix character should be that specified by the
7660 current locale.
7661
7662 The synonym Strtod() may be used instead.
7663
7664 NV my_strtod(const char * const s, char ** e)
7665
7666 "PERL_ABS"
7667 Typeless "abs" or "fabs", etc. (The usage below indicates it is
7668 for integers, but it works for any type.) Use instead of these,
7669 since the C library ones force their argument to be what it is
7670 expecting, potentially leading to disaster. But also beware that
7671 this evaluates its argument twice, so no "x++".
7672
7673 int PERL_ABS(int x)
7674
7675 "Perl_acos"
7676 "Perl_asin"
7677 "Perl_atan"
7678 "Perl_atan2"
7679 "Perl_ceil"
7680 "Perl_cos"
7681 "Perl_cosh"
7682 "Perl_exp"
7683 "Perl_floor"
7684 "Perl_fmod"
7685 "Perl_frexp"
7686 "Perl_isfinite"
7687 "Perl_isinf"
7688 "Perl_isnan"
7689 "Perl_ldexp"
7690 "Perl_log"
7691 "Perl_log10"
7692 "Perl_modf"
7693 "Perl_pow"
7694 "Perl_sin"
7695 "Perl_sinh"
7696 "Perl_sqrt"
7697 "Perl_tan"
7698 "Perl_tanh"
7699 These perform the corresponding mathematical operation on the
7700 operand(s), using the libc function designed for the task that has
7701 just enough precision for an NV on this platform. If no such
7702 function with sufficient precision exists, the highest precision
7703 one available is used.
7704
7705 NV Perl_acos (NV x)
7706 NV Perl_asin (NV x)
7707 NV Perl_atan (NV x)
7708 NV Perl_atan2 (NV x, NV y)
7709 NV Perl_ceil (NV x)
7710 NV Perl_cos (NV x)
7711 NV Perl_cosh (NV x)
7712 NV Perl_exp (NV x)
7713 NV Perl_floor (NV x)
7714 NV Perl_fmod (NV x, NV y)
7715 NV Perl_frexp (NV x, int *exp)
7716 IV Perl_isfinite(NV x)
7717 IV Perl_isinf (NV x)
7718 IV Perl_isnan (NV x)
7719 NV Perl_ldexp (NV x, int exp)
7720 NV Perl_log (NV x)
7721 NV Perl_log10 (NV x)
7722 NV Perl_modf (NV x, NV *iptr)
7723 NV Perl_pow (NV x, NV y)
7724 NV Perl_sin (NV x)
7725 NV Perl_sinh (NV x)
7726 NV Perl_sqrt (NV x)
7727 NV Perl_tan (NV x)
7728 NV Perl_tanh (NV x)
7729
7730 "Perl_signbit"
7731 NOTE: "Perl_signbit" is experimental and may change or be removed
7732 without notice.
7733
7734 Return a non-zero integer if the sign bit on an NV is set, and 0 if
7735 it is not.
7736
7737 If Configure detects this system has a "signbit()" that will work
7738 with our NVs, then we just use it via the "#define" in perl.h.
7739 Otherwise, fall back on this implementation. The main use of this
7740 function is catching "-0.0".
7741
7742 "Configure" notes: This function is called 'Perl_signbit' instead
7743 of a plain 'signbit' because it is easy to imagine a system having
7744 a "signbit()" function or macro that doesn't happen to work with
7745 our particular choice of NVs. We shouldn't just re-"#define"
7746 "signbit" as "Perl_signbit" and expect the standard system headers
7747 to be happy. Also, this is a no-context function (no "pTHX_")
7748 because "Perl_signbit()" is usually re-"#defined" in perl.h as a
7749 simple macro call to the system's "signbit()". Users should just
7750 always call "Perl_signbit()".
7751
7752 int Perl_signbit(NV f)
7753
7754 "PL_hexdigit"
7755 This array, indexed by an integer, converts that value into the
7756 character that represents it. For example, if the input is 8, the
7757 return will be a string whose first character is '8'. What is
7758 actually returned is a pointer into a string. All you are
7759 interested in is the first character of that string. To get
7760 uppercase letters (for the values 10..15), add 16 to the index.
7761 Hence, "PL_hexdigit[11]" is 'b', and "PL_hexdigit[11+16]" is 'B'.
7762 Adding 16 to an index whose representation is '0'..'9' yields the
7763 same as not adding 16. Indices outside the range 0..31 result in
7764 (bad) undedefined behavior.
7765
7766 "READ_XDIGIT"
7767 Returns the value of an ASCII-range hex digit and advances the
7768 string pointer. Behaviour is only well defined when isXDIGIT(*str)
7769 is true.
7770
7771 U8 READ_XDIGIT(char str*)
7772
7773 "scan_bin"
7774 For backwards compatibility. Use "grok_bin" instead.
7775
7776 NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
7777
7778 "scan_hex"
7779 For backwards compatibility. Use "grok_hex" instead.
7780
7781 NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
7782
7783 "scan_oct"
7784 For backwards compatibility. Use "grok_oct" instead.
7785
7786 NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
7787
7788 "seedDrand01"
7789 This symbol defines the macro to be used in seeding the random
7790 number generator (see "Drand01").
7791
7792 void seedDrand01(Rand_seed_t x)
7793
7794 "Strtod"
7795 This is a synonym for "my_strtod".
7796
7797 NV Strtod(NN const char * const s, NULLOK char ** e)
7798
7799 "Strtol"
7800 Platform and configuration independent "strtol". This expands to
7801 the appropriate "strotol"-like function based on the platform and
7802 Configure options>. For example it could expand to "strtoll" or
7803 "strtoq" instead of "strtol".
7804
7805 NV Strtol(NN const char * const s, NULLOK char ** e, int base)
7806
7807 "Strtoul"
7808 Platform and configuration independent "strtoul". This expands to
7809 the appropriate "strotoul"-like function based on the platform and
7810 Configure options>. For example it could expand to "strtoull" or
7811 "strtouq" instead of "strtoul".
7812
7813 NV Strtoul(NN const char * const s, NULLOK char ** e, int base)
7814
7816 "newASSIGNOP"
7817 Constructs, checks, and returns an assignment op. "left" and
7818 "right" supply the parameters of the assignment; they are consumed
7819 by this function and become part of the constructed op tree.
7820
7821 If "optype" is "OP_ANDASSIGN", "OP_ORASSIGN", or "OP_DORASSIGN",
7822 then a suitable conditional optree is constructed. If "optype" is
7823 the opcode of a binary operator, such as "OP_BIT_OR", then an op is
7824 constructed that performs the binary operation and assigns the
7825 result to the left argument. Either way, if "optype" is non-zero
7826 then "flags" has no effect.
7827
7828 If "optype" is zero, then a plain scalar or list assignment is
7829 constructed. Which type of assignment it is is automatically
7830 determined. "flags" gives the eight bits of "op_flags", except
7831 that "OPf_KIDS" will be set automatically, and, shifted up eight
7832 bits, the eight bits of "op_private", except that the bit with
7833 value 1 or 2 is automatically set as required.
7834
7835 OP* newASSIGNOP(I32 flags, OP* left, I32 optype, OP* right)
7836
7837 "newBINOP"
7838 Constructs, checks, and returns an op of any binary type. "type"
7839 is the opcode. "flags" gives the eight bits of "op_flags", except
7840 that "OPf_KIDS" will be set automatically, and, shifted up eight
7841 bits, the eight bits of "op_private", except that the bit with
7842 value 1 or 2 is automatically set as required. "first" and "last"
7843 supply up to two ops to be the direct children of the binary op;
7844 they are consumed by this function and become part of the
7845 constructed op tree.
7846
7847 OP* newBINOP(I32 type, I32 flags, OP* first, OP* last)
7848
7849 "newCONDOP"
7850 Constructs, checks, and returns a conditional-expression
7851 ("cond_expr") op. "flags" gives the eight bits of "op_flags",
7852 except that "OPf_KIDS" will be set automatically, and, shifted up
7853 eight bits, the eight bits of "op_private", except that the bit
7854 with value 1 is automatically set. "first" supplies the expression
7855 selecting between the two branches, and "trueop" and "falseop"
7856 supply the branches; they are consumed by this function and become
7857 part of the constructed op tree.
7858
7859 OP* newCONDOP(I32 flags, OP* first, OP* trueop, OP* falseop)
7860
7861 "newDEFSVOP"
7862 Constructs and returns an op to access $_.
7863
7864 OP* newDEFSVOP()
7865
7866 "newFOROP"
7867 Constructs, checks, and returns an op tree expressing a "foreach"
7868 loop (iteration through a list of values). This is a heavyweight
7869 loop, with structure that allows exiting the loop by "last" and
7870 suchlike.
7871
7872 "sv" optionally supplies the variable that will be aliased to each
7873 item in turn; if null, it defaults to $_. "expr" supplies the list
7874 of values to iterate over. "block" supplies the main body of the
7875 loop, and "cont" optionally supplies a "continue" block that
7876 operates as a second half of the body. All of these optree inputs
7877 are consumed by this function and become part of the constructed op
7878 tree.
7879
7880 "flags" gives the eight bits of "op_flags" for the "leaveloop" op
7881 and, shifted up eight bits, the eight bits of "op_private" for the
7882 "leaveloop" op, except that (in both cases) some bits will be set
7883 automatically.
7884
7885 OP* newFOROP(I32 flags, OP* sv, OP* expr, OP* block, OP* cont)
7886
7887 "newGIVENOP"
7888 Constructs, checks, and returns an op tree expressing a "given"
7889 block. "cond" supplies the expression to whose value $_ will be
7890 locally aliased, and "block" supplies the body of the "given"
7891 construct; they are consumed by this function and become part of
7892 the constructed op tree. "defsv_off" must be zero (it used to
7893 identity the pad slot of lexical $_).
7894
7895 OP* newGIVENOP(OP* cond, OP* block, PADOFFSET defsv_off)
7896
7897 "newGVOP"
7898 Constructs, checks, and returns an op of any type that involves an
7899 embedded reference to a GV. "type" is the opcode. "flags" gives
7900 the eight bits of "op_flags". "gv" identifies the GV that the op
7901 should reference; calling this function does not transfer ownership
7902 of any reference to it.
7903
7904 OP* newGVOP(I32 type, I32 flags, GV* gv)
7905
7906 "newLISTOP"
7907 Constructs, checks, and returns an op of any list type. "type" is
7908 the opcode. "flags" gives the eight bits of "op_flags", except
7909 that "OPf_KIDS" will be set automatically if required. "first" and
7910 "last" supply up to two ops to be direct children of the list op;
7911 they are consumed by this function and become part of the
7912 constructed op tree.
7913
7914 For most list operators, the check function expects all the kid ops
7915 to be present already, so calling "newLISTOP(OP_JOIN, ...)" (e.g.)
7916 is not appropriate. What you want to do in that case is create an
7917 op of type "OP_LIST", append more children to it, and then call
7918 "op_convert_list". See "op_convert_list" for more information.
7919
7920 OP* newLISTOP(I32 type, I32 flags, OP* first, OP* last)
7921
7922 "newLOGOP"
7923 Constructs, checks, and returns a logical (flow control) op.
7924 "type" is the opcode. "flags" gives the eight bits of "op_flags",
7925 except that "OPf_KIDS" will be set automatically, and, shifted up
7926 eight bits, the eight bits of "op_private", except that the bit
7927 with value 1 is automatically set. "first" supplies the expression
7928 controlling the flow, and "other" supplies the side (alternate)
7929 chain of ops; they are consumed by this function and become part of
7930 the constructed op tree.
7931
7932 OP* newLOGOP(I32 optype, I32 flags, OP *first, OP *other)
7933
7934 "newLOOPEX"
7935 Constructs, checks, and returns a loop-exiting op (such as "goto"
7936 or "last"). "type" is the opcode. "label" supplies the parameter
7937 determining the target of the op; it is consumed by this function
7938 and becomes part of the constructed op tree.
7939
7940 OP* newLOOPEX(I32 type, OP* label)
7941
7942 "newLOOPOP"
7943 Constructs, checks, and returns an op tree expressing a loop. This
7944 is only a loop in the control flow through the op tree; it does not
7945 have the heavyweight loop structure that allows exiting the loop by
7946 "last" and suchlike. "flags" gives the eight bits of "op_flags"
7947 for the top-level op, except that some bits will be set
7948 automatically as required. "expr" supplies the expression
7949 controlling loop iteration, and "block" supplies the body of the
7950 loop; they are consumed by this function and become part of the
7951 constructed op tree. "debuggable" is currently unused and should
7952 always be 1.
7953
7954 OP* newLOOPOP(I32 flags, I32 debuggable, OP* expr, OP* block)
7955
7956 "newMETHOP"
7957 Constructs, checks, and returns an op of method type with a method
7958 name evaluated at runtime. "type" is the opcode. "flags" gives
7959 the eight bits of "op_flags", except that "OPf_KIDS" will be set
7960 automatically, and, shifted up eight bits, the eight bits of
7961 "op_private", except that the bit with value 1 is automatically
7962 set. "dynamic_meth" supplies an op which evaluates method name; it
7963 is consumed by this function and become part of the constructed op
7964 tree. Supported optypes: "OP_METHOD".
7965
7966 OP* newMETHOP(I32 type, I32 flags, OP* dynamic_meth)
7967
7968 "newMETHOP_named"
7969 Constructs, checks, and returns an op of method type with a
7970 constant method name. "type" is the opcode. "flags" gives the
7971 eight bits of "op_flags", and, shifted up eight bits, the eight
7972 bits of "op_private". "const_meth" supplies a constant method
7973 name; it must be a shared COW string. Supported optypes:
7974 "OP_METHOD_NAMED".
7975
7976 OP* newMETHOP_named(I32 type, I32 flags, SV* const_meth)
7977
7978 "newNULLLIST"
7979 Constructs, checks, and returns a new "stub" op, which represents
7980 an empty list expression.
7981
7982 OP* newNULLLIST()
7983
7984 "newOP"
7985 Constructs, checks, and returns an op of any base type (any type
7986 that has no extra fields). "type" is the opcode. "flags" gives
7987 the eight bits of "op_flags", and, shifted up eight bits, the eight
7988 bits of "op_private".
7989
7990 OP* newOP(I32 optype, I32 flags)
7991
7992 "newPADOP"
7993 Constructs, checks, and returns an op of any type that involves a
7994 reference to a pad element. "type" is the opcode. "flags" gives
7995 the eight bits of "op_flags". A pad slot is automatically
7996 allocated, and is populated with "sv"; this function takes
7997 ownership of one reference to it.
7998
7999 This function only exists if Perl has been compiled to use
8000 ithreads.
8001
8002 OP* newPADOP(I32 type, I32 flags, SV* sv)
8003
8004 "newPMOP"
8005 Constructs, checks, and returns an op of any pattern matching type.
8006 "type" is the opcode. "flags" gives the eight bits of "op_flags"
8007 and, shifted up eight bits, the eight bits of "op_private".
8008
8009 OP* newPMOP(I32 type, I32 flags)
8010
8011 "newPVOP"
8012 Constructs, checks, and returns an op of any type that involves an
8013 embedded C-level pointer (PV). "type" is the opcode. "flags"
8014 gives the eight bits of "op_flags". "pv" supplies the C-level
8015 pointer. Depending on the op type, the memory referenced by "pv"
8016 may be freed when the op is destroyed. If the op is of a freeing
8017 type, "pv" must have been allocated using "PerlMemShared_malloc".
8018
8019 OP* newPVOP(I32 type, I32 flags, char* pv)
8020
8021 "newRANGE"
8022 Constructs and returns a "range" op, with subordinate "flip" and
8023 "flop" ops. "flags" gives the eight bits of "op_flags" for the
8024 "flip" op and, shifted up eight bits, the eight bits of
8025 "op_private" for both the "flip" and "range" ops, except that the
8026 bit with value 1 is automatically set. "left" and "right" supply
8027 the expressions controlling the endpoints of the range; they are
8028 consumed by this function and become part of the constructed op
8029 tree.
8030
8031 OP* newRANGE(I32 flags, OP* left, OP* right)
8032
8033 "newSLICEOP"
8034 Constructs, checks, and returns an "lslice" (list slice) op.
8035 "flags" gives the eight bits of "op_flags", except that "OPf_KIDS"
8036 will be set automatically, and, shifted up eight bits, the eight
8037 bits of "op_private", except that the bit with value 1 or 2 is
8038 automatically set as required. "listval" and "subscript" supply
8039 the parameters of the slice; they are consumed by this function and
8040 become part of the constructed op tree.
8041
8042 OP* newSLICEOP(I32 flags, OP* subscript, OP* listop)
8043
8044 "newSTATEOP"
8045 Constructs a state op (COP). The state op is normally a
8046 "nextstate" op, but will be a "dbstate" op if debugging is enabled
8047 for currently-compiled code. The state op is populated from
8048 "PL_curcop" (or "PL_compiling"). If "label" is non-null, it
8049 supplies the name of a label to attach to the state op; this
8050 function takes ownership of the memory pointed at by "label", and
8051 will free it. "flags" gives the eight bits of "op_flags" for the
8052 state op.
8053
8054 If "o" is null, the state op is returned. Otherwise the state op
8055 is combined with "o" into a "lineseq" list op, which is returned.
8056 "o" is consumed by this function and becomes part of the returned
8057 op tree.
8058
8059 OP* newSTATEOP(I32 flags, char* label, OP* o)
8060
8061 "newSVOP"
8062 Constructs, checks, and returns an op of any type that involves an
8063 embedded SV. "type" is the opcode. "flags" gives the eight bits
8064 of "op_flags". "sv" gives the SV to embed in the op; this function
8065 takes ownership of one reference to it.
8066
8067 OP* newSVOP(I32 type, I32 flags, SV* sv)
8068
8069 "newTRYCATCHOP"
8070 NOTE: "newTRYCATCHOP" is experimental and may change or be removed
8071 without notice.
8072
8073 Constructs and returns a conditional execution statement that
8074 implements the "try"/"catch" semantics. First the op tree in
8075 "tryblock" is executed, inside a context that traps exceptions. If
8076 an exception occurs then the optree in "catchblock" is executed,
8077 with the trapped exception set into the lexical variable given by
8078 "catchvar" (which must be an op of type "OP_PADSV"). All the
8079 optrees are consumed by this function and become part of the
8080 returned op tree.
8081
8082 The "flags" argument is currently ignored.
8083
8084 OP* newTRYCATCHOP(I32 flags, OP* tryblock, OP *catchvar,
8085 OP* catchblock)
8086
8087 "newUNOP"
8088 Constructs, checks, and returns an op of any unary type. "type" is
8089 the opcode. "flags" gives the eight bits of "op_flags", except
8090 that "OPf_KIDS" will be set automatically if required, and, shifted
8091 up eight bits, the eight bits of "op_private", except that the bit
8092 with value 1 is automatically set. "first" supplies an optional op
8093 to be the direct child of the unary op; it is consumed by this
8094 function and become part of the constructed op tree.
8095
8096 OP* newUNOP(I32 type, I32 flags, OP* first)
8097
8098 "newUNOP_AUX"
8099 Similar to "newUNOP", but creates an "UNOP_AUX" struct instead,
8100 with "op_aux" initialised to "aux"
8101
8102 OP* newUNOP_AUX(I32 type, I32 flags, OP* first,
8103 UNOP_AUX_item *aux)
8104
8105 "newWHENOP"
8106 Constructs, checks, and returns an op tree expressing a "when"
8107 block. "cond" supplies the test expression, and "block" supplies
8108 the block that will be executed if the test evaluates to true; they
8109 are consumed by this function and become part of the constructed op
8110 tree. "cond" will be interpreted DWIMically, often as a comparison
8111 against $_, and may be null to generate a "default" block.
8112
8113 OP* newWHENOP(OP* cond, OP* block)
8114
8115 "newWHILEOP"
8116 Constructs, checks, and returns an op tree expressing a "while"
8117 loop. This is a heavyweight loop, with structure that allows
8118 exiting the loop by "last" and suchlike.
8119
8120 "loop" is an optional preconstructed "enterloop" op to use in the
8121 loop; if it is null then a suitable op will be constructed
8122 automatically. "expr" supplies the loop's controlling expression.
8123 "block" supplies the main body of the loop, and "cont" optionally
8124 supplies a "continue" block that operates as a second half of the
8125 body. All of these optree inputs are consumed by this function and
8126 become part of the constructed op tree.
8127
8128 "flags" gives the eight bits of "op_flags" for the "leaveloop" op
8129 and, shifted up eight bits, the eight bits of "op_private" for the
8130 "leaveloop" op, except that (in both cases) some bits will be set
8131 automatically. "debuggable" is currently unused and should always
8132 be 1. "has_my" can be supplied as true to force the loop body to
8133 be enclosed in its own scope.
8134
8135 OP* newWHILEOP(I32 flags, I32 debuggable, LOOP* loop, OP* expr,
8136 OP* block, OP* cont, I32 has_my)
8137
8138 "PL_opfreehook"
8139 When non-"NULL", the function pointed by this variable will be
8140 called each time an OP is freed with the corresponding OP as the
8141 argument. This allows extensions to free any extra attribute they
8142 have locally attached to an OP. It is also assured to first fire
8143 for the parent OP and then for its kids.
8144
8145 When you replace this variable, it is considered a good practice to
8146 store the possibly previously installed hook and that you recall it
8147 inside your own.
8148
8149 On threaded perls, each thread has an independent copy of this
8150 variable; each initialized at creation time with the current value
8151 of the creating thread's copy.
8152
8153 Perl_ophook_t PL_opfreehook
8154
8155 "PL_peepp"
8156 Pointer to the per-subroutine peephole optimiser. This is a
8157 function that gets called at the end of compilation of a Perl
8158 subroutine (or equivalently independent piece of Perl code) to
8159 perform fixups of some ops and to perform small-scale
8160 optimisations. The function is called once for each subroutine
8161 that is compiled, and is passed, as sole parameter, a pointer to
8162 the op that is the entry point to the subroutine. It modifies the
8163 op tree in place.
8164
8165 The peephole optimiser should never be completely replaced.
8166 Rather, add code to it by wrapping the existing optimiser. The
8167 basic way to do this can be seen in "Compile pass 3: peephole
8168 optimization" in perlguts. If the new code wishes to operate on
8169 ops throughout the subroutine's structure, rather than just at the
8170 top level, it is likely to be more convenient to wrap the
8171 "PL_rpeepp" hook.
8172
8173 On threaded perls, each thread has an independent copy of this
8174 variable; each initialized at creation time with the current value
8175 of the creating thread's copy.
8176
8177 peep_t PL_peepp
8178
8179 "PL_rpeepp"
8180 Pointer to the recursive peephole optimiser. This is a function
8181 that gets called at the end of compilation of a Perl subroutine (or
8182 equivalently independent piece of Perl code) to perform fixups of
8183 some ops and to perform small-scale optimisations. The function is
8184 called once for each chain of ops linked through their "op_next"
8185 fields; it is recursively called to handle each side chain. It is
8186 passed, as sole parameter, a pointer to the op that is at the head
8187 of the chain. It modifies the op tree in place.
8188
8189 The peephole optimiser should never be completely replaced.
8190 Rather, add code to it by wrapping the existing optimiser. The
8191 basic way to do this can be seen in "Compile pass 3: peephole
8192 optimization" in perlguts. If the new code wishes to operate only
8193 on ops at a subroutine's top level, rather than throughout the
8194 structure, it is likely to be more convenient to wrap the
8195 "PL_peepp" hook.
8196
8197 On threaded perls, each thread has an independent copy of this
8198 variable; each initialized at creation time with the current value
8199 of the creating thread's copy.
8200
8201 peep_t PL_rpeepp
8202
8204 "alloccopstash"
8205 NOTE: "alloccopstash" is experimental and may change or be removed
8206 without notice.
8207
8208 Available only under threaded builds, this function allocates an
8209 entry in "PL_stashpad" for the stash passed to it.
8210
8211 PADOFFSET alloccopstash(HV *hv)
8212
8213 "block_end"
8214 Handles compile-time scope exit. "floor" is the savestack index
8215 returned by "block_start", and "seq" is the body of the block.
8216 Returns the block, possibly modified.
8217
8218 OP* block_end(I32 floor, OP* seq)
8219
8220 "block_start"
8221 Handles compile-time scope entry. Arranges for hints to be
8222 restored on block exit and also handles pad sequence numbers to
8223 make lexical variables scope right. Returns a savestack index for
8224 use with "block_end".
8225
8226 int block_start(int full)
8227
8228 "ck_entersub_args_list"
8229 Performs the default fixup of the arguments part of an "entersub"
8230 op tree. This consists of applying list context to each of the
8231 argument ops. This is the standard treatment used on a call marked
8232 with "&", or a method call, or a call through a subroutine
8233 reference, or any other call where the callee can't be identified
8234 at compile time, or a call where the callee has no prototype.
8235
8236 OP* ck_entersub_args_list(OP *entersubop)
8237
8238 "ck_entersub_args_proto"
8239 Performs the fixup of the arguments part of an "entersub" op tree
8240 based on a subroutine prototype. This makes various modifications
8241 to the argument ops, from applying context up to inserting "refgen"
8242 ops, and checking the number and syntactic types of arguments, as
8243 directed by the prototype. This is the standard treatment used on
8244 a subroutine call, not marked with "&", where the callee can be
8245 identified at compile time and has a prototype.
8246
8247 "protosv" supplies the subroutine prototype to be applied to the
8248 call. It may be a normal defined scalar, of which the string value
8249 will be used. Alternatively, for convenience, it may be a
8250 subroutine object (a "CV*" that has been cast to "SV*") which has a
8251 prototype. The prototype supplied, in whichever form, does not
8252 need to match the actual callee referenced by the op tree.
8253
8254 If the argument ops disagree with the prototype, for example by
8255 having an unacceptable number of arguments, a valid op tree is
8256 returned anyway. The error is reflected in the parser state,
8257 normally resulting in a single exception at the top level of
8258 parsing which covers all the compilation errors that occurred. In
8259 the error message, the callee is referred to by the name defined by
8260 the "namegv" parameter.
8261
8262 OP* ck_entersub_args_proto(OP *entersubop, GV *namegv,
8263 SV *protosv)
8264
8265 "ck_entersub_args_proto_or_list"
8266 Performs the fixup of the arguments part of an "entersub" op tree
8267 either based on a subroutine prototype or using default list-
8268 context processing. This is the standard treatment used on a
8269 subroutine call, not marked with "&", where the callee can be
8270 identified at compile time.
8271
8272 "protosv" supplies the subroutine prototype to be applied to the
8273 call, or indicates that there is no prototype. It may be a normal
8274 scalar, in which case if it is defined then the string value will
8275 be used as a prototype, and if it is undefined then there is no
8276 prototype. Alternatively, for convenience, it may be a subroutine
8277 object (a "CV*" that has been cast to "SV*"), of which the
8278 prototype will be used if it has one. The prototype (or lack
8279 thereof) supplied, in whichever form, does not need to match the
8280 actual callee referenced by the op tree.
8281
8282 If the argument ops disagree with the prototype, for example by
8283 having an unacceptable number of arguments, a valid op tree is
8284 returned anyway. The error is reflected in the parser state,
8285 normally resulting in a single exception at the top level of
8286 parsing which covers all the compilation errors that occurred. In
8287 the error message, the callee is referred to by the name defined by
8288 the "namegv" parameter.
8289
8290 OP* ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
8291 SV *protosv)
8292
8293 "cv_const_sv"
8294 If "cv" is a constant sub eligible for inlining, returns the
8295 constant value returned by the sub. Otherwise, returns "NULL".
8296
8297 Constant subs can be created with "newCONSTSUB" or as described in
8298 "Constant Functions" in perlsub.
8299
8300 SV* cv_const_sv(const CV *const cv)
8301
8302 "cv_get_call_checker"
8303 The original form of "cv_get_call_checker_flags", which does not
8304 return checker flags. When using a checker function returned by
8305 this function, it is only safe to call it with a genuine GV as its
8306 "namegv" argument.
8307
8308 void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
8309 SV **ckobj_p)
8310
8311 "cv_get_call_checker_flags"
8312 Retrieves the function that will be used to fix up a call to "cv".
8313 Specifically, the function is applied to an "entersub" op tree for
8314 a subroutine call, not marked with "&", where the callee can be
8315 identified at compile time as "cv".
8316
8317 The C-level function pointer is returned in *ckfun_p, an SV
8318 argument for it is returned in *ckobj_p, and control flags are
8319 returned in *ckflags_p. The function is intended to be called in
8320 this manner:
8321
8322 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
8323
8324 In this call, "entersubop" is a pointer to the "entersub" op, which
8325 may be replaced by the check function, and "namegv" supplies the
8326 name that should be used by the check function to refer to the
8327 callee of the "entersub" op if it needs to emit any diagnostics.
8328 It is permitted to apply the check function in non-standard
8329 situations, such as to a call to a different subroutine or to a
8330 method call.
8331
8332 "namegv" may not actually be a GV. If the
8333 "CALL_CHECKER_REQUIRE_GV" bit is clear in *ckflags_p, it is
8334 permitted to pass a CV or other SV instead, anything that can be
8335 used as the first argument to "cv_name". If the
8336 "CALL_CHECKER_REQUIRE_GV" bit is set in *ckflags_p then the check
8337 function requires "namegv" to be a genuine GV.
8338
8339 By default, the check function is
8340 Perl_ck_entersub_args_proto_or_list, the SV parameter is "cv"
8341 itself, and the "CALL_CHECKER_REQUIRE_GV" flag is clear. This
8342 implements standard prototype processing. It can be changed, for a
8343 particular subroutine, by "cv_set_call_checker_flags".
8344
8345 If the "CALL_CHECKER_REQUIRE_GV" bit is set in "gflags" then it
8346 indicates that the caller only knows about the genuine GV version
8347 of "namegv", and accordingly the corresponding bit will always be
8348 set in *ckflags_p, regardless of the check function's recorded
8349 requirements. If the "CALL_CHECKER_REQUIRE_GV" bit is clear in
8350 "gflags" then it indicates the caller knows about the possibility
8351 of passing something other than a GV as "namegv", and accordingly
8352 the corresponding bit may be either set or clear in *ckflags_p,
8353 indicating the check function's recorded requirements.
8354
8355 "gflags" is a bitset passed into "cv_get_call_checker_flags", in
8356 which only the "CALL_CHECKER_REQUIRE_GV" bit currently has a
8357 defined meaning (for which see above). All other bits should be
8358 clear.
8359
8360 void cv_get_call_checker_flags(CV *cv, U32 gflags,
8361 Perl_call_checker *ckfun_p,
8362 SV **ckobj_p, U32 *ckflags_p)
8363
8364 "cv_set_call_checker"
8365 The original form of "cv_set_call_checker_flags", which passes it
8366 the "CALL_CHECKER_REQUIRE_GV" flag for backward-compatibility. The
8367 effect of that flag setting is that the check function is
8368 guaranteed to get a genuine GV as its "namegv" argument.
8369
8370 void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
8371 SV *ckobj)
8372
8373 "cv_set_call_checker_flags"
8374 Sets the function that will be used to fix up a call to "cv".
8375 Specifically, the function is applied to an "entersub" op tree for
8376 a subroutine call, not marked with "&", where the callee can be
8377 identified at compile time as "cv".
8378
8379 The C-level function pointer is supplied in "ckfun", an SV argument
8380 for it is supplied in "ckobj", and control flags are supplied in
8381 "ckflags". The function should be defined like this:
8382
8383 STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
8384
8385 It is intended to be called in this manner:
8386
8387 entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
8388
8389 In this call, "entersubop" is a pointer to the "entersub" op, which
8390 may be replaced by the check function, and "namegv" supplies the
8391 name that should be used by the check function to refer to the
8392 callee of the "entersub" op if it needs to emit any diagnostics.
8393 It is permitted to apply the check function in non-standard
8394 situations, such as to a call to a different subroutine or to a
8395 method call.
8396
8397 "namegv" may not actually be a GV. For efficiency, perl may pass a
8398 CV or other SV instead. Whatever is passed can be used as the
8399 first argument to "cv_name". You can force perl to pass a GV by
8400 including "CALL_CHECKER_REQUIRE_GV" in the "ckflags".
8401
8402 "ckflags" is a bitset, in which only the "CALL_CHECKER_REQUIRE_GV"
8403 bit currently has a defined meaning (for which see above). All
8404 other bits should be clear.
8405
8406 The current setting for a particular CV can be retrieved by
8407 "cv_get_call_checker_flags".
8408
8409 void cv_set_call_checker_flags(CV *cv, Perl_call_checker ckfun,
8410 SV *ckobj, U32 ckflags)
8411
8412 "LINKLIST"
8413 Given the root of an optree, link the tree in execution order using
8414 the "op_next" pointers and return the first op executed. If this
8415 has already been done, it will not be redone, and "o->op_next" will
8416 be returned. If "o->op_next" is not already set, "o" should be at
8417 least an "UNOP".
8418
8419 OP* LINKLIST(OP *o)
8420
8421 "newATTRSUB"
8422 Construct a Perl subroutine, also performing some surrounding jobs.
8423
8424 This is the same as ""newATTRSUB_x"" in perlintern with its
8425 "o_is_gv" parameter set to FALSE. This means that if "o" is null,
8426 the new sub will be anonymous; otherwise the name will be derived
8427 from "o" in the way described (as with all other details) in
8428 ""newATTRSUB_x"" in perlintern.
8429
8430 CV* newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs, OP *block)
8431
8432 "newCONSTSUB"
8433 Behaves like "newCONSTSUB_flags", except that "name" is nul-
8434 terminated rather than of counted length, and no flags are set.
8435 (This means that "name" is always interpreted as Latin-1.)
8436
8437 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
8438
8439 "newCONSTSUB_flags"
8440 Construct a constant subroutine, also performing some surrounding
8441 jobs. A scalar constant-valued subroutine is eligible for inlining
8442 at compile-time, and in Perl code can be created by
8443 "sub FOO () { 123 }". Other kinds of constant subroutine have
8444 other treatment.
8445
8446 The subroutine will have an empty prototype and will ignore any
8447 arguments when called. Its constant behaviour is determined by
8448 "sv". If "sv" is null, the subroutine will yield an empty list.
8449 If "sv" points to a scalar, the subroutine will always yield that
8450 scalar. If "sv" points to an array, the subroutine will always
8451 yield a list of the elements of that array in list context, or the
8452 number of elements in the array in scalar context. This function
8453 takes ownership of one counted reference to the scalar or array,
8454 and will arrange for the object to live as long as the subroutine
8455 does. If "sv" points to a scalar then the inlining assumes that
8456 the value of the scalar will never change, so the caller must
8457 ensure that the scalar is not subsequently written to. If "sv"
8458 points to an array then no such assumption is made, so it is
8459 ostensibly safe to mutate the array or its elements, but whether
8460 this is really supported has not been determined.
8461
8462 The subroutine will have "CvFILE" set according to "PL_curcop".
8463 Other aspects of the subroutine will be left in their default
8464 state. The caller is free to mutate the subroutine beyond its
8465 initial state after this function has returned.
8466
8467 If "name" is null then the subroutine will be anonymous, with its
8468 "CvGV" referring to an "__ANON__" glob. If "name" is non-null then
8469 the subroutine will be named accordingly, referenced by the
8470 appropriate glob. "name" is a string of length "len" bytes giving
8471 a sigilless symbol name, in UTF-8 if "flags" has the "SVf_UTF8" bit
8472 set and in Latin-1 otherwise. The name may be either qualified or
8473 unqualified. If the name is unqualified then it defaults to being
8474 in the stash specified by "stash" if that is non-null, or to
8475 "PL_curstash" if "stash" is null. The symbol is always added to
8476 the stash if necessary, with "GV_ADDMULTI" semantics.
8477
8478 "flags" should not have bits set other than "SVf_UTF8".
8479
8480 If there is already a subroutine of the specified name, then the
8481 new sub will replace the existing one in the glob. A warning may
8482 be generated about the redefinition.
8483
8484 If the subroutine has one of a few special names, such as "BEGIN"
8485 or "END", then it will be claimed by the appropriate queue for
8486 automatic running of phase-related subroutines. In this case the
8487 relevant glob will be left not containing any subroutine, even if
8488 it did contain one before. Execution of the subroutine will likely
8489 be a no-op, unless "sv" was a tied array or the caller modified the
8490 subroutine in some interesting way before it was executed. In the
8491 case of "BEGIN", the treatment is buggy: the sub will be executed
8492 when only half built, and may be deleted prematurely, possibly
8493 causing a crash.
8494
8495 The function returns a pointer to the constructed subroutine. If
8496 the sub is anonymous then ownership of one counted reference to the
8497 subroutine is transferred to the caller. If the sub is named then
8498 the caller does not get ownership of a reference. In most such
8499 cases, where the sub has a non-phase name, the sub will be alive at
8500 the point it is returned by virtue of being contained in the glob
8501 that names it. A phase-named subroutine will usually be alive by
8502 virtue of the reference owned by the phase's automatic run queue.
8503 A "BEGIN" subroutine may have been destroyed already by the time
8504 this function returns, but currently bugs occur in that case before
8505 the caller gets control. It is the caller's responsibility to
8506 ensure that it knows which of these situations applies.
8507
8508 CV* newCONSTSUB_flags(HV* stash, const char* name, STRLEN len,
8509 U32 flags, SV* sv)
8510
8511 "newSUB"
8512 Like "newATTRSUB", but without attributes.
8513
8514 CV* newSUB(I32 floor, OP* o, OP* proto, OP* block)
8515
8516 "newXS"
8517 Used by "xsubpp" to hook up XSUBs as Perl subs. "filename" needs
8518 to be static storage, as it is used directly as CvFILE(), without a
8519 copy being made.
8520
8521 "op_append_elem"
8522 Append an item to the list of ops contained directly within a list-
8523 type op, returning the lengthened list. "first" is the list-type
8524 op, and "last" is the op to append to the list. "optype" specifies
8525 the intended opcode for the list. If "first" is not already a list
8526 of the right type, it will be upgraded into one. If either "first"
8527 or "last" is null, the other is returned unchanged.
8528
8529 OP* op_append_elem(I32 optype, OP* first, OP* last)
8530
8531 "op_append_list"
8532 Concatenate the lists of ops contained directly within two list-
8533 type ops, returning the combined list. "first" and "last" are the
8534 list-type ops to concatenate. "optype" specifies the intended
8535 opcode for the list. If either "first" or "last" is not already a
8536 list of the right type, it will be upgraded into one. If either
8537 "first" or "last" is null, the other is returned unchanged.
8538
8539 OP* op_append_list(I32 optype, OP* first, OP* last)
8540
8541 "OP_CLASS"
8542 Return the class of the provided OP: that is, which of the *OP
8543 structures it uses. For core ops this currently gets the
8544 information out of "PL_opargs", which does not always accurately
8545 reflect the type used; in v5.26 onwards, see also the function
8546 "op_class" which can do a better job of determining the used type.
8547
8548 For custom ops the type is returned from the registration, and it
8549 is up to the registree to ensure it is accurate. The value
8550 returned will be one of the "OA_"* constants from op.h.
8551
8552 U32 OP_CLASS(OP *o)
8553
8554 "op_contextualize"
8555 Applies a syntactic context to an op tree representing an
8556 expression. "o" is the op tree, and "context" must be "G_SCALAR",
8557 "G_ARRAY", or "G_VOID" to specify the context to apply. The
8558 modified op tree is returned.
8559
8560 OP* op_contextualize(OP* o, I32 context)
8561
8562 "op_convert_list"
8563 Converts "o" into a list op if it is not one already, and then
8564 converts it into the specified "type", calling its check function,
8565 allocating a target if it needs one, and folding constants.
8566
8567 A list-type op is usually constructed one kid at a time via
8568 "newLISTOP", "op_prepend_elem" and "op_append_elem". Then finally
8569 it is passed to "op_convert_list" to make it the right type.
8570
8571 OP* op_convert_list(I32 optype, I32 flags, OP* o)
8572
8573 "OP_DESC"
8574 Return a short description of the provided OP.
8575
8576 const char * OP_DESC(OP *o)
8577
8578 "op_free"
8579 Free an op and its children. Only use this when an op is no longer
8580 linked to from any optree.
8581
8582 void op_free(OP* arg)
8583
8584 "OpHAS_SIBLING"
8585 Returns true if "o" has a sibling
8586
8587 bool OpHAS_SIBLING(OP *o)
8588
8589 "OpLASTSIB_set"
8590 Marks "o" as having no further siblings and marks o as having the
8591 specified parent. See also "OpMORESIB_set" and "OpMAYBESIB_set".
8592 For a higher-level interface, see "op_sibling_splice".
8593
8594 void OpLASTSIB_set(OP *o, OP *parent)
8595
8596 "op_linklist"
8597 This function is the implementation of the "LINKLIST" macro. It
8598 should not be called directly.
8599
8600 OP* op_linklist(OP *o)
8601
8602 "op_lvalue"
8603 NOTE: "op_lvalue" is experimental and may change or be removed
8604 without notice.
8605
8606 Propagate lvalue ("modifiable") context to an op and its children.
8607 "type" represents the context type, roughly based on the type of op
8608 that would do the modifying, although "local()" is represented by
8609 "OP_NULL", because it has no op type of its own (it is signalled by
8610 a flag on the lvalue op).
8611
8612 This function detects things that can't be modified, such as
8613 "$x+1", and generates errors for them. For example, "$x+1 = 2"
8614 would cause it to be called with an op of type "OP_ADD" and a
8615 "type" argument of "OP_SASSIGN".
8616
8617 It also flags things that need to behave specially in an lvalue
8618 context, such as "$$x = 5" which might have to vivify a reference
8619 in $x.
8620
8621 OP* op_lvalue(OP* o, I32 type)
8622
8623 "OpMAYBESIB_set"
8624 Conditionally does "OpMORESIB_set" or "OpLASTSIB_set" depending on
8625 whether "sib" is non-null. For a higher-level interface, see
8626 "op_sibling_splice".
8627
8628 void OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
8629
8630 "OpMORESIB_set"
8631 Sets the sibling of "o" to the non-zero value "sib". See also
8632 "OpLASTSIB_set" and "OpMAYBESIB_set". For a higher-level interface,
8633 see "op_sibling_splice".
8634
8635 void OpMORESIB_set(OP *o, OP *sib)
8636
8637 "OP_NAME"
8638 Return the name of the provided OP. For core ops this looks up the
8639 name from the op_type; for custom ops from the op_ppaddr.
8640
8641 const char * OP_NAME(OP *o)
8642
8643 "op_null"
8644 Neutralizes an op when it is no longer needed, but is still linked
8645 to from other ops.
8646
8647 void op_null(OP* o)
8648
8649 "op_parent"
8650 Returns the parent OP of "o", if it has a parent. Returns "NULL"
8651 otherwise.
8652
8653 OP* op_parent(OP *o)
8654
8655 "op_prepend_elem"
8656 Prepend an item to the list of ops contained directly within a
8657 list-type op, returning the lengthened list. "first" is the op to
8658 prepend to the list, and "last" is the list-type op. "optype"
8659 specifies the intended opcode for the list. If "last" is not
8660 already a list of the right type, it will be upgraded into one. If
8661 either "first" or "last" is null, the other is returned unchanged.
8662
8663 OP* op_prepend_elem(I32 optype, OP* first, OP* last)
8664
8665 "op_scope"
8666 NOTE: "op_scope" is experimental and may change or be removed
8667 without notice.
8668
8669 Wraps up an op tree with some additional ops so that at runtime a
8670 dynamic scope will be created. The original ops run in the new
8671 dynamic scope, and then, provided that they exit normally, the
8672 scope will be unwound. The additional ops used to create and
8673 unwind the dynamic scope will normally be an "enter"/"leave" pair,
8674 but a "scope" op may be used instead if the ops are simple enough
8675 to not need the full dynamic scope structure.
8676
8677 OP* op_scope(OP* o)
8678
8679 "OpSIBLING"
8680 Returns the sibling of "o", or "NULL" if there is no sibling
8681
8682 OP* OpSIBLING(OP *o)
8683
8684 "op_sibling_splice"
8685 A general function for editing the structure of an existing chain
8686 of op_sibling nodes. By analogy with the perl-level "splice()"
8687 function, allows you to delete zero or more sequential nodes,
8688 replacing them with zero or more different nodes. Performs the
8689 necessary op_first/op_last housekeeping on the parent node and
8690 op_sibling manipulation on the children. The last deleted node
8691 will be marked as the last node by updating the
8692 op_sibling/op_sibparent or op_moresib field as appropriate.
8693
8694 Note that op_next is not manipulated, and nodes are not freed; that
8695 is the responsibility of the caller. It also won't create a new
8696 list op for an empty list etc; use higher-level functions like
8697 op_append_elem() for that.
8698
8699 "parent" is the parent node of the sibling chain. It may passed as
8700 "NULL" if the splicing doesn't affect the first or last op in the
8701 chain.
8702
8703 "start" is the node preceding the first node to be spliced.
8704 Node(s) following it will be deleted, and ops will be inserted
8705 after it. If it is "NULL", the first node onwards is deleted, and
8706 nodes are inserted at the beginning.
8707
8708 "del_count" is the number of nodes to delete. If zero, no nodes
8709 are deleted. If -1 or greater than or equal to the number of
8710 remaining kids, all remaining kids are deleted.
8711
8712 "insert" is the first of a chain of nodes to be inserted in place
8713 of the nodes. If "NULL", no nodes are inserted.
8714
8715 The head of the chain of deleted ops is returned, or "NULL" if no
8716 ops were deleted.
8717
8718 For example:
8719
8720 action before after returns
8721 ------ ----- ----- -------
8722
8723 P P
8724 splice(P, A, 2, X-Y-Z) | | B-C
8725 A-B-C-D A-X-Y-Z-D
8726
8727 P P
8728 splice(P, NULL, 1, X-Y) | | A
8729 A-B-C-D X-Y-B-C-D
8730
8731 P P
8732 splice(P, NULL, 3, NULL) | | A-B-C
8733 A-B-C-D D
8734
8735 P P
8736 splice(P, B, 0, X-Y) | | NULL
8737 A-B-C-D A-B-X-Y-C-D
8738
8739 For lower-level direct manipulation of "op_sibparent" and
8740 "op_moresib", see "OpMORESIB_set", "OpLASTSIB_set",
8741 "OpMAYBESIB_set".
8742
8743 OP* op_sibling_splice(OP *parent, OP *start, int del_count,
8744 OP* insert)
8745
8746 "OP_TYPE_IS"
8747 Returns true if the given OP is not a "NULL" pointer and if it is
8748 of the given type.
8749
8750 The negation of this macro, "OP_TYPE_ISNT" is also available as
8751 well as "OP_TYPE_IS_NN" and "OP_TYPE_ISNT_NN" which elide the NULL
8752 pointer check.
8753
8754 bool OP_TYPE_IS(OP *o, Optype type)
8755
8756 "OP_TYPE_IS_OR_WAS"
8757 Returns true if the given OP is not a NULL pointer and if it is of
8758 the given type or used to be before being replaced by an OP of type
8759 OP_NULL.
8760
8761 The negation of this macro, "OP_TYPE_ISNT_AND_WASNT" is also
8762 available as well as "OP_TYPE_IS_OR_WAS_NN" and
8763 "OP_TYPE_ISNT_AND_WASNT_NN" which elide the "NULL" pointer check.
8764
8765 bool OP_TYPE_IS_OR_WAS(OP *o, Optype type)
8766
8767 "rv2cv_op_cv"
8768 Examines an op, which is expected to identify a subroutine at
8769 runtime, and attempts to determine at compile time which subroutine
8770 it identifies. This is normally used during Perl compilation to
8771 determine whether a prototype can be applied to a function call.
8772 "cvop" is the op being considered, normally an "rv2cv" op. A
8773 pointer to the identified subroutine is returned, if it could be
8774 determined statically, and a null pointer is returned if it was not
8775 possible to determine statically.
8776
8777 Currently, the subroutine can be identified statically if the RV
8778 that the "rv2cv" is to operate on is provided by a suitable "gv" or
8779 "const" op. A "gv" op is suitable if the GV's CV slot is
8780 populated. A "const" op is suitable if the constant value must be
8781 an RV pointing to a CV. Details of this process may change in
8782 future versions of Perl. If the "rv2cv" op has the
8783 "OPpENTERSUB_AMPER" flag set then no attempt is made to identify
8784 the subroutine statically: this flag is used to suppress compile-
8785 time magic on a subroutine call, forcing it to use default runtime
8786 behaviour.
8787
8788 If "flags" has the bit "RV2CVOPCV_MARK_EARLY" set, then the
8789 handling of a GV reference is modified. If a GV was examined and
8790 its CV slot was found to be empty, then the "gv" op has the
8791 "OPpEARLY_CV" flag set. If the op is not optimised away, and the
8792 CV slot is later populated with a subroutine having a prototype,
8793 that flag eventually triggers the warning "called too early to
8794 check prototype".
8795
8796 If "flags" has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then instead
8797 of returning a pointer to the subroutine it returns a pointer to
8798 the GV giving the most appropriate name for the subroutine in this
8799 context. Normally this is just the "CvGV" of the subroutine, but
8800 for an anonymous ("CvANON") subroutine that is referenced through a
8801 GV it will be the referencing GV. The resulting "GV*" is cast to
8802 "CV*" to be returned. A null pointer is returned as usual if there
8803 is no statically-determinable subroutine.
8804
8805 CV* rv2cv_op_cv(OP *cvop, U32 flags)
8806
8808 "pack_cat"
8809 "DEPRECATED!" It is planned to remove "pack_cat" from a future
8810 release of Perl. Do not use it for new code; remove it from
8811 existing code.
8812
8813 The engine implementing "pack()" Perl function. Note: parameters
8814 "next_in_list" and "flags" are not used. This call should not be
8815 used; use "packlist" instead.
8816
8817 void pack_cat(SV *cat, const char *pat, const char *patend,
8818 SV **beglist, SV **endlist, SV ***next_in_list,
8819 U32 flags)
8820
8821 "packlist"
8822 The engine implementing "pack()" Perl function.
8823
8824 void packlist(SV *cat, const char *pat, const char *patend,
8825 SV **beglist, SV **endlist)
8826
8827 "unpack_str"
8828 "DEPRECATED!" It is planned to remove "unpack_str" from a future
8829 release of Perl. Do not use it for new code; remove it from
8830 existing code.
8831
8832 The engine implementing "unpack()" Perl function. Note: parameters
8833 "strbeg", "new_s" and "ocnt" are not used. This call should not be
8834 used, use "unpackstring" instead.
8835
8836 SSize_t unpack_str(const char *pat, const char *patend,
8837 const char *s, const char *strbeg,
8838 const char *strend, char **new_s, I32 ocnt,
8839 U32 flags)
8840
8841 "unpackstring"
8842 The engine implementing the "unpack()" Perl function.
8843
8844 Using the template "pat..patend", this function unpacks the string
8845 "s..strend" into a number of mortal SVs, which it pushes onto the
8846 perl argument (@_) stack (so you will need to issue a "PUTBACK"
8847 before and "SPAGAIN" after the call to this function). It returns
8848 the number of pushed elements.
8849
8850 The "strend" and "patend" pointers should point to the byte
8851 following the last character of each string.
8852
8853 Although this function returns its values on the perl argument
8854 stack, it doesn't take any parameters from that stack (and thus in
8855 particular there's no need to do a "PUSHMARK" before calling it,
8856 unlike "call_pv" for example).
8857
8858 SSize_t unpackstring(const char *pat, const char *patend,
8859 const char *s, const char *strend,
8860 U32 flags)
8861
8863 "CvPADLIST"
8864 NOTE: "CvPADLIST" is experimental and may change or be removed
8865 without notice.
8866
8867 CV's can have CvPADLIST(cv) set to point to a PADLIST. This is the
8868 CV's scratchpad, which stores lexical variables and opcode
8869 temporary and per-thread values.
8870
8871 For these purposes "formats" are a kind-of CV; eval""s are too
8872 (except they're not callable at will and are always thrown away
8873 after the eval"" is done executing). Require'd files are simply
8874 evals without any outer lexical scope.
8875
8876 XSUBs do not have a "CvPADLIST". "dXSTARG" fetches values from
8877 "PL_curpad", but that is really the callers pad (a slot of which is
8878 allocated by every entersub). Do not get or set "CvPADLIST" if a CV
8879 is an XSUB (as determined by "CvISXSUB()"), "CvPADLIST" slot is
8880 reused for a different internal purpose in XSUBs.
8881
8882 The PADLIST has a C array where pads are stored.
8883
8884 The 0th entry of the PADLIST is a PADNAMELIST which represents the
8885 "names" or rather the "static type information" for lexicals. The
8886 individual elements of a PADNAMELIST are PADNAMEs. Future
8887 refactorings might stop the PADNAMELIST from being stored in the
8888 PADLIST's array, so don't rely on it. See "PadlistNAMES".
8889
8890 The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the
8891 stack frame at that depth of recursion into the CV. The 0th slot
8892 of a frame AV is an AV which is @_. Other entries are storage for
8893 variables and op targets.
8894
8895 Iterating over the PADNAMELIST iterates over all possible pad
8896 items. Pad slots for targets ("SVs_PADTMP") and GVs end up having
8897 &PL_padname_undef "names", while slots for constants have
8898 &PL_padname_const "names" (see "pad_alloc"). That
8899 &PL_padname_undef and &PL_padname_const are used is an
8900 implementation detail subject to change. To test for them, use
8901 "!PadnamePV(name)" and "PadnamePV(name) && !PadnameLEN(name)",
8902 respectively.
8903
8904 Only "my"/"our" variable slots get valid names. The rest are op
8905 targets/GVs/constants which are statically allocated or resolved at
8906 compile time. These don't have names by which they can be looked
8907 up from Perl code at run time through eval"" the way "my"/"our"
8908 variables can be. Since they can't be looked up by "name" but only
8909 by their index allocated at compile time (which is usually in
8910 "PL_op->op_targ"), wasting a name SV for them doesn't make sense.
8911
8912 The pad names in the PADNAMELIST have their PV holding the name of
8913 the variable. The "COP_SEQ_RANGE_LOW" and "_HIGH" fields form a
8914 range (low+1..high inclusive) of cop_seq numbers for which the name
8915 is valid. During compilation, these fields may hold the special
8916 value PERL_PADSEQ_INTRO to indicate various stages:
8917
8918 COP_SEQ_RANGE_LOW _HIGH
8919 ----------------- -----
8920 PERL_PADSEQ_INTRO 0 variable not yet introduced:
8921 { my ($x
8922 valid-seq# PERL_PADSEQ_INTRO variable in scope:
8923 { my ($x);
8924 valid-seq# valid-seq# compilation of scope complete:
8925 { my ($x); .... }
8926
8927 When a lexical var hasn't yet been introduced, it already exists
8928 from the perspective of duplicate declarations, but not for
8929 variable lookups, e.g.
8930
8931 my ($x, $x); # '"my" variable $x masks earlier declaration'
8932 my $x = $x; # equal to my $x = $::x;
8933
8934 For typed lexicals "PadnameTYPE" points at the type stash. For
8935 "our" lexicals, "PadnameOURSTASH" points at the stash of the
8936 associated global (so that duplicate "our" declarations in the same
8937 package can be detected). "PadnameGEN" is sometimes used to store
8938 the generation number during compilation.
8939
8940 If "PadnameOUTER" is set on the pad name, then that slot in the
8941 frame AV is a REFCNT'ed reference to a lexical from "outside".
8942 Such entries are sometimes referred to as 'fake'. In this case,
8943 the name does not use 'low' and 'high' to store a cop_seq range,
8944 since it is in scope throughout. Instead 'high' stores some flags
8945 containing info about the real lexical (is it declared in an anon,
8946 and is it capable of being instantiated multiple times?), and for
8947 fake ANONs, 'low' contains the index within the parent's pad where
8948 the lexical's value is stored, to make cloning quicker.
8949
8950 If the 'name' is "&" the corresponding entry in the PAD is a CV
8951 representing a possible closure.
8952
8953 Note that formats are treated as anon subs, and are cloned each
8954 time write is called (if necessary).
8955
8956 The flag "SVs_PADSTALE" is cleared on lexicals each time the "my()"
8957 is executed, and set on scope exit. This allows the "Variable $x
8958 is not available" warning to be generated in evals, such as
8959
8960 { my $x = 1; sub f { eval '$x'} } f();
8961
8962 For state vars, "SVs_PADSTALE" is overloaded to mean 'not yet
8963 initialised', but this internal state is stored in a separate pad
8964 entry.
8965
8966 PADLIST * CvPADLIST(CV *cv)
8967
8968 "pad_add_name_pvs"
8969 Exactly like "pad_add_name_pvn", but takes a literal string instead
8970 of a string/length pair.
8971
8972 PADOFFSET pad_add_name_pvs("name", U32 flags, HV *typestash,
8973 HV *ourstash)
8974
8975 "PadARRAY"
8976 NOTE: "PadARRAY" is experimental and may change or be removed
8977 without notice.
8978
8979 The C array of pad entries.
8980
8981 SV ** PadARRAY(PAD * pad)
8982
8983 "pad_findmy_pvs"
8984 Exactly like "pad_findmy_pvn", but takes a literal string instead
8985 of a string/length pair.
8986
8987 PADOFFSET pad_findmy_pvs("name", U32 flags)
8988
8989 "PadlistARRAY"
8990 NOTE: "PadlistARRAY" is experimental and may change or be removed
8991 without notice.
8992
8993 The C array of a padlist, containing the pads. Only subscript it
8994 with numbers >= 1, as the 0th entry is not guaranteed to remain
8995 usable.
8996
8997 PAD ** PadlistARRAY(PADLIST * padlist)
8998
8999 "PadlistMAX"
9000 NOTE: "PadlistMAX" is experimental and may change or be removed
9001 without notice.
9002
9003 The index of the last allocated space in the padlist. Note that
9004 the last pad may be in an earlier slot. Any entries following it
9005 will be "NULL" in that case.
9006
9007 SSize_t PadlistMAX(PADLIST * padlist)
9008
9009 "PadlistNAMES"
9010 NOTE: "PadlistNAMES" is experimental and may change or be removed
9011 without notice.
9012
9013 The names associated with pad entries.
9014
9015 PADNAMELIST * PadlistNAMES(PADLIST * padlist)
9016
9017 "PadlistNAMESARRAY"
9018 NOTE: "PadlistNAMESARRAY" is experimental and may change or be
9019 removed without notice.
9020
9021 The C array of pad names.
9022
9023 PADNAME ** PadlistNAMESARRAY(PADLIST * padlist)
9024
9025 "PadlistNAMESMAX"
9026 NOTE: "PadlistNAMESMAX" is experimental and may change or be
9027 removed without notice.
9028
9029 The index of the last pad name.
9030
9031 SSize_t PadlistNAMESMAX(PADLIST * padlist)
9032
9033 "PadlistREFCNT"
9034 NOTE: "PadlistREFCNT" is experimental and may change or be removed
9035 without notice.
9036
9037 The reference count of the padlist. Currently this is always 1.
9038
9039 U32 PadlistREFCNT(PADLIST * padlist)
9040
9041 "PadMAX"
9042 NOTE: "PadMAX" is experimental and may change or be removed without
9043 notice.
9044
9045 The index of the last pad entry.
9046
9047 SSize_t PadMAX(PAD * pad)
9048
9049 "PadnameLEN"
9050 NOTE: "PadnameLEN" is experimental and may change or be removed
9051 without notice.
9052
9053 The length of the name.
9054
9055 STRLEN PadnameLEN(PADNAME * pn)
9056
9057 "PadnamelistARRAY"
9058 NOTE: "PadnamelistARRAY" is experimental and may change or be
9059 removed without notice.
9060
9061 The C array of pad names.
9062
9063 PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl)
9064
9065 "PadnamelistMAX"
9066 NOTE: "PadnamelistMAX" is experimental and may change or be removed
9067 without notice.
9068
9069 The index of the last pad name.
9070
9071 SSize_t PadnamelistMAX(PADNAMELIST * pnl)
9072
9073 "PadnamelistREFCNT"
9074 NOTE: "PadnamelistREFCNT" is experimental and may change or be
9075 removed without notice.
9076
9077 The reference count of the pad name list.
9078
9079 SSize_t PadnamelistREFCNT(PADNAMELIST * pnl)
9080
9081 "PadnamelistREFCNT_dec"
9082 NOTE: "PadnamelistREFCNT_dec" is experimental and may change or be
9083 removed without notice.
9084
9085 Lowers the reference count of the pad name list.
9086
9087 void PadnamelistREFCNT_dec(PADNAMELIST * pnl)
9088
9089 "PadnamePV"
9090 NOTE: "PadnamePV" is experimental and may change or be removed
9091 without notice.
9092
9093 The name stored in the pad name struct. This returns "NULL" for a
9094 target slot.
9095
9096 char * PadnamePV(PADNAME * pn)
9097
9098 "PadnameREFCNT"
9099 NOTE: "PadnameREFCNT" is experimental and may change or be removed
9100 without notice.
9101
9102 The reference count of the pad name.
9103
9104 SSize_t PadnameREFCNT(PADNAME * pn)
9105
9106 "PadnameREFCNT_dec"
9107 NOTE: "PadnameREFCNT_dec" is experimental and may change or be
9108 removed without notice.
9109
9110 Lowers the reference count of the pad name.
9111
9112 void PadnameREFCNT_dec(PADNAME * pn)
9113
9114 "PadnameSV"
9115 NOTE: "PadnameSV" is experimental and may change or be removed
9116 without notice.
9117
9118 Returns the pad name as a mortal SV.
9119
9120 SV * PadnameSV(PADNAME * pn)
9121
9122 "PadnameUTF8"
9123 NOTE: "PadnameUTF8" is experimental and may change or be removed
9124 without notice.
9125
9126 Whether PadnamePV is in UTF-8. Currently, this is always true.
9127
9128 bool PadnameUTF8(PADNAME * pn)
9129
9130 "pad_new"
9131 Create a new padlist, updating the global variables for the
9132 currently-compiling padlist to point to the new padlist. The
9133 following flags can be OR'ed together:
9134
9135 padnew_CLONE this pad is for a cloned CV
9136 padnew_SAVE save old globals on the save stack
9137 padnew_SAVESUB also save extra stuff for start of sub
9138
9139 PADLIST* pad_new(int flags)
9140
9141 "PL_comppad"
9142 NOTE: "PL_comppad" is experimental and may change or be removed
9143 without notice.
9144
9145 During compilation, this points to the array containing the values
9146 part of the pad for the currently-compiling code. (At runtime a CV
9147 may have many such value arrays; at compile time just one is
9148 constructed.) At runtime, this points to the array containing the
9149 currently-relevant values for the pad for the currently-executing
9150 code.
9151
9152 "PL_comppad_name"
9153 NOTE: "PL_comppad_name" is experimental and may change or be
9154 removed without notice.
9155
9156 During compilation, this points to the array containing the names
9157 part of the pad for the currently-compiling code.
9158
9159 "PL_curpad"
9160 NOTE: "PL_curpad" is experimental and may change or be removed
9161 without notice.
9162
9163 Points directly to the body of the "PL_comppad" array. (I.e., this
9164 is "PadARRAY(PL_comppad)".)
9165
9167 "GRPASSWD"
9168 This symbol, if defined, indicates to the C program that "struct
9169 group" in grp.h contains "gr_passwd".
9170
9171 "HAS_ENDGRENT"
9172 This symbol, if defined, indicates that the getgrent routine is
9173 available for finalizing sequential access of the group database.
9174
9175 "HAS_ENDGRENT_R"
9176 This symbol, if defined, indicates that the "endgrent_r" routine is
9177 available to endgrent re-entrantly.
9178
9179 "HAS_ENDPWENT"
9180 This symbol, if defined, indicates that the getgrent routine is
9181 available for finalizing sequential access of the passwd database.
9182
9183 "HAS_ENDPWENT_R"
9184 This symbol, if defined, indicates that the "endpwent_r" routine is
9185 available to endpwent re-entrantly.
9186
9187 "HAS_GETGRENT"
9188 This symbol, if defined, indicates that the "getgrent" routine is
9189 available for sequential access of the group database.
9190
9191 "HAS_GETGRENT_R"
9192 This symbol, if defined, indicates that the "getgrent_r" routine is
9193 available to getgrent re-entrantly.
9194
9195 "HAS_GETPWENT"
9196 This symbol, if defined, indicates that the "getpwent" routine is
9197 available for sequential access of the passwd database. If this is
9198 not available, the older "getpw()" function may be available.
9199
9200 "HAS_GETPWENT_R"
9201 This symbol, if defined, indicates that the "getpwent_r" routine is
9202 available to getpwent re-entrantly.
9203
9204 "HAS_SETGRENT"
9205 This symbol, if defined, indicates that the "setgrent" routine is
9206 available for initializing sequential access of the group database.
9207
9208 "HAS_SETGRENT_R"
9209 This symbol, if defined, indicates that the "setgrent_r" routine is
9210 available to setgrent re-entrantly.
9211
9212 "HAS_SETPWENT"
9213 This symbol, if defined, indicates that the "setpwent" routine is
9214 available for initializing sequential access of the passwd
9215 database.
9216
9217 "HAS_SETPWENT_R"
9218 This symbol, if defined, indicates that the "setpwent_r" routine is
9219 available to setpwent re-entrantly.
9220
9221 "PWAGE"
9222 This symbol, if defined, indicates to the C program that "struct
9223 passwd" contains "pw_age".
9224
9225 "PWCHANGE"
9226 This symbol, if defined, indicates to the C program that "struct
9227 passwd" contains "pw_change".
9228
9229 "PWCLASS"
9230 This symbol, if defined, indicates to the C program that "struct
9231 passwd" contains "pw_class".
9232
9233 "PWCOMMENT"
9234 This symbol, if defined, indicates to the C program that "struct
9235 passwd" contains "pw_comment".
9236
9237 "PWEXPIRE"
9238 This symbol, if defined, indicates to the C program that "struct
9239 passwd" contains "pw_expire".
9240
9241 "PWGECOS"
9242 This symbol, if defined, indicates to the C program that "struct
9243 passwd" contains "pw_gecos".
9244
9245 "PWPASSWD"
9246 This symbol, if defined, indicates to the C program that "struct
9247 passwd" contains "pw_passwd".
9248
9249 "PWQUOTA"
9250 This symbol, if defined, indicates to the C program that "struct
9251 passwd" contains "pw_quota".
9252
9254 "CSH"
9255 This symbol, if defined, contains the full pathname of csh.
9256
9257 "LOC_SED"
9258 This symbol holds the complete pathname to the sed program.
9259
9260 "SH_PATH"
9261 This symbol contains the full pathname to the shell used on this on
9262 this system to execute Bourne shell scripts. Usually, this will be
9263 /bin/sh, though it's possible that some systems will have /bin/ksh,
9264 /bin/pdksh, /bin/ash, /bin/bash, or even something such as
9265 D:/bin/sh.exe.
9266
9268 "CRYPT_R_PROTO"
9269 This symbol encodes the prototype of "crypt_r". It is zero if
9270 "d_crypt_r" is undef, and one of the "REENTRANT_PROTO_T_ABC" macros
9271 of reentr.h if "d_crypt_r" is defined.
9272
9273 "CTERMID_R_PROTO"
9274 This symbol encodes the prototype of "ctermid_r". It is zero if
9275 "d_ctermid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9276 macros of reentr.h if "d_ctermid_r" is defined.
9277
9278 "DRAND48_R_PROTO"
9279 This symbol encodes the prototype of "drand48_r". It is zero if
9280 "d_drand48_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9281 macros of reentr.h if "d_drand48_r" is defined.
9282
9283 "ENDGRENT_R_PROTO"
9284 This symbol encodes the prototype of "endgrent_r". It is zero if
9285 "d_endgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9286 macros of reentr.h if "d_endgrent_r" is defined.
9287
9288 "ENDHOSTENT_R_PROTO"
9289 This symbol encodes the prototype of "endhostent_r". It is zero if
9290 "d_endhostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9291 macros of reentr.h if "d_endhostent_r" is defined.
9292
9293 "ENDNETENT_R_PROTO"
9294 This symbol encodes the prototype of "endnetent_r". It is zero if
9295 "d_endnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9296 macros of reentr.h if "d_endnetent_r" is defined.
9297
9298 "ENDPROTOENT_R_PROTO"
9299 This symbol encodes the prototype of "endprotoent_r". It is zero
9300 if "d_endprotoent_r" is undef, and one of the
9301 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_endprotoent_r" is
9302 defined.
9303
9304 "ENDPWENT_R_PROTO"
9305 This symbol encodes the prototype of "endpwent_r". It is zero if
9306 "d_endpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9307 macros of reentr.h if "d_endpwent_r" is defined.
9308
9309 "ENDSERVENT_R_PROTO"
9310 This symbol encodes the prototype of "endservent_r". It is zero if
9311 "d_endservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9312 macros of reentr.h if "d_endservent_r" is defined.
9313
9314 "GDBMNDBM_H_USES_PROTOTYPES"
9315 This symbol, if defined, indicates that gdbm/ndbm.h uses real
9316 "ANSI" C prototypes instead of K&R style function declarations
9317 without any parameter information. While "ANSI" C prototypes are
9318 supported in C++, K&R style function declarations will yield
9319 errors.
9320
9321 "GDBM_NDBM_H_USES_PROTOTYPES"
9322 This symbol, if defined, indicates that <gdbm-ndbm.h> uses real
9323 "ANSI" C prototypes instead of K&R style function declarations
9324 without any parameter information. While "ANSI" C prototypes are
9325 supported in C++, K&R style function declarations will yield
9326 errors.
9327
9328 "GETGRENT_R_PROTO"
9329 This symbol encodes the prototype of "getgrent_r". It is zero if
9330 "d_getgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9331 macros of reentr.h if "d_getgrent_r" is defined.
9332
9333 "GETGRGID_R_PROTO"
9334 This symbol encodes the prototype of "getgrgid_r". It is zero if
9335 "d_getgrgid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9336 macros of reentr.h if "d_getgrgid_r" is defined.
9337
9338 "GETGRNAM_R_PROTO"
9339 This symbol encodes the prototype of "getgrnam_r". It is zero if
9340 "d_getgrnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9341 macros of reentr.h if "d_getgrnam_r" is defined.
9342
9343 "GETHOSTBYADDR_R_PROTO"
9344 This symbol encodes the prototype of "gethostbyaddr_r". It is zero
9345 if "d_gethostbyaddr_r" is undef, and one of the
9346 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_gethostbyaddr_r"
9347 is defined.
9348
9349 "GETHOSTBYNAME_R_PROTO"
9350 This symbol encodes the prototype of "gethostbyname_r". It is zero
9351 if "d_gethostbyname_r" is undef, and one of the
9352 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_gethostbyname_r"
9353 is defined.
9354
9355 "GETHOSTENT_R_PROTO"
9356 This symbol encodes the prototype of "gethostent_r". It is zero if
9357 "d_gethostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9358 macros of reentr.h if "d_gethostent_r" is defined.
9359
9360 "GETLOGIN_R_PROTO"
9361 This symbol encodes the prototype of "getlogin_r". It is zero if
9362 "d_getlogin_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9363 macros of reentr.h if "d_getlogin_r" is defined.
9364
9365 "GETNETBYADDR_R_PROTO"
9366 This symbol encodes the prototype of "getnetbyaddr_r". It is zero
9367 if "d_getnetbyaddr_r" is undef, and one of the
9368 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getnetbyaddr_r" is
9369 defined.
9370
9371 "GETNETBYNAME_R_PROTO"
9372 This symbol encodes the prototype of "getnetbyname_r". It is zero
9373 if "d_getnetbyname_r" is undef, and one of the
9374 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getnetbyname_r" is
9375 defined.
9376
9377 "GETNETENT_R_PROTO"
9378 This symbol encodes the prototype of "getnetent_r". It is zero if
9379 "d_getnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9380 macros of reentr.h if "d_getnetent_r" is defined.
9381
9382 "GETPROTOBYNAME_R_PROTO"
9383 This symbol encodes the prototype of "getprotobyname_r". It is
9384 zero if "d_getprotobyname_r" is undef, and one of the
9385 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getprotobyname_r"
9386 is defined.
9387
9388 "GETPROTOBYNUMBER_R_PROTO"
9389 This symbol encodes the prototype of "getprotobynumber_r". It is
9390 zero if "d_getprotobynumber_r" is undef, and one of the
9391 "REENTRANT_PROTO_T_ABC" macros of reentr.h if
9392 "d_getprotobynumber_r" is defined.
9393
9394 "GETPROTOENT_R_PROTO"
9395 This symbol encodes the prototype of "getprotoent_r". It is zero
9396 if "d_getprotoent_r" is undef, and one of the
9397 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getprotoent_r" is
9398 defined.
9399
9400 "GETPWENT_R_PROTO"
9401 This symbol encodes the prototype of "getpwent_r". It is zero if
9402 "d_getpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9403 macros of reentr.h if "d_getpwent_r" is defined.
9404
9405 "GETPWNAM_R_PROTO"
9406 This symbol encodes the prototype of "getpwnam_r". It is zero if
9407 "d_getpwnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9408 macros of reentr.h if "d_getpwnam_r" is defined.
9409
9410 "GETPWUID_R_PROTO"
9411 This symbol encodes the prototype of "getpwuid_r". It is zero if
9412 "d_getpwuid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9413 macros of reentr.h if "d_getpwuid_r" is defined.
9414
9415 "GETSERVBYNAME_R_PROTO"
9416 This symbol encodes the prototype of "getservbyname_r". It is zero
9417 if "d_getservbyname_r" is undef, and one of the
9418 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getservbyname_r"
9419 is defined.
9420
9421 "GETSERVBYPORT_R_PROTO"
9422 This symbol encodes the prototype of "getservbyport_r". It is zero
9423 if "d_getservbyport_r" is undef, and one of the
9424 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getservbyport_r"
9425 is defined.
9426
9427 "GETSERVENT_R_PROTO"
9428 This symbol encodes the prototype of "getservent_r". It is zero if
9429 "d_getservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9430 macros of reentr.h if "d_getservent_r" is defined.
9431
9432 "GETSPNAM_R_PROTO"
9433 This symbol encodes the prototype of "getspnam_r". It is zero if
9434 "d_getspnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9435 macros of reentr.h if "d_getspnam_r" is defined.
9436
9437 "HAS_DBMINIT_PROTO"
9438 This symbol, if defined, indicates that the system provides a
9439 prototype for the "dbminit()" function. Otherwise, it is up to the
9440 program to supply one. A good guess is
9441
9442 extern int dbminit(char *);
9443
9444 "HAS_DRAND48_PROTO"
9445 This symbol, if defined, indicates that the system provides a
9446 prototype for the "drand48()" function. Otherwise, it is up to the
9447 program to supply one. A good guess is
9448
9449 extern double drand48(void);
9450
9451 "HAS_FLOCK_PROTO"
9452 This symbol, if defined, indicates that the system provides a
9453 prototype for the "flock()" function. Otherwise, it is up to the
9454 program to supply one. A good guess is
9455
9456 extern int flock(int, int);
9457
9458 "HAS_GETHOST_PROTOS"
9459 This symbol, if defined, indicates that netdb.h includes prototypes
9460 for "gethostent()", "gethostbyname()", and "gethostbyaddr()".
9461 Otherwise, it is up to the program to guess them. See netdbtype.U
9462 (part of metaconfig) for probing for various "Netdb_xxx_t" types.
9463
9464 "HAS_GETNET_PROTOS"
9465 This symbol, if defined, indicates that netdb.h includes prototypes
9466 for "getnetent()", "getnetbyname()", and "getnetbyaddr()".
9467 Otherwise, it is up to the program to guess them. See netdbtype.U
9468 (part of metaconfig) for probing for various "Netdb_xxx_t" types.
9469
9470 "HAS_GETPROTO_PROTOS"
9471 This symbol, if defined, indicates that netdb.h includes prototypes
9472 for "getprotoent()", "getprotobyname()", and "getprotobyaddr()".
9473 Otherwise, it is up to the program to guess them. See netdbtype.U
9474 (part of metaconfig) for probing for various "Netdb_xxx_t" types.
9475
9476 "HAS_GETSERV_PROTOS"
9477 This symbol, if defined, indicates that netdb.h includes prototypes
9478 for "getservent()", "getservbyname()", and "getservbyaddr()".
9479 Otherwise, it is up to the program to guess them. See netdbtype.U
9480 (part of metaconfig) for probing for various "Netdb_xxx_t" types.
9481
9482 "HAS_MODFL_PROTO"
9483 This symbol, if defined, indicates that the system provides a
9484 prototype for the "modfl()" function. Otherwise, it is up to the
9485 program to supply one.
9486
9487 "HAS_SBRK_PROTO"
9488 This symbol, if defined, indicates that the system provides a
9489 prototype for the "sbrk()" function. Otherwise, it is up to the
9490 program to supply one. Good guesses are
9491
9492 extern void* sbrk(int);
9493 extern void* sbrk(size_t);
9494
9495 "HAS_SETRESGID_PROTO"
9496 This symbol, if defined, indicates that the system provides a
9497 prototype for the "setresgid()" function. Otherwise, it is up to
9498 the program to supply one. Good guesses are
9499
9500 extern int setresgid(uid_t ruid, uid_t euid, uid_t suid);
9501
9502 "HAS_SETRESUID_PROTO"
9503 This symbol, if defined, indicates that the system provides a
9504 prototype for the "setresuid()" function. Otherwise, it is up to
9505 the program to supply one. Good guesses are
9506
9507 extern int setresuid(uid_t ruid, uid_t euid, uid_t suid);
9508
9509 "HAS_SHMAT_PROTOTYPE"
9510 This symbol, if defined, indicates that the sys/shm.h includes a
9511 prototype for "shmat()". Otherwise, it is up to the program to
9512 guess one. "Shmat_t" "shmat(int, Shmat_t, int)" is a good guess,
9513 but not always right so it should be emitted by the program only
9514 when "HAS_SHMAT_PROTOTYPE" is not defined to avoid conflicting
9515 defs.
9516
9517 "HAS_SOCKATMARK_PROTO"
9518 This symbol, if defined, indicates that the system provides a
9519 prototype for the "sockatmark()" function. Otherwise, it is up to
9520 the program to supply one. A good guess is
9521
9522 extern int sockatmark(int);
9523
9524 "HAS_SYSCALL_PROTO"
9525 This symbol, if defined, indicates that the system provides a
9526 prototype for the "syscall()" function. Otherwise, it is up to the
9527 program to supply one. Good guesses are
9528
9529 extern int syscall(int, ...);
9530 extern int syscall(long, ...);
9531
9532 "HAS_TELLDIR_PROTO"
9533 This symbol, if defined, indicates that the system provides a
9534 prototype for the "telldir()" function. Otherwise, it is up to the
9535 program to supply one. A good guess is
9536
9537 extern long telldir(DIR*);
9538
9539 "NDBM_H_USES_PROTOTYPES"
9540 This symbol, if defined, indicates that ndbm.h uses real "ANSI" C
9541 prototypes instead of K&R style function declarations without any
9542 parameter information. While "ANSI" C prototypes are supported in
9543 C++, K&R style function declarations will yield errors.
9544
9545 "RANDOM_R_PROTO"
9546 This symbol encodes the prototype of "random_r". It is zero if
9547 "d_random_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9548 macros of reentr.h if "d_random_r" is defined.
9549
9550 "READDIR_R_PROTO"
9551 This symbol encodes the prototype of "readdir_r". It is zero if
9552 "d_readdir_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9553 macros of reentr.h if "d_readdir_r" is defined.
9554
9555 "SETGRENT_R_PROTO"
9556 This symbol encodes the prototype of "setgrent_r". It is zero if
9557 "d_setgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9558 macros of reentr.h if "d_setgrent_r" is defined.
9559
9560 "SETHOSTENT_R_PROTO"
9561 This symbol encodes the prototype of "sethostent_r". It is zero if
9562 "d_sethostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9563 macros of reentr.h if "d_sethostent_r" is defined.
9564
9565 "SETLOCALE_R_PROTO"
9566 This symbol encodes the prototype of "setlocale_r". It is zero if
9567 "d_setlocale_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9568 macros of reentr.h if "d_setlocale_r" is defined.
9569
9570 "SETNETENT_R_PROTO"
9571 This symbol encodes the prototype of "setnetent_r". It is zero if
9572 "d_setnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9573 macros of reentr.h if "d_setnetent_r" is defined.
9574
9575 "SETPROTOENT_R_PROTO"
9576 This symbol encodes the prototype of "setprotoent_r". It is zero
9577 if "d_setprotoent_r" is undef, and one of the
9578 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_setprotoent_r" is
9579 defined.
9580
9581 "SETPWENT_R_PROTO"
9582 This symbol encodes the prototype of "setpwent_r". It is zero if
9583 "d_setpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9584 macros of reentr.h if "d_setpwent_r" is defined.
9585
9586 "SETSERVENT_R_PROTO"
9587 This symbol encodes the prototype of "setservent_r". It is zero if
9588 "d_setservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9589 macros of reentr.h if "d_setservent_r" is defined.
9590
9591 "SRAND48_R_PROTO"
9592 This symbol encodes the prototype of "srand48_r". It is zero if
9593 "d_srand48_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9594 macros of reentr.h if "d_srand48_r" is defined.
9595
9596 "SRANDOM_R_PROTO"
9597 This symbol encodes the prototype of "srandom_r". It is zero if
9598 "d_srandom_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9599 macros of reentr.h if "d_srandom_r" is defined.
9600
9601 "STRERROR_R_PROTO"
9602 This symbol encodes the prototype of "strerror_r". It is zero if
9603 "d_strerror_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9604 macros of reentr.h if "d_strerror_r" is defined.
9605
9606 "TMPNAM_R_PROTO"
9607 This symbol encodes the prototype of "tmpnam_r". It is zero if
9608 "d_tmpnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9609 macros of reentr.h if "d_tmpnam_r" is defined.
9610
9611 "TTYNAME_R_PROTO"
9612 This symbol encodes the prototype of "ttyname_r". It is zero if
9613 "d_ttyname_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9614 macros of reentr.h if "d_ttyname_r" is defined.
9615
9617 "pregcomp"
9618 Described in perlreguts.
9619
9620 REGEXP* pregcomp(SV * const pattern, const U32 flags)
9621
9622 "pregexec"
9623 Described in perlreguts.
9624
9625 I32 pregexec(REGEXP * const prog, char* stringarg, char* strend,
9626 char* strbeg, SSize_t minend, SV* screamer,
9627 U32 nosave)
9628
9629 "re_dup_guts"
9630 Duplicate a regexp.
9631
9632 This routine is expected to clone a given regexp structure. It is
9633 only compiled under USE_ITHREADS.
9634
9635 After all of the core data stored in struct regexp is duplicated
9636 the "regexp_engine.dupe" method is used to copy any private data
9637 stored in the *pprivate pointer. This allows extensions to handle
9638 any duplication they need to do.
9639
9640 void re_dup_guts(const REGEXP *sstr, REGEXP *dstr,
9641 CLONE_PARAMS* param)
9642
9643 "regmatch_info"
9644 Some basic information about the current match that is created by
9645 Perl_regexec_flags and then passed to regtry(), regmatch() etc. It
9646 is allocated as a local var on the stack, so nothing should be
9647 stored in it that needs preserving or clearing up on croak(). For
9648 that, see the aux_info and aux_info_eval members of the
9649 regmatch_state union.
9650
9651 "SvRX"
9652 Convenience macro to get the REGEXP from a SV. This is
9653 approximately equivalent to the following snippet:
9654
9655 if (SvMAGICAL(sv))
9656 mg_get(sv);
9657 if (SvROK(sv))
9658 sv = MUTABLE_SV(SvRV(sv));
9659 if (SvTYPE(sv) == SVt_REGEXP)
9660 return (REGEXP*) sv;
9661
9662 "NULL" will be returned if a REGEXP* is not found.
9663
9664 REGEXP * SvRX(SV *sv)
9665
9666 "SvRXOK"
9667 Returns a boolean indicating whether the SV (or the one it
9668 references) is a REGEXP.
9669
9670 If you want to do something with the REGEXP* later use SvRX instead
9671 and check for NULL.
9672
9673 bool SvRXOK(SV* sv)
9674
9676 "HAS_SIGINFO_SI_ADDR"
9677 This symbol, if defined, indicates that "siginfo_t" has the
9678 "si_addr" member
9679
9680 "HAS_SIGINFO_SI_BAND"
9681 This symbol, if defined, indicates that "siginfo_t" has the
9682 "si_band" member
9683
9684 "HAS_SIGINFO_SI_ERRNO"
9685 This symbol, if defined, indicates that "siginfo_t" has the
9686 "si_errno" member
9687
9688 "HAS_SIGINFO_SI_PID"
9689 This symbol, if defined, indicates that "siginfo_t" has the
9690 "si_pid" member
9691
9692 "HAS_SIGINFO_SI_STATUS"
9693 This symbol, if defined, indicates that "siginfo_t" has the
9694 "si_status" member
9695
9696 "HAS_SIGINFO_SI_UID"
9697 This symbol, if defined, indicates that "siginfo_t" has the
9698 "si_uid" member
9699
9700 "HAS_SIGINFO_SI_VALUE"
9701 This symbol, if defined, indicates that "siginfo_t" has the
9702 "si_value" member
9703
9704 "PERL_SIGNALS_UNSAFE_FLAG"
9705 If this bit in "PL_signals" is set, the system is uing the pre-Perl
9706 5.8 unsafe signals. See "PERL_SIGNALS" in perlrun and "Deferred
9707 Signals (Safe Signals)" in perlipc.
9708
9709 U32 PERL_SIGNALS_UNSAFE_FLAG
9710
9711 "rsignal"
9712 A wrapper for the C library signal(2). Don't use the latter, as
9713 the Perl version knows things that interact with the rest of the
9714 perl interpreter.
9715
9716 Sighandler_t rsignal(int i, Sighandler_t t)
9717
9718 "Sigjmp_buf"
9719 This is the buffer type to be used with Sigsetjmp and Siglongjmp.
9720
9721 "Siglongjmp"
9722 This macro is used in the same way as "siglongjmp()", but will
9723 invoke traditional "longjmp()" if siglongjmp isn't available. See
9724 "HAS_SIGSETJMP".
9725
9726 void Siglongjmp(jmp_buf env, int val)
9727
9728 "SIG_NAME"
9729 This symbol contains a list of signal names in order of signal
9730 number. This is intended to be used as a static array
9731 initialization, like this:
9732
9733 char *sig_name[] = { SIG_NAME };
9734
9735 The signals in the list are separated with commas, and each signal
9736 is surrounded by double quotes. There is no leading "SIG" in the
9737 signal name, i.e. "SIGQUIT" is known as ""QUIT"". Gaps in the
9738 signal numbers (up to "NSIG") are filled in with "NUMnn", etc.,
9739 where nn is the actual signal number (e.g. "NUM37"). The signal
9740 number for "sig_name[i]" is stored in "sig_num[i]". The last
9741 element is 0 to terminate the list with a "NULL". This corresponds
9742 to the 0 at the end of the "sig_name_init" list. Note that this
9743 variable is initialized from the "sig_name_init", not from
9744 "sig_name" (which is unused).
9745
9746 "SIG_NUM"
9747 This symbol contains a list of signal numbers, in the same order as
9748 the "SIG_NAME" list. It is suitable for static array
9749 initialization, as in:
9750
9751 int sig_num[] = { SIG_NUM };
9752
9753 The signals in the list are separated with commas, and the indices
9754 within that list and the "SIG_NAME" list match, so it's easy to
9755 compute the signal name from a number or vice versa at the price of
9756 a small dynamic linear lookup. Duplicates are allowed, but are
9757 moved to the end of the list. The signal number corresponding to
9758 "sig_name[i]" is "sig_number[i]". if (i < "NSIG") then
9759 "sig_number[i]" == i. The last element is 0, corresponding to the
9760 0 at the end of the "sig_name_init" list. Note that this variable
9761 is initialized from the "sig_num_init", not from "sig_num" (which
9762 is unused).
9763
9764 "Sigsetjmp"
9765 This macro is used in the same way as "sigsetjmp()", but will
9766 invoke traditional "setjmp()" if sigsetjmp isn't available. See
9767 "HAS_SIGSETJMP".
9768
9769 int Sigsetjmp(jmp_buf env, int savesigs)
9770
9771 "SIG_SIZE"
9772 This variable contains the number of elements of the "SIG_NAME" and
9773 "SIG_NUM" arrays, excluding the final "NULL" entry.
9774
9775 "whichsig"
9776 "whichsig_pv"
9777 "whichsig_pvn"
9778 "whichsig_sv"
9779 These all convert a signal name into its corresponding signal
9780 number; returning -1 if no corresponding number was found.
9781
9782 They differ only in the source of the signal name:
9783
9784 "whichsig_pv" takes the name from the "NUL"-terminated string
9785 starting at "sig".
9786
9787 "whichsig" is merely a different spelling, a synonym, of
9788 "whichsig_pv".
9789
9790 "whichsig_pvn" takes the name from the string starting at "sig",
9791 with length "len" bytes.
9792
9793 "whichsig_sv" takes the name from the PV stored in the SV "sigsv".
9794
9795 I32 whichsig (const char* sig)
9796 I32 whichsig_pv (const char* sig)
9797 I32 whichsig_pvn(const char* sig, STRLEN len)
9798 I32 whichsig_sv (SV* sigsv)
9799
9801 These variables give details as to where various libraries,
9802 installation destinations, etc., go, as well as what various
9803 installation options were selected
9804
9805 "ARCHLIB"
9806 This variable, if defined, holds the name of the directory in which
9807 the user wants to put architecture-dependent public library files
9808 for perl5. It is most often a local directory such as
9809 /usr/local/lib. Programs using this variable must be prepared to
9810 deal with filename expansion. If "ARCHLIB" is the same as
9811 "PRIVLIB", it is not defined, since presumably the program already
9812 searches "PRIVLIB".
9813
9814 "ARCHLIB_EXP"
9815 This symbol contains the ~name expanded version of "ARCHLIB", to be
9816 used in programs that are not prepared to deal with ~ expansion at
9817 run-time.
9818
9819 "ARCHNAME"
9820 This symbol holds a string representing the architecture name. It
9821 may be used to construct an architecture-dependant pathname where
9822 library files may be held under a private library, for instance.
9823
9824 "BIN"
9825 This symbol holds the path of the bin directory where the package
9826 will be installed. Program must be prepared to deal with ~name
9827 substitution.
9828
9829 "BIN_EXP"
9830 This symbol is the filename expanded version of the "BIN" symbol,
9831 for programs that do not want to deal with that at run-time.
9832
9833 "INSTALL_USR_BIN_PERL"
9834 This symbol, if defined, indicates that Perl is to be installed
9835 also as /usr/bin/perl.
9836
9837 "MULTIARCH"
9838 This symbol, if defined, signifies that the build process will
9839 produce some binary files that are going to be used in a cross-
9840 platform environment. This is the case for example with the NeXT
9841 "fat" binaries that contain executables for several "CPUs".
9842
9843 "PERL_INC_VERSION_LIST"
9844 This variable specifies the list of subdirectories in over which
9845 perl.c:"incpush()" and lib/lib.pm will automatically search when
9846 adding directories to @"INC", in a format suitable for a C
9847 initialization string. See the "inc_version_list" entry in
9848 Porting/Glossary for more details.
9849
9850 "PERL_OTHERLIBDIRS"
9851 This variable contains a colon-separated set of paths for the perl
9852 binary to search for additional library files or modules. These
9853 directories will be tacked to the end of @"INC". Perl will
9854 automatically search below each path for version- and architecture-
9855 specific directories. See "PERL_INC_VERSION_LIST" for more
9856 details.
9857
9858 "PERL_RELOCATABLE_INC"
9859 This symbol, if defined, indicates that we'd like to relocate
9860 entries in @"INC" at run time based on the location of the perl
9861 binary.
9862
9863 "PERL_TARGETARCH"
9864 This symbol, if defined, indicates the target architecture Perl has
9865 been cross-compiled to. Undefined if not a cross-compile.
9866
9867 "PERL_USE_DEVEL"
9868 This symbol, if defined, indicates that Perl was configured with
9869 "-Dusedevel", to enable development features. This should not be
9870 done for production builds.
9871
9872 "PERL_VENDORARCH"
9873 If defined, this symbol contains the name of a private library.
9874 The library is private in the sense that it needn't be in anyone's
9875 execution path, but it should be accessible by the world. It may
9876 have a ~ on the front. The standard distribution will put nothing
9877 in this directory. Vendors who distribute perl may wish to place
9878 their own architecture-dependent modules and extensions in this
9879 directory with
9880
9881 MakeMaker Makefile.PL INSTALLDIRS=vendor
9882
9883 or equivalent. See "INSTALL" for details.
9884
9885 "PERL_VENDORARCH_EXP"
9886 This symbol contains the ~name expanded version of
9887 "PERL_VENDORARCH", to be used in programs that are not prepared to
9888 deal with ~ expansion at run-time.
9889
9890 "PERL_VENDORLIB_EXP"
9891 This symbol contains the ~name expanded version of "VENDORLIB", to
9892 be used in programs that are not prepared to deal with ~ expansion
9893 at run-time.
9894
9895 "PERL_VENDORLIB_STEM"
9896 This define is "PERL_VENDORLIB_EXP" with any trailing version-
9897 specific component removed. The elements in "inc_version_list"
9898 ("inc_version_list".U (part of metaconfig)) can be tacked onto this
9899 variable to generate a list of directories to search.
9900
9901 "PRIVLIB"
9902 This symbol contains the name of the private library for this
9903 package. The library is private in the sense that it needn't be in
9904 anyone's execution path, but it should be accessible by the world.
9905 The program should be prepared to do ~ expansion.
9906
9907 "PRIVLIB_EXP"
9908 This symbol contains the ~name expanded version of "PRIVLIB", to be
9909 used in programs that are not prepared to deal with ~ expansion at
9910 run-time.
9911
9912 "SITEARCH"
9913 This symbol contains the name of the private library for this
9914 package. The library is private in the sense that it needn't be in
9915 anyone's execution path, but it should be accessible by the world.
9916 The program should be prepared to do ~ expansion. The standard
9917 distribution will put nothing in this directory. After perl has
9918 been installed, users may install their own local architecture-
9919 dependent modules in this directory with
9920
9921 MakeMaker Makefile.PL
9922
9923 or equivalent. See "INSTALL" for details.
9924
9925 "SITEARCH_EXP"
9926 This symbol contains the ~name expanded version of "SITEARCH", to
9927 be used in programs that are not prepared to deal with ~ expansion
9928 at run-time.
9929
9930 "SITELIB"
9931 This symbol contains the name of the private library for this
9932 package. The library is private in the sense that it needn't be in
9933 anyone's execution path, but it should be accessible by the world.
9934 The program should be prepared to do ~ expansion. The standard
9935 distribution will put nothing in this directory. After perl has
9936 been installed, users may install their own local architecture-
9937 independent modules in this directory with
9938
9939 MakeMaker Makefile.PL
9940
9941 or equivalent. See "INSTALL" for details.
9942
9943 "SITELIB_EXP"
9944 This symbol contains the ~name expanded version of "SITELIB", to be
9945 used in programs that are not prepared to deal with ~ expansion at
9946 run-time.
9947
9948 "SITELIB_STEM"
9949 This define is "SITELIB_EXP" with any trailing version-specific
9950 component removed. The elements in "inc_version_list"
9951 ("inc_version_list".U (part of metaconfig)) can be tacked onto this
9952 variable to generate a list of directories to search.
9953
9954 "STARTPERL"
9955 This variable contains the string to put in front of a perl script
9956 to make sure (one hopes) that it runs with perl and not some shell.
9957
9958 "USE_64_BIT_ALL"
9959 This symbol, if defined, indicates that 64-bit integers should be
9960 used when available. If not defined, the native integers will be
9961 used (be they 32 or 64 bits). The maximal possible 64-bitness is
9962 employed: LP64 or "ILP64", meaning that you will be able to use
9963 more than 2 gigabytes of memory. This mode is even more binary
9964 incompatible than "USE_64_BIT_INT". You may not be able to run the
9965 resulting executable in a 32-bit "CPU" at all or you may need at
9966 least to reboot your OS to 64-bit mode.
9967
9968 "USE_64_BIT_INT"
9969 This symbol, if defined, indicates that 64-bit integers should be
9970 used when available. If not defined, the native integers will be
9971 employed (be they 32 or 64 bits). The minimal possible 64-bitness
9972 is used, just enough to get 64-bit integers into Perl. This may
9973 mean using for example "long longs", while your memory may still be
9974 limited to 2 gigabytes.
9975
9976 "USE_BSD_GETPGRP"
9977 This symbol, if defined, indicates that getpgrp needs one arguments
9978 whereas "USG" one needs none.
9979
9980 "USE_BSD_SETPGRP"
9981 This symbol, if defined, indicates that setpgrp needs two arguments
9982 whereas "USG" one needs none. See also "HAS_SETPGID" for a "POSIX"
9983 interface.
9984
9985 "USE_CPLUSPLUS"
9986 This symbol, if defined, indicates that a C++ compiler was used to
9987 compiled Perl and will be used to compile extensions.
9988
9989 "USE_CROSS_COMPILE"
9990 This symbol, if defined, indicates that Perl is being cross-
9991 compiled.
9992
9993 "USE_C_BACKTRACE"
9994 This symbol, if defined, indicates that Perl should be built with
9995 support for backtrace.
9996
9997 "USE_DTRACE"
9998 This symbol, if defined, indicates that Perl should be built with
9999 support for DTrace.
10000
10001 "USE_DYNAMIC_LOADING"
10002 This symbol, if defined, indicates that dynamic loading of some
10003 sort is available.
10004
10005 "USE_FAST_STDIO"
10006 This symbol, if defined, indicates that Perl should be built to use
10007 'fast stdio'. Defaults to define in Perls 5.8 and earlier, to
10008 undef later.
10009
10010 "USE_ITHREADS"
10011 This symbol, if defined, indicates that Perl should be built to use
10012 the interpreter-based threading implementation.
10013
10014 "USE_KERN_PROC_PATHNAME"
10015 This symbol, if defined, indicates that we can use sysctl with
10016 "KERN_PROC_PATHNAME" to get a full path for the executable, and
10017 hence convert $^X to an absolute path.
10018
10019 "USE_LARGE_FILES"
10020 This symbol, if defined, indicates that large file support should
10021 be used when available.
10022
10023 "USE_LONG_DOUBLE"
10024 This symbol, if defined, indicates that long doubles should be used
10025 when available.
10026
10027 "USE_MORE_BITS"
10028 This symbol, if defined, indicates that 64-bit interfaces and long
10029 doubles should be used when available.
10030
10031 "USE_NSGETEXECUTABLEPATH"
10032 This symbol, if defined, indicates that we can use
10033 "_NSGetExecutablePath" and realpath to get a full path for the
10034 executable, and hence convert $^X to an absolute path.
10035
10036 "USE_PERLIO"
10037 This symbol, if defined, indicates that the PerlIO abstraction
10038 should be used throughout. If not defined, stdio should be used in
10039 a fully backward compatible manner.
10040
10041 "USE_QUADMATH"
10042 This symbol, if defined, indicates that the quadmath library should
10043 be used when available.
10044
10045 "USE_REENTRANT_API"
10046 This symbol, if defined, indicates that Perl should try to use the
10047 various "_r" versions of library functions. This is extremely
10048 experimental.
10049
10050 "USE_SEMCTL_SEMID_DS"
10051 This symbol, if defined, indicates that "struct semid_ds" * is used
10052 for semctl "IPC_STAT".
10053
10054 "USE_SEMCTL_SEMUN"
10055 This symbol, if defined, indicates that "union semun" is used for
10056 semctl "IPC_STAT".
10057
10058 "USE_SITECUSTOMIZE"
10059 This symbol, if defined, indicates that sitecustomize should be
10060 used.
10061
10062 "USE_SOCKS"
10063 This symbol, if defined, indicates that Perl should be built to use
10064 socks.
10065
10066 "USE_STAT_BLOCKS"
10067 This symbol is defined if this system has a stat structure
10068 declaring "st_blksize" and "st_blocks".
10069
10070 "USE_STDIO_BASE"
10071 This symbol is defined if the "_base" field (or similar) of the
10072 stdio "FILE" structure can be used to access the stdio buffer for a
10073 file handle. If this is defined, then the "FILE_base(fp)" macro
10074 will also be defined and should be used to access this field.
10075 Also, the "FILE_bufsiz(fp)" macro will be defined and should be
10076 used to determine the number of bytes in the buffer.
10077 "USE_STDIO_BASE" will never be defined unless "USE_STDIO_PTR" is.
10078
10079 "USE_STDIO_PTR"
10080 This symbol is defined if the "_ptr" and "_cnt" fields (or similar)
10081 of the stdio "FILE" structure can be used to access the stdio
10082 buffer for a file handle. If this is defined, then the
10083 "FILE_ptr(fp)" and "FILE_cnt(fp)" macros will also be defined and
10084 should be used to access these fields.
10085
10086 "USE_STRICT_BY_DEFAULT"
10087 This symbol, if defined, enables additional defaults. At this time
10088 it only enables implicit strict by default.
10089
10090 "USE_THREADS"
10091 This symbol, if defined, indicates that Perl should be built to use
10092 threads. At present, it is a synonym for and "USE_ITHREADS", but
10093 eventually the source ought to be changed to use this to mean
10094 "_any_" threading implementation.
10095
10097 "HAS_SOCKADDR_IN6"
10098 This symbol, if defined, indicates the availability of "struct
10099 sockaddr_in6";
10100
10101 "HAS_SOCKADDR_SA_LEN"
10102 This symbol, if defined, indicates that the "struct sockaddr"
10103 structure has a member called "sa_len", indicating the length of
10104 the structure.
10105
10106 "HAS_SOCKADDR_STORAGE"
10107 This symbol, if defined, indicates the availability of "struct
10108 sockaddr_storage";
10109
10110 "HAS_SOCKATMARK"
10111 This symbol, if defined, indicates that the "sockatmark" routine is
10112 available to test whether a socket is at the out-of-band mark.
10113
10114 "HAS_SOCKET"
10115 This symbol, if defined, indicates that the "BSD" "socket"
10116 interface is supported.
10117
10118 "HAS_SOCKETPAIR"
10119 This symbol, if defined, indicates that the "BSD" "socketpair()"
10120 call is supported.
10121
10122 "HAS_SOCKS5_INIT"
10123 This symbol, if defined, indicates that the "socks5_init" routine
10124 is available to initialize "SOCKS" 5.
10125
10126 "I_SOCKS"
10127 This symbol, if defined, indicates that socks.h exists and should
10128 be included.
10129
10130 #ifdef I_SOCKS
10131 #include <socks.h>
10132 #endif
10133
10134 "I_SYS_SOCKIO"
10135 This symbol, if defined, indicates the sys/sockio.h should be
10136 included to get socket ioctl options, like "SIOCATMARK".
10137
10138 #ifdef I_SYS_SOCKIO
10139 #include <sys_sockio.h>
10140 #endif
10141
10143 "filter_add"
10144 Described in perlfilter.
10145
10146 SV* filter_add(filter_t funcp, SV* datasv)
10147
10148 "filter_read"
10149 Described in perlfilter.
10150
10151 I32 filter_read(int idx, SV *buf_sv, int maxlen)
10152
10154 "BHK"
10155 Described in perlguts.
10156
10157 "BINOP"
10158 Described in perlguts.
10159
10160 "DESTRUCTORFUNC_NOCONTEXT_t"
10161 Described in perlguts.
10162
10163 "DESTRUCTORFUNC_t"
10164 Described in perlguts.
10165
10166 "dMARK"
10167 Declare a stack marker variable, "mark", for the XSUB. See "MARK"
10168 and "dORIGMARK".
10169
10170 dMARK;
10171
10172 "dORIGMARK"
10173 Saves the original stack mark for the XSUB. See "ORIGMARK".
10174
10175 dORIGMARK;
10176
10177 "dSP"
10178 Declares a local copy of perl's stack pointer for the XSUB,
10179 available via the "SP" macro. See "SP".
10180
10181 dSP;
10182
10183 "dTARGET"
10184 Declare that this function uses "TARG"
10185
10186 dTARGET;
10187
10188 "EXTEND"
10189 Used to extend the argument stack for an XSUB's return values.
10190 Once used, guarantees that there is room for at least "nitems" to
10191 be pushed onto the stack.
10192
10193 void EXTEND(SP, SSize_t nitems)
10194
10195 "LISTOP"
10196 Described in perlguts.
10197
10198 "LOGOP"
10199 Described in perlguts.
10200
10201 "LOOP"
10202 Described in perlguts.
10203
10204 "MARK"
10205 Stack marker variable for the XSUB. See "dMARK".
10206
10207 "mPUSHi"
10208 Push an integer onto the stack. The stack must have room for this
10209 element. Does not use "TARG". See also "PUSHi", "mXPUSHi" and
10210 "XPUSHi".
10211
10212 void mPUSHi(IV iv)
10213
10214 "mPUSHn"
10215 Push a double onto the stack. The stack must have room for this
10216 element. Does not use "TARG". See also "PUSHn", "mXPUSHn" and
10217 "XPUSHn".
10218
10219 void mPUSHn(NV nv)
10220
10221 "mPUSHp"
10222 Push a string onto the stack. The stack must have room for this
10223 element. The "len" indicates the length of the string. Does not
10224 use "TARG". See also "PUSHp", "mXPUSHp" and "XPUSHp".
10225
10226 void mPUSHp(char* str, STRLEN len)
10227
10228 "mPUSHs"
10229 Push an SV onto the stack and mortalizes the SV. The stack must
10230 have room for this element. Does not use "TARG". See also "PUSHs"
10231 and "mXPUSHs".
10232
10233 void mPUSHs(SV* sv)
10234
10235 "mPUSHu"
10236 Push an unsigned integer onto the stack. The stack must have room
10237 for this element. Does not use "TARG". See also "PUSHu",
10238 "mXPUSHu" and "XPUSHu".
10239
10240 void mPUSHu(UV uv)
10241
10242 "mXPUSHi"
10243 Push an integer onto the stack, extending the stack if necessary.
10244 Does not use "TARG". See also "XPUSHi", "mPUSHi" and "PUSHi".
10245
10246 void mXPUSHi(IV iv)
10247
10248 "mXPUSHn"
10249 Push a double onto the stack, extending the stack if necessary.
10250 Does not use "TARG". See also "XPUSHn", "mPUSHn" and "PUSHn".
10251
10252 void mXPUSHn(NV nv)
10253
10254 "mXPUSHp"
10255 Push a string onto the stack, extending the stack if necessary.
10256 The "len" indicates the length of the string. Does not use "TARG".
10257 See also "XPUSHp", "mPUSHp" and "PUSHp".
10258
10259 void mXPUSHp(char* str, STRLEN len)
10260
10261 "mXPUSHs"
10262 Push an SV onto the stack, extending the stack if necessary and
10263 mortalizes the SV. Does not use "TARG". See also "XPUSHs" and
10264 "mPUSHs".
10265
10266 void mXPUSHs(SV* sv)
10267
10268 "mXPUSHu"
10269 Push an unsigned integer onto the stack, extending the stack if
10270 necessary. Does not use "TARG". See also "XPUSHu", "mPUSHu" and
10271 "PUSHu".
10272
10273 void mXPUSHu(UV uv)
10274
10275 "newXSproto"
10276 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl
10277 prototypes to the subs.
10278
10279 "OP"
10280 Described in perlguts.
10281
10282 "ORIGMARK"
10283 The original stack mark for the XSUB. See "dORIGMARK".
10284
10285 "peep_t"
10286 Described in perlguts.
10287
10288 "PL_runops"
10289 Described in perlguts.
10290
10291 "PMOP"
10292 Described in perlguts.
10293
10294 "POPi"
10295 Pops an integer off the stack.
10296
10297 IV POPi
10298
10299 "POPl"
10300 Pops a long off the stack.
10301
10302 long POPl
10303
10304 "POPn"
10305 Pops a double off the stack.
10306
10307 NV POPn
10308
10309 "POPp"
10310 Pops a string off the stack.
10311
10312 char* POPp
10313
10314 "POPpbytex"
10315 Pops a string off the stack which must consist of bytes i.e.
10316 characters < 256.
10317
10318 char* POPpbytex
10319
10320 "POPpx"
10321 Pops a string off the stack. Identical to POPp. There are two
10322 names for historical reasons.
10323
10324 char* POPpx
10325
10326 "POPs"
10327 Pops an SV off the stack.
10328
10329 SV* POPs
10330
10331 "POPu"
10332 Pops an unsigned integer off the stack.
10333
10334 UV POPu
10335
10336 "POPul"
10337 Pops an unsigned long off the stack.
10338
10339 long POPul
10340
10341 "PUSHi"
10342 Push an integer onto the stack. The stack must have room for this
10343 element. Handles 'set' magic. Uses "TARG", so "dTARGET" or
10344 "dXSTARG" should be called to declare it. Do not call multiple
10345 "TARG"-oriented macros to return lists from XSUB's - see "mPUSHi"
10346 instead. See also "XPUSHi" and "mXPUSHi".
10347
10348 void PUSHi(IV iv)
10349
10350 "PUSHMARK"
10351 Opening bracket for arguments on a callback. See "PUTBACK" and
10352 perlcall.
10353
10354 void PUSHMARK(SP)
10355
10356 "PUSHmortal"
10357 Push a new mortal SV onto the stack. The stack must have room for
10358 this element. Does not use "TARG". See also "PUSHs",
10359 "XPUSHmortal" and "XPUSHs".
10360
10361 void PUSHmortal
10362
10363 "PUSHn"
10364 Push a double onto the stack. The stack must have room for this
10365 element. Handles 'set' magic. Uses "TARG", so "dTARGET" or
10366 "dXSTARG" should be called to declare it. Do not call multiple
10367 "TARG"-oriented macros to return lists from XSUB's - see "mPUSHn"
10368 instead. See also "XPUSHn" and "mXPUSHn".
10369
10370 void PUSHn(NV nv)
10371
10372 "PUSHp"
10373 Push a string onto the stack. The stack must have room for this
10374 element. The "len" indicates the length of the string. Handles
10375 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG" should be
10376 called to declare it. Do not call multiple "TARG"-oriented macros
10377 to return lists from XSUB's - see "mPUSHp" instead. See also
10378 "XPUSHp" and "mXPUSHp".
10379
10380 void PUSHp(char* str, STRLEN len)
10381
10382 "PUSHs"
10383 Push an SV onto the stack. The stack must have room for this
10384 element. Does not handle 'set' magic. Does not use "TARG". See
10385 also "PUSHmortal", "XPUSHs", and "XPUSHmortal".
10386
10387 void PUSHs(SV* sv)
10388
10389 "PUSHu"
10390 Push an unsigned integer onto the stack. The stack must have room
10391 for this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
10392 or "dXSTARG" should be called to declare it. Do not call multiple
10393 "TARG"-oriented macros to return lists from XSUB's - see "mPUSHu"
10394 instead. See also "XPUSHu" and "mXPUSHu".
10395
10396 void PUSHu(UV uv)
10397
10398 "PUTBACK"
10399 Closing bracket for XSUB arguments. This is usually handled by
10400 "xsubpp". See "PUSHMARK" and perlcall for other uses.
10401
10402 PUTBACK;
10403
10404 "save_aptr"
10405 Described in perlguts.
10406
10407 void save_aptr(AV** aptr)
10408
10409 "save_ary"
10410 Described in perlguts.
10411
10412 AV* save_ary(GV* gv)
10413
10414 "SAVEBOOL"
10415 Described in perlguts.
10416
10417 SAVEBOOL(bool i)
10418
10419 "SAVEDELETE"
10420 Described in perlguts.
10421
10422 SAVEDELETE(HV * hv, char * key, I32 length)
10423
10424 "SAVEDESTRUCTOR"
10425 Described in perlguts.
10426
10427 SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)
10428
10429 "SAVEDESTRUCTOR_X"
10430 Described in perlguts.
10431
10432 SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)
10433
10434 "SAVEFREEOP"
10435 Described in perlguts.
10436
10437 SAVEFREEOP(OP *op)
10438
10439 "SAVEFREEPV"
10440 Described in perlguts.
10441
10442 SAVEFREEPV(void * p)
10443
10444 "SAVEFREESV"
10445 Described in perlguts.
10446
10447 SAVEFREESV(SV* sv)
10448
10449 "save_hash"
10450 Described in perlguts.
10451
10452 HV* save_hash(GV* gv)
10453
10454 "save_hptr"
10455 Described in perlguts.
10456
10457 void save_hptr(HV** hptr)
10458
10459 "SAVEI8"
10460 Described in perlguts.
10461
10462 SAVEI8(I8 i)
10463
10464 "SAVEI32"
10465 Described in perlguts.
10466
10467 SAVEI32(I32 i)
10468
10469 "SAVEI16"
10470 Described in perlguts.
10471
10472 SAVEI16(I16 i)
10473
10474 "SAVEINT"
10475 Described in perlguts.
10476
10477 SAVEINT(int i)
10478
10479 "save_item"
10480 Described in perlguts.
10481
10482 void save_item(SV* item)
10483
10484 "SAVEIV"
10485 Described in perlguts.
10486
10487 SAVEIV(IV i)
10488
10489 "save_list"
10490 "DEPRECATED!" It is planned to remove "save_list" from a future
10491 release of Perl. Do not use it for new code; remove it from
10492 existing code.
10493
10494 Described in perlguts.
10495
10496 void save_list(SV** sarg, I32 maxsarg)
10497
10498 "SAVELONG"
10499 Described in perlguts.
10500
10501 SAVELONG(long i)
10502
10503 "SAVEMORTALIZESV"
10504 Described in perlguts.
10505
10506 SAVEMORTALIZESV(SV* sv)
10507
10508 "SAVEPPTR"
10509 Described in perlguts.
10510
10511 SAVEPPTR(char * p)
10512
10513 "save_scalar"
10514 Described in perlguts.
10515
10516 SV* save_scalar(GV* gv)
10517
10518 "SAVESPTR"
10519 Described in perlguts.
10520
10521 SAVESPTR(SV * s)
10522
10523 "SAVESTACK_POS"
10524 Described in perlguts.
10525
10526 SAVESTACK_POS()
10527
10528 "save_svref"
10529 Described in perlguts.
10530
10531 SV* save_svref(SV** sptr)
10532
10533 "SP"
10534 Stack pointer. This is usually handled by "xsubpp". See "dSP" and
10535 "SPAGAIN".
10536
10537 "SPAGAIN"
10538 Refetch the stack pointer. Used after a callback. See perlcall.
10539
10540 SPAGAIN;
10541
10542 "TARG"
10543 "TARG" is short for "target". It is an entry in the pad that an
10544 OPs "op_targ" refers to. It is scratchpad space, often used as a
10545 return value for the OP, but some use it for other purposes.
10546
10547 TARG;
10548
10549 "UNOP"
10550 Described in perlguts.
10551
10552 "XPUSHi"
10553 Push an integer onto the stack, extending the stack if necessary.
10554 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG" should
10555 be called to declare it. Do not call multiple "TARG"-oriented
10556 macros to return lists from XSUB's - see "mXPUSHi" instead. See
10557 also "PUSHi" and "mPUSHi".
10558
10559 void XPUSHi(IV iv)
10560
10561 "XPUSHmortal"
10562 Push a new mortal SV onto the stack, extending the stack if
10563 necessary. Does not use "TARG". See also "XPUSHs", "PUSHmortal"
10564 and "PUSHs".
10565
10566 void XPUSHmortal
10567
10568 "XPUSHn"
10569 Push a double onto the stack, extending the stack if necessary.
10570 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG" should
10571 be called to declare it. Do not call multiple "TARG"-oriented
10572 macros to return lists from XSUB's - see "mXPUSHn" instead. See
10573 also "PUSHn" and "mPUSHn".
10574
10575 void XPUSHn(NV nv)
10576
10577 "XPUSHp"
10578 Push a string onto the stack, extending the stack if necessary.
10579 The "len" indicates the length of the string. Handles 'set' magic.
10580 Uses "TARG", so "dTARGET" or "dXSTARG" should be called to declare
10581 it. Do not call multiple "TARG"-oriented macros to return lists
10582 from XSUB's - see "mXPUSHp" instead. See also "PUSHp" and
10583 "mPUSHp".
10584
10585 void XPUSHp(char* str, STRLEN len)
10586
10587 "XPUSHs"
10588 Push an SV onto the stack, extending the stack if necessary. Does
10589 not handle 'set' magic. Does not use "TARG". See also
10590 "XPUSHmortal", "PUSHs" and "PUSHmortal".
10591
10592 void XPUSHs(SV* sv)
10593
10594 "XPUSHu"
10595 Push an unsigned integer onto the stack, extending the stack if
10596 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
10597 "dXSTARG" should be called to declare it. Do not call multiple
10598 "TARG"-oriented macros to return lists from XSUB's - see "mXPUSHu"
10599 instead. See also "PUSHu" and "mPUSHu".
10600
10601 void XPUSHu(UV uv)
10602
10603 "XS_APIVERSION_BOOTCHECK"
10604 Macro to verify that the perl api version an XS module has been
10605 compiled against matches the api version of the perl interpreter
10606 it's being loaded into.
10607
10608 XS_APIVERSION_BOOTCHECK;
10609
10610 "XSRETURN"
10611 Return from XSUB, indicating number of items on the stack. This is
10612 usually handled by "xsubpp".
10613
10614 void XSRETURN(int nitems)
10615
10616 "XSRETURN_EMPTY"
10617 Return an empty list from an XSUB immediately.
10618
10619 XSRETURN_EMPTY;
10620
10621 "XSRETURN_IV"
10622 Return an integer from an XSUB immediately. Uses "XST_mIV".
10623
10624 void XSRETURN_IV(IV iv)
10625
10626 "XSRETURN_NO"
10627 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
10628
10629 XSRETURN_NO;
10630
10631 "XSRETURN_NV"
10632 Return a double from an XSUB immediately. Uses "XST_mNV".
10633
10634 void XSRETURN_NV(NV nv)
10635
10636 "XSRETURN_PV"
10637 Return a copy of a string from an XSUB immediately. Uses
10638 "XST_mPV".
10639
10640 void XSRETURN_PV(char* str)
10641
10642 "XSRETURN_UNDEF"
10643 Return &PL_sv_undef from an XSUB immediately. Uses "XST_mUNDEF".
10644
10645 XSRETURN_UNDEF;
10646
10647 "XSRETURN_UV"
10648 Return an integer from an XSUB immediately. Uses "XST_mUV".
10649
10650 void XSRETURN_UV(IV uv)
10651
10652 "XSRETURN_YES"
10653 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
10654
10655 XSRETURN_YES;
10656
10657 "XST_mIV"
10658 Place an integer into the specified position "pos" on the stack.
10659 The value is stored in a new mortal SV.
10660
10661 void XST_mIV(int pos, IV iv)
10662
10663 "XST_mNO"
10664 Place &PL_sv_no into the specified position "pos" on the stack.
10665
10666 void XST_mNO(int pos)
10667
10668 "XST_mNV"
10669 Place a double into the specified position "pos" on the stack. The
10670 value is stored in a new mortal SV.
10671
10672 void XST_mNV(int pos, NV nv)
10673
10674 "XST_mPV"
10675 Place a copy of a string into the specified position "pos" on the
10676 stack. The value is stored in a new mortal SV.
10677
10678 void XST_mPV(int pos, char* str)
10679
10680 "XST_mUNDEF"
10681 Place &PL_sv_undef into the specified position "pos" on the stack.
10682
10683 void XST_mUNDEF(int pos)
10684
10685 "XST_mUV"
10686 Place an unsigned integer into the specified position "pos" on the
10687 stack. The value is stored in a new mortal SV.
10688
10689 void XST_mUV(int pos, UV uv)
10690
10691 "XST_mYES"
10692 Place &PL_sv_yes into the specified position "pos" on the stack.
10693
10694 void XST_mYES(int pos)
10695
10696 "XS_VERSION"
10697 The version identifier for an XS module. This is usually handled
10698 automatically by "ExtUtils::MakeMaker". See
10699 "XS_VERSION_BOOTCHECK".
10700
10701 "XS_VERSION_BOOTCHECK"
10702 Macro to verify that a PM module's $VERSION variable matches the XS
10703 module's "XS_VERSION" variable. This is usually handled
10704 automatically by "xsubpp". See "The VERSIONCHECK: Keyword" in
10705 perlxs.
10706
10707 XS_VERSION_BOOTCHECK;
10708
10710 See also "Unicode Support".
10711
10712 "CAT2"
10713 This macro concatenates 2 tokens together.
10714
10715 token CAT2(token x, token y)
10716
10717 "Copy"
10718 The XSUB-writer's interface to the C "memcpy" function. The "src"
10719 is the source, "dest" is the destination, "nitems" is the number of
10720 items, and "type" is the type. May fail on overlapping copies.
10721 See also "Move".
10722
10723 void Copy(void* src, void* dest, int nitems, type)
10724
10725 "CopyD"
10726 Like "Copy" but returns "dest". Useful for encouraging compilers
10727 to tail-call optimise.
10728
10729 void * CopyD(void* src, void* dest, int nitems, type)
10730
10731 "delimcpy"
10732 Copy a source buffer to a destination buffer, stopping at (but not
10733 including) the first occurrence in the source of an unescaped
10734 (defined below) delimiter byte, "delim". The source is the bytes
10735 between "from" and "from_end" - 1. Similarly, the dest is "to" up
10736 to "to_end".
10737
10738 The number of bytes copied is written to *retlen.
10739
10740 Returns the position of the first uncopied "delim" in the "from"
10741 buffer, but if there is no such occurrence before "from_end", then
10742 "from_end" is returned, and the entire buffer
10743 "from" .. "from_end" - 1 is copied.
10744
10745 If there is room in the destination available after the copy, an
10746 extra terminating safety "NUL" byte is appended (not included in
10747 the returned length).
10748
10749 The error case is if the destination buffer is not large enough to
10750 accommodate everything that should be copied. In this situation, a
10751 value larger than "to_end" - "to" is written to *retlen, and as
10752 much of the source as fits will be written to the destination. Not
10753 having room for the safety "NUL" is not considered an error.
10754
10755 In the following examples, let "x" be the delimiter, and 0
10756 represent a "NUL" byte (NOT the digit 0). Then we would have
10757
10758 Source Destination
10759 abcxdef abc0
10760
10761 provided the destination buffer is at least 4 bytes long.
10762
10763 An escaped delimiter is one which is immediately preceded by a
10764 single backslash. Escaped delimiters are copied, and the copy
10765 continues past the delimiter; the backslash is not copied:
10766
10767 Source Destination
10768 abc\xdef abcxdef0
10769
10770 (provided the destination buffer is at least 8 bytes long).
10771
10772 It's actually somewhat more complicated than that. A sequence of
10773 any odd number of backslashes escapes the following delimiter, and
10774 the copy continues with exactly one of the backslashes stripped.
10775
10776 Source Destination
10777 abc\xdef abcxdef0
10778 abc\\\xdef abc\\xdef0
10779 abc\\\\\xdef abc\\\\xdef0
10780
10781 (as always, if the destination is large enough)
10782
10783 An even number of preceding backslashes does not escape the
10784 delimiter, so that the copy stops just before it, and includes all
10785 the backslashes (no stripping; zero is considered even):
10786
10787 Source Destination
10788 abcxdef abc0
10789 abc\\xdef abc\\0
10790 abc\\\\xdef abc\\\\0
10791
10792 char* delimcpy(char* to, const char* to_end, const char* from,
10793 const char* from_end, const int delim,
10794 I32* retlen)
10795
10796 "fbm_compile"
10797 Analyzes the string in order to make fast searches on it using
10798 "fbm_instr()" -- the Boyer-Moore algorithm.
10799
10800 void fbm_compile(SV* sv, U32 flags)
10801
10802 "fbm_instr"
10803 Returns the location of the SV in the string delimited by "big" and
10804 "bigend" ("bigend") is the char following the last char). It
10805 returns "NULL" if the string can't be found. The "sv" does not
10806 have to be "fbm_compiled", but the search will not be as fast then.
10807
10808 char* fbm_instr(unsigned char* big, unsigned char* bigend,
10809 SV* littlestr, U32 flags)
10810
10811 "foldEQ"
10812 Returns true if the leading "len" bytes of the strings "s1" and
10813 "s2" are the same case-insensitively; false otherwise. Uppercase
10814 and lowercase ASCII range bytes match themselves and their opposite
10815 case counterparts. Non-cased and non-ASCII range bytes match only
10816 themselves.
10817
10818 I32 foldEQ(const char* a, const char* b, I32 len)
10819
10820 "ibcmp"
10821 This is a synonym for "(! foldEQ())"
10822
10823 I32 ibcmp(const char* a, const char* b, I32 len)
10824
10825 "ibcmp_locale"
10826 This is a synonym for "(! foldEQ_locale())"
10827
10828 I32 ibcmp_locale(const char* a, const char* b, I32 len)
10829
10830 "ibcmp_utf8"
10831 This is a synonym for "(! foldEQ_utf8())"
10832
10833 I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1,
10834 const char *s2, char **pe2, UV l2, bool u2)
10835
10836 "instr"
10837 Same as strstr(3), which finds and returns a pointer to the first
10838 occurrence of the NUL-terminated substring "little" in the NUL-
10839 terminated string "big", returning NULL if not found. The
10840 terminating NUL bytes are not compared.
10841
10842 char* instr(const char* big, const char* little)
10843
10844 "memCHRs"
10845 Returns the position of the first occurence of the byte "c" in the
10846 literal string "list", or NULL if "c" doesn't appear in "list".
10847 All bytes are treated as unsigned char. Thus this macro can be
10848 used to determine if "c" is in a set of particular characters.
10849 Unlike strchr(3), it works even if "c" is "NUL" (and the set
10850 doesn't include "NUL").
10851
10852 bool memCHRs("list", char c)
10853
10854 "memEQ"
10855 Test two buffers (which may contain embedded "NUL" characters, to
10856 see if they are equal. The "len" parameter indicates the number of
10857 bytes to compare. Returns true or false. It is undefined behavior
10858 if either of the buffers doesn't contain at least "len" bytes.
10859
10860 bool memEQ(char* s1, char* s2, STRLEN len)
10861
10862 "memEQs"
10863 Like "memEQ", but the second string is a literal enclosed in double
10864 quotes, "l1" gives the number of bytes in "s1". Returns true or
10865 false.
10866
10867 bool memEQs(char* s1, STRLEN l1, "s2")
10868
10869 "memNE"
10870 Test two buffers (which may contain embedded "NUL" characters, to
10871 see if they are not equal. The "len" parameter indicates the
10872 number of bytes to compare. Returns true or false. It is
10873 undefined behavior if either of the buffers doesn't contain at
10874 least "len" bytes.
10875
10876 bool memNE(char* s1, char* s2, STRLEN len)
10877
10878 "memNEs"
10879 Like "memNE", but the second string is a literal enclosed in double
10880 quotes, "l1" gives the number of bytes in "s1". Returns true or
10881 false.
10882
10883 bool memNEs(char* s1, STRLEN l1, "s2")
10884
10885 "Move"
10886 The XSUB-writer's interface to the C "memmove" function. The "src"
10887 is the source, "dest" is the destination, "nitems" is the number of
10888 items, and "type" is the type. Can do overlapping moves. See also
10889 "Copy".
10890
10891 void Move(void* src, void* dest, int nitems, type)
10892
10893 "MoveD"
10894 Like "Move" but returns "dest". Useful for encouraging compilers
10895 to tail-call optimise.
10896
10897 void * MoveD(void* src, void* dest, int nitems, type)
10898
10899 "my_snprintf"
10900 The C library "snprintf" functionality, if available and standards-
10901 compliant (uses "vsnprintf", actually). However, if the
10902 "vsnprintf" is not available, will unfortunately use the unsafe
10903 "vsprintf" which can overrun the buffer (there is an overrun check,
10904 but that may be too late). Consider using "sv_vcatpvf" instead, or
10905 getting "vsnprintf".
10906
10907 int my_snprintf(char *buffer, const Size_t len,
10908 const char *format, ...)
10909
10910 "my_sprintf"
10911 "DEPRECATED!" It is planned to remove "my_sprintf" from a future
10912 release of Perl. Do not use it for new code; remove it from
10913 existing code.
10914
10915 Do NOT use this due to the possibility of overflowing "buffer".
10916 Instead use my_snprintf()
10917
10918 int my_sprintf(NN char *buffer, NN const char *pat, ...)
10919
10920 "my_strlcat"
10921 The C library "strlcat" if available, or a Perl implementation of
10922 it. This operates on C "NUL"-terminated strings.
10923
10924 "my_strlcat()" appends string "src" to the end of "dst". It will
10925 append at most "size - strlen(dst) - 1" characters. It will then
10926 "NUL"-terminate, unless "size" is 0 or the original "dst" string
10927 was longer than "size" (in practice this should not happen as it
10928 means that either "size" is incorrect or that "dst" is not a proper
10929 "NUL"-terminated string).
10930
10931 Note that "size" is the full size of the destination buffer and the
10932 result is guaranteed to be "NUL"-terminated if there is room. Note
10933 that room for the "NUL" should be included in "size".
10934
10935 The return value is the total length that "dst" would have if
10936 "size" is sufficiently large. Thus it is the initial length of
10937 "dst" plus the length of "src". If "size" is smaller than the
10938 return, the excess was not appended.
10939
10940 Size_t my_strlcat(char *dst, const char *src, Size_t size)
10941
10942 "my_strlcpy"
10943 The C library "strlcpy" if available, or a Perl implementation of
10944 it. This operates on C "NUL"-terminated strings.
10945
10946 "my_strlcpy()" copies up to "size - 1" characters from the string
10947 "src" to "dst", "NUL"-terminating the result if "size" is not 0.
10948
10949 The return value is the total length "src" would be if the copy
10950 completely succeeded. If it is larger than "size", the excess was
10951 not copied.
10952
10953 Size_t my_strlcpy(char *dst, const char *src, Size_t size)
10954
10955 "my_strnlen"
10956 The C library "strnlen" if available, or a Perl implementation of
10957 it.
10958
10959 "my_strnlen()" computes the length of the string, up to "maxlen"
10960 characters. It will never attempt to address more than "maxlen"
10961 characters, making it suitable for use with strings that are not
10962 guaranteed to be NUL-terminated.
10963
10964 Size_t my_strnlen(const char *str, Size_t maxlen)
10965
10966 "my_vsnprintf"
10967 The C library "vsnprintf" if available and standards-compliant.
10968 However, if the "vsnprintf" is not available, will unfortunately
10969 use the unsafe "vsprintf" which can overrun the buffer (there is an
10970 overrun check, but that may be too late). Consider using
10971 "sv_vcatpvf" instead, or getting "vsnprintf".
10972
10973 int my_vsnprintf(char *buffer, const Size_t len,
10974 const char *format, va_list ap)
10975
10976 "ninstr"
10977 Find the first (leftmost) occurrence of a sequence of bytes within
10978 another sequence. This is the Perl version of "strstr()", extended
10979 to handle arbitrary sequences, potentially containing embedded
10980 "NUL" characters ("NUL" is what the initial "n" in the function
10981 name stands for; some systems have an equivalent, "memmem()", but
10982 with a somewhat different API).
10983
10984 Another way of thinking about this function is finding a needle in
10985 a haystack. "big" points to the first byte in the haystack.
10986 "big_end" points to one byte beyond the final byte in the haystack.
10987 "little" points to the first byte in the needle. "little_end"
10988 points to one byte beyond the final byte in the needle. All the
10989 parameters must be non-"NULL".
10990
10991 The function returns "NULL" if there is no occurrence of "little"
10992 within "big". If "little" is the empty string, "big" is returned.
10993
10994 Because this function operates at the byte level, and because of
10995 the inherent characteristics of UTF-8 (or UTF-EBCDIC), it will work
10996 properly if both the needle and the haystack are strings with the
10997 same UTF-8ness, but not if the UTF-8ness differs.
10998
10999 char* ninstr(const char* big, const char* bigend,
11000 const char* little, const char* lend)
11001
11002 "Nullch"
11003 Null character pointer. (No longer available when "PERL_CORE" is
11004 defined.)
11005
11006 "rninstr"
11007 Like "ninstr", but instead finds the final (rightmost) occurrence
11008 of a sequence of bytes within another sequence, returning "NULL" if
11009 there is no such occurrence.
11010
11011 char* rninstr(const char* big, const char* bigend,
11012 const char* little, const char* lend)
11013
11014 "savepv"
11015 Perl's version of "strdup()". Returns a pointer to a newly
11016 allocated string which is a duplicate of "pv". The size of the
11017 string is determined by "strlen()", which means it may not contain
11018 embedded "NUL" characters and must have a trailing "NUL". To
11019 prevent memory leaks, the memory allocated for the new string needs
11020 to be freed when no longer needed. This can be done with the
11021 "Safefree" function, or "SAVEFREEPV".
11022
11023 On some platforms, Windows for example, all allocated memory owned
11024 by a thread is deallocated when that thread ends. So if you need
11025 that not to happen, you need to use the shared memory functions,
11026 such as "savesharedpv".
11027
11028 char* savepv(const char* pv)
11029
11030 "savepvn"
11031 Perl's version of what "strndup()" would be if it existed. Returns
11032 a pointer to a newly allocated string which is a duplicate of the
11033 first "len" bytes from "pv", plus a trailing "NUL" byte. The
11034 memory allocated for the new string can be freed with the
11035 "Safefree()" function.
11036
11037 On some platforms, Windows for example, all allocated memory owned
11038 by a thread is deallocated when that thread ends. So if you need
11039 that not to happen, you need to use the shared memory functions,
11040 such as "savesharedpvn".
11041
11042 char* savepvn(const char* pv, Size_t len)
11043
11044 "savepvs"
11045 Like "savepvn", but takes a literal string instead of a
11046 string/length pair.
11047
11048 char* savepvs("literal string")
11049
11050 "savesharedpv"
11051 A version of "savepv()" which allocates the duplicate string in
11052 memory which is shared between threads.
11053
11054 char* savesharedpv(const char* pv)
11055
11056 "savesharedpvn"
11057 A version of "savepvn()" which allocates the duplicate string in
11058 memory which is shared between threads. (With the specific
11059 difference that a "NULL" pointer is not acceptable)
11060
11061 char* savesharedpvn(const char *const pv, const STRLEN len)
11062
11063 "savesharedpvs"
11064 A version of "savepvs()" which allocates the duplicate string in
11065 memory which is shared between threads.
11066
11067 char* savesharedpvs("literal string")
11068
11069 "savesharedsvpv"
11070 A version of "savesharedpv()" which allocates the duplicate string
11071 in memory which is shared between threads.
11072
11073 char* savesharedsvpv(SV *sv)
11074
11075 "savesvpv"
11076 A version of "savepv()"/"savepvn()" which gets the string to
11077 duplicate from the passed in SV using "SvPV()"
11078
11079 On some platforms, Windows for example, all allocated memory owned
11080 by a thread is deallocated when that thread ends. So if you need
11081 that not to happen, you need to use the shared memory functions,
11082 such as "savesharedsvpv".
11083
11084 char* savesvpv(SV* sv)
11085
11086 "strEQ"
11087 Test two "NUL"-terminated strings to see if they are equal.
11088 Returns true or false.
11089
11090 bool strEQ(char* s1, char* s2)
11091
11092 "strGE"
11093 Test two "NUL"-terminated strings to see if the first, "s1", is
11094 greater than or equal to the second, "s2". Returns true or false.
11095
11096 bool strGE(char* s1, char* s2)
11097
11098 "strGT"
11099 Test two "NUL"-terminated strings to see if the first, "s1", is
11100 greater than the second, "s2". Returns true or false.
11101
11102 bool strGT(char* s1, char* s2)
11103
11104 "STRINGIFY"
11105 This macro surrounds its token with double quotes.
11106
11107 string STRINGIFY(token x)
11108
11109 "strLE"
11110 Test two "NUL"-terminated strings to see if the first, "s1", is
11111 less than or equal to the second, "s2". Returns true or false.
11112
11113 bool strLE(char* s1, char* s2)
11114
11115 "strLT"
11116 Test two "NUL"-terminated strings to see if the first, "s1", is
11117 less than the second, "s2". Returns true or false.
11118
11119 bool strLT(char* s1, char* s2)
11120
11121 "strNE"
11122 Test two "NUL"-terminated strings to see if they are different.
11123 Returns true or false.
11124
11125 bool strNE(char* s1, char* s2)
11126
11127 "strnEQ"
11128 Test two "NUL"-terminated strings to see if they are equal. The
11129 "len" parameter indicates the number of bytes to compare. Returns
11130 true or false. (A wrapper for "strncmp").
11131
11132 bool strnEQ(char* s1, char* s2, STRLEN len)
11133
11134 "strnNE"
11135 Test two "NUL"-terminated strings to see if they are different.
11136 The "len" parameter indicates the number of bytes to compare.
11137 Returns true or false. (A wrapper for "strncmp").
11138
11139 bool strnNE(char* s1, char* s2, STRLEN len)
11140
11141 "STR_WITH_LEN"
11142 Returns two comma separated tokens of the input literal string, and
11143 its length. This is convenience macro which helps out in some API
11144 calls. Note that it can't be used as an argument to macros or
11145 functions that under some configurations might be macros, which
11146 means that it requires the full Perl_xxx(aTHX_ ...) form for any
11147 API calls where it's used.
11148
11149 pair STR_WITH_LEN("literal string")
11150
11151 "Zero"
11152 The XSUB-writer's interface to the C "memzero" function. The
11153 "dest" is the destination, "nitems" is the number of items, and
11154 "type" is the type.
11155
11156 void Zero(void* dest, int nitems, type)
11157
11158 "ZeroD"
11159 Like "Zero" but returns dest. Useful for encouraging compilers to
11160 tail-call optimise.
11161
11162 void * ZeroD(void* dest, int nitems, type)
11163
11165 "SVt_IV"
11166 Type flag for scalars. See "svtype".
11167
11168 "SVt_NULL"
11169 Type flag for scalars. See "svtype".
11170
11171 "SVt_NV"
11172 Type flag for scalars. See "svtype".
11173
11174 "SVt_PV"
11175 Type flag for scalars. See "svtype".
11176
11177 "SVt_PVAV"
11178 Type flag for arrays. See "svtype".
11179
11180 "SVt_PVCV"
11181 Type flag for subroutines. See "svtype".
11182
11183 "SVt_PVFM"
11184 Type flag for formats. See "svtype".
11185
11186 "SVt_PVGV"
11187 Type flag for typeglobs. See "svtype".
11188
11189 "SVt_PVHV"
11190 Type flag for hashes. See "svtype".
11191
11192 "SVt_PVIO"
11193 Type flag for I/O objects. See "svtype".
11194
11195 "SVt_PVIV"
11196 Type flag for scalars. See "svtype".
11197
11198 "SVt_PVLV"
11199 Type flag for scalars. See "svtype".
11200
11201 "SVt_PVMG"
11202 Type flag for scalars. See "svtype".
11203
11204 "SVt_PVNV"
11205 Type flag for scalars. See "svtype".
11206
11207 "SVt_REGEXP"
11208 Type flag for regular expressions. See "svtype".
11209
11210 "svtype"
11211 An enum of flags for Perl types. These are found in the file sv.h
11212 in the "svtype" enum. Test these flags with the "SvTYPE" macro.
11213
11214 The types are:
11215
11216 SVt_NULL
11217 SVt_IV
11218 SVt_NV
11219 SVt_RV
11220 SVt_PV
11221 SVt_PVIV
11222 SVt_PVNV
11223 SVt_PVMG
11224 SVt_INVLIST
11225 SVt_REGEXP
11226 SVt_PVGV
11227 SVt_PVLV
11228 SVt_PVAV
11229 SVt_PVHV
11230 SVt_PVCV
11231 SVt_PVFM
11232 SVt_PVIO
11233
11234 These are most easily explained from the bottom up.
11235
11236 "SVt_PVIO" is for I/O objects, "SVt_PVFM" for formats, "SVt_PVCV"
11237 for subroutines, "SVt_PVHV" for hashes and "SVt_PVAV" for arrays.
11238
11239 All the others are scalar types, that is, things that can be bound
11240 to a "$" variable. For these, the internal types are mostly
11241 orthogonal to types in the Perl language.
11242
11243 Hence, checking "SvTYPE(sv) < SVt_PVAV" is the best way to see
11244 whether something is a scalar.
11245
11246 "SVt_PVGV" represents a typeglob. If "!SvFAKE(sv)", then it is a
11247 real, incoercible typeglob. If "SvFAKE(sv)", then it is a scalar
11248 to which a typeglob has been assigned. Assigning to it again will
11249 stop it from being a typeglob. "SVt_PVLV" represents a scalar that
11250 delegates to another scalar behind the scenes. It is used, e.g.,
11251 for the return value of "substr" and for tied hash and array
11252 elements. It can hold any scalar value, including a typeglob.
11253 "SVt_REGEXP" is for regular expressions. "SVt_INVLIST" is for Perl
11254 core internal use only.
11255
11256 "SVt_PVMG" represents a "normal" scalar (not a typeglob, regular
11257 expression, or delegate). Since most scalars do not need all the
11258 internal fields of a PVMG, we save memory by allocating smaller
11259 structs when possible. All the other types are just simpler forms
11260 of "SVt_PVMG", with fewer internal fields. "SVt_NULL" can only
11261 hold undef. "SVt_IV" can hold undef, an integer, or a reference.
11262 ("SVt_RV" is an alias for "SVt_IV", which exists for backward
11263 compatibility.) "SVt_NV" can hold any of those or a double.
11264 "SVt_PV" can only hold "undef" or a string. "SVt_PVIV" is a
11265 superset of "SVt_PV" and "SVt_IV". "SVt_PVNV" is similar.
11266 "SVt_PVMG" can hold anything "SVt_PVNV" can hold, but it can, but
11267 does not have to, be blessed or magical.
11268
11270 An SV (or AV, HV, etc.) is allocated in two parts: the head (struct sv,
11271 av, hv...) contains type and reference count information, and for many
11272 types, a pointer to the body (struct xrv, xpv, xpviv...), which
11273 contains fields specific to each type. Some types store all they need
11274 in the head, so don't have a body.
11275
11276 In all but the most memory-paranoid configurations (ex: PURIFY), heads
11277 and bodies are allocated out of arenas, which by default are
11278 approximately 4K chunks of memory parcelled up into N heads or bodies.
11279 Sv-bodies are allocated by their sv-type, guaranteeing size consistency
11280 needed to allocate safely from arrays.
11281
11282 For SV-heads, the first slot in each arena is reserved, and holds a
11283 link to the next arena, some flags, and a note of the number of slots.
11284 Snaked through each arena chain is a linked list of free items; when
11285 this becomes empty, an extra arena is allocated and divided up into N
11286 items which are threaded into the free list.
11287
11288 SV-bodies are similar, but they use arena-sets by default, which
11289 separate the link and info from the arena itself, and reclaim the 1st
11290 slot in the arena. SV-bodies are further described later.
11291
11292 The following global variables are associated with arenas:
11293
11294 PL_sv_arenaroot pointer to list of SV arenas
11295 PL_sv_root pointer to list of free SV structures
11296
11297 PL_body_arenas head of linked-list of body arenas
11298 PL_body_roots[] array of pointers to list of free bodies of svtype
11299 arrays are indexed by the svtype needed
11300
11301 A few special SV heads are not allocated from an arena, but are instead
11302 directly created in the interpreter structure, eg PL_sv_undef. The
11303 size of arenas can be changed from the default by setting
11304 PERL_ARENA_SIZE appropriately at compile time.
11305
11306 The SV arena serves the secondary purpose of allowing still-live SVs to
11307 be located and destroyed during final cleanup.
11308
11309 At the lowest level, the macros new_SV() and del_SV() grab and free an
11310 SV head. (If debugging with -DD, del_SV() calls the function
11311 S_del_sv() to return the SV to the free list with error checking.)
11312 new_SV() calls more_sv() / sv_add_arena() to add an extra arena if the
11313 free list is empty. SVs in the free list have their SvTYPE field set
11314 to all ones.
11315
11316 At the time of very final cleanup, sv_free_arenas() is called from
11317 perl_destruct() to physically free all the arenas allocated since the
11318 start of the interpreter.
11319
11320 The internal function visit() scans the SV arenas list, and calls a
11321 specified function for each SV it finds which is still live, i.e. which
11322 has an SvTYPE other than all 1's, and a non-zero SvREFCNT. visit() is
11323 used by the following functions (specified as [function that calls
11324 visit()] / [function called by visit() for each SV]):
11325
11326 sv_report_used() / do_report_used()
11327 dump all remaining SVs (debugging aid)
11328
11329 sv_clean_objs() / do_clean_objs(),do_clean_named_objs(),
11330 do_clean_named_io_objs(),do_curse()
11331 Attempt to free all objects pointed to by RVs,
11332 try to do the same for all objects indir-
11333 ectly referenced by typeglobs too, and
11334 then do a final sweep, cursing any
11335 objects that remain. Called once from
11336 perl_destruct(), prior to calling sv_clean_all()
11337 below.
11338
11339 sv_clean_all() / do_clean_all()
11340 SvREFCNT_dec(sv) each remaining SV, possibly
11341 triggering an sv_free(). It also sets the
11342 SVf_BREAK flag on the SV to indicate that the
11343 refcnt has been artificially lowered, and thus
11344 stopping sv_free() from giving spurious warnings
11345 about SVs which unexpectedly have a refcnt
11346 of zero. called repeatedly from perl_destruct()
11347 until there are no SVs left.
11348
11349 Arena allocator API Summary
11350 Private API to rest of sv.c
11351
11352 new_SV(), del_SV(),
11353
11354 new_XPVNV(), del_XPVGV(),
11355 etc
11356
11357 Public API:
11358
11359 sv_report_used(), sv_clean_objs(), sv_clean_all(), sv_free_arenas()
11360
11361 "boolSV"
11362 Returns a true SV if "b" is a true value, or a false SV if "b" is
11363 0.
11364
11365 See also "PL_sv_yes" and "PL_sv_no".
11366
11367 SV * boolSV(bool b)
11368
11369 "croak_xs_usage"
11370 A specialised variant of "croak()" for emitting the usage message
11371 for xsubs
11372
11373 croak_xs_usage(cv, "eee_yow");
11374
11375 works out the package name and subroutine name from "cv", and then
11376 calls "croak()". Hence if "cv" is &ouch::awk, it would call
11377 "croak" as:
11378
11379 Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
11380 "eee_yow");
11381
11382 void croak_xs_usage(const CV *const cv, const char *const params)
11383
11384 "DEFSV"
11385 Returns the SV associated with $_
11386
11387 SV * DEFSV
11388
11389 "DEFSV_set"
11390 Associate "sv" with $_
11391
11392 void DEFSV_set(SV * sv)
11393
11394 "get_sv"
11395 Returns the SV of the specified Perl scalar. "flags" are passed to
11396 "gv_fetchpv". If "GV_ADD" is set and the Perl variable does not
11397 exist then it will be created. If "flags" is zero and the variable
11398 does not exist then NULL is returned.
11399
11400 NOTE: the "perl_get_sv()" form is deprecated.
11401
11402 SV* get_sv(const char *name, I32 flags)
11403
11404 "isGV_with_GP"
11405 Returns a boolean as to whether or not "sv" is a GV with a pointer
11406 to a GP (glob pointer).
11407
11408 bool isGV_with_GP(SV * sv)
11409
11410 "looks_like_number"
11411 Test if the content of an SV looks like a number (or is a number).
11412 "Inf" and "Infinity" are treated as numbers (so will not issue a
11413 non-numeric warning), even if your "atof()" doesn't grok them.
11414 Get-magic is ignored.
11415
11416 I32 looks_like_number(SV *const sv)
11417
11418 "MUTABLE_PTR"
11419 "MUTABLE_AV"
11420 "MUTABLE_CV"
11421 "MUTABLE_GV"
11422 "MUTABLE_HV"
11423 "MUTABLE_IO"
11424 "MUTABLE_SV"
11425 The "MUTABLE_*"() macros cast pointers to the types shown, in such
11426 a way (compiler permitting) that casting away const-ness will give
11427 a warning; e.g.:
11428
11429 const SV *sv = ...;
11430 AV *av1 = (AV*)sv; <== BAD: the const has been silently
11431 cast away
11432 AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
11433
11434 "MUTABLE_PTR" is the base macro used to derive new casts. The
11435 other already-built-in ones return pointers to what their names
11436 indicate.
11437
11438 void * MUTABLE_PTR(void * p)
11439 AV * MUTABLE_AV (AV * p)
11440 CV * MUTABLE_CV (CV * p)
11441 GV * MUTABLE_GV (GV * p)
11442 HV * MUTABLE_HV (HV * p)
11443 IO * MUTABLE_IO (IO * p)
11444 SV * MUTABLE_SV (SV * p)
11445
11446 "newRV"
11447 "newRV_inc"
11448 These are identical. They create an RV wrapper for an SV. The
11449 reference count for the original SV is incremented.
11450
11451 SV* newRV(SV *const sv)
11452
11453 "newRV_noinc"
11454 Creates an RV wrapper for an SV. The reference count for the
11455 original SV is not incremented.
11456
11457 SV* newRV_noinc(SV *const tmpRef)
11458
11459 "newSV"
11460 Creates a new SV. A non-zero "len" parameter indicates the number
11461 of bytes of preallocated string space the SV should have. An extra
11462 byte for a trailing "NUL" is also reserved. ("SvPOK" is not set
11463 for the SV even if string space is allocated.) The reference count
11464 for the new SV is set to 1.
11465
11466 In 5.9.3, "newSV()" replaces the older "NEWSV()" API, and drops the
11467 first parameter, x, a debug aid which allowed callers to identify
11468 themselves. This aid has been superseded by a new build option,
11469 "PERL_MEM_LOG" (see "PERL_MEM_LOG" in perlhacktips). The older API
11470 is still there for use in XS modules supporting older perls.
11471
11472 SV* newSV(const STRLEN len)
11473
11474 "newSVhek"
11475 Creates a new SV from the hash key structure. It will generate
11476 scalars that point to the shared string table where possible.
11477 Returns a new (undefined) SV if "hek" is NULL.
11478
11479 SV* newSVhek(const HEK *const hek)
11480
11481 "newSViv"
11482 Creates a new SV and copies an integer into it. The reference
11483 count for the SV is set to 1.
11484
11485 SV* newSViv(const IV i)
11486
11487 "newSVnv"
11488 Creates a new SV and copies a floating point value into it. The
11489 reference count for the SV is set to 1.
11490
11491 SV* newSVnv(const NV n)
11492
11493 "newSVpadname"
11494 NOTE: "newSVpadname" is experimental and may change or be removed
11495 without notice.
11496
11497 Creates a new SV containing the pad name.
11498
11499 SV* newSVpadname(PADNAME *pn)
11500
11501 "newSVpv"
11502 Creates a new SV and copies a string (which may contain "NUL"
11503 ("\0") characters) into it. The reference count for the SV is set
11504 to 1. If "len" is zero, Perl will compute the length using
11505 "strlen()", (which means if you use this option, that "s" can't
11506 have embedded "NUL" characters and has to have a terminating "NUL"
11507 byte).
11508
11509 This function can cause reliability issues if you are likely to
11510 pass in empty strings that are not null terminated, because it will
11511 run strlen on the string and potentially run past valid memory.
11512
11513 Using "newSVpvn" is a safer alternative for non "NUL" terminated
11514 strings. For string literals use "newSVpvs" instead. This
11515 function will work fine for "NUL" terminated strings, but if you
11516 want to avoid the if statement on whether to call "strlen" use
11517 "newSVpvn" instead (calling "strlen" yourself).
11518
11519 SV* newSVpv(const char *const s, const STRLEN len)
11520
11521 "newSVpvf"
11522 Creates a new SV and initializes it with the string formatted like
11523 "sv_catpvf".
11524
11525 NOTE: "newSVpvf" must be explicitly called as "Perl_newSVpvf" with
11526 an "aTHX_" parameter.
11527
11528 SV* Perl_newSVpvf(pTHX_ const char *const pat, ...)
11529
11530 "newSVpvf_nocontext"
11531 Like "newSVpvf" but does not take a thread context ("aTHX")
11532 parameter, so is used in situations where the caller doesn't
11533 already have the thread context.
11534
11535 SV* newSVpvf_nocontext(const char *const pat, ...)
11536
11537 "newSVpvn"
11538 Creates a new SV and copies a string into it, which may contain
11539 "NUL" characters ("\0") and other binary data. The reference count
11540 for the SV is set to 1. Note that if "len" is zero, Perl will
11541 create a zero length (Perl) string. You are responsible for
11542 ensuring that the source buffer is at least "len" bytes long. If
11543 the "buffer" argument is NULL the new SV will be undefined.
11544
11545 SV* newSVpvn(const char *const buffer, const STRLEN len)
11546
11547 "newSVpvn_flags"
11548 Creates a new SV and copies a string (which may contain "NUL"
11549 ("\0") characters) into it. The reference count for the SV is set
11550 to 1. Note that if "len" is zero, Perl will create a zero length
11551 string. You are responsible for ensuring that the source string is
11552 at least "len" bytes long. If the "s" argument is NULL the new SV
11553 will be undefined. Currently the only flag bits accepted are
11554 "SVf_UTF8" and "SVs_TEMP". If "SVs_TEMP" is set, then
11555 "sv_2mortal()" is called on the result before returning. If
11556 "SVf_UTF8" is set, "s" is considered to be in UTF-8 and the
11557 "SVf_UTF8" flag will be set on the new SV. "newSVpvn_utf8()" is a
11558 convenience wrapper for this function, defined as
11559
11560 #define newSVpvn_utf8(s, len, u) \
11561 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
11562
11563 SV* newSVpvn_flags(const char *const s, const STRLEN len,
11564 const U32 flags)
11565
11566 "newSVpvn_share"
11567 Creates a new SV with its "SvPVX_const" pointing to a shared string
11568 in the string table. If the string does not already exist in the
11569 table, it is created first. Turns on the "SvIsCOW" flag (or
11570 "READONLY" and "FAKE" in 5.16 and earlier). If the "hash"
11571 parameter is non-zero, that value is used; otherwise the hash is
11572 computed. The string's hash can later be retrieved from the SV
11573 with the "SvSHARED_HASH" macro. The idea here is that as the
11574 string table is used for shared hash keys these strings will have
11575 "SvPVX_const == HeKEY" and hash lookup will avoid string compare.
11576
11577 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
11578
11579 "newSVpvn_utf8"
11580 Creates a new SV and copies a string (which may contain "NUL"
11581 ("\0") characters) into it. If "utf8" is true, calls "SvUTF8_on"
11582 on the new SV. Implemented as a wrapper around "newSVpvn_flags".
11583
11584 SV* newSVpvn_utf8(const char* s, STRLEN len, U32 utf8)
11585
11586 "newSVpvs"
11587 Like "newSVpvn", but takes a literal string instead of a
11588 string/length pair.
11589
11590 SV* newSVpvs("literal string")
11591
11592 "newSVpvs_flags"
11593 Like "newSVpvn_flags", but takes a literal string instead of a
11594 string/length pair.
11595
11596 SV* newSVpvs_flags("literal string", U32 flags)
11597
11598 "newSVpv_share"
11599 Like "newSVpvn_share", but takes a "NUL"-terminated string instead
11600 of a string/length pair.
11601
11602 SV* newSVpv_share(const char* s, U32 hash)
11603
11604 "newSVpvs_share"
11605 Like "newSVpvn_share", but takes a literal string instead of a
11606 string/length pair and omits the hash parameter.
11607
11608 SV* newSVpvs_share("literal string")
11609
11610 "newSVrv"
11611 Creates a new SV for the existing RV, "rv", to point to. If "rv"
11612 is not an RV then it will be upgraded to one. If "classname" is
11613 non-null then the new SV will be blessed in the specified package.
11614 The new SV is returned and its reference count is 1. The reference
11615 count 1 is owned by "rv". See also newRV_inc() and newRV_noinc()
11616 for creating a new RV properly.
11617
11618 SV* newSVrv(SV *const rv, const char *const classname)
11619
11620 "newSVsv"
11621 "newSVsv_nomg"
11622 "newSVsv_flags"
11623 These create a new SV which is an exact duplicate of the original
11624 SV (using "sv_setsv".)
11625
11626 They differ only in that "newSVsv" performs 'get' magic;
11627 "newSVsv_nomg" skips any magic; and "newSVsv_flags" allows you to
11628 explicitly set a "flags" parameter.
11629
11630 SV* newSVsv (SV *const old)
11631 SV* newSVsv_nomg (SV *const old)
11632 SV* newSVsv_flags(SV *const old, I32 flags)
11633
11634 "newSV_type"
11635 Creates a new SV, of the type specified. The reference count for
11636 the new SV is set to 1.
11637
11638 SV* newSV_type(const svtype type)
11639
11640 "newSVuv"
11641 Creates a new SV and copies an unsigned integer into it. The
11642 reference count for the SV is set to 1.
11643
11644 SV* newSVuv(const UV u)
11645
11646 "Nullsv"
11647 Null SV pointer. (No longer available when "PERL_CORE" is
11648 defined.)
11649
11650 "PL_na"
11651 A convenience variable which is typically used with "SvPV" when one
11652 doesn't care about the length of the string. It is usually more
11653 efficient to either declare a local variable and use that instead
11654 or to use the "SvPV_nolen" macro.
11655
11656 STRLEN PL_na
11657
11658 "PL_sv_no"
11659 This is the "false" SV. It is readonly. See "PL_sv_yes". Always
11660 refer to this as &PL_sv_no.
11661
11662 SV PL_sv_no
11663
11664 "PL_sv_undef"
11665 This is the "undef" SV. It is readonly. Always refer to this as
11666 &PL_sv_undef.
11667
11668 SV PL_sv_undef
11669
11670 "PL_sv_yes"
11671 This is the "true" SV. It is readonly. See "PL_sv_no". Always
11672 refer to this as &PL_sv_yes.
11673
11674 SV PL_sv_yes
11675
11676 "PL_sv_zero"
11677 This readonly SV has a zero numeric value and a "0" string value.
11678 It's similar to "PL_sv_no" except for its string value. Can be used
11679 as a cheap alternative to mXPUSHi(0) for example. Always refer to
11680 this as &PL_sv_zero. Introduced in 5.28.
11681
11682 SV PL_sv_zero
11683
11684 "SAVE_DEFSV"
11685 Localize $_. See "Localizing changes" in perlguts.
11686
11687 void SAVE_DEFSV
11688
11689 "sortsv"
11690 In-place sort an array of SV pointers with the given comparison
11691 routine.
11692
11693 Currently this always uses mergesort. See "sortsv_flags" for a
11694 more flexible routine.
11695
11696 void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
11697
11698 "sortsv_flags"
11699 In-place sort an array of SV pointers with the given comparison
11700 routine, with various SORTf_* flag options.
11701
11702 void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp,
11703 U32 flags)
11704
11705 "SV"
11706 Described in perlguts.
11707
11708 "sv_2cv"
11709 Using various gambits, try to get a CV from an SV; in addition, try
11710 if possible to set *st and *gvp to the stash and GV associated with
11711 it. The flags in "lref" are passed to "gv_fetchsv".
11712
11713 CV* sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)
11714
11715 "sv_2io"
11716 Using various gambits, try to get an IO from an SV: the IO slot if
11717 its a GV; or the recursive result if we're an RV; or the IO slot of
11718 the symbol named after the PV if we're a string.
11719
11720 'Get' magic is ignored on the "sv" passed in, but will be called on
11721 "SvRV(sv)" if "sv" is an RV.
11722
11723 IO* sv_2io(SV *const sv)
11724
11725 "sv_2iv_flags"
11726 Return the integer value of an SV, doing any necessary string
11727 conversion. If "flags" has the "SV_GMAGIC" bit set, does an
11728 "mg_get()" first. Normally used via the "SvIV(sv)" and "SvIVx(sv)"
11729 macros.
11730
11731 IV sv_2iv_flags(SV *const sv, const I32 flags)
11732
11733 "sv_2mortal"
11734 Marks an existing SV as mortal. The SV will be destroyed "soon",
11735 either by an explicit call to "FREETMPS", or by an implicit call at
11736 places such as statement boundaries. "SvTEMP()" is turned on which
11737 means that the SV's string buffer can be "stolen" if this SV is
11738 copied. See also "sv_newmortal" and "sv_mortalcopy".
11739
11740 SV* sv_2mortal(SV *const sv)
11741
11742 "sv_2nv_flags"
11743 Return the num value of an SV, doing any necessary string or
11744 integer conversion. If "flags" has the "SV_GMAGIC" bit set, does
11745 an "mg_get()" first. Normally used via the "SvNV(sv)" and
11746 "SvNVx(sv)" macros.
11747
11748 NV sv_2nv_flags(SV *const sv, const I32 flags)
11749
11750 "sv_2pvbyte"
11751 Returns a pointer to the byte-encoded representation of the SV, and
11752 set *lp to its length. If the SV is marked as being encoded as
11753 UTF-8, it will downgrade it to a byte string as a side-effect, if
11754 possible. If the SV cannot be downgraded, this croaks.
11755
11756 Processes 'get' magic.
11757
11758 Usually accessed via the "SvPVbyte" macro.
11759
11760 char* sv_2pvbyte(SV *sv, STRLEN *const lp)
11761
11762 "sv_2pvutf8"
11763 Return a pointer to the UTF-8-encoded representation of the SV, and
11764 set *lp to its length. May cause the SV to be upgraded to UTF-8 as
11765 a side-effect.
11766
11767 Usually accessed via the "SvPVutf8" macro.
11768
11769 char* sv_2pvutf8(SV *sv, STRLEN *const lp)
11770
11771 "sv_2uv_flags"
11772 Return the unsigned integer value of an SV, doing any necessary
11773 string conversion. If "flags" has the "SV_GMAGIC" bit set, does an
11774 "mg_get()" first. Normally used via the "SvUV(sv)" and "SvUVx(sv)"
11775 macros.
11776
11777 UV sv_2uv_flags(SV *const sv, const I32 flags)
11778
11779 "sv_backoff"
11780 Remove any string offset. You should normally use the "SvOOK_off"
11781 macro wrapper instead.
11782
11783 void sv_backoff(SV *const sv)
11784
11785 "sv_bless"
11786 Blesses an SV into a specified package. The SV must be an RV. The
11787 package must be designated by its stash (see "gv_stashpv"). The
11788 reference count of the SV is unaffected.
11789
11790 SV* sv_bless(SV *const sv, HV *const stash)
11791
11792 "sv_catpv"
11793 "sv_catpv_flags"
11794 "sv_catpv_mg"
11795 "sv_catpv_nomg"
11796 These concatenate the "NUL"-terminated string "sstr" onto the end
11797 of the string which is in the SV. If the SV has the UTF-8 status
11798 set, then the bytes appended should be valid UTF-8.
11799
11800 They differ only in how they handle magic:
11801
11802 "sv_catpv_mg" performs both 'get' and 'set' magic.
11803
11804 "sv_catpv" performs only 'get' magic.
11805
11806 "sv_catpv_nomg" skips all magic.
11807
11808 "sv_catpv_flags" has an extra "flags" parameter which allows you to
11809 specify any combination of magic handling (using "SV_GMAGIC" and/or
11810 "SV_SMAGIC"), and to also override the UTF-8 handling. By
11811 supplying the "SV_CATUTF8" flag, the appended string is forced to
11812 be interpreted as UTF-8; by supplying instead the "SV_CATBYTES"
11813 flag, it will be interpreted as just bytes. Either the SV or the
11814 string appended will be upgraded to UTF-8 if necessary.
11815
11816 void sv_catpv (SV *const dsv, const char* sstr)
11817 void sv_catpv_flags(SV *dsv, const char *sstr, const I32 flags)
11818 void sv_catpv_mg (SV *const dsv, const char *const sstr)
11819 void sv_catpv_nomg (SV *const dsv, const char* sstr)
11820
11821 "sv_catpvf"
11822 "sv_catpvf_nocontext"
11823 "sv_catpvf_mg"
11824 "sv_catpvf_mg_nocontext"
11825 These process their arguments like "sprintf", and append the
11826 formatted output to an SV. As with "sv_vcatpvfn", argument
11827 reordering is not supporte when called with a non-null C-style
11828 variable argument list.
11829
11830 If the appended data contains "wide" characters (including, but not
11831 limited to, SVs with a UTF-8 PV formatted with %s, and characters
11832 >255 formatted with %c), the original SV might get upgraded to
11833 UTF-8.
11834
11835 If the original SV was UTF-8, the pattern should be valid UTF-8; if
11836 the original SV was bytes, the pattern should be too.
11837
11838 All perform 'get' magic, but only "sv_catpvf_mg" and
11839 "sv_catpvf_mg_nocontext" perform 'set' magic.
11840
11841 "sv_catpvf_nocontext" and "sv_catpvf_mg_nocontext" do not take a
11842 thread context ("aTHX") parameter, so are used in situations where
11843 the caller doesn't already have the thread context.
11844
11845 NOTE: "sv_catpvf" must be explicitly called as "Perl_sv_catpvf"
11846 with an "aTHX_" parameter.
11847
11848 NOTE: "sv_catpvf_mg" must be explicitly called as
11849 "Perl_sv_catpvf_mg" with an "aTHX_" parameter.
11850
11851 void Perl_sv_catpvf (pTHX_ SV *const sv,
11852 const char *const pat, ...)
11853 void sv_catpvf_nocontext (SV *const sv, const char *const pat,
11854 ...)
11855 void Perl_sv_catpvf_mg (pTHX_ SV *const sv,
11856 const char *const pat, ...)
11857 void sv_catpvf_mg_nocontext(SV *const sv, const char *const pat,
11858 ...)
11859
11860 "sv_catpvn"
11861 "sv_catpvn_flags"
11862 "sv_catpvn_mg"
11863 "sv_catpvn_nomg"
11864 These concatenate the "len" bytes of the string beginning at "ptr"
11865 onto the end of the string which is in "dsv". The caller must make
11866 sure "ptr" contains at least "len" bytes.
11867
11868 For all but "sv_catpvn_flags", the string appended is assumed to be
11869 valid UTF-8 if the SV has the UTF-8 status set, and a string of
11870 bytes otherwise.
11871
11872 They differ in that:
11873
11874 "sv_catpvn_mg" performs both 'get' and 'set' magic on "dsv".
11875
11876 "sv_catpvn" performs only 'get' magic.
11877
11878 "sv_catpvn_nomg" skips all magic.
11879
11880 "sv_catpvn_flags" has an extra "flags" parameter which allows you
11881 to specify any combination of magic handling (using "SV_GMAGIC"
11882 and/or "SV_SMAGIC") and to also override the UTF-8 handling. By
11883 supplying the "SV_CATBYTES" flag, the appended string is
11884 interpreted as plain bytes; by supplying instead the "SV_CATUTF8"
11885 flag, it will be interpreted as UTF-8, and the "dsv" will be
11886 upgraded to UTF-8 if necessary.
11887
11888 "sv_catpvn", "sv_catpvn_mg", and "sv_catpvn_nomg" are implemented
11889 in terms of "sv_catpvn_flags".
11890
11891 void sv_catpvn (SV *dsv, const char *sstr, STRLEN len)
11892 void sv_catpvn_flags(SV *const dsv, const char *sstr,
11893 const STRLEN len, const I32 flags)
11894 void sv_catpvn_mg (SV *dsv, const char *sstr, STRLEN len)
11895 void sv_catpvn_nomg (SV *dsv, const char *sstr, STRLEN len)
11896
11897 "sv_catpvs"
11898 Like "sv_catpvn", but takes a literal string instead of a
11899 string/length pair.
11900
11901 void sv_catpvs(SV* sv, "literal string")
11902
11903 "sv_catpvs_flags"
11904 Like "sv_catpvn_flags", but takes a literal string instead of a
11905 string/length pair.
11906
11907 void sv_catpvs_flags(SV* sv, "literal string", I32 flags)
11908
11909 "sv_catpvs_mg"
11910 Like "sv_catpvn_mg", but takes a literal string instead of a
11911 string/length pair.
11912
11913 void sv_catpvs_mg(SV* sv, "literal string")
11914
11915 "sv_catpvs_nomg"
11916 Like "sv_catpvn_nomg", but takes a literal string instead of a
11917 string/length pair.
11918
11919 void sv_catpvs_nomg(SV* sv, "literal string")
11920
11921 "sv_catsv"
11922 "sv_catsv_flags"
11923 "sv_catsv_mg"
11924 "sv_catsv_nomg"
11925 These concatenate the string from SV "sstr" onto the end of the
11926 string in SV "dsv". If "sstr" is null, these are no-ops; otherwise
11927 only "dsv" is modified.
11928
11929 They differ only in what magic they perform:
11930
11931 "sv_catsv_mg" performs 'get' magic on both SVs before the copy, and
11932 'set' magic on "dsv" afterwards.
11933
11934 "sv_catsv" performs just 'get' magic, on both SVs.
11935
11936 "sv_catsv_nomg" skips all magic.
11937
11938 "sv_catsv_flags" has an extra "flags" parameter which allows you to
11939 use "SV_GMAGIC" and/or "SV_SMAGIC" to specify any combination of
11940 magic handling (although either both or neither SV will have 'get'
11941 magic applied to it.)
11942
11943 "sv_catsv", "sv_catsv_mg", and "sv_catsv_nomg" are implemented in
11944 terms of "sv_catsv_flags".
11945
11946 void sv_catsv (SV *dsv, SV *sstr)
11947 void sv_catsv_flags(SV *const dsv, SV *const sstr,
11948 const I32 flags)
11949 void sv_catsv_mg (SV *dsv, SV *sstr)
11950 void sv_catsv_nomg (SV *dsv, SV *sstr)
11951
11952 "sv_chop"
11953 Efficient removal of characters from the beginning of the string
11954 buffer. "SvPOK(sv)", or at least "SvPOKp(sv)", must be true and
11955 "ptr" must be a pointer to somewhere inside the string buffer.
11956 "ptr" becomes the first character of the adjusted string. Uses the
11957 "OOK" hack. On return, only "SvPOK(sv)" and "SvPOKp(sv)" among the
11958 "OK" flags will be true.
11959
11960 Beware: after this function returns, "ptr" and SvPVX_const(sv) may
11961 no longer refer to the same chunk of data.
11962
11963 The unfortunate similarity of this function's name to that of
11964 Perl's "chop" operator is strictly coincidental. This function
11965 works from the left; "chop" works from the right.
11966
11967 void sv_chop(SV *const sv, const char *const ptr)
11968
11969 "sv_clear"
11970 Clear an SV: call any destructors, free up any memory used by the
11971 body, and free the body itself. The SV's head is not freed,
11972 although its type is set to all 1's so that it won't inadvertently
11973 be assumed to be live during global destruction etc. This function
11974 should only be called when "REFCNT" is zero. Most of the time
11975 you'll want to call "sv_free()" (or its macro wrapper
11976 "SvREFCNT_dec") instead.
11977
11978 void sv_clear(SV *const orig_sv)
11979
11980 "sv_cmp"
11981 Compares the strings in two SVs. Returns -1, 0, or 1 indicating
11982 whether the string in "sv1" is less than, equal to, or greater than
11983 the string in "sv2". Is UTF-8 and 'use bytes' aware, handles get
11984 magic, and will coerce its args to strings if necessary. See also
11985 "sv_cmp_locale".
11986
11987 I32 sv_cmp(SV *const sv1, SV *const sv2)
11988
11989 "sv_cmp_flags"
11990 Compares the strings in two SVs. Returns -1, 0, or 1 indicating
11991 whether the string in "sv1" is less than, equal to, or greater than
11992 the string in "sv2". Is UTF-8 and 'use bytes' aware and will
11993 coerce its args to strings if necessary. If the flags has the
11994 "SV_GMAGIC" bit set, it handles get magic. See also
11995 "sv_cmp_locale_flags".
11996
11997 I32 sv_cmp_flags(SV *const sv1, SV *const sv2, const U32 flags)
11998
11999 "sv_cmp_locale"
12000 Compares the strings in two SVs in a locale-aware manner. Is UTF-8
12001 and 'use bytes' aware, handles get magic, and will coerce its args
12002 to strings if necessary. See also "sv_cmp".
12003
12004 I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
12005
12006 "sv_cmp_locale_flags"
12007 Compares the strings in two SVs in a locale-aware manner. Is UTF-8
12008 and 'use bytes' aware and will coerce its args to strings if
12009 necessary. If the flags contain "SV_GMAGIC", it handles get magic.
12010 See also "sv_cmp_flags".
12011
12012 I32 sv_cmp_locale_flags(SV *const sv1, SV *const sv2,
12013 const U32 flags)
12014
12015 "sv_collxfrm"
12016 This calls "sv_collxfrm_flags" with the SV_GMAGIC flag. See
12017 "sv_collxfrm_flags".
12018
12019 char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
12020
12021 "sv_collxfrm_flags"
12022 Add Collate Transform magic to an SV if it doesn't already have it.
12023 If the flags contain "SV_GMAGIC", it handles get-magic.
12024
12025 Any scalar variable may carry "PERL_MAGIC_collxfrm" magic that
12026 contains the scalar data of the variable, but transformed to such a
12027 format that a normal memory comparison can be used to compare the
12028 data according to the locale settings.
12029
12030 char* sv_collxfrm_flags(SV *const sv, STRLEN *const nxp,
12031 I32 const flags)
12032
12033 "sv_copypv"
12034 "sv_copypv_nomg"
12035 "sv_copypv_flags"
12036 These copy a stringified representation of the source SV into the
12037 destination SV. They automatically perform coercion of numeric
12038 values into strings. Guaranteed to preserve the "UTF8" flag even
12039 from overloaded objects. Similar in nature to "sv_2pv[_flags]" but
12040 they operate directly on an SV instead of just the string. Mostly
12041 they use ""sv_2pv_flags"" in perlintern to do the work, except when
12042 that would lose the UTF-8'ness of the PV.
12043
12044 The three forms differ only in whether or not they perform 'get
12045 magic' on "sv". "sv_copypv_nomg" skips 'get magic'; "sv_copypv"
12046 performs it; and "sv_copypv_flags" either performs it (if the
12047 "SV_GMAGIC" bit is set in "flags") or doesn't (if that bit is
12048 cleared).
12049
12050 void sv_copypv (SV *const dsv, SV *const ssv)
12051 void sv_copypv_nomg (SV *const dsv, SV *const ssv)
12052 void sv_copypv_flags(SV *const dsv, SV *const ssv,
12053 const I32 flags)
12054
12055 "SvCUR"
12056 Returns the length, in bytes, of the PV inside the SV. Note that
12057 this may not match Perl's "length"; for that, use
12058 "sv_len_utf8(sv)". See "SvLEN" also.
12059
12060 STRLEN SvCUR(SV* sv)
12061
12062 "SvCUR_set"
12063 Sets the current length, in bytes, of the C string which is in the
12064 SV. See "SvCUR" and "SvIV_set">.
12065
12066 void SvCUR_set(SV* sv, STRLEN len)
12067
12068 "sv_dec"
12069 "sv_dec_nomg"
12070 These auto-decrement the value in the SV, doing string to numeric
12071 conversion if necessary. They both handle operator overloading.
12072
12073 They differ only in that:
12074
12075 "sv_dec" handles 'get' magic; "sv_dec_nomg" skips 'get' magic.
12076
12077 void sv_dec(SV *const sv)
12078
12079 "sv_derived_from"
12080 Exactly like "sv_derived_from_pv", but doesn't take a "flags"
12081 parameter.
12082
12083 bool sv_derived_from(SV* sv, const char *const name)
12084
12085 "sv_derived_from_pv"
12086 Exactly like "sv_derived_from_pvn", but takes a nul-terminated
12087 string instead of a string/length pair.
12088
12089 bool sv_derived_from_pv(SV* sv, const char *const name,
12090 U32 flags)
12091
12092 "sv_derived_from_pvn"
12093 Returns a boolean indicating whether the SV is derived from the
12094 specified class at the C level. To check derivation at the Perl
12095 level, call "isa()" as a normal Perl method.
12096
12097 Currently, the only significant value for "flags" is SVf_UTF8.
12098
12099 bool sv_derived_from_pvn(SV* sv, const char *const name,
12100 const STRLEN len, U32 flags)
12101
12102 "sv_derived_from_sv"
12103 Exactly like "sv_derived_from_pvn", but takes the name string in
12104 the form of an SV instead of a string/length pair. This is the
12105 advised form.
12106
12107 bool sv_derived_from_sv(SV* sv, SV *namesv, U32 flags)
12108
12109 "sv_does"
12110 Like "sv_does_pv", but doesn't take a "flags" parameter.
12111
12112 bool sv_does(SV* sv, const char *const name)
12113
12114 "sv_does_pv"
12115 Like "sv_does_sv", but takes a nul-terminated string instead of an
12116 SV.
12117
12118 bool sv_does_pv(SV* sv, const char *const name, U32 flags)
12119
12120 "sv_does_pvn"
12121 Like "sv_does_sv", but takes a string/length pair instead of an SV.
12122
12123 bool sv_does_pvn(SV* sv, const char *const name,
12124 const STRLEN len, U32 flags)
12125
12126 "sv_does_sv"
12127 Returns a boolean indicating whether the SV performs a specific,
12128 named role. The SV can be a Perl object or the name of a Perl
12129 class.
12130
12131 bool sv_does_sv(SV* sv, SV* namesv, U32 flags)
12132
12133 "SvEND"
12134 Returns a pointer to the spot just after the last character in the
12135 string which is in the SV, where there is usually a trailing "NUL"
12136 character (even though Perl scalars do not strictly require it).
12137 See "SvCUR". Access the character as "*(SvEND(sv))".
12138
12139 Warning: If "SvCUR" is equal to "SvLEN", then "SvEND" points to
12140 unallocated memory.
12141
12142 char* SvEND(SV* sv)
12143
12144 "sv_eq"
12145 Returns a boolean indicating whether the strings in the two SVs are
12146 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and
12147 will coerce its args to strings if necessary.
12148
12149 I32 sv_eq(SV* sv1, SV* sv2)
12150
12151 "sv_eq_flags"
12152 Returns a boolean indicating whether the strings in the two SVs are
12153 identical. Is UTF-8 and 'use bytes' aware and coerces its args to
12154 strings if necessary. If the flags has the "SV_GMAGIC" bit set, it
12155 handles get-magic, too.
12156
12157 I32 sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)
12158
12159 "sv_force_normal"
12160 Undo various types of fakery on an SV: if the PV is a shared
12161 string, make a private copy; if we're a ref, stop refing; if we're
12162 a glob, downgrade to an "xpvmg". See also "sv_force_normal_flags".
12163
12164 void sv_force_normal(SV *sv)
12165
12166 "sv_force_normal_flags"
12167 Undo various types of fakery on an SV, where fakery means "more
12168 than" a string: if the PV is a shared string, make a private copy;
12169 if we're a ref, stop refing; if we're a glob, downgrade to an
12170 "xpvmg"; if we're a copy-on-write scalar, this is the on-write time
12171 when we do the copy, and is also used locally; if this is a
12172 vstring, drop the vstring magic. If "SV_COW_DROP_PV" is set then a
12173 copy-on-write scalar drops its PV buffer (if any) and becomes
12174 "SvPOK_off" rather than making a copy. (Used where this scalar is
12175 about to be set to some other value.) In addition, the "flags"
12176 parameter gets passed to "sv_unref_flags()" when unreffing.
12177 "sv_force_normal" calls this function with flags set to 0.
12178
12179 This function is expected to be used to signal to perl that this SV
12180 is about to be written to, and any extra book-keeping needs to be
12181 taken care of. Hence, it croaks on read-only values.
12182
12183 void sv_force_normal_flags(SV *const sv, const U32 flags)
12184
12185 "sv_free"
12186 Decrement an SV's reference count, and if it drops to zero, call
12187 "sv_clear" to invoke destructors and free up any memory used by the
12188 body; finally, deallocating the SV's head itself. Normally called
12189 via a wrapper macro "SvREFCNT_dec".
12190
12191 void sv_free(SV *const sv)
12192
12193 "SvGAMAGIC"
12194 Returns true if the SV has get magic or overloading. If either is
12195 true then the scalar is active data, and has the potential to
12196 return a new value every time it is accessed. Hence you must be
12197 careful to only read it once per user logical operation and work
12198 with that returned value. If neither is true then the scalar's
12199 value cannot change unless written to.
12200
12201 U32 SvGAMAGIC(SV* sv)
12202
12203 "SvGETMAGIC"
12204 Invokes "mg_get" on an SV if it has 'get' magic. For example, this
12205 will call "FETCH" on a tied variable. This macro evaluates its
12206 argument more than once.
12207
12208 void SvGETMAGIC(SV* sv)
12209
12210 "sv_gets"
12211 Get a line from the filehandle and store it into the SV, optionally
12212 appending to the currently-stored string. If "append" is not 0,
12213 the line is appended to the SV instead of overwriting it. "append"
12214 should be set to the byte offset that the appended string should
12215 start at in the SV (typically, "SvCUR(sv)" is a suitable choice).
12216
12217 char* sv_gets(SV *const sv, PerlIO *const fp, I32 append)
12218
12219 "sv_get_backrefs"
12220 NOTE: "sv_get_backrefs" is experimental and may change or be
12221 removed without notice.
12222
12223 If "sv" is the target of a weak reference then it returns the back
12224 references structure associated with the sv; otherwise return
12225 "NULL".
12226
12227 When returning a non-null result the type of the return is
12228 relevant. If it is an AV then the elements of the AV are the weak
12229 reference RVs which point at this item. If it is any other type
12230 then the item itself is the weak reference.
12231
12232 See also "Perl_sv_add_backref()", "Perl_sv_del_backref()",
12233 "Perl_sv_kill_backrefs()"
12234
12235 SV* sv_get_backrefs(SV *const sv)
12236
12237 "SvGROW"
12238 Expands the character buffer in the SV so that it has room for the
12239 indicated number of bytes (remember to reserve space for an extra
12240 trailing "NUL" character). Calls "sv_grow" to perform the
12241 expansion if necessary. Returns a pointer to the character buffer.
12242 SV must be of type >= "SVt_PV". One alternative is to call
12243 "sv_grow" if you are not sure of the type of SV.
12244
12245 You might mistakenly think that "len" is the number of bytes to add
12246 to the existing size, but instead it is the total size "sv" should
12247 be.
12248
12249 char * SvGROW(SV* sv, STRLEN len)
12250
12251 "sv_inc"
12252 "sv_inc_nomg"
12253 These auto-increment the value in the SV, doing string to numeric
12254 conversion if necessary. They both handle operator overloading.
12255
12256 They differ only in that "sv_inc" performs 'get' magic;
12257 "sv_inc_nomg" skips any magic.
12258
12259 void sv_inc(SV *const sv)
12260
12261 "sv_insert"
12262 Inserts and/or replaces a string at the specified offset/length
12263 within the SV. Similar to the Perl "substr()" function, with
12264 "littlelen" bytes starting at "little" replacing "len" bytes of the
12265 string in "bigstr" starting at "offset". Handles get magic.
12266
12267 void sv_insert(SV *const bigstr, const STRLEN offset,
12268 const STRLEN len, const char *const little,
12269 const STRLEN littlelen)
12270
12271 "sv_insert_flags"
12272 Same as "sv_insert", but the extra "flags" are passed to the
12273 "SvPV_force_flags" that applies to "bigstr".
12274
12275 void sv_insert_flags(SV *const bigstr, const STRLEN offset,
12276 const STRLEN len, const char *little,
12277 const STRLEN littlelen, const U32 flags)
12278
12279 "SvIOK"
12280 Returns a U32 value indicating whether the SV contains an integer.
12281
12282 U32 SvIOK(SV* sv)
12283
12284 "SvIOK_notUV"
12285 Returns a boolean indicating whether the SV contains a signed
12286 integer.
12287
12288 bool SvIOK_notUV(SV* sv)
12289
12290 "SvIOK_off"
12291 Unsets the IV status of an SV.
12292
12293 void SvIOK_off(SV* sv)
12294
12295 "SvIOK_on"
12296 Tells an SV that it is an integer.
12297
12298 void SvIOK_on(SV* sv)
12299
12300 "SvIOK_only"
12301 Tells an SV that it is an integer and disables all other "OK" bits.
12302
12303 void SvIOK_only(SV* sv)
12304
12305 "SvIOK_only_UV"
12306 Tells an SV that it is an unsigned integer and disables all other
12307 "OK" bits.
12308
12309 void SvIOK_only_UV(SV* sv)
12310
12311 "SvIOKp"
12312 Returns a U32 value indicating whether the SV contains an integer.
12313 Checks the private setting. Use "SvIOK" instead.
12314
12315 U32 SvIOKp(SV* sv)
12316
12317 "SvIOK_UV"
12318 Returns a boolean indicating whether the SV contains an integer
12319 that must be interpreted as unsigned. A non-negative integer whose
12320 value is within the range of both an IV and a UV may be flagged as
12321 either "SvUOK" or "SvIOK".
12322
12323 bool SvIOK_UV(SV* sv)
12324
12325 "sv_isa"
12326 Returns a boolean indicating whether the SV is blessed into the
12327 specified class.
12328
12329 This does not check for subtypes or method overloading. Use
12330 "sv_isa_sv" to verify an inheritance relationship in the same way
12331 as the "isa" operator by respecting any "isa()" method overloading;
12332 or "sv_derived_from_sv" to test directly on the actual object type.
12333
12334 int sv_isa(SV* sv, const char *const name)
12335
12336 "sv_isa_sv"
12337 NOTE: "sv_isa_sv" is experimental and may change or be removed
12338 without notice.
12339
12340 Returns a boolean indicating whether the SV is an object reference
12341 and is derived from the specified class, respecting any "isa()"
12342 method overloading it may have. Returns false if "sv" is not a
12343 reference to an object, or is not derived from the specified class.
12344
12345 This is the function used to implement the behaviour of the "isa"
12346 operator.
12347
12348 Does not invoke magic on "sv".
12349
12350 Not to be confused with the older "sv_isa" function, which does not
12351 use an overloaded "isa()" method, nor will check subclassing.
12352
12353 bool sv_isa_sv(SV* sv, SV* namesv)
12354
12355 "SvIsCOW"
12356 Returns a U32 value indicating whether the SV is Copy-On-Write
12357 (either shared hash key scalars, or full Copy On Write scalars if
12358 5.9.0 is configured for COW).
12359
12360 U32 SvIsCOW(SV* sv)
12361
12362 "SvIsCOW_shared_hash"
12363 Returns a boolean indicating whether the SV is Copy-On-Write shared
12364 hash key scalar.
12365
12366 bool SvIsCOW_shared_hash(SV* sv)
12367
12368 "sv_isobject"
12369 Returns a boolean indicating whether the SV is an RV pointing to a
12370 blessed object. If the SV is not an RV, or if the object is not
12371 blessed, then this will return false.
12372
12373 int sv_isobject(SV* sv)
12374
12375 "SvIV"
12376 "SvIVx"
12377 "SvIV_nomg"
12378 These coerce the given SV to IV and return it. The returned value
12379 in many circumstances will get stored in "sv"'s IV slot, but not in
12380 all cases. (Use "sv_setiv" to make sure it does).
12381
12382 "SvIVx" is different from the others in that it is guaranteed to
12383 evaluate "sv" exactly once; the others may evaluate it multiple
12384 times. Only use this form if "sv" is an expression with side
12385 effects, otherwise use the more efficient "SvIV".
12386
12387 "SvIV_nomg" is the same as "SvIV", but does not perform 'get'
12388 magic.
12389
12390 IV SvIV(SV* sv)
12391
12392 "SvIV_set"
12393 Set the value of the IV pointer in sv to val. It is possible to
12394 perform the same function of this macro with an lvalue assignment
12395 to "SvIVX". With future Perls, however, it will be more efficient
12396 to use "SvIV_set" instead of the lvalue assignment to "SvIVX".
12397
12398 void SvIV_set(SV* sv, IV val)
12399
12400 "SvIVX"
12401 Returns the raw value in the SV's IV slot, without checks or
12402 conversions. Only use when you are sure "SvIOK" is true. See also
12403 "SvIV".
12404
12405 IV SvIVX(SV* sv)
12406
12407 "SvLEN"
12408 Returns the size of the string buffer in the SV, not including any
12409 part attributable to "SvOOK". See "SvCUR".
12410
12411 STRLEN SvLEN(SV* sv)
12412
12413 "sv_len"
12414 Returns the length of the string in the SV. Handles magic and type
12415 coercion and sets the UTF8 flag appropriately. See also "SvCUR",
12416 which gives raw access to the "xpv_cur" slot.
12417
12418 STRLEN sv_len(SV *const sv)
12419
12420 "SvLEN_set"
12421 Set the size of the string buffer for the SV. See "SvLEN".
12422
12423 void SvLEN_set(SV* sv, STRLEN len)
12424
12425 "sv_len_utf8"
12426 Returns the number of characters in the string in an SV, counting
12427 wide UTF-8 bytes as a single character. Handles magic and type
12428 coercion.
12429
12430 STRLEN sv_len_utf8(SV *const sv)
12431
12432 "SvLOCK"
12433 Arranges for a mutual exclusion lock to be obtained on "sv" if a
12434 suitable module has been loaded.
12435
12436 void SvLOCK(SV* sv)
12437
12438 "sv_magic"
12439 Adds magic to an SV. First upgrades "sv" to type "SVt_PVMG" if
12440 necessary, then adds a new magic item of type "how" to the head of
12441 the magic list.
12442
12443 See "sv_magicext" (which "sv_magic" now calls) for a description of
12444 the handling of the "name" and "namlen" arguments.
12445
12446 You need to use "sv_magicext" to add magic to "SvREADONLY" SVs and
12447 also to add more than one instance of the same "how".
12448
12449 void sv_magic(SV *const sv, SV *const obj, const int how,
12450 const char *const name, const I32 namlen)
12451
12452 "sv_magicext"
12453 Adds magic to an SV, upgrading it if necessary. Applies the
12454 supplied "vtable" and returns a pointer to the magic added.
12455
12456 Note that "sv_magicext" will allow things that "sv_magic" will not.
12457 In particular, you can add magic to "SvREADONLY" SVs, and add more
12458 than one instance of the same "how".
12459
12460 If "namlen" is greater than zero then a "savepvn" copy of "name" is
12461 stored, if "namlen" is zero then "name" is stored as-is and - as
12462 another special case - if "(name && namlen == HEf_SVKEY)" then
12463 "name" is assumed to contain an SV* and is stored as-is with its
12464 "REFCNT" incremented.
12465
12466 (This is now used as a subroutine by "sv_magic".)
12467
12468 MAGIC * sv_magicext(SV *const sv, SV *const obj, const int how,
12469 const MGVTBL *const vtbl,
12470 const char *const name, const I32 namlen)
12471
12472 "SvMAGIC_set"
12473 Set the value of the MAGIC pointer in "sv" to val. See "SvIV_set".
12474
12475 void SvMAGIC_set(SV* sv, MAGIC* val)
12476
12477 "sv_mortalcopy"
12478 Creates a new SV which is a copy of the original SV (using
12479 "sv_setsv"). The new SV is marked as mortal. It will be destroyed
12480 "soon", either by an explicit call to "FREETMPS", or by an implicit
12481 call at places such as statement boundaries. See also
12482 "sv_newmortal" and "sv_2mortal".
12483
12484 SV* sv_mortalcopy(SV *const oldsv)
12485
12486 "sv_mortalcopy_flags"
12487 Like "sv_mortalcopy", but the extra "flags" are passed to the
12488 "sv_setsv_flags".
12489
12490 SV* sv_mortalcopy_flags(SV *const oldsv, U32 flags)
12491
12492 "sv_newmortal"
12493 Creates a new null SV which is mortal. The reference count of the
12494 SV is set to 1. It will be destroyed "soon", either by an explicit
12495 call to "FREETMPS", or by an implicit call at places such as
12496 statement boundaries. See also "sv_mortalcopy" and "sv_2mortal".
12497
12498 SV* sv_newmortal()
12499
12500 "SvNIOK"
12501 Returns a U32 value indicating whether the SV contains a number,
12502 integer or double.
12503
12504 U32 SvNIOK(SV* sv)
12505
12506 "SvNIOK_off"
12507 Unsets the NV/IV status of an SV.
12508
12509 void SvNIOK_off(SV* sv)
12510
12511 "SvNIOKp"
12512 Returns a U32 value indicating whether the SV contains a number,
12513 integer or double. Checks the private setting. Use "SvNIOK"
12514 instead.
12515
12516 U32 SvNIOKp(SV* sv)
12517
12518 "SvNOK"
12519 Returns a U32 value indicating whether the SV contains a double.
12520
12521 U32 SvNOK(SV* sv)
12522
12523 "SvNOK_off"
12524 Unsets the NV status of an SV.
12525
12526 void SvNOK_off(SV* sv)
12527
12528 "SvNOK_on"
12529 Tells an SV that it is a double.
12530
12531 void SvNOK_on(SV* sv)
12532
12533 "SvNOK_only"
12534 Tells an SV that it is a double and disables all other OK bits.
12535
12536 void SvNOK_only(SV* sv)
12537
12538 "SvNOKp"
12539 Returns a U32 value indicating whether the SV contains a double.
12540 Checks the private setting. Use "SvNOK" instead.
12541
12542 U32 SvNOKp(SV* sv)
12543
12544 "sv_nolocking"
12545 "DEPRECATED!" It is planned to remove "sv_nolocking" from a future
12546 release of Perl. Do not use it for new code; remove it from
12547 existing code.
12548
12549 Dummy routine which "locks" an SV when there is no locking module
12550 present. Exists to avoid test for a "NULL" function pointer and
12551 because it could potentially warn under some level of strict-ness.
12552
12553 "Superseded" by "sv_nosharing()".
12554
12555 void sv_nolocking(SV *sv)
12556
12557 "sv_nounlocking"
12558 "DEPRECATED!" It is planned to remove "sv_nounlocking" from a
12559 future release of Perl. Do not use it for new code; remove it from
12560 existing code.
12561
12562 Dummy routine which "unlocks" an SV when there is no locking module
12563 present. Exists to avoid test for a "NULL" function pointer and
12564 because it could potentially warn under some level of strict-ness.
12565
12566 "Superseded" by "sv_nosharing()".
12567
12568 void sv_nounlocking(SV *sv)
12569
12570 "SvNV"
12571 "SvNVx"
12572 "SvNV_nomg"
12573 These coerce the given SV to NV and return it. The returned value
12574 in many circumstances will get stored in "sv"'s NV slot, but not in
12575 all cases. (Use "sv_setnv" to make sure it does).
12576
12577 "SvNVx" is different from the others in that it is guaranteed to
12578 evaluate "sv" exactly once; the others may evaluate it multiple
12579 times. Only use this form if "sv" is an expression with side
12580 effects, otherwise use the more efficient "SvNV".
12581
12582 "SvNV_nomg" is the same as "SvNV", but does not perform 'get'
12583 magic.
12584
12585 NV SvNV(SV* sv)
12586
12587 "SvNV_set"
12588 Set the value of the NV pointer in "sv" to val. See "SvIV_set".
12589
12590 void SvNV_set(SV* sv, NV val)
12591
12592 "SvNVX"
12593 Returns the raw value in the SV's NV slot, without checks or
12594 conversions. Only use when you are sure "SvNOK" is true. See also
12595 "SvNV".
12596
12597 NV SvNVX(SV* sv)
12598
12599 "SvOK"
12600 Returns a U32 value indicating whether the value is defined. This
12601 is only meaningful for scalars.
12602
12603 U32 SvOK(SV* sv)
12604
12605 "SvOOK"
12606 Returns a U32 indicating whether the pointer to the string buffer
12607 is offset. This hack is used internally to speed up removal of
12608 characters from the beginning of a "SvPV". When "SvOOK" is true,
12609 then the start of the allocated string buffer is actually
12610 "SvOOK_offset()" bytes before "SvPVX". This offset used to be
12611 stored in "SvIVX", but is now stored within the spare part of the
12612 buffer.
12613
12614 U32 SvOOK(SV* sv)
12615
12616 "SvOOK_off"
12617 Remove any string offset.
12618
12619 void SvOOK_off(SV * sv)
12620
12621 "SvOOK_offset"
12622 Reads into "len" the offset from "SvPVX" back to the true start of
12623 the allocated buffer, which will be non-zero if "sv_chop" has been
12624 used to efficiently remove characters from start of the buffer.
12625 Implemented as a macro, which takes the address of "len", which
12626 must be of type "STRLEN". Evaluates "sv" more than once. Sets
12627 "len" to 0 if "SvOOK(sv)" is false.
12628
12629 void SvOOK_offset(SV*sv, STRLEN len)
12630
12631 "SvPOK"
12632 Returns a U32 value indicating whether the SV contains a character
12633 string.
12634
12635 U32 SvPOK(SV* sv)
12636
12637 "SvPOK_off"
12638 Unsets the PV status of an SV.
12639
12640 void SvPOK_off(SV* sv)
12641
12642 "SvPOK_on"
12643 Tells an SV that it is a string.
12644
12645 void SvPOK_on(SV* sv)
12646
12647 "SvPOK_only"
12648 Tells an SV that it is a string and disables all other "OK" bits.
12649 Will also turn off the UTF-8 status.
12650
12651 void SvPOK_only(SV* sv)
12652
12653 "SvPOK_only_UTF8"
12654 Tells an SV that it is a string and disables all other "OK" bits,
12655 and leaves the UTF-8 status as it was.
12656
12657 void SvPOK_only_UTF8(SV* sv)
12658
12659 "SvPOKp"
12660 Returns a U32 value indicating whether the SV contains a character
12661 string. Checks the private setting. Use "SvPOK" instead.
12662
12663 U32 SvPOKp(SV* sv)
12664
12665 "sv_pos_b2u"
12666 Converts the value pointed to by "offsetp" from a count of bytes
12667 from the start of the string, to a count of the equivalent number
12668 of UTF-8 chars. Handles magic and type coercion.
12669
12670 Use "sv_pos_b2u_flags" in preference, which correctly handles
12671 strings longer than 2Gb.
12672
12673 void sv_pos_b2u(SV *const sv, I32 *const offsetp)
12674
12675 "sv_pos_b2u_flags"
12676 Converts "offset" from a count of bytes from the start of the
12677 string, to a count of the equivalent number of UTF-8 chars.
12678 Handles type coercion. "flags" is passed to "SvPV_flags", and
12679 usually should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
12680
12681 STRLEN sv_pos_b2u_flags(SV *const sv, STRLEN const offset,
12682 U32 flags)
12683
12684 "sv_pos_u2b"
12685 Converts the value pointed to by "offsetp" from a count of UTF-8
12686 chars from the start of the string, to a count of the equivalent
12687 number of bytes; if "lenp" is non-zero, it does the same to "lenp",
12688 but this time starting from the offset, rather than from the start
12689 of the string. Handles magic and type coercion.
12690
12691 Use "sv_pos_u2b_flags" in preference, which correctly handles
12692 strings longer than 2Gb.
12693
12694 void sv_pos_u2b(SV *const sv, I32 *const offsetp,
12695 I32 *const lenp)
12696
12697 "sv_pos_u2b_flags"
12698 Converts the offset from a count of UTF-8 chars from the start of
12699 the string, to a count of the equivalent number of bytes; if "lenp"
12700 is non-zero, it does the same to "lenp", but this time starting
12701 from "offset", rather than from the start of the string. Handles
12702 type coercion. "flags" is passed to "SvPV_flags", and usually
12703 should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
12704
12705 STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
12706 STRLEN *const lenp, U32 flags)
12707
12708 "SvPV"
12709 "SvPVx"
12710 "SvPV_nomg"
12711 "SvPV_nolen"
12712 "SvPVx_nolen"
12713 "SvPV_nomg_nolen"
12714 "SvPV_mutable"
12715 "SvPV_const"
12716 "SvPVx_const"
12717 "SvPV_nolen_const"
12718 "SvPVx_nolen_const"
12719 "SvPV_nomg_const"
12720 "SvPV_nomg_const_nolen"
12721 "SvPV_flags"
12722 "SvPV_flags_const"
12723 "SvPV_flags_mutable"
12724 "SvPVbyte"
12725 "SvPVbyte_nomg"
12726 "SvPVbyte_nolen"
12727 "SvPVbytex_nolen"
12728 "SvPVbytex"
12729 "SvPVbyte_or_null"
12730 "SvPVbyte_or_null_nomg"
12731 "SvPVutf8"
12732 "SvPVutf8x"
12733 "SvPVutf8_nomg"
12734 "SvPVutf8_nolen"
12735 "SvPVutf8_or_null"
12736 "SvPVutf8_or_null_nomg"
12737 All these return a pointer to the string in "sv", or a stringified
12738 form of "sv" if it does not contain a string. The SV may cache the
12739 stringified version becoming "SvPOK".
12740
12741 This is a very basic and common operation, so there are lots of
12742 slightly different versions of it.
12743
12744 Note that there is no guarantee that the return value of
12745 "SvPV(sv)", for example, is equal to "SvPVX(sv)", or that
12746 "SvPVX(sv)" contains valid data, or that successive calls to
12747 "SvPV(sv)" (or another of these forms) will return the same pointer
12748 value each time. This is due to the way that things like
12749 overloading and Copy-On-Write are handled. In these cases, the
12750 return value may point to a temporary buffer or similar. If you
12751 absolutely need the "SvPVX" field to be valid (for example, if you
12752 intend to write to it), then see "SvPV_force".
12753
12754 The differences between the forms are:
12755
12756 The forms with neither "byte" nor "utf8" in their names (e.g.,
12757 "SvPV" or "SvPV_nolen") can expose the SV's internal string buffer.
12758 If that buffer consists entirely of bytes 0-255 and includes any
12759 bytes above 127, then you MUST consult "SvUTF8" to determine the
12760 actual code points the string is meant to contain. Generally
12761 speaking, it is probably safer to prefer "SvPVbyte", "SvPVutf8",
12762 and the like. See "How do I pass a Perl string to a C library?" in
12763 perlguts for more details.
12764
12765 The forms with "flags" in their names allow you to use the "flags"
12766 parameter to specify to process 'get' magic (by setting the
12767 "SV_GMAGIC" flag) or to skip 'get' magic (by clearing it). The
12768 other forms process 'get' magic, except for the ones with "nomg" in
12769 their names, which skip 'get' magic.
12770
12771 The forms that take a "len" parameter will set that variable to the
12772 byte length of the resultant string (these are macros, so don't use
12773 &len).
12774
12775 The forms with "nolen" in their names indicate they don't have a
12776 "len" parameter. They should be used only when it is known that
12777 the PV is a C string, terminated by a NUL byte, and without
12778 intermediate NUL characters; or when you don't care about its
12779 length.
12780
12781 The forms with "const" in their names return "const char *" so that
12782 the compiler will hopefully complain if you were to try to modify
12783 the contents of the string (unless you cast away const yourself).
12784
12785 The other forms return a mutable pointer so that the string is
12786 modifiable by the caller; this is emphasized for the ones with
12787 "mutable" in their names.
12788
12789 The forms whose name ends in "x" are the same as the corresponding
12790 form without the "x", but the "x" form is guaranteed to evaluate
12791 "sv" exactly once, with a slight loss of efficiency. Use this if
12792 "sv" is an expression with side effects.
12793
12794 "SvPVutf8" is like "SvPV", but converts "sv" to UTF-8 first if not
12795 already UTF-8. Similiarly, the other forms with "utf8" in their
12796 names correspond to their respective forms without.
12797
12798 "SvPVutf8_or_null" and "SvPVutf8_or_null_nomg" don't have
12799 corresponding non-"utf8" forms. Instead they are like
12800 "SvPVutf8_nomg", but when "sv" is undef, they return "NULL".
12801
12802 "SvPVbyte" is like "SvPV", but converts "sv" to byte representation
12803 first if currently encoded as UTF-8. If "sv" cannot be downgraded
12804 from UTF-8, it croaks. Similiarly, the other forms with "byte" in
12805 their names correspond to their respective forms without.
12806
12807 "SvPVbyte_or_null" doesn't have a corresponding non-"byte" form.
12808 Instead it is like "SvPVbyte", but when "sv" is undef, it returns
12809 "NULL".
12810
12811 char* SvPV (SV* sv, STRLEN len)
12812 char* SvPVx (SV* sv, STRLEN len)
12813 char* SvPV_nomg (SV* sv, STRLEN len)
12814 char* SvPV_nolen (SV* sv)
12815 char* SvPVx_nolen (SV* sv)
12816 char* SvPV_nomg_nolen (SV* sv)
12817 char* SvPV_mutable (SV* sv, STRLEN len)
12818 const char* SvPV_const (SV* sv, STRLEN len)
12819 const char* SvPVx_const (SV* sv, STRLEN len)
12820 const char* SvPV_nolen_const (SV* sv)
12821 const char* SvPVx_nolen_const (SV* sv)
12822 const char* SvPV_nomg_const (SV* sv, STRLEN len)
12823 const char* SvPV_nomg_const_nolen(SV* sv)
12824 char * SvPV_flags (SV * sv, STRLEN len,
12825 U32 flags)
12826 const char * SvPV_flags_const (SV * sv, STRLEN len,
12827 U32 flags)
12828 char * SvPV_flags_mutable (SV * sv, STRLEN len,
12829 U32 flags)
12830 char* SvPVbyte (SV* sv, STRLEN len)
12831 char* SvPVbyte_nomg (SV* sv, STRLEN len)
12832 char* SvPVbyte_nolen (SV* sv)
12833 char* SvPVbytex_nolen (SV* sv)
12834 char* SvPVbytex (SV* sv, STRLEN len)
12835 char* SvPVbyte_or_null (SV* sv, STRLEN len)
12836 char* SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
12837 char* SvPVutf8 (SV* sv, STRLEN len)
12838 char* SvPVutf8x (SV* sv, STRLEN len)
12839 char* SvPVutf8_nomg (SV* sv, STRLEN len)
12840 char* SvPVutf8_nolen (SV* sv)
12841 char* SvPVutf8_or_null (SV* sv, STRLEN len)
12842 char* SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
12843
12844 "SvPVbyte"
12845 Like "SvPV", but converts "sv" to byte representation first if
12846 necessary. If the SV cannot be downgraded from UTF-8, this croaks.
12847
12848 char* SvPVbyte(SV* sv, STRLEN len)
12849
12850 "SvPVbyte_force"
12851 Like "SvPV_force", but converts "sv" to byte representation first
12852 if necessary. If the SV cannot be downgraded from UTF-8, this
12853 croaks.
12854
12855 char* SvPVbyte_force(SV* sv, STRLEN len)
12856
12857 "SvPVbyte_nolen"
12858 Like "SvPV_nolen", but converts "sv" to byte representation first
12859 if necessary. If the SV cannot be downgraded from UTF-8, this
12860 croaks.
12861
12862 char* SvPVbyte_nolen(SV* sv)
12863
12864 "SvPVbyte_nomg"
12865 Like "SvPVbyte", but does not process get magic.
12866
12867 char* SvPVbyte_nomg(SV* sv, STRLEN len)
12868
12869 "SvPVbyte_or_null"
12870 Like "SvPVbyte", but when "sv" is undef, returns "NULL".
12871
12872 char* SvPVbyte_or_null(SV* sv, STRLEN len)
12873
12874 "SvPVbyte_or_null_nomg"
12875 Like "SvPVbyte_or_null", but does not process get magic.
12876
12877 char* SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
12878
12879 "SvPVCLEAR"
12880 Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is
12881 properly null terminated. Equivalent to sv_setpvs(""), but more
12882 efficient.
12883
12884 char * SvPVCLEAR(SV* sv)
12885
12886 "SvPV_force"
12887 "SvPV_force_nolen"
12888 "SvPVx_force"
12889 "SvPV_force_nomg"
12890 "SvPV_force_nomg_nolen"
12891 "SvPV_force_mutable"
12892 "SvPV_force_flags"
12893 "SvPV_force_flags_nolen"
12894 "SvPV_force_flags_mutable"
12895 "SvPVbyte_force"
12896 "SvPVbytex_force"
12897 "SvPVutf8_force"
12898 "SvPVutf8x_force"
12899 These are like "SvPV", returning the string in the SV, but will
12900 force the SV into containing a string ("SvPOK"), and only a string
12901 ("SvPOK_only"), by hook or by crook. You need to use one of these
12902 "force" routines if you are going to update the "SvPVX" directly.
12903
12904 Note that coercing an arbitrary scalar into a plain PV will
12905 potentially strip useful data from it. For example if the SV was
12906 "SvROK", then the referent will have its reference count
12907 decremented, and the SV itself may be converted to an "SvPOK"
12908 scalar with a string buffer containing a value such as
12909 "ARRAY(0x1234)".
12910
12911 The differences between the forms are:
12912
12913 The forms with "flags" in their names allow you to use the "flags"
12914 parameter to specify to perform 'get' magic (by setting the
12915 "SV_GMAGIC" flag) or to skip 'get' magic (by clearing it). The
12916 other forms do perform 'get' magic, except for the ones with "nomg"
12917 in their names, which skip 'get' magic.
12918
12919 The forms that take a "len" parameter will set that variable to the
12920 byte length of the resultant string (these are macros, so don't use
12921 &len).
12922
12923 The forms with "nolen" in their names indicate they don't have a
12924 "len" parameter. They should be used only when it is known that
12925 the PV is a C string, terminated by a NUL byte, and without
12926 intermediate NUL characters; or when you don't care about its
12927 length.
12928
12929 The forms with "mutable" in their names are effectively the same as
12930 those without, but the name emphasizes that the string is
12931 modifiable by the caller, which it is in all the forms.
12932
12933 "SvPVutf8_force" is like "SvPV_force", but converts "sv" to UTF-8
12934 first if not already UTF-8.
12935
12936 "SvPVutf8x_force" is like "SvPVutf8_force", but guarantees to
12937 evaluate "sv" only once; use the more efficient "SvPVutf8_force"
12938 otherwise.
12939
12940 "SvPVbyte_force" is like "SvPV_force", but converts "sv" to byte
12941 representation first if currently encoded as UTF-8. If the SV
12942 cannot be downgraded from UTF-8, this croaks.
12943
12944 "SvPVbytex_force" is like "SvPVbyte_force", but guarantees to
12945 evaluate "sv" only once; use the more efficient "SvPVbyte_force"
12946 otherwise.
12947
12948 char* SvPV_force (SV* sv, STRLEN len)
12949 char* SvPV_force_nolen (SV* sv)
12950 char* SvPVx_force (SV* sv, STRLEN len)
12951 char* SvPV_force_nomg (SV* sv, STRLEN len)
12952 char* SvPV_force_nomg_nolen (SV * sv)
12953 char* SvPV_force_mutable (SV * sv, STRLEN len)
12954 char* SvPV_force_flags (SV * sv, STRLEN len, U32 flags)
12955 char* SvPV_force_flags_nolen (SV * sv, U32 flags)
12956 char* SvPV_force_flags_mutable(SV * sv, STRLEN len, U32 flags)
12957 char* SvPVbyte_force (SV* sv, STRLEN len)
12958 char* SvPVbytex_force (SV* sv, STRLEN len)
12959 char* SvPVutf8_force (SV* sv, STRLEN len)
12960 char* SvPVutf8x_force (SV* sv, STRLEN len)
12961
12962 "SvPV_free"
12963 Frees the PV buffer in "sv", leaving things in a precarious state,
12964 so should only be used as part of a larger operation
12965
12966 void SvPV_free(SV * sv)
12967
12968 "sv_pvn_force_flags"
12969 Get a sensible string out of the SV somehow. If "flags" has the
12970 "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate, else
12971 not. "sv_pvn_force" and "sv_pvn_force_nomg" are implemented in
12972 terms of this function. You normally want to use the various
12973 wrapper macros instead: see "SvPV_force" and "SvPV_force_nomg".
12974
12975 char* sv_pvn_force_flags(SV *const sv, STRLEN *const lp,
12976 const U32 flags)
12977
12978 "SvPV_renew"
12979 Low level micro optimization of "SvGROW". It is generally better
12980 to use "SvGROW" instead. This is because "SvPV_renew" ignores
12981 potential issues that "SvGROW" handles. "sv" needs to have a real
12982 "PV" that is unencombered by things like COW. Using
12983 "SV_CHECK_THINKFIRST" or "SV_CHECK_THINKFIRST_COW_DROP" before
12984 calling this should clean it up, but why not just use "SvGROW" if
12985 you're not sure about the provenance?
12986
12987 void SvPV_renew(SV* sv, STRLEN len)
12988
12989 "SvPV_set"
12990 This is probably not what you want to use, you probably wanted
12991 "sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
12992
12993 Set the value of the PV pointer in "sv" to the Perl allocated
12994 "NUL"-terminated string "val". See also "SvIV_set".
12995
12996 Remember to free the previous PV buffer. There are many things to
12997 check. Beware that the existing pointer may be involved in copy-
12998 on-write or other mischief, so do "SvOOK_off(sv)" and use
12999 "sv_force_normal" or "SvPV_force" (or check the "SvIsCOW" flag)
13000 first to make sure this modification is safe. Then finally, if it
13001 is not a COW, call "SvPV_free" to free the previous PV buffer.
13002
13003 void SvPV_set(SV* sv, char* val)
13004
13005 "SvPVutf8"
13006 Like "SvPV", but converts "sv" to UTF-8 first if necessary.
13007
13008 char* SvPVutf8(SV* sv, STRLEN len)
13009
13010 "SvPVutf8_force"
13011 Like "SvPV_force", but converts "sv" to UTF-8 first if necessary.
13012
13013 char* SvPVutf8_force(SV* sv, STRLEN len)
13014
13015 "SvPVutf8_nolen"
13016 Like "SvPV_nolen", but converts "sv" to UTF-8 first if necessary.
13017
13018 char* SvPVutf8_nolen(SV* sv)
13019
13020 "SvPVutf8_nomg"
13021 Like "SvPVutf8", but does not process get magic.
13022
13023 char* SvPVutf8_nomg(SV* sv, STRLEN len)
13024
13025 "SvPVutf8_or_null"
13026 Like "SvPVutf8", but when "sv" is undef, returns "NULL".
13027
13028 char* SvPVutf8_or_null(SV* sv, STRLEN len)
13029
13030 "SvPVutf8_or_null_nomg"
13031 Like "SvPVutf8_or_null", but does not process get magic.
13032
13033 char* SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
13034
13035 "SvPVX"
13036 "SvPVXx"
13037 "SvPVX_const"
13038 "SvPVX_mutable"
13039 These return a pointer to the physical string in the SV. The SV
13040 must contain a string. Prior to 5.9.3 it is not safe to execute
13041 these unless the SV's type >= "SVt_PV".
13042
13043 These are also used to store the name of an autoloaded subroutine
13044 in an XS AUTOLOAD routine. See "Autoloading with XSUBs" in
13045 perlguts.
13046
13047 "SvPVXx" is identical to "SvPVX".
13048
13049 "SvPVX_mutable" is merely a synonym for "SvPVX", but its name
13050 emphasizes that the string is modifiable by the caller.
13051
13052 "SvPVX_const" differs in that the return value has been cast so
13053 that the compiler will complain if you were to try to modify the
13054 contents of the string, (unless you cast away const yourself).
13055
13056 char* SvPVX (SV* sv)
13057 char* SvPVXx (SV* sv)
13058 const char* SvPVX_const (SV* sv)
13059 char* SvPVX_mutable(SV* sv)
13060
13061 "SvREADONLY"
13062 Returns true if the argument is readonly, otherwise returns false.
13063 Exposed to perl code via Internals::SvREADONLY().
13064
13065 U32 SvREADONLY(SV* sv)
13066
13067 "SvREADONLY_off"
13068 Mark an object as not-readonly. Exactly what this mean depends on
13069 the object type. Exposed to perl code via Internals::SvREADONLY().
13070
13071 U32 SvREADONLY_off(SV* sv)
13072
13073 "SvREADONLY_on"
13074 Mark an object as readonly. Exactly what this means depends on the
13075 object type. Exposed to perl code via Internals::SvREADONLY().
13076
13077 U32 SvREADONLY_on(SV* sv)
13078
13079 "sv_ref"
13080 Returns a SV describing what the SV passed in is a reference to.
13081
13082 dst can be a SV to be set to the description or NULL, in which case
13083 a mortal SV is returned.
13084
13085 If ob is true and the SV is blessed, the description is the class
13086 name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
13087
13088 SV* sv_ref(SV *dst, const SV *const sv, const int ob)
13089
13090 "SvREFCNT"
13091 Returns the value of the object's reference count. Exposed to perl
13092 code via Internals::SvREFCNT().
13093
13094 U32 SvREFCNT(SV* sv)
13095
13096 "SvREFCNT_dec"
13097 "SvREFCNT_dec_NN"
13098 These decrement the reference count of the given SV.
13099
13100 "SvREFCNT_dec_NN" may only be used when "sv" is known to not be
13101 "NULL".
13102
13103 void SvREFCNT_dec(SV *sv)
13104
13105 "SvREFCNT_inc"
13106 "SvREFCNT_inc_NN"
13107 "SvREFCNT_inc_void"
13108 "SvREFCNT_inc_void_NN"
13109 "SvREFCNT_inc_simple"
13110 "SvREFCNT_inc_simple_NN"
13111 "SvREFCNT_inc_simple_void"
13112 "SvREFCNT_inc_simple_void_NN"
13113 These all increment the reference count of the given SV. The ones
13114 without "void" in their names return the SV.
13115
13116 "SvREFCNT_inc" is the base operation; the rest are optimizations if
13117 various input constraints are known to be true; hence, all can be
13118 replaced with "SvREFCNT_inc".
13119
13120 "SvREFCNT_inc_NN" can only be used if you know "sv" is not "NULL".
13121 Since we don't have to check the NULLness, it's faster and smaller.
13122
13123 "SvREFCNT_inc_void" can only be used if you don't need the return
13124 value. The macro doesn't need to return a meaningful value.
13125
13126 "SvREFCNT_inc_void_NN" can only be used if you both don't need the
13127 return value, and you know that "sv" is not "NULL". The macro
13128 doesn't need to return a meaningful value, or check for NULLness,
13129 so it's smaller and faster.
13130
13131 "SvREFCNT_inc_simple" can only be used with expressions without
13132 side effects. Since we don't have to store a temporary value, it's
13133 faster.
13134
13135 "SvREFCNT_inc_simple_NN" can only be used with expressions without
13136 side effects and you know "sv" is not "NULL". Since we don't have
13137 to store a temporary value, nor check for NULLness, it's faster and
13138 smaller.
13139
13140 "SvREFCNT_inc_simple_void" can only be used with expressions
13141 without side effects and you don't need the return value.
13142
13143 "SvREFCNT_inc_simple_void_NN" can only be used with expressions
13144 without side effects, you don't need the return value, and you know
13145 "sv" is not "NULL".
13146
13147 SV * SvREFCNT_inc (SV *sv)
13148 SV * SvREFCNT_inc_NN (SV *sv)
13149 void SvREFCNT_inc_void (SV *sv)
13150 void SvREFCNT_inc_void_NN (SV* sv)
13151 SV* SvREFCNT_inc_simple (SV* sv)
13152 SV* SvREFCNT_inc_simple_NN (SV* sv)
13153 void SvREFCNT_inc_simple_void (SV* sv)
13154 void SvREFCNT_inc_simple_void_NN(SV* sv)
13155
13156 "sv_reftype"
13157 Returns a string describing what the SV is a reference to.
13158
13159 If ob is true and the SV is blessed, the string is the class name,
13160 otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
13161
13162 const char* sv_reftype(const SV *const sv, const int ob)
13163
13164 "sv_replace"
13165 Make the first argument a copy of the second, then delete the
13166 original. The target SV physically takes over ownership of the
13167 body of the source SV and inherits its flags; however, the target
13168 keeps any magic it owns, and any magic in the source is discarded.
13169 Note that this is a rather specialist SV copying operation; most of
13170 the time you'll want to use "sv_setsv" or one of its many macro
13171 front-ends.
13172
13173 void sv_replace(SV *const sv, SV *const nsv)
13174
13175 "sv_report_used"
13176 Dump the contents of all SVs not yet freed (debugging aid).
13177
13178 void sv_report_used()
13179
13180 "sv_reset"
13181 Underlying implementation for the "reset" Perl function. Note that
13182 the perl-level function is vaguely deprecated.
13183
13184 void sv_reset(const char* s, HV *const stash)
13185
13186 "SvROK"
13187 Tests if the SV is an RV.
13188
13189 U32 SvROK(SV* sv)
13190
13191 "SvROK_off"
13192 Unsets the RV status of an SV.
13193
13194 void SvROK_off(SV* sv)
13195
13196 "SvROK_on"
13197 Tells an SV that it is an RV.
13198
13199 void SvROK_on(SV* sv)
13200
13201 "SvRV"
13202 Dereferences an RV to return the SV.
13203
13204 SV* SvRV(SV* sv)
13205
13206 "SvRV_set"
13207 Set the value of the RV pointer in "sv" to val. See "SvIV_set".
13208
13209 void SvRV_set(SV* sv, SV* val)
13210
13211 "sv_rvunweaken"
13212 Unweaken a reference: Clear the "SvWEAKREF" flag on this RV; remove
13213 the backreference to this RV from the array of backreferences
13214 associated with the target SV, increment the refcount of the
13215 target. Silently ignores "undef" and warns on non-weak references.
13216
13217 SV* sv_rvunweaken(SV *const sv)
13218
13219 "sv_rvweaken"
13220 Weaken a reference: set the "SvWEAKREF" flag on this RV; give the
13221 referred-to SV "PERL_MAGIC_backref" magic if it hasn't already; and
13222 push a back-reference to this RV onto the array of backreferences
13223 associated with that magic. If the RV is magical, set magic will
13224 be called after the RV is cleared. Silently ignores "undef" and
13225 warns on already-weak references.
13226
13227 SV* sv_rvweaken(SV *const sv)
13228
13229 "sv_setiv"
13230 "sv_setiv_mg"
13231 These copy an integer into the given SV, upgrading first if
13232 necessary.
13233
13234 They differ only in that "sv_setiv_mg" handles 'set' magic;
13235 "sv_setiv" does not.
13236
13237 void sv_setiv (SV *const sv, const IV num)
13238 void sv_setiv_mg(SV *const sv, const IV i)
13239
13240 "SvSETMAGIC"
13241 Invokes "mg_set" on an SV if it has 'set' magic. This is necessary
13242 after modifying a scalar, in case it is a magical variable like $|
13243 or a tied variable (it calls "STORE"). This macro evaluates its
13244 argument more than once.
13245
13246 void SvSETMAGIC(SV* sv)
13247
13248 "sv_setnv"
13249 "sv_setnv_mg"
13250 These copy a double into the given SV, upgrading first if
13251 necessary.
13252
13253 They differ only in that "sv_setnv_mg" handles 'set' magic;
13254 "sv_setnv" does not.
13255
13256 void sv_setnv(SV *const sv, const NV num)
13257
13258 "sv_setpv"
13259 "sv_setpv_mg"
13260 These copy a string into an SV. The string must be terminated with
13261 a "NUL" character, and not contain embeded "NUL"'s.
13262
13263 They differ only in that:
13264
13265 "sv_setpv" does not handle 'set' magic; "sv_setpv_mg" does.
13266
13267 void sv_setpv(SV *const sv, const char *const ptr)
13268
13269 "sv_setpvf"
13270 "sv_setpvf_nocontext"
13271 "sv_setpvf_mg"
13272 "sv_setpvf_mg_nocontext"
13273 These work like "sv_catpvf" but copy the text into the SV instead
13274 of appending it.
13275
13276 The differences between these are:
13277
13278 "sv_setpvf" and "sv_setpvf_nocontext" do not handle 'set' magic;
13279 "sv_setpvf_mg" and "sv_setpvf_mg_nocontext" do.
13280
13281 "sv_setpvf_nocontext" and "sv_setpvf_mg_nocontext" do not take a
13282 thread context ("aTHX") parameter, so are used in situations where
13283 the caller doesn't already have the thread context.
13284
13285 NOTE: "sv_setpvf" must be explicitly called as "Perl_sv_setpvf"
13286 with an "aTHX_" parameter.
13287
13288 NOTE: "sv_setpvf_mg" must be explicitly called as
13289 "Perl_sv_setpvf_mg" with an "aTHX_" parameter.
13290
13291 void Perl_sv_setpvf (pTHX_ SV *const sv,
13292 const char *const pat, ...)
13293 void sv_setpvf_nocontext (SV *const sv, const char *const pat,
13294 ...)
13295 void Perl_sv_setpvf_mg (pTHX_ SV *const sv,
13296 const char *const pat, ...)
13297 void sv_setpvf_mg_nocontext(SV *const sv, const char *const pat,
13298 ...)
13299
13300 "sv_setpviv"
13301 "sv_setpviv_mg"
13302 "DEPRECATED!" It is planned to remove "sv_setpviv" from a future
13303 release of Perl. Do not use it for new code; remove it from
13304 existing code.
13305
13306 "DEPRECATED!" It is planned to remove "sv_setpviv_mg" from a
13307 future release of Perl. Do not use it for new code; remove it from
13308 existing code.
13309
13310 These copy an integer into the given SV, also updating its string
13311 value.
13312
13313 They differ only in that "sv_setpviv_mg" performs 'set' magic;
13314 "sv_setpviv" skips any magic.
13315
13316 void sv_setpviv (SV *const sv, const IV num)
13317 void sv_setpviv_mg(SV *const sv, const IV iv)
13318
13319 "sv_setpvn"
13320 "sv_setpvn_mg"
13321 These copy a string (possibly containing embedded "NUL" characters)
13322 into an SV. The "len" parameter indicates the number of bytes to
13323 be copied. If the "ptr" argument is NULL the SV will become
13324 undefined.
13325
13326 The UTF-8 flag is not changed by these functions. A terminating
13327 NUL byte is guaranteed.
13328
13329 They differ only in that:
13330
13331 "sv_setpvn" does not handle 'set' magic; "sv_setpvn_mg" does.
13332
13333 void sv_setpvn(SV *const sv, const char *const ptr,
13334 const STRLEN len)
13335
13336 "sv_setpvs"
13337 Like "sv_setpvn", but takes a literal string instead of a
13338 string/length pair.
13339
13340 void sv_setpvs(SV* sv, "literal string")
13341
13342 "sv_setpvs_mg"
13343 Like "sv_setpvn_mg", but takes a literal string instead of a
13344 string/length pair.
13345
13346 void sv_setpvs_mg(SV* sv, "literal string")
13347
13348 "sv_setpv_bufsize"
13349 Sets the SV to be a string of cur bytes length, with at least len
13350 bytes available. Ensures that there is a null byte at SvEND.
13351 Returns a char * pointer to the SvPV buffer.
13352
13353 char * sv_setpv_bufsize(SV *const sv, const STRLEN cur,
13354 const STRLEN len)
13355
13356 "sv_setref_iv"
13357 Copies an integer into a new SV, optionally blessing the SV. The
13358 "rv" argument will be upgraded to an RV. That RV will be modified
13359 to point to the new SV. The "classname" argument indicates the
13360 package for the blessing. Set "classname" to "NULL" to avoid the
13361 blessing. The new SV will have a reference count of 1, and the RV
13362 will be returned.
13363
13364 SV* sv_setref_iv(SV *const rv, const char *const classname,
13365 const IV iv)
13366
13367 "sv_setref_nv"
13368 Copies a double into a new SV, optionally blessing the SV. The
13369 "rv" argument will be upgraded to an RV. That RV will be modified
13370 to point to the new SV. The "classname" argument indicates the
13371 package for the blessing. Set "classname" to "NULL" to avoid the
13372 blessing. The new SV will have a reference count of 1, and the RV
13373 will be returned.
13374
13375 SV* sv_setref_nv(SV *const rv, const char *const classname,
13376 const NV nv)
13377
13378 "sv_setref_pv"
13379 Copies a pointer into a new SV, optionally blessing the SV. The
13380 "rv" argument will be upgraded to an RV. That RV will be modified
13381 to point to the new SV. If the "pv" argument is "NULL", then
13382 "PL_sv_undef" will be placed into the SV. The "classname" argument
13383 indicates the package for the blessing. Set "classname" to "NULL"
13384 to avoid the blessing. The new SV will have a reference count of
13385 1, and the RV will be returned.
13386
13387 Do not use with other Perl types such as HV, AV, SV, CV, because
13388 those objects will become corrupted by the pointer copy process.
13389
13390 Note that "sv_setref_pvn" copies the string while this copies the
13391 pointer.
13392
13393 SV* sv_setref_pv(SV *const rv, const char *const classname,
13394 void *const pv)
13395
13396 "sv_setref_pvn"
13397 Copies a string into a new SV, optionally blessing the SV. The
13398 length of the string must be specified with "n". The "rv" argument
13399 will be upgraded to an RV. That RV will be modified to point to
13400 the new SV. The "classname" argument indicates the package for the
13401 blessing. Set "classname" to "NULL" to avoid the blessing. The
13402 new SV will have a reference count of 1, and the RV will be
13403 returned.
13404
13405 Note that "sv_setref_pv" copies the pointer while this copies the
13406 string.
13407
13408 SV* sv_setref_pvn(SV *const rv, const char *const classname,
13409 const char *const pv, const STRLEN n)
13410
13411 "sv_setref_pvs"
13412 Like "sv_setref_pvn", but takes a literal string instead of a
13413 string/length pair.
13414
13415 SV * sv_setref_pvs(SV *const rv, const char *const classname,
13416 "literal string")
13417
13418 "sv_setref_uv"
13419 Copies an unsigned integer into a new SV, optionally blessing the
13420 SV. The "rv" argument will be upgraded to an RV. That RV will be
13421 modified to point to the new SV. The "classname" argument
13422 indicates the package for the blessing. Set "classname" to "NULL"
13423 to avoid the blessing. The new SV will have a reference count of
13424 1, and the RV will be returned.
13425
13426 SV* sv_setref_uv(SV *const rv, const char *const classname,
13427 const UV uv)
13428
13429 "SvSetSV"
13430 "SvSetMagicSV"
13431 "SvSetSV_nosteal"
13432 "SvSetMagicSV_nosteal"
13433 if "dsv" is the same as "ssv", these do nothing. Otherwise they
13434 all call some form of "sv_setsv". They may evaluate their
13435 arguments more than once.
13436
13437 The only differences are:
13438
13439 "SvSetMagicSV" and "SvSetMagicSV_nosteal" perform any required
13440 'set' magic afterwards on the destination SV; "SvSetSV" and
13441 "SvSetSV_nosteal" do not.
13442
13443 "SvSetSV_nosteal" "SvSetMagicSV_nosteal" call a non-destructive
13444 version of "sv_setsv".
13445
13446 void SvSetSV(SV* dsv, SV* ssv)
13447
13448 "sv_setsv"
13449 "sv_setsv_flags"
13450 "sv_setsv_mg"
13451 "sv_setsv_nomg"
13452 These copy the contents of the source SV "ssv" into the destination
13453 SV "dsv". "ssv" may be destroyed if it is mortal, so don't use
13454 these functions if the source SV needs to be reused. Loosely
13455 speaking, they perform a copy-by-value, obliterating any previous
13456 content of the destination.
13457
13458 They differ only in that:
13459
13460 "sv_setsv" calls 'get' magic on "ssv", but skips 'set' magic on
13461 "dsv".
13462
13463 "sv_setsv_mg" calls both 'get' magic on "ssv" and 'set' magic on
13464 "dsv".
13465
13466 "sv_setsv_nomg" skips all magic.
13467
13468 "sv_setsv_flags" has a "flags" parameter which you can use to
13469 specify any combination of magic handling, and also you can specify
13470 "SV_NOSTEAL" so that the buffers of temps will not be stolen.
13471
13472 You probably want to instead use one of the assortment of wrappers,
13473 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
13474 "SvSetMagicSV_nosteal".
13475
13476 "sv_setsv_flags" is the primary function for copying scalars, and
13477 most other copy-ish functions and macros use it underneath.
13478
13479 void sv_setsv (SV *dsv, SV *ssv)
13480 void sv_setsv_flags(SV *dsv, SV *ssv, const I32 flags)
13481 void sv_setsv_mg (SV *const dsv, SV *const ssv)
13482 void sv_setsv_nomg (SV *dsv, SV *ssv)
13483
13484 "sv_setuv"
13485 "sv_setuv_mg"
13486 These copy an unsigned integer into the given SV, upgrading first
13487 if necessary.
13488
13489 They differ only in that "sv_setuv_mg" handles 'set' magic;
13490 "sv_setuv" does not.
13491
13492 void sv_setuv (SV *const sv, const UV num)
13493 void sv_setuv_mg(SV *const sv, const UV u)
13494
13495 "sv_set_undef"
13496 Equivalent to "sv_setsv(sv, &PL_sv_undef)", but more efficient.
13497 Doesn't handle set magic.
13498
13499 The perl equivalent is "$sv = undef;". Note that it doesn't free
13500 any string buffer, unlike "undef $sv".
13501
13502 Introduced in perl 5.25.12.
13503
13504 void sv_set_undef(SV *sv)
13505
13506 "SvSHARE"
13507 Arranges for "sv" to be shared between threads if a suitable module
13508 has been loaded.
13509
13510 void SvSHARE(SV* sv)
13511
13512 "SvSHARED_HASH"
13513 Returns the hash for "sv" created by "newSVpvn_share".
13514
13515 struct hek* SvSHARED_HASH(SV * sv)
13516
13517 "SvSTASH"
13518 Returns the stash of the SV.
13519
13520 HV* SvSTASH(SV* sv)
13521
13522 "SvSTASH_set"
13523 Set the value of the STASH pointer in "sv" to val. See "SvIV_set".
13524
13525 void SvSTASH_set(SV* sv, HV* val)
13526
13527 "SvTAINT"
13528 Taints an SV if tainting is enabled, and if some input to the
13529 current expression is tainted--usually a variable, but possibly
13530 also implicit inputs such as locale settings. "SvTAINT" propagates
13531 that taintedness to the outputs of an expression in a pessimistic
13532 fashion; i.e., without paying attention to precisely which outputs
13533 are influenced by which inputs.
13534
13535 void SvTAINT(SV* sv)
13536
13537 "SvTAINTED"
13538 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
13539 not.
13540
13541 bool SvTAINTED(SV* sv)
13542
13543 "SvTAINTED_off"
13544 Untaints an SV. Be very careful with this routine, as it short-
13545 circuits some of Perl's fundamental security features. XS module
13546 authors should not use this function unless they fully understand
13547 all the implications of unconditionally untainting the value.
13548 Untainting should be done in the standard perl fashion, via a
13549 carefully crafted regexp, rather than directly untainting
13550 variables.
13551
13552 void SvTAINTED_off(SV* sv)
13553
13554 "SvTAINTED_on"
13555 Marks an SV as tainted if tainting is enabled.
13556
13557 void SvTAINTED_on(SV* sv)
13558
13559 "SvTRUE"
13560 "SvTRUEx"
13561 "SvTRUE_nomg"
13562 "SvTRUE_NN"
13563 "SvTRUE_nomg_NN"
13564 These return a boolean indicating whether Perl would evaluate the
13565 SV as true or false. See "SvOK" for a defined/undefined test.
13566
13567 As of Perl 5.32, all are guaranteed to evaluate "sv" only once.
13568 Prior to that release, only "SvTRUEx" guaranteed single evaluation;
13569 now "SvTRUEx" is identical to "SvTRUE".
13570
13571 "SvTRUE_nomg" and "TRUE_nomg_NN" do not perform 'get' magic; the
13572 others do unless the scalar is already "SvPOK", "SvIOK", or "SvNOK"
13573 (the public, not the private flags).
13574
13575 "SvTRUE_NN" is like "SvTRUE", but "sv" is assumed to be non-null
13576 (NN). If there is a possibility that it is NULL, use plain
13577 "SvTRUE".
13578
13579 "SvTRUE_nomg_NN" is like "SvTRUE_nomg", but "sv" is assumed to be
13580 non-null (NN). If there is a possibility that it is NULL, use
13581 plain "SvTRUE_nomg".
13582
13583 bool SvTRUE(SV *sv)
13584
13585 "SvTYPE"
13586 Returns the type of the SV. See "svtype".
13587
13588 svtype SvTYPE(SV* sv)
13589
13590 "SvUNLOCK"
13591 Releases a mutual exclusion lock on "sv" if a suitable module has
13592 been loaded.
13593
13594 void SvUNLOCK(SV* sv)
13595
13596 "sv_unmagic"
13597 Removes all magic of type "type" from an SV.
13598
13599 int sv_unmagic(SV *const sv, const int type)
13600
13601 "sv_unmagicext"
13602 Removes all magic of type "type" with the specified "vtbl" from an
13603 SV.
13604
13605 int sv_unmagicext(SV *const sv, const int type, MGVTBL *vtbl)
13606
13607 "sv_unref"
13608 Unsets the RV status of the SV, and decrements the reference count
13609 of whatever was being referenced by the RV. This can almost be
13610 thought of as a reversal of "newSVrv". This is "sv_unref_flags"
13611 with the "flag" being zero. See "SvROK_off".
13612
13613 void sv_unref(SV* sv)
13614
13615 "sv_unref_flags"
13616 Unsets the RV status of the SV, and decrements the reference count
13617 of whatever was being referenced by the RV. This can almost be
13618 thought of as a reversal of "newSVrv". The "cflags" argument can
13619 contain "SV_IMMEDIATE_UNREF" to force the reference count to be
13620 decremented (otherwise the decrementing is conditional on the
13621 reference count being different from one or the reference being a
13622 readonly SV). See "SvROK_off".
13623
13624 void sv_unref_flags(SV *const ref, const U32 flags)
13625
13626 "SvUOK"
13627 Returns a boolean indicating whether the SV contains an integer
13628 that must be interpreted as unsigned. A non-negative integer whose
13629 value is within the range of both an IV and a UV may be flagged as
13630 either "SvUOK" or "SvIOK".
13631
13632 bool SvUOK(SV* sv)
13633
13634 "SvUPGRADE"
13635 Used to upgrade an SV to a more complex form. Uses "sv_upgrade" to
13636 perform the upgrade if necessary. See "svtype".
13637
13638 void SvUPGRADE(SV* sv, svtype type)
13639
13640 "sv_upgrade"
13641 Upgrade an SV to a more complex form. Generally adds a new body
13642 type to the SV, then copies across as much information as possible
13643 from the old body. It croaks if the SV is already in a more
13644 complex form than requested. You generally want to use the
13645 "SvUPGRADE" macro wrapper, which checks the type before calling
13646 "sv_upgrade", and hence does not croak. See also "svtype".
13647
13648 void sv_upgrade(SV *const sv, svtype new_type)
13649
13650 "sv_usepvn"
13651 Tells an SV to use "ptr" to find its string value. Implemented by
13652 calling "sv_usepvn_flags" with "flags" of 0, hence does not handle
13653 'set' magic. See "sv_usepvn_flags".
13654
13655 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
13656
13657 "sv_usepvn_flags"
13658 Tells an SV to use "ptr" to find its string value. Normally the
13659 string is stored inside the SV, but sv_usepvn allows the SV to use
13660 an outside string. "ptr" should point to memory that was allocated
13661 by "Newx". It must be the start of a "Newx"-ed block of memory,
13662 and not a pointer to the middle of it (beware of "OOK" and copy-on-
13663 write), and not be from a non-"Newx" memory allocator like
13664 "malloc". The string length, "len", must be supplied. By default
13665 this function will "Renew" (i.e. realloc, move) the memory pointed
13666 to by "ptr", so that pointer should not be freed or used by the
13667 programmer after giving it to "sv_usepvn", and neither should any
13668 pointers from "behind" that pointer (e.g. ptr + 1) be used.
13669
13670 If "flags & SV_SMAGIC" is true, will call "SvSETMAGIC". If
13671 "flags & SV_HAS_TRAILING_NUL" is true, then "ptr[len]" must be
13672 "NUL", and the realloc will be skipped (i.e. the buffer is actually
13673 at least 1 byte longer than "len", and already meets the
13674 requirements for storing in "SvPVX").
13675
13676 void sv_usepvn_flags(SV *const sv, char* ptr, const STRLEN len,
13677 const U32 flags)
13678
13679 "sv_usepvn_mg"
13680 Like "sv_usepvn", but also handles 'set' magic.
13681
13682 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
13683
13684 "SvUTF8"
13685 Returns a U32 value indicating the UTF-8 status of an SV. If
13686 things are set-up properly, this indicates whether or not the SV
13687 contains UTF-8 encoded data. You should use this after a call to
13688 "SvPV" or one of its variants, in case any call to string
13689 overloading updates the internal flag.
13690
13691 If you want to take into account the bytes pragma, use "DO_UTF8"
13692 instead.
13693
13694 U32 SvUTF8(SV* sv)
13695
13696 "sv_utf8_decode"
13697 If the PV of the SV is an octet sequence in Perl's extended UTF-8
13698 and contains a multiple-byte character, the "SvUTF8" flag is turned
13699 on so that it looks like a character. If the PV contains only
13700 single-byte characters, the "SvUTF8" flag stays off. Scans PV for
13701 validity and returns FALSE if the PV is invalid UTF-8.
13702
13703 bool sv_utf8_decode(SV *const sv)
13704
13705 "sv_utf8_downgrade"
13706 "sv_utf8_downgrade_flags"
13707 "sv_utf8_downgrade_nomg"
13708 These attempt to convert the PV of an SV from characters to bytes.
13709 If the PV contains a character that cannot fit in a byte, this
13710 conversion will fail; in this case, "FALSE" is returned if
13711 "fail_ok" is true; otherwise they croak.
13712
13713 They are not a general purpose Unicode to byte encoding interface:
13714 use the "Encode" extension for that.
13715
13716 They differ only in that:
13717
13718 "sv_utf8_downgrade" processes 'get' magic on "sv".
13719
13720 "sv_utf8_downgrade_nomg" does not.
13721
13722 "sv_utf8_downgrade_flags" has an additional "flags" parameter in
13723 which you can specify "SV_GMAGIC" to process 'get' magic, or leave
13724 it cleared to not proccess 'get' magic.
13725
13726 bool sv_utf8_downgrade (SV *const sv, const bool fail_ok)
13727 bool sv_utf8_downgrade_flags(SV *const sv, const bool fail_ok,
13728 const U32 flags)
13729 bool sv_utf8_downgrade_nomg (SV *const sv, const bool fail_ok)
13730
13731 "sv_utf8_encode"
13732 Converts the PV of an SV to UTF-8, but then turns the "SvUTF8" flag
13733 off so that it looks like octets again.
13734
13735 void sv_utf8_encode(SV *const sv)
13736
13737 "sv_utf8_upgrade"
13738 "sv_utf8_upgrade_nomg"
13739 "sv_utf8_upgrade_flags"
13740 "sv_utf8_upgrade_flags_grow"
13741 These convert the PV of an SV to its UTF-8-encoded form. The SV is
13742 forced to string form if it is not already. They always set the
13743 "SvUTF8" flag to avoid future validity checks even if the whole
13744 string is the same in UTF-8 as not. They return the number of
13745 bytes in the converted string
13746
13747 The forms differ in just two ways. The main difference is whether
13748 or not they perform 'get magic' on "sv". "sv_utf8_upgrade_nomg"
13749 skips 'get magic'; "sv_utf8_upgrade" performs it; and
13750 "sv_utf8_upgrade_flags" and "sv_utf8_upgrade_flags_grow" either
13751 perform it (if the "SV_GMAGIC" bit is set in "flags") or don't (if
13752 that bit is cleared).
13753
13754 The other difference is that "sv_utf8_upgrade_flags_grow" has an
13755 additional parameter, "extra", which allows the caller to specify
13756 an amount of space to be reserved as spare beyond what is needed
13757 for the actual conversion. This is used when the caller knows it
13758 will soon be needing yet more space, and it is more efficient to
13759 request space from the system in a single call. This form is
13760 otherwise identical to "sv_utf8_upgrade_flags".
13761
13762 These are not a general purpose byte encoding to Unicode interface:
13763 use the Encode extension for that.
13764
13765 The "SV_FORCE_UTF8_UPGRADE" flag is now ignored.
13766
13767 STRLEN sv_utf8_upgrade (SV *sv)
13768 STRLEN sv_utf8_upgrade_nomg (SV *sv)
13769 STRLEN sv_utf8_upgrade_flags (SV *const sv, const I32 flags)
13770 STRLEN sv_utf8_upgrade_flags_grow(SV *const sv, const I32 flags,
13771 STRLEN extra)
13772
13773 "SvUTF8_off"
13774 Unsets the UTF-8 status of an SV (the data is not changed, just the
13775 flag). Do not use frivolously.
13776
13777 void SvUTF8_off(SV *sv)
13778
13779 "SvUTF8_on"
13780 Turn on the UTF-8 status of an SV (the data is not changed, just
13781 the flag). Do not use frivolously.
13782
13783 void SvUTF8_on(SV *sv)
13784
13785 "SvUV"
13786 "SvUVx"
13787 "SvUV_nomg"
13788 These coerce the given SV to UV and return it. The returned value
13789 in many circumstances will get stored in "sv"'s UV slot, but not in
13790 all cases. (Use "sv_setuv" to make sure it does).
13791
13792 "SvUVx" is different from the others in that it is guaranteed to
13793 evaluate "sv" exactly once; the others may evaluate it multiple
13794 times. Only use this form if "sv" is an expression with side
13795 effects, otherwise use the more efficient "SvUV".
13796
13797 "SvUV_nomg" is the same as "SvUV", but does not perform 'get'
13798 magic.
13799
13800 UV SvUV(SV* sv)
13801
13802 "SvUV_set"
13803 Set the value of the UV pointer in "sv" to val. See "SvIV_set".
13804
13805 void SvUV_set(SV* sv, UV val)
13806
13807 "SvUVX"
13808 Returns the raw value in the SV's UV slot, without checks or
13809 conversions. Only use when you are sure "SvIOK" is true. See also
13810 "SvUV".
13811
13812 UV SvUVX(SV* sv)
13813
13814 "SvUVXx"
13815 "DEPRECATED!" It is planned to remove "SvUVXx" from a future
13816 release of Perl. Do not use it for new code; remove it from
13817 existing code.
13818
13819 This is an unnecessary synonym for "SvUVX"
13820
13821 UV SvUVXx(SV* sv)
13822
13823 "sv_vcatpvf"
13824 "sv_vcatpvf_mg"
13825 These process their arguments like "sv_vcatpvfn" called with a non-
13826 null C-style variable argument list, and append the formatted
13827 output to "sv".
13828
13829 They differ only in that "sv_vcatpvf_mg" performs 'set' magic;
13830 "sv_vcatpvf" skips 'set' magic.
13831
13832 Both perform 'get' magic.
13833
13834 They are usually accessed via their frontends "sv_catpvf" and
13835 "sv_catpvf_mg".
13836
13837 void sv_vcatpvf(SV *const sv, const char *const pat,
13838 va_list *const args)
13839
13840 "sv_vcatpvfn"
13841 "sv_vcatpvfn_flags"
13842 These process their arguments like vsprintf(3) and append the
13843 formatted output to an SV. They use an array of SVs if the C-style
13844 variable argument list is missing ("NULL"). Argument reordering
13845 (using format specifiers like "%2$d" or "%*2$d") is supported only
13846 when using an array of SVs; using a C-style "va_list" argument list
13847 with a format string that uses argument reordering will yield an
13848 exception.
13849
13850 When running with taint checks enabled, they indicate via
13851 "maybe_tainted" if results are untrustworthy (often due to the use
13852 of locales).
13853
13854 They assume that "pat" has the same utf8-ness as "sv". It's the
13855 caller's responsibility to ensure that this is so.
13856
13857 They differ in that "sv_vcatpvfn_flags" has a "flags" parameter in
13858 which you can set or clear the "SV_GMAGIC" and/or SV_SMAGIC flags,
13859 to specify which magic to handle or not handle; whereas plain
13860 "sv_vcatpvfn" always specifies both 'get' and 'set' magic.
13861
13862 They are usually used via one of the frontends "sv_vcatpvf" and
13863 "sv_vcatpvf_mg".
13864
13865 void sv_vcatpvfn (SV *const sv, const char *const pat,
13866 const STRLEN patlen, va_list *const args,
13867 SV **const svargs, const Size_t sv_count,
13868 bool *const maybe_tainted)
13869 void sv_vcatpvfn_flags(SV *const sv, const char *const pat,
13870 const STRLEN patlen, va_list *const args,
13871 SV **const svargs, const Size_t sv_count,
13872 bool *const maybe_tainted,
13873 const U32 flags)
13874
13875 "SvVOK"
13876 Returns a boolean indicating whether the SV contains a v-string.
13877
13878 bool SvVOK(SV* sv)
13879
13880 "sv_vsetpvf"
13881 "sv_vsetpvf_mg"
13882 These work like "sv_vcatpvf" but copy the text into the SV instead
13883 of appending it.
13884
13885 They differ only in that "sv_vsetpvf_mg" performs 'set' magic;
13886 "sv_vsetpvf" skips all magic.
13887
13888 They are usually used via their frontends, "sv_setpvf" and
13889 "sv_setpvf_mg".
13890
13891 void sv_vsetpvf(SV *const sv, const char *const pat,
13892 va_list *const args)
13893
13894 "sv_vsetpvfn"
13895 Works like "sv_vcatpvfn" but copies the text into the SV instead of
13896 appending it.
13897
13898 Usually used via one of its frontends "sv_vsetpvf" and
13899 "sv_vsetpvf_mg".
13900
13901 void sv_vsetpvfn(SV *const sv, const char *const pat,
13902 const STRLEN patlen, va_list *const args,
13903 SV **const svargs, const Size_t sv_count,
13904 bool *const maybe_tainted)
13905
13906 "SvVSTRING_mg"
13907 Returns the vstring magic, or NULL if none
13908
13909 MAGIC* SvVSTRING_mg(SV * sv)
13910
13911 "vnewSVpvf"
13912 Like "newSVpvf" but but the arguments are an encapsulated argument
13913 list.
13914
13915 SV* vnewSVpvf(const char *const pat, va_list *const args)
13916
13918 "ASCTIME_R_PROTO"
13919 This symbol encodes the prototype of "asctime_r". It is zero if
13920 "d_asctime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
13921 macros of reentr.h if "d_asctime_r" is defined.
13922
13923 "CTIME_R_PROTO"
13924 This symbol encodes the prototype of "ctime_r". It is zero if
13925 "d_ctime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC" macros
13926 of reentr.h if "d_ctime_r" is defined.
13927
13928 "GMTIME_MAX"
13929 This symbol contains the maximum value for the "time_t" offset that
13930 the system function gmtime () accepts, and defaults to 0
13931
13932 "GMTIME_MIN"
13933 This symbol contains the minimum value for the "time_t" offset that
13934 the system function gmtime () accepts, and defaults to 0
13935
13936 "GMTIME_R_PROTO"
13937 This symbol encodes the prototype of "gmtime_r". It is zero if
13938 "d_gmtime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
13939 macros of reentr.h if "d_gmtime_r" is defined.
13940
13941 "HAS_ASCTIME64"
13942 This symbol, if defined, indicates that the "asctime64" () routine
13943 is available to do the 64bit variant of asctime ()
13944
13945 "HAS_ASCTIME_R"
13946 This symbol, if defined, indicates that the "asctime_r" routine is
13947 available to asctime re-entrantly.
13948
13949 "HAS_CTIME64"
13950 This symbol, if defined, indicates that the "ctime64" () routine is
13951 available to do the 64bit variant of ctime ()
13952
13953 "HAS_CTIME_R"
13954 This symbol, if defined, indicates that the "ctime_r" routine is
13955 available to ctime re-entrantly.
13956
13957 "HAS_DIFFTIME"
13958 This symbol, if defined, indicates that the "difftime" routine is
13959 available.
13960
13961 "HAS_DIFFTIME64"
13962 This symbol, if defined, indicates that the "difftime64" () routine
13963 is available to do the 64bit variant of difftime ()
13964
13965 "HAS_FUTIMES"
13966 This symbol, if defined, indicates that the "futimes" routine is
13967 available to change file descriptor time stamps with "struct
13968 timevals".
13969
13970 "HAS_GETITIMER"
13971 This symbol, if defined, indicates that the "getitimer" routine is
13972 available to return interval timers.
13973
13974 "HAS_GETTIMEOFDAY"
13975 This symbol, if defined, indicates that the "gettimeofday()" system
13976 call is available for a sub-second accuracy clock. Usually, the
13977 file sys/resource.h needs to be included (see "I_SYS_RESOURCE").
13978 The type "Timeval" should be used to refer to ""struct timeval"".
13979
13980 "HAS_GMTIME64"
13981 This symbol, if defined, indicates that the "gmtime64" () routine
13982 is available to do the 64bit variant of gmtime ()
13983
13984 "HAS_GMTIME_R"
13985 This symbol, if defined, indicates that the "gmtime_r" routine is
13986 available to gmtime re-entrantly.
13987
13988 "HAS_LOCALTIME64"
13989 This symbol, if defined, indicates that the "localtime64" ()
13990 routine is available to do the 64bit variant of localtime ()
13991
13992 "HAS_LOCALTIME_R"
13993 This symbol, if defined, indicates that the "localtime_r" routine
13994 is available to localtime re-entrantly.
13995
13996 "HAS_MKTIME"
13997 This symbol, if defined, indicates that the "mktime" routine is
13998 available.
13999
14000 "HAS_MKTIME64"
14001 This symbol, if defined, indicates that the "mktime64" () routine
14002 is available to do the 64bit variant of mktime ()
14003
14004 "HAS_NANOSLEEP"
14005 This symbol, if defined, indicates that the "nanosleep" system call
14006 is available to sleep with 1E-9 sec accuracy.
14007
14008 "HAS_SETITIMER"
14009 This symbol, if defined, indicates that the "setitimer" routine is
14010 available to set interval timers.
14011
14012 "HAS_STRFTIME"
14013 This symbol, if defined, indicates that the "strftime" routine is
14014 available to do time formatting.
14015
14016 "HAS_TIME"
14017 This symbol, if defined, indicates that the "time()" routine
14018 exists.
14019
14020 "HAS_TIMEGM"
14021 This symbol, if defined, indicates that the "timegm" routine is
14022 available to do the opposite of gmtime ()
14023
14024 "HAS_TIMES"
14025 This symbol, if defined, indicates that the "times()" routine
14026 exists. Note that this became obsolete on some systems ("SUNOS"),
14027 which now use "getrusage()". It may be necessary to include
14028 sys/times.h.
14029
14030 "HAS_TM_TM_GMTOFF"
14031 This symbol, if defined, indicates to the C program that the
14032 "struct tm" has a "tm_gmtoff" field.
14033
14034 "HAS_TM_TM_ZONE"
14035 This symbol, if defined, indicates to the C program that the
14036 "struct tm" has a "tm_zone" field.
14037
14038 "HAS_TZNAME"
14039 This symbol, if defined, indicates that the "tzname[]" array is
14040 available to access timezone names.
14041
14042 "HAS_USLEEP"
14043 This symbol, if defined, indicates that the "usleep" routine is
14044 available to let the process sleep on a sub-second accuracy.
14045
14046 "HAS_USLEEP_PROTO"
14047 This symbol, if defined, indicates that the system provides a
14048 prototype for the "usleep()" function. Otherwise, it is up to the
14049 program to supply one. A good guess is
14050
14051 extern int usleep(useconds_t);
14052
14053 "I_TIME"
14054 This symbol is always defined, and indicates to the C program that
14055 it should include time.h.
14056
14057 #ifdef I_TIME
14058 #include <time.h>
14059 #endif
14060
14061 "I_UTIME"
14062 This symbol, if defined, indicates to the C program that it should
14063 include utime.h.
14064
14065 #ifdef I_UTIME
14066 #include <utime.h>
14067 #endif
14068
14069 "LOCALTIME_MAX"
14070 This symbol contains the maximum value for the "time_t" offset that
14071 the system function localtime () accepts, and defaults to 0
14072
14073 "LOCALTIME_MIN"
14074 This symbol contains the minimum value for the "time_t" offset that
14075 the system function localtime () accepts, and defaults to 0
14076
14077 "LOCALTIME_R_NEEDS_TZSET"
14078 Many libc's "localtime_r" implementations do not call tzset, making
14079 them differ from "localtime()", and making timezone changes using
14080 $"ENV"{TZ} without explicitly calling tzset impossible. This symbol
14081 makes us call tzset before "localtime_r"
14082
14083 "LOCALTIME_R_PROTO"
14084 This symbol encodes the prototype of "localtime_r". It is zero if
14085 "d_localtime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
14086 macros of reentr.h if "d_localtime_r" is defined.
14087
14088 "L_R_TZSET"
14089 If "localtime_r()" needs tzset, it is defined in this define
14090
14091 "mini_mktime"
14092 normalise "struct tm" values without the localtime() semantics (and
14093 overhead) of mktime().
14094
14095 void mini_mktime(struct tm *ptm)
14096
14097 "my_strftime"
14098 strftime(), but with a different API so that the return value is a
14099 pointer to the formatted result (which MUST be arranged to be FREED
14100 BY THE CALLER). This allows this function to increase the buffer
14101 size as needed, so that the caller doesn't have to worry about
14102 that.
14103
14104 Note that yday and wday effectively are ignored by this function,
14105 as mini_mktime() overwrites them
14106
14107 Also note that this is always executed in the underlying locale of
14108 the program, giving localized results.
14109
14110 NOTE: "my_strftime" must be explicitly called as "Perl_my_strftime"
14111 with an "aTHX_" parameter.
14112
14113 char * Perl_my_strftime(pTHX_ const char *fmt, int sec, int min,
14114 int hour, int mday, int mon, int year,
14115 int wday, int yday, int isdst)
14116
14118 "DB_Hash_t"
14119 This symbol contains the type of the prefix structure element in
14120 the db.h header file. In older versions of DB, it was int, while
14121 in newer ones it is "size_t".
14122
14123 "DB_Prefix_t"
14124 This symbol contains the type of the prefix structure element in
14125 the db.h header file. In older versions of DB, it was int, while
14126 in newer ones it is "u_int32_t".
14127
14128 "Direntry_t"
14129 This symbol is set to '"struct direct"' or '"struct dirent"'
14130 depending on whether dirent is available or not. You should use
14131 this pseudo type to portably declare your directory entries.
14132
14133 "Fpos_t"
14134 This symbol holds the type used to declare file positions in libc.
14135 It can be "fpos_t", long, uint, etc... It may be necessary to
14136 include sys/types.h to get any typedef'ed information.
14137
14138 "Free_t"
14139 This variable contains the return type of "free()". It is usually
14140 void, but occasionally int.
14141
14142 "Gid_t"
14143 This symbol holds the return type of "getgid()" and the type of
14144 argument to "setrgid()" and related functions. Typically, it is
14145 the type of group ids in the kernel. It can be int, ushort,
14146 "gid_t", etc... It may be necessary to include sys/types.h to get
14147 any typedef'ed information.
14148
14149 "Gid_t_f"
14150 This symbol defines the format string used for printing a "Gid_t".
14151
14152 "Gid_t_sign"
14153 This symbol holds the signedness of a "Gid_t". 1 for unsigned, -1
14154 for signed.
14155
14156 "Gid_t_size"
14157 This symbol holds the size of a "Gid_t" in bytes.
14158
14159 "Groups_t"
14160 This symbol holds the type used for the second argument to
14161 "getgroups()" and "setgroups()". Usually, this is the same as
14162 gidtype ("gid_t") , but sometimes it isn't. It can be int, ushort,
14163 "gid_t", etc... It may be necessary to include sys/types.h to get
14164 any typedef'ed information. This is only required if you have
14165 "getgroups()" or "setgroups()"..
14166
14167 "Malloc_t"
14168 This symbol is the type of pointer returned by malloc and realloc.
14169
14170 "Mmap_t"
14171 This symbol holds the return type of the "mmap()" system call (and
14172 simultaneously the type of the first argument). Usually set to
14173 'void *' or '"caddr_t"'.
14174
14175 "Mode_t"
14176 This symbol holds the type used to declare file modes for systems
14177 calls. It is usually "mode_t", but may be int or unsigned short.
14178 It may be necessary to include sys/types.h to get any typedef'ed
14179 information.
14180
14181 "Netdb_hlen_t"
14182 This symbol holds the type used for the 2nd argument to
14183 "gethostbyaddr()".
14184
14185 "Netdb_host_t"
14186 This symbol holds the type used for the 1st argument to
14187 "gethostbyaddr()".
14188
14189 "Netdb_name_t"
14190 This symbol holds the type used for the argument to
14191 "gethostbyname()".
14192
14193 "Netdb_net_t"
14194 This symbol holds the type used for the 1st argument to
14195 "getnetbyaddr()".
14196
14197 "Off_t"
14198 This symbol holds the type used to declare offsets in the kernel.
14199 It can be int, long, "off_t", etc... It may be necessary to include
14200 sys/types.h to get any typedef'ed information.
14201
14202 "Off_t_size"
14203 This symbol holds the number of bytes used by the "Off_t".
14204
14205 "Pid_t"
14206 This symbol holds the type used to declare process ids in the
14207 kernel. It can be int, uint, "pid_t", etc... It may be necessary
14208 to include sys/types.h to get any typedef'ed information.
14209
14210 "Rand_seed_t"
14211 This symbol defines the type of the argument of the random seed
14212 function.
14213
14214 "Select_fd_set_t"
14215 This symbol holds the type used for the 2nd, 3rd, and 4th arguments
14216 to select. Usually, this is '"fd_set" *', if "HAS_FD_SET" is
14217 defined, and 'int *' otherwise. This is only useful if you have
14218 "select()", of course.
14219
14220 "Shmat_t"
14221 This symbol holds the return type of the "shmat()" system call.
14222 Usually set to 'void *' or 'char *'.
14223
14224 "Signal_t"
14225 This symbol's value is either "void" or "int", corresponding to the
14226 appropriate return type of a signal handler. Thus, you can declare
14227 a signal handler using ""Signal_t" (*handler)()", and define the
14228 handler using ""Signal_t" "handler(sig)"".
14229
14230 "Size_t"
14231 This symbol holds the type used to declare length parameters for
14232 string functions. It is usually "size_t", but may be unsigned
14233 long, int, etc. It may be necessary to include sys/types.h to get
14234 any typedef'ed information.
14235
14236 "Size_t_size"
14237 This symbol holds the size of a "Size_t" in bytes.
14238
14239 "Sock_size_t"
14240 This symbol holds the type used for the size argument of various
14241 socket calls (just the base type, not the pointer-to).
14242
14243 "SSize_t"
14244 This symbol holds the type used by functions that return a count of
14245 bytes or an error condition. It must be a signed type. It is
14246 usually "ssize_t", but may be long or int, etc. It may be
14247 necessary to include sys/types.h or unistd.h to get any typedef'ed
14248 information. We will pick a type such that "sizeof(SSize_t)" ==
14249 "sizeof(Size_t)".
14250
14251 "Time_t"
14252 This symbol holds the type returned by "time()". It can be long, or
14253 "time_t" on "BSD" sites (in which case sys/types.h should be
14254 included).
14255
14256 "Uid_t"
14257 This symbol holds the type used to declare user ids in the kernel.
14258 It can be int, ushort, "uid_t", etc... It may be necessary to
14259 include sys/types.h to get any typedef'ed information.
14260
14261 "Uid_t_f"
14262 This symbol defines the format string used for printing a "Uid_t".
14263
14264 "Uid_t_sign"
14265 This symbol holds the signedness of a "Uid_t". 1 for unsigned, -1
14266 for signed.
14267
14268 "Uid_t_size"
14269 This symbol holds the size of a "Uid_t" in bytes.
14270
14272 "Unicode Support" in perlguts has an introduction to this API.
14273
14274 See also "Character classification", "Character case changing", and
14275 "String Handling". Various functions outside this section also work
14276 specially with Unicode. Search for the string "utf8" in this document.
14277
14278 "BOM_UTF8"
14279 This is a macro that evaluates to a string constant of the UTF-8
14280 bytes that define the Unicode BYTE ORDER MARK (U+FEFF) for the
14281 platform that perl is compiled on. This allows code to use a
14282 mnemonic for this character that works on both ASCII and EBCDIC
14283 platforms. "sizeof(BOM_UTF8) - 1" can be used to get its length in
14284 bytes.
14285
14286 "bytes_cmp_utf8"
14287 Compares the sequence of characters (stored as octets) in "b",
14288 "blen" with the sequence of characters (stored as UTF-8) in "u",
14289 "ulen". Returns 0 if they are equal, -1 or -2 if the first string
14290 is less than the second string, +1 or +2 if the first string is
14291 greater than the second string.
14292
14293 -1 or +1 is returned if the shorter string was identical to the
14294 start of the longer string. -2 or +2 is returned if there was a
14295 difference between characters within the strings.
14296
14297 int bytes_cmp_utf8(const U8 *b, STRLEN blen, const U8 *u,
14298 STRLEN ulen)
14299
14300 "bytes_from_utf8"
14301 NOTE: "bytes_from_utf8" is experimental and may change or be
14302 removed without notice.
14303
14304 Converts a potentially UTF-8 encoded string "s" of length *lenp
14305 into native byte encoding. On input, the boolean *is_utf8p gives
14306 whether or not "s" is actually encoded in UTF-8.
14307
14308 Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-
14309 destructive of the input string.
14310
14311 Do nothing if *is_utf8p is 0, or if there are code points in the
14312 string not expressible in native byte encoding. In these cases,
14313 *is_utf8p and *lenp are unchanged, and the return value is the
14314 original "s".
14315
14316 Otherwise, *is_utf8p is set to 0, and the return value is a pointer
14317 to a newly created string containing a downgraded copy of "s", and
14318 whose length is returned in *lenp, updated. The new string is
14319 "NUL"-terminated. The caller is responsible for arranging for the
14320 memory used by this string to get freed.
14321
14322 Upon successful return, the number of variants in the string can be
14323 computed by having saved the value of *lenp before the call, and
14324 subtracting the after-call value of *lenp from it.
14325
14326 U8* bytes_from_utf8(const U8 *s, STRLEN *lenp, bool *is_utf8p)
14327
14328 "bytes_to_utf8"
14329 NOTE: "bytes_to_utf8" is experimental and may change or be removed
14330 without notice.
14331
14332 Converts a string "s" of length *lenp bytes from the native
14333 encoding into UTF-8. Returns a pointer to the newly-created
14334 string, and sets *lenp to reflect the new length in bytes. The
14335 caller is responsible for arranging for the memory used by this
14336 string to get freed.
14337
14338 Upon successful return, the number of variants in the string can be
14339 computed by having saved the value of *lenp before the call, and
14340 subtracting it from the after-call value of *lenp.
14341
14342 A "NUL" character will be written after the end of the string.
14343
14344 If you want to convert to UTF-8 from encodings other than the
14345 native (Latin1 or EBCDIC), see "sv_recode_to_utf8"().
14346
14347 U8* bytes_to_utf8(const U8 *s, STRLEN *lenp)
14348
14349 "DO_UTF8"
14350 Returns a bool giving whether or not the PV in "sv" is to be
14351 treated as being encoded in UTF-8.
14352
14353 You should use this after a call to "SvPV()" or one of its
14354 variants, in case any call to string overloading updates the
14355 internal UTF-8 encoding flag.
14356
14357 bool DO_UTF8(SV* sv)
14358
14359 "foldEQ_utf8"
14360 Returns true if the leading portions of the strings "s1" and "s2"
14361 (either or both of which may be in UTF-8) are the same case-
14362 insensitively; false otherwise. How far into the strings to
14363 compare is determined by other input parameters.
14364
14365 If "u1" is true, the string "s1" is assumed to be in UTF-8-encoded
14366 Unicode; otherwise it is assumed to be in native 8-bit encoding.
14367 Correspondingly for "u2" with respect to "s2".
14368
14369 If the byte length "l1" is non-zero, it says how far into "s1" to
14370 check for fold equality. In other words, "s1"+"l1" will be used as
14371 a goal to reach. The scan will not be considered to be a match
14372 unless the goal is reached, and scanning won't continue past that
14373 goal. Correspondingly for "l2" with respect to "s2".
14374
14375 If "pe1" is non-"NULL" and the pointer it points to is not "NULL",
14376 that pointer is considered an end pointer to the position 1 byte
14377 past the maximum point in "s1" beyond which scanning will not
14378 continue under any circumstances. (This routine assumes that UTF-8
14379 encoded input strings are not malformed; malformed input can cause
14380 it to read past "pe1"). This means that if both "l1" and "pe1" are
14381 specified, and "pe1" is less than "s1"+"l1", the match will never
14382 be successful because it can never get as far as its goal (and in
14383 fact is asserted against). Correspondingly for "pe2" with respect
14384 to "s2".
14385
14386 At least one of "s1" and "s2" must have a goal (at least one of
14387 "l1" and "l2" must be non-zero), and if both do, both have to be
14388 reached for a successful match. Also, if the fold of a character
14389 is multiple characters, all of them must be matched (see tr21
14390 reference below for 'folding').
14391
14392 Upon a successful match, if "pe1" is non-"NULL", it will be set to
14393 point to the beginning of the next character of "s1" beyond what
14394 was matched. Correspondingly for "pe2" and "s2".
14395
14396 For case-insensitiveness, the "casefolding" of Unicode is used
14397 instead of upper/lowercasing both the characters, see
14398 <https://www.unicode.org/unicode/reports/tr21/> (Case Mappings).
14399
14400 I32 foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1,
14401 const char *s2, char **pe2, UV l2, bool u2)
14402
14403 "is_ascii_string"
14404 This is a misleadingly-named synonym for
14405 "is_utf8_invariant_string". On ASCII-ish platforms, the name isn't
14406 misleading: the ASCII-range characters are exactly the UTF-8
14407 invariants. But EBCDIC machines have more invariants than just the
14408 ASCII characters, so "is_utf8_invariant_string" is preferred.
14409
14410 bool is_ascii_string(const U8* const s, STRLEN len)
14411
14412 "is_c9strict_utf8_string"
14413 Returns TRUE if the first "len" bytes of string "s" form a valid
14414 UTF-8-encoded string that conforms to Unicode Corrigendum #9
14415 <http://www.unicode.org/versions/corrigendum9.html>; otherwise it
14416 returns FALSE. If "len" is 0, it will be calculated using
14417 strlen(s) (which means if you use this option, that "s" can't have
14418 embedded "NUL" characters and has to have a terminating "NUL"
14419 byte). Note that all characters being ASCII constitute 'a valid
14420 UTF-8 string'.
14421
14422 This function returns FALSE for strings containing any code points
14423 above the Unicode max of 0x10FFFF or surrogate code points, but
14424 accepts non-character code points per Corrigendum #9
14425 <http://www.unicode.org/versions/corrigendum9.html>.
14426
14427 See also "is_utf8_invariant_string",
14428 "is_utf8_invariant_string_loc", "is_utf8_string",
14429 "is_utf8_string_flags", "is_utf8_string_loc",
14430 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
14431 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
14432 "is_utf8_fixed_width_buf_loc_flags",
14433 "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
14434 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
14435 "is_c9strict_utf8_string_loc", and
14436 "is_c9strict_utf8_string_loclen".
14437
14438 bool is_c9strict_utf8_string(const U8 *s, STRLEN len)
14439
14440 "is_c9strict_utf8_string_loc"
14441 Like "is_c9strict_utf8_string" but stores the location of the
14442 failure (in the case of "utf8ness failure") or the location
14443 "s"+"len" (in the case of "utf8ness success") in the "ep" pointer.
14444
14445 See also "is_c9strict_utf8_string_loclen".
14446
14447 bool is_c9strict_utf8_string_loc(const U8 *s, STRLEN len,
14448 const U8 **ep)
14449
14450 "is_c9strict_utf8_string_loclen"
14451 Like "is_c9strict_utf8_string" but stores the location of the
14452 failure (in the case of "utf8ness failure") or the location
14453 "s"+"len" (in the case of "utf8ness success") in the "ep" pointer,
14454 and the number of UTF-8 encoded characters in the "el" pointer.
14455
14456 See also "is_c9strict_utf8_string_loc".
14457
14458 bool is_c9strict_utf8_string_loclen(const U8 *s, STRLEN len,
14459 const U8 **ep, STRLEN *el)
14460
14461 "isC9_STRICT_UTF8_CHAR"
14462 Evaluates to non-zero if the first few bytes of the string starting
14463 at "s" and looking no further than "e - 1" are well-formed UTF-8
14464 that represents some Unicode non-surrogate code point; otherwise it
14465 evaluates to 0. If non-zero, the value gives how many bytes
14466 starting at "s" comprise the code point's representation. Any
14467 bytes remaining before "e", but beyond the ones needed to form the
14468 first code point in "s", are not examined.
14469
14470 The largest acceptable code point is the Unicode maximum 0x10FFFF.
14471 This differs from "isSTRICT_UTF8_CHAR" only in that it accepts non-
14472 character code points. This corresponds to Unicode Corrigendum #9
14473 <http://www.unicode.org/versions/corrigendum9.html>. which said
14474 that non-character code points are merely discouraged rather than
14475 completely forbidden in open interchange. See "Noncharacter code
14476 points" in perlunicode.
14477
14478 Use "isUTF8_CHAR" to check for Perl's extended UTF-8; and
14479 "isUTF8_CHAR_flags" for a more customized definition.
14480
14481 Use "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
14482 "is_c9strict_utf8_string_loclen" to check entire strings.
14483
14484 Size_t isC9_STRICT_UTF8_CHAR(const U8 * const s0,
14485 const U8 * const e)
14486
14487 "is_invariant_string"
14488 This is a somewhat misleadingly-named synonym for
14489 "is_utf8_invariant_string". "is_utf8_invariant_string" is
14490 preferred, as it indicates under what conditions the string is
14491 invariant.
14492
14493 bool is_invariant_string(const U8* const s, STRLEN len)
14494
14495 "isSTRICT_UTF8_CHAR"
14496 Evaluates to non-zero if the first few bytes of the string starting
14497 at "s" and looking no further than "e - 1" are well-formed UTF-8
14498 that represents some Unicode code point completely acceptable for
14499 open interchange between all applications; otherwise it evaluates
14500 to 0. If non-zero, the value gives how many bytes starting at "s"
14501 comprise the code point's representation. Any bytes remaining
14502 before "e", but beyond the ones needed to form the first code point
14503 in "s", are not examined.
14504
14505 The largest acceptable code point is the Unicode maximum 0x10FFFF,
14506 and must not be a surrogate nor a non-character code point. Thus
14507 this excludes any code point from Perl's extended UTF-8.
14508
14509 This is used to efficiently decide if the next few bytes in "s" is
14510 legal Unicode-acceptable UTF-8 for a single character.
14511
14512 Use "isC9_STRICT_UTF8_CHAR" to use the Unicode Corrigendum #9
14513 <http://www.unicode.org/versions/corrigendum9.html> definition of
14514 allowable code points; "isUTF8_CHAR" to check for Perl's extended
14515 UTF-8; and "isUTF8_CHAR_flags" for a more customized definition.
14516
14517 Use "is_strict_utf8_string", "is_strict_utf8_string_loc", and
14518 "is_strict_utf8_string_loclen" to check entire strings.
14519
14520 Size_t isSTRICT_UTF8_CHAR(const U8 * const s0,
14521 const U8 * const e)
14522
14523 "is_strict_utf8_string"
14524 Returns TRUE if the first "len" bytes of string "s" form a valid
14525 UTF-8-encoded string that is fully interchangeable by any
14526 application using Unicode rules; otherwise it returns FALSE. If
14527 "len" is 0, it will be calculated using strlen(s) (which means if
14528 you use this option, that "s" can't have embedded "NUL" characters
14529 and has to have a terminating "NUL" byte). Note that all
14530 characters being ASCII constitute 'a valid UTF-8 string'.
14531
14532 This function returns FALSE for strings containing any code points
14533 above the Unicode max of 0x10FFFF, surrogate code points, or non-
14534 character code points.
14535
14536 See also "is_utf8_invariant_string",
14537 "is_utf8_invariant_string_loc", "is_utf8_string",
14538 "is_utf8_string_flags", "is_utf8_string_loc",
14539 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
14540 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
14541 "is_utf8_fixed_width_buf_loc_flags",
14542 "is_utf8_fixed_width_buf_loclen_flags",
14543 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
14544 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
14545 "is_c9strict_utf8_string_loclen".
14546
14547 bool is_strict_utf8_string(const U8 *s, STRLEN len)
14548
14549 "is_strict_utf8_string_loc"
14550 Like "is_strict_utf8_string" but stores the location of the failure
14551 (in the case of "utf8ness failure") or the location "s"+"len" (in
14552 the case of "utf8ness success") in the "ep" pointer.
14553
14554 See also "is_strict_utf8_string_loclen".
14555
14556 bool is_strict_utf8_string_loc(const U8 *s, STRLEN len,
14557 const U8 **ep)
14558
14559 "is_strict_utf8_string_loclen"
14560 Like "is_strict_utf8_string" but stores the location of the failure
14561 (in the case of "utf8ness failure") or the location "s"+"len" (in
14562 the case of "utf8ness success") in the "ep" pointer, and the number
14563 of UTF-8 encoded characters in the "el" pointer.
14564
14565 See also "is_strict_utf8_string_loc".
14566
14567 bool is_strict_utf8_string_loclen(const U8 *s, STRLEN len,
14568 const U8 **ep, STRLEN *el)
14569
14570 "is_utf8_char"
14571 "DEPRECATED!" It is planned to remove "is_utf8_char" from a future
14572 release of Perl. Do not use it for new code; remove it from
14573 existing code.
14574
14575 Tests if some arbitrary number of bytes begins in a valid UTF-8
14576 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC
14577 machines) character is a valid UTF-8 character. The actual number
14578 of bytes in the UTF-8 character will be returned if it is valid,
14579 otherwise 0.
14580
14581 This function is deprecated due to the possibility that malformed
14582 input could cause reading beyond the end of the input buffer. Use
14583 "isUTF8_CHAR" instead.
14584
14585 STRLEN is_utf8_char(const U8 *s)
14586
14587 "is_utf8_char_buf"
14588 This is identical to the macro "isUTF8_CHAR" in perlapi.
14589
14590 STRLEN is_utf8_char_buf(const U8 *buf, const U8 *buf_end)
14591
14592 "is_utf8_fixed_width_buf_flags"
14593 Returns TRUE if the fixed-width buffer starting at "s" with length
14594 "len" is entirely valid UTF-8, subject to the restrictions given by
14595 "flags"; otherwise it returns FALSE.
14596
14597 If "flags" is 0, any well-formed UTF-8, as extended by Perl, is
14598 accepted without restriction. If the final few bytes of the buffer
14599 do not form a complete code point, this will return TRUE anyway,
14600 provided that "is_utf8_valid_partial_char_flags" returns TRUE for
14601 them.
14602
14603 If "flags" in non-zero, it can be any combination of the
14604 "UTF8_DISALLOW_foo" flags accepted by "utf8n_to_uvchr", and with
14605 the same meanings.
14606
14607 This function differs from "is_utf8_string_flags" only in that the
14608 latter returns FALSE if the final few bytes of the string don't
14609 form a complete code point.
14610
14611 bool is_utf8_fixed_width_buf_flags(const U8 * const s,
14612 STRLEN len, const U32 flags)
14613
14614 "is_utf8_fixed_width_buf_loclen_flags"
14615 Like "is_utf8_fixed_width_buf_loc_flags" but stores the number of
14616 complete, valid characters found in the "el" pointer.
14617
14618 bool is_utf8_fixed_width_buf_loclen_flags(const U8 * const s,
14619 STRLEN len,
14620 const U8 **ep,
14621 STRLEN *el,
14622 const U32 flags)
14623
14624 "is_utf8_fixed_width_buf_loc_flags"
14625 Like "is_utf8_fixed_width_buf_flags" but stores the location of the
14626 failure in the "ep" pointer. If the function returns TRUE, *ep
14627 will point to the beginning of any partial character at the end of
14628 the buffer; if there is no partial character *ep will contain
14629 "s"+"len".
14630
14631 See also "is_utf8_fixed_width_buf_loclen_flags".
14632
14633 bool is_utf8_fixed_width_buf_loc_flags(const U8 * const s,
14634 STRLEN len, const U8 **ep,
14635 const U32 flags)
14636
14637 "is_utf8_invariant_string"
14638 Returns TRUE if the first "len" bytes of the string "s" are the
14639 same regardless of the UTF-8 encoding of the string (or UTF-EBCDIC
14640 encoding on EBCDIC machines); otherwise it returns FALSE. That is,
14641 it returns TRUE if they are UTF-8 invariant. On ASCII-ish
14642 machines, all the ASCII characters and only the ASCII characters
14643 fit this definition. On EBCDIC machines, the ASCII-range
14644 characters are invariant, but so also are the C1 controls.
14645
14646 If "len" is 0, it will be calculated using strlen(s), (which means
14647 if you use this option, that "s" can't have embedded "NUL"
14648 characters and has to have a terminating "NUL" byte).
14649
14650 See also "is_utf8_string", "is_utf8_string_flags",
14651 "is_utf8_string_loc", "is_utf8_string_loc_flags",
14652 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
14653 "is_utf8_fixed_width_buf_flags",
14654 "is_utf8_fixed_width_buf_loc_flags",
14655 "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
14656 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
14657 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
14658 "is_c9strict_utf8_string_loclen".
14659
14660 bool is_utf8_invariant_string(const U8* const s, STRLEN len)
14661
14662 "is_utf8_invariant_string_loc"
14663 Like "is_utf8_invariant_string" but upon failure, stores the
14664 location of the first UTF-8 variant character in the "ep" pointer;
14665 if all characters are UTF-8 invariant, this function does not
14666 change the contents of *ep.
14667
14668 bool is_utf8_invariant_string_loc(const U8* const s, STRLEN len,
14669 const U8 ** ep)
14670
14671 "is_utf8_string"
14672 Returns TRUE if the first "len" bytes of string "s" form a valid
14673 Perl-extended-UTF-8 string; returns FALSE otherwise. If "len" is
14674 0, it will be calculated using strlen(s) (which means if you use
14675 this option, that "s" can't have embedded "NUL" characters and has
14676 to have a terminating "NUL" byte). Note that all characters being
14677 ASCII constitute 'a valid UTF-8 string'.
14678
14679 This function considers Perl's extended UTF-8 to be valid. That
14680 means that code points above Unicode, surrogates, and non-character
14681 code points are considered valid by this function. Use
14682 "is_strict_utf8_string", "is_c9strict_utf8_string", or
14683 "is_utf8_string_flags" to restrict what code points are considered
14684 valid.
14685
14686 See also "is_utf8_invariant_string",
14687 "is_utf8_invariant_string_loc", "is_utf8_string_loc",
14688 "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags",
14689 "is_utf8_fixed_width_buf_loc_flags",
14690 "is_utf8_fixed_width_buf_loclen_flags",
14691
14692 bool is_utf8_string(const U8 *s, STRLEN len)
14693
14694 "is_utf8_string_flags"
14695 Returns TRUE if the first "len" bytes of string "s" form a valid
14696 UTF-8 string, subject to the restrictions imposed by "flags";
14697 returns FALSE otherwise. If "len" is 0, it will be calculated
14698 using strlen(s) (which means if you use this option, that "s" can't
14699 have embedded "NUL" characters and has to have a terminating "NUL"
14700 byte). Note that all characters being ASCII constitute 'a valid
14701 UTF-8 string'.
14702
14703 If "flags" is 0, this gives the same results as "is_utf8_string";
14704 if "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the
14705 same results as "is_strict_utf8_string"; and if "flags" is
14706 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same results
14707 as "is_c9strict_utf8_string". Otherwise "flags" may be any
14708 combination of the "UTF8_DISALLOW_foo" flags understood by
14709 "utf8n_to_uvchr", with the same meanings.
14710
14711 See also "is_utf8_invariant_string",
14712 "is_utf8_invariant_string_loc", "is_utf8_string",
14713 "is_utf8_string_loc", "is_utf8_string_loc_flags",
14714 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
14715 "is_utf8_fixed_width_buf_flags",
14716 "is_utf8_fixed_width_buf_loc_flags",
14717 "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
14718 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
14719 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
14720 "is_c9strict_utf8_string_loclen".
14721
14722 bool is_utf8_string_flags(const U8 *s, STRLEN len,
14723 const U32 flags)
14724
14725 "is_utf8_string_loc"
14726 Like "is_utf8_string" but stores the location of the failure (in
14727 the case of "utf8ness failure") or the location "s"+"len" (in the
14728 case of "utf8ness success") in the "ep" pointer.
14729
14730 See also "is_utf8_string_loclen".
14731
14732 bool is_utf8_string_loc(const U8 *s, const STRLEN len,
14733 const U8 **ep)
14734
14735 "is_utf8_string_loclen"
14736 Like "is_utf8_string" but stores the location of the failure (in
14737 the case of "utf8ness failure") or the location "s"+"len" (in the
14738 case of "utf8ness success") in the "ep" pointer, and the number of
14739 UTF-8 encoded characters in the "el" pointer.
14740
14741 See also "is_utf8_string_loc".
14742
14743 bool is_utf8_string_loclen(const U8 *s, STRLEN len,
14744 const U8 **ep, STRLEN *el)
14745
14746 "is_utf8_string_loclen_flags"
14747 Like "is_utf8_string_flags" but stores the location of the failure
14748 (in the case of "utf8ness failure") or the location "s"+"len" (in
14749 the case of "utf8ness success") in the "ep" pointer, and the number
14750 of UTF-8 encoded characters in the "el" pointer.
14751
14752 See also "is_utf8_string_loc_flags".
14753
14754 bool is_utf8_string_loclen_flags(const U8 *s, STRLEN len,
14755 const U8 **ep, STRLEN *el,
14756 const U32 flags)
14757
14758 "is_utf8_string_loc_flags"
14759 Like "is_utf8_string_flags" but stores the location of the failure
14760 (in the case of "utf8ness failure") or the location "s"+"len" (in
14761 the case of "utf8ness success") in the "ep" pointer.
14762
14763 See also "is_utf8_string_loclen_flags".
14764
14765 bool is_utf8_string_loc_flags(const U8 *s, STRLEN len,
14766 const U8 **ep, const U32 flags)
14767
14768 "is_utf8_valid_partial_char"
14769 Returns 0 if the sequence of bytes starting at "s" and looking no
14770 further than "e - 1" is the UTF-8 encoding, as extended by Perl,
14771 for one or more code points. Otherwise, it returns 1 if there
14772 exists at least one non-empty sequence of bytes that when appended
14773 to sequence "s", starting at position "e" causes the entire
14774 sequence to be the well-formed UTF-8 of some code point; otherwise
14775 returns 0.
14776
14777 In other words this returns TRUE if "s" points to a partial
14778 UTF-8-encoded code point.
14779
14780 This is useful when a fixed-length buffer is being tested for being
14781 well-formed UTF-8, but the final few bytes in it don't comprise a
14782 full character; that is, it is split somewhere in the middle of the
14783 final code point's UTF-8 representation. (Presumably when the
14784 buffer is refreshed with the next chunk of data, the new first
14785 bytes will complete the partial code point.) This function is
14786 used to verify that the final bytes in the current buffer are in
14787 fact the legal beginning of some code point, so that if they
14788 aren't, the failure can be signalled without having to wait for the
14789 next read.
14790
14791 bool is_utf8_valid_partial_char(const U8 * const s,
14792 const U8 * const e)
14793
14794 "is_utf8_valid_partial_char_flags"
14795 Like "is_utf8_valid_partial_char", it returns a boolean giving
14796 whether or not the input is a valid UTF-8 encoded partial
14797 character, but it takes an extra parameter, "flags", which can
14798 further restrict which code points are considered valid.
14799
14800 If "flags" is 0, this behaves identically to
14801 "is_utf8_valid_partial_char". Otherwise "flags" can be any
14802 combination of the "UTF8_DISALLOW_foo" flags accepted by
14803 "utf8n_to_uvchr". If there is any sequence of bytes that can
14804 complete the input partial character in such a way that a non-
14805 prohibited character is formed, the function returns TRUE;
14806 otherwise FALSE. Non character code points cannot be determined
14807 based on partial character input. But many of the other possible
14808 excluded types can be determined from just the first one or two
14809 bytes.
14810
14811 bool is_utf8_valid_partial_char_flags(const U8 * const s,
14812 const U8 * const e,
14813 const U32 flags)
14814
14815 "isUTF8_CHAR"
14816 Evaluates to non-zero if the first few bytes of the string starting
14817 at "s" and looking no further than "e - 1" are well-formed UTF-8,
14818 as extended by Perl, that represents some code point; otherwise it
14819 evaluates to 0. If non-zero, the value gives how many bytes
14820 starting at "s" comprise the code point's representation. Any
14821 bytes remaining before "e", but beyond the ones needed to form the
14822 first code point in "s", are not examined.
14823
14824 The code point can be any that will fit in an IV on this machine,
14825 using Perl's extension to official UTF-8 to represent those higher
14826 than the Unicode maximum of 0x10FFFF. That means that this macro
14827 is used to efficiently decide if the next few bytes in "s" is legal
14828 UTF-8 for a single character.
14829
14830 Use "isSTRICT_UTF8_CHAR" to restrict the acceptable code points to
14831 those defined by Unicode to be fully interchangeable across
14832 applications; "isC9_STRICT_UTF8_CHAR" to use the Unicode
14833 Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>
14834 definition of allowable code points; and "isUTF8_CHAR_flags" for a
14835 more customized definition.
14836
14837 Use "is_utf8_string", "is_utf8_string_loc", and
14838 "is_utf8_string_loclen" to check entire strings.
14839
14840 Note also that a UTF-8 "invariant" character (i.e. ASCII on non-
14841 EBCDIC machines) is a valid UTF-8 character.
14842
14843 Size_t isUTF8_CHAR(const U8 * const s0, const U8 * const e)
14844
14845 "isUTF8_CHAR_flags"
14846 Evaluates to non-zero if the first few bytes of the string starting
14847 at "s" and looking no further than "e - 1" are well-formed UTF-8,
14848 as extended by Perl, that represents some code point, subject to
14849 the restrictions given by "flags"; otherwise it evaluates to 0. If
14850 non-zero, the value gives how many bytes starting at "s" comprise
14851 the code point's representation. Any bytes remaining before "e",
14852 but beyond the ones needed to form the first code point in "s", are
14853 not examined.
14854
14855 If "flags" is 0, this gives the same results as "isUTF8_CHAR"; if
14856 "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the same
14857 results as "isSTRICT_UTF8_CHAR"; and if "flags" is
14858 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same results
14859 as "isC9_STRICT_UTF8_CHAR". Otherwise "flags" may be any
14860 combination of the "UTF8_DISALLOW_foo" flags understood by
14861 "utf8n_to_uvchr", with the same meanings.
14862
14863 The three alternative macros are for the most commonly needed
14864 validations; they are likely to run somewhat faster than this more
14865 general one, as they can be inlined into your code.
14866
14867 Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
14868 "is_utf8_string_loclen_flags" to check entire strings.
14869
14870 STRLEN isUTF8_CHAR_flags(const U8 *s, const U8 *e,
14871 const U32 flags)
14872
14873 "LATIN1_TO_NATIVE"
14874 Returns the native equivalent of the input Latin-1 code point
14875 (including ASCII and control characters) given by "ch". Thus,
14876 "LATIN1_TO_NATIVE(66)" on EBCDIC platforms returns 194. These each
14877 represent the character "B" on their respective platforms. On
14878 ASCII platforms no conversion is needed, so this macro expands to
14879 just its input, adding no time nor space requirements to the
14880 implementation.
14881
14882 For conversion of code points potentially larger than will fit in a
14883 character, use "UNI_TO_NATIVE".
14884
14885 U8 LATIN1_TO_NATIVE(U8 ch)
14886
14887 "NATIVE_TO_LATIN1"
14888 Returns the Latin-1 (including ASCII and control characters)
14889 equivalent of the input native code point given by "ch". Thus,
14890 "NATIVE_TO_LATIN1(193)" on EBCDIC platforms returns 65. These each
14891 represent the character "A" on their respective platforms. On
14892 ASCII platforms no conversion is needed, so this macro expands to
14893 just its input, adding no time nor space requirements to the
14894 implementation.
14895
14896 For conversion of code points potentially larger than will fit in a
14897 character, use "NATIVE_TO_UNI".
14898
14899 U8 NATIVE_TO_LATIN1(U8 ch)
14900
14901 "NATIVE_TO_UNI"
14902 Returns the Unicode equivalent of the input native code point
14903 given by "ch". Thus, "NATIVE_TO_UNI(195)" on EBCDIC platforms
14904 returns 67. These each represent the character "C" on their
14905 respective platforms. On ASCII platforms no conversion is needed,
14906 so this macro expands to just its input, adding no time nor space
14907 requirements to the implementation.
14908
14909 UV NATIVE_TO_UNI(UV ch)
14910
14911 "pad_compname_type"
14912 "DEPRECATED!" It is planned to remove "pad_compname_type" from a
14913 future release of Perl. Do not use it for new code; remove it from
14914 existing code.
14915
14916 Looks up the type of the lexical variable at position "po" in the
14917 currently-compiling pad. If the variable is typed, the stash of
14918 the class to which it is typed is returned. If not, "NULL" is
14919 returned.
14920
14921 Use ""PAD_COMPNAME_TYPE"" in perlintern instead.
14922
14923 HV* pad_compname_type(const PADOFFSET po)
14924
14925 "pv_uni_display"
14926 Build to the scalar "dsv" a displayable version of the UTF-8
14927 encoded string "spv", length "len", the displayable version being
14928 at most "pvlim" bytes long (if longer, the rest is truncated and
14929 "..." will be appended).
14930
14931 The "flags" argument can have "UNI_DISPLAY_ISPRINT" set to display
14932 "isPRINT()"able characters as themselves, "UNI_DISPLAY_BACKSLASH"
14933 to display the "\\[nrfta\\]" as the backslashed versions (like
14934 "\n") ("UNI_DISPLAY_BACKSLASH" is preferred over
14935 "UNI_DISPLAY_ISPRINT" for "\\"). "UNI_DISPLAY_QQ" (and its alias
14936 "UNI_DISPLAY_REGEX") have both "UNI_DISPLAY_BACKSLASH" and
14937 "UNI_DISPLAY_ISPRINT" turned on.
14938
14939 Additionally, there is now "UNI_DISPLAY_BACKSPACE" which allows
14940 "\b" for a backspace, but only when "UNI_DISPLAY_BACKSLASH" also is
14941 set.
14942
14943 The pointer to the PV of the "dsv" is returned.
14944
14945 See also "sv_uni_display".
14946
14947 char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len,
14948 STRLEN pvlim, UV flags)
14949
14950 "REPLACEMENT_CHARACTER_UTF8"
14951 This is a macro that evaluates to a string constant of the UTF-8
14952 bytes that define the Unicode REPLACEMENT CHARACTER (U+FFFD) for
14953 the platform that perl is compiled on. This allows code to use a
14954 mnemonic for this character that works on both ASCII and EBCDIC
14955 platforms. "sizeof(REPLACEMENT_CHARACTER_UTF8) - 1" can be used to
14956 get its length in bytes.
14957
14958 "sv_cat_decode"
14959 "encoding" is assumed to be an "Encode" object, the PV of "ssv" is
14960 assumed to be octets in that encoding and decoding the input starts
14961 from the position which "(PV + *offset)" pointed to. "dsv" will be
14962 concatenated with the decoded UTF-8 string from "ssv". Decoding
14963 will terminate when the string "tstr" appears in decoding output or
14964 the input ends on the PV of "ssv". The value which "offset" points
14965 will be modified to the last input position on "ssv".
14966
14967 Returns TRUE if the terminator was found, else returns FALSE.
14968
14969 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset,
14970 char* tstr, int tlen)
14971
14972 "sv_recode_to_utf8"
14973 "encoding" is assumed to be an "Encode" object, on entry the PV of
14974 "sv" is assumed to be octets in that encoding, and "sv" will be
14975 converted into Unicode (and UTF-8).
14976
14977 If "sv" already is UTF-8 (or if it is not "POK"), or if "encoding"
14978 is not a reference, nothing is done to "sv". If "encoding" is not
14979 an "Encode::XS" Encoding object, bad things will happen. (See
14980 cpan/Encode/encoding.pm and Encode.)
14981
14982 The PV of "sv" is returned.
14983
14984 char* sv_recode_to_utf8(SV* sv, SV *encoding)
14985
14986 "sv_uni_display"
14987 Build to the scalar "dsv" a displayable version of the scalar "sv",
14988 the displayable version being at most "pvlim" bytes long (if
14989 longer, the rest is truncated and "..." will be appended).
14990
14991 The "flags" argument is as in "pv_uni_display"().
14992
14993 The pointer to the PV of the "dsv" is returned.
14994
14995 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
14996
14997 "UNICODE_REPLACEMENT"
14998 Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT
14999 CHARACTER
15000
15001 "UNI_TO_NATIVE"
15002 Returns the native equivalent of the input Unicode code point
15003 given by "ch". Thus, "UNI_TO_NATIVE(68)" on EBCDIC platforms
15004 returns 196. These each represent the character "D" on their
15005 respective platforms. On ASCII platforms no conversion is needed,
15006 so this macro expands to just its input, adding no time nor space
15007 requirements to the implementation.
15008
15009 UV UNI_TO_NATIVE(UV ch)
15010
15011 "utf8n_to_uvchr"
15012 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15013 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"() rather
15014 than call this directly.
15015
15016 Bottom level UTF-8 decode routine. Returns the native code point
15017 value of the first character in the string "s", which is assumed to
15018 be in UTF-8 (or UTF-EBCDIC) encoding, and no longer than "curlen"
15019 bytes; *retlen (if "retlen" isn't NULL) will be set to the length,
15020 in bytes, of that character.
15021
15022 The value of "flags" determines the behavior when "s" does not
15023 point to a well-formed UTF-8 character. If "flags" is 0,
15024 encountering a malformation causes zero to be returned and *retlen
15025 is set so that ("s" + *retlen) is the next possible position in "s"
15026 that could begin a non-malformed character. Also, if UTF-8
15027 warnings haven't been lexically disabled, a warning is raised.
15028 Some UTF-8 input sequences may contain multiple malformations.
15029 This function tries to find every possible one in each call, so
15030 multiple warnings can be raised for the same sequence.
15031
15032 Various ALLOW flags can be set in "flags" to allow (and not warn
15033 on) individual types of malformations, such as the sequence being
15034 overlong (that is, when there is a shorter sequence that can
15035 express the same code point; overlong sequences are expressly
15036 forbidden in the UTF-8 standard due to potential security issues).
15037 Another malformation example is the first byte of a character not
15038 being a legal first byte. See utf8.h for the list of such flags.
15039 Even if allowed, this function generally returns the Unicode
15040 REPLACEMENT CHARACTER when it encounters a malformation. There are
15041 flags in utf8.h to override this behavior for the overlong
15042 malformations, but don't do that except for very specialized
15043 purposes.
15044
15045 The "UTF8_CHECK_ONLY" flag overrides the behavior when a non-
15046 allowed (by other flags) malformation is found. If this flag is
15047 set, the routine assumes that the caller will raise a warning, and
15048 this function will silently just set "retlen" to "-1" (cast to
15049 "STRLEN") and return zero.
15050
15051 Note that this API requires disambiguation between successful
15052 decoding a "NUL" character, and an error return (unless the
15053 "UTF8_CHECK_ONLY" flag is set), as in both cases, 0 is returned,
15054 and, depending on the malformation, "retlen" may be set to 1. To
15055 disambiguate, upon a zero return, see if the first byte of "s" is 0
15056 as well. If so, the input was a "NUL"; if not, the input had an
15057 error. Or you can use "utf8n_to_uvchr_error".
15058
15059 Certain code points are considered problematic. These are Unicode
15060 surrogates, Unicode non-characters, and code points above the
15061 Unicode maximum of 0x10FFFF. By default these are considered
15062 regular code points, but certain situations warrant special
15063 handling for them, which can be specified using the "flags"
15064 parameter. If "flags" contains
15065 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", all three classes are treated
15066 as malformations and handled as such. The flags
15067 "UTF8_DISALLOW_SURROGATE", "UTF8_DISALLOW_NONCHAR", and
15068 "UTF8_DISALLOW_SUPER" (meaning above the legal Unicode maximum) can
15069 be set to disallow these categories individually.
15070 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed inputs to
15071 the strict UTF-8 traditionally defined by Unicode. Use
15072 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE" to use the strictness
15073 definition given by Unicode Corrigendum #9
15074 <https://www.unicode.org/versions/corrigendum9.html>. The
15075 difference between traditional strictness and C9 strictness is that
15076 the latter does not forbid non-character code points. (They are
15077 still discouraged, however.) For more discussion see "Noncharacter
15078 code points" in perlunicode.
15079
15080 The flags "UTF8_WARN_ILLEGAL_INTERCHANGE",
15081 "UTF8_WARN_ILLEGAL_C9_INTERCHANGE", "UTF8_WARN_SURROGATE",
15082 "UTF8_WARN_NONCHAR", and "UTF8_WARN_SUPER" will cause warning
15083 messages to be raised for their respective categories, but
15084 otherwise the code points are considered valid (not malformations).
15085 To get a category to both be treated as a malformation and raise a
15086 warning, specify both the WARN and DISALLOW flags. (But note that
15087 warnings are not raised if lexically disabled nor if
15088 "UTF8_CHECK_ONLY" is also specified.)
15089
15090 Extremely high code points were never specified in any standard,
15091 and require an extension to UTF-8 to express, which Perl does. It
15092 is likely that programs written in something other than Perl would
15093 not be able to read files that contain these; nor would Perl
15094 understand files written by something that uses a different
15095 extension. For these reasons, there is a separate set of flags
15096 that can warn and/or disallow these extremely high code points,
15097 even if other above-Unicode ones are accepted. They are the
15098 "UTF8_WARN_PERL_EXTENDED" and "UTF8_DISALLOW_PERL_EXTENDED" flags.
15099 For more information see "UTF8_GOT_PERL_EXTENDED". Of course
15100 "UTF8_DISALLOW_SUPER" will treat all above-Unicode code points,
15101 including these, as malformations. (Note that the Unicode standard
15102 considers anything above 0x10FFFF to be illegal, but there are
15103 standards predating it that allow up to 0x7FFF_FFFF (2**31 -1))
15104
15105 A somewhat misleadingly named synonym for "UTF8_WARN_PERL_EXTENDED"
15106 is retained for backward compatibility: "UTF8_WARN_ABOVE_31_BIT".
15107 Similarly, "UTF8_DISALLOW_ABOVE_31_BIT" is usable instead of the
15108 more accurately named "UTF8_DISALLOW_PERL_EXTENDED". The names are
15109 misleading because these flags can apply to code points that
15110 actually do fit in 31 bits. This happens on EBCDIC platforms, and
15111 sometimes when the overlong malformation is also present. The new
15112 names accurately describe the situation in all cases.
15113
15114 All other code points corresponding to Unicode characters,
15115 including private use and those yet to be assigned, are never
15116 considered malformed and never warn.
15117
15118 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen,
15119 const U32 flags)
15120
15121 "utf8n_to_uvchr_error"
15122 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15123 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"() rather
15124 than call this directly.
15125
15126 This function is for code that needs to know what the precise
15127 malformation(s) are when an error is found. If you also need to
15128 know the generated warning messages, use "utf8n_to_uvchr_msgs"()
15129 instead.
15130
15131 It is like "utf8n_to_uvchr" but it takes an extra parameter placed
15132 after all the others, "errors". If this parameter is 0, this
15133 function behaves identically to "utf8n_to_uvchr". Otherwise,
15134 "errors" should be a pointer to a "U32" variable, which this
15135 function sets to indicate any errors found. Upon return, if
15136 *errors is 0, there were no errors found. Otherwise, *errors is
15137 the bit-wise "OR" of the bits described in the list below. Some of
15138 these bits will be set if a malformation is found, even if the
15139 input "flags" parameter indicates that the given malformation is
15140 allowed; those exceptions are noted:
15141
15142 "UTF8_GOT_PERL_EXTENDED"
15143 The input sequence is not standard UTF-8, but a Perl extension.
15144 This bit is set only if the input "flags" parameter contains
15145 either the "UTF8_DISALLOW_PERL_EXTENDED" or the
15146 "UTF8_WARN_PERL_EXTENDED" flags.
15147
15148 Code points above 0x7FFF_FFFF (2**31 - 1) were never specified
15149 in any standard, and so some extension must be used to express
15150 them. Perl uses a natural extension to UTF-8 to represent the
15151 ones up to 2**36-1, and invented a further extension to
15152 represent even higher ones, so that any code point that fits in
15153 a 64-bit word can be represented. Text using these extensions
15154 is not likely to be portable to non-Perl code. We lump both of
15155 these extensions together and refer to them as Perl extended
15156 UTF-8. There exist other extensions that people have invented,
15157 incompatible with Perl's.
15158
15159 On EBCDIC platforms starting in Perl v5.24, the Perl extension
15160 for representing extremely high code points kicks in at
15161 0x3FFF_FFFF (2**30 -1), which is lower than on ASCII. Prior to
15162 that, code points 2**31 and higher were simply unrepresentable,
15163 and a different, incompatible method was used to represent code
15164 points between 2**30 and 2**31 - 1.
15165
15166 On both platforms, ASCII and EBCDIC, "UTF8_GOT_PERL_EXTENDED"
15167 is set if Perl extended UTF-8 is used.
15168
15169 In earlier Perls, this bit was named "UTF8_GOT_ABOVE_31_BIT",
15170 which you still may use for backward compatibility. That name
15171 is misleading, as this flag may be set when the code point
15172 actually does fit in 31 bits. This happens on EBCDIC
15173 platforms, and sometimes when the overlong malformation is also
15174 present. The new name accurately describes the situation in
15175 all cases.
15176
15177 "UTF8_GOT_CONTINUATION"
15178 The input sequence was malformed in that the first byte was a
15179 UTF-8 continuation byte.
15180
15181 "UTF8_GOT_EMPTY"
15182 The input "curlen" parameter was 0.
15183
15184 "UTF8_GOT_LONG"
15185 The input sequence was malformed in that there is some other
15186 sequence that evaluates to the same code point, but that
15187 sequence is shorter than this one.
15188
15189 Until Unicode 3.1, it was legal for programs to accept this
15190 malformation, but it was discovered that this created security
15191 issues.
15192
15193 "UTF8_GOT_NONCHAR"
15194 The code point represented by the input UTF-8 sequence is for a
15195 Unicode non-character code point. This bit is set only if the
15196 input "flags" parameter contains either the
15197 "UTF8_DISALLOW_NONCHAR" or the "UTF8_WARN_NONCHAR" flags.
15198
15199 "UTF8_GOT_NON_CONTINUATION"
15200 The input sequence was malformed in that a non-continuation
15201 type byte was found in a position where only a continuation
15202 type one should be. See also "UTF8_GOT_SHORT".
15203
15204 "UTF8_GOT_OVERFLOW"
15205 The input sequence was malformed in that it is for a code point
15206 that is not representable in the number of bits available in an
15207 IV on the current platform.
15208
15209 "UTF8_GOT_SHORT"
15210 The input sequence was malformed in that "curlen" is smaller
15211 than required for a complete sequence. In other words, the
15212 input is for a partial character sequence.
15213
15214 "UTF8_GOT_SHORT" and "UTF8_GOT_NON_CONTINUATION" both indicate
15215 a too short sequence. The difference is that
15216 "UTF8_GOT_NON_CONTINUATION" indicates always that there is an
15217 error, while "UTF8_GOT_SHORT" means that an incomplete sequence
15218 was looked at. If no other flags are present, it means that
15219 the sequence was valid as far as it went. Depending on the
15220 application, this could mean one of three things:
15221
15222 • The "curlen" length parameter passed in was too small, and
15223 the function was prevented from examining all the necessary
15224 bytes.
15225
15226 • The buffer being looked at is based on reading data, and
15227 the data received so far stopped in the middle of a
15228 character, so that the next read will read the remainder of
15229 this character. (It is up to the caller to deal with the
15230 split bytes somehow.)
15231
15232 • This is a real error, and the partial sequence is all we're
15233 going to get.
15234
15235 "UTF8_GOT_SUPER"
15236 The input sequence was malformed in that it is for a non-
15237 Unicode code point; that is, one above the legal Unicode
15238 maximum. This bit is set only if the input "flags" parameter
15239 contains either the "UTF8_DISALLOW_SUPER" or the
15240 "UTF8_WARN_SUPER" flags.
15241
15242 "UTF8_GOT_SURROGATE"
15243 The input sequence was malformed in that it is for a -Unicode
15244 UTF-16 surrogate code point. This bit is set only if the input
15245 "flags" parameter contains either the "UTF8_DISALLOW_SURROGATE"
15246 or the "UTF8_WARN_SURROGATE" flags.
15247
15248 To do your own error handling, call this function with the
15249 "UTF8_CHECK_ONLY" flag to suppress any warnings, and then examine
15250 the *errors return.
15251
15252 UV utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
15253 STRLEN *retlen, const U32 flags,
15254 U32 * errors)
15255
15256 "utf8n_to_uvchr_msgs"
15257 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15258 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"() rather
15259 than call this directly.
15260
15261 This function is for code that needs to know what the precise
15262 malformation(s) are when an error is found, and wants the
15263 corresponding warning and/or error messages to be returned to the
15264 caller rather than be displayed. All messages that would have been
15265 displayed if all lexical warnings are enabled will be returned.
15266
15267 It is just like "utf8n_to_uvchr_error" but it takes an extra
15268 parameter placed after all the others, "msgs". If this parameter
15269 is 0, this function behaves identically to "utf8n_to_uvchr_error".
15270 Otherwise, "msgs" should be a pointer to an "AV *" variable, in
15271 which this function creates a new AV to contain any appropriate
15272 messages. The elements of the array are ordered so that the first
15273 message that would have been displayed is in the 0th element, and
15274 so on. Each element is a hash with three key-value pairs, as
15275 follows:
15276
15277 "text"
15278 The text of the message as a "SVpv".
15279
15280 "warn_categories"
15281 The warning category (or categories) packed into a "SVuv".
15282
15283 "flag"
15284 A single flag bit associated with this message, in a "SVuv".
15285 The bit corresponds to some bit in the *errors return value,
15286 such as "UTF8_GOT_LONG".
15287
15288 It's important to note that specifying this parameter as non-null
15289 will cause any warnings this function would otherwise generate to
15290 be suppressed, and instead be placed in *msgs. The caller can
15291 check the lexical warnings state (or not) when choosing what to do
15292 with the returned messages.
15293
15294 If the flag "UTF8_CHECK_ONLY" is passed, no warnings are generated,
15295 and hence no AV is created.
15296
15297 The caller, of course, is responsible for freeing any returned AV.
15298
15299 UV utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
15300 STRLEN *retlen, const U32 flags,
15301 U32 * errors, AV ** msgs)
15302
15303 "UTF8SKIP"
15304 returns the number of bytes a non-malformed UTF-8 encoded character
15305 whose first (perhaps only) byte is pointed to by "s".
15306
15307 If there is a possibility of malformed input, use instead:
15308
15309 "UTF8_SAFE_SKIP" if you know the maximum ending pointer in the
15310 buffer pointed to by "s"; or
15311 "UTF8_CHK_SKIP" if you don't know it.
15312
15313 It is better to restructure your code so the end pointer is passed
15314 down so that you know what it actually is at the point of this
15315 call, but if that isn't possible, "UTF8_CHK_SKIP" can minimize the
15316 chance of accessing beyond the end of the input buffer.
15317
15318 STRLEN UTF8SKIP(char* s)
15319
15320 "UTF8_CHK_SKIP"
15321 This is a safer version of "UTF8SKIP", but still not as safe as
15322 "UTF8_SAFE_SKIP". This version doesn't blindly assume that the
15323 input string pointed to by "s" is well-formed, but verifies that
15324 there isn't a NUL terminating character before the expected end of
15325 the next character in "s". The length "UTF8_CHK_SKIP" returns
15326 stops just before any such NUL.
15327
15328 Perl tends to add NULs, as an insurance policy, after the end of
15329 strings in SV's, so it is likely that using this macro will prevent
15330 inadvertent reading beyond the end of the input buffer, even if it
15331 is malformed UTF-8.
15332
15333 This macro is intended to be used by XS modules where the inputs
15334 could be malformed, and it isn't feasible to restructure to use the
15335 safer "UTF8_SAFE_SKIP", for example when interfacing with a C
15336 library.
15337
15338 STRLEN UTF8_CHK_SKIP(char* s)
15339
15340 "utf8_distance"
15341 Returns the number of UTF-8 characters between the UTF-8 pointers
15342 "a" and "b".
15343
15344 WARNING: use only if you *know* that the pointers point inside the
15345 same UTF-8 buffer.
15346
15347 IV utf8_distance(const U8 *a, const U8 *b)
15348
15349 "utf8_hop"
15350 Return the UTF-8 pointer "s" displaced by "off" characters, either
15351 forward or backward.
15352
15353 WARNING: do not use the following unless you *know* "off" is within
15354 the UTF-8 data pointed to by "s" *and* that on entry "s" is aligned
15355 on the first byte of character or just after the last byte of a
15356 character.
15357
15358 U8* utf8_hop(const U8 *s, SSize_t off)
15359
15360 "utf8_hop_back"
15361 Return the UTF-8 pointer "s" displaced by up to "off" characters,
15362 backward.
15363
15364 "off" must be non-positive.
15365
15366 "s" must be after or equal to "start".
15367
15368 When moving backward it will not move before "start".
15369
15370 Will not exceed this limit even if the string is not valid "UTF-8".
15371
15372 U8* utf8_hop_back(const U8 *s, SSize_t off, const U8 *start)
15373
15374 "utf8_hop_forward"
15375 Return the UTF-8 pointer "s" displaced by up to "off" characters,
15376 forward.
15377
15378 "off" must be non-negative.
15379
15380 "s" must be before or equal to "end".
15381
15382 When moving forward it will not move beyond "end".
15383
15384 Will not exceed this limit even if the string is not valid "UTF-8".
15385
15386 U8* utf8_hop_forward(const U8 *s, SSize_t off, const U8 *end)
15387
15388 "utf8_hop_safe"
15389 Return the UTF-8 pointer "s" displaced by up to "off" characters,
15390 either forward or backward.
15391
15392 When moving backward it will not move before "start".
15393
15394 When moving forward it will not move beyond "end".
15395
15396 Will not exceed those limits even if the string is not valid
15397 "UTF-8".
15398
15399 U8* utf8_hop_safe(const U8 *s, SSize_t off, const U8 *start,
15400 const U8 *end)
15401
15402 "UTF8_IS_INVARIANT"
15403 Evaluates to 1 if the byte "c" represents the same character when
15404 encoded in UTF-8 as when not; otherwise evaluates to 0. UTF-8
15405 invariant characters can be copied as-is when converting to/from
15406 UTF-8, saving time.
15407
15408 In spite of the name, this macro gives the correct result if the
15409 input string from which "c" comes is not encoded in UTF-8.
15410
15411 See "UVCHR_IS_INVARIANT" for checking if a UV is invariant.
15412
15413 bool UTF8_IS_INVARIANT(char c)
15414
15415 "UTF8_IS_NONCHAR"
15416 Evaluates to non-zero if the first few bytes of the string starting
15417 at "s" and looking no further than "e - 1" are well-formed UTF-8
15418 that represents one of the Unicode non-character code points;
15419 otherwise it evaluates to 0. If non-zero, the value gives how many
15420 bytes starting at "s" comprise the code point's representation.
15421
15422 bool UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
15423
15424 "UTF8_IS_SUPER"
15425 Recall that Perl recognizes an extension to UTF-8 that can encode
15426 code points larger than the ones defined by Unicode, which are
15427 0..0x10FFFF.
15428
15429 This macro evaluates to non-zero if the first few bytes of the
15430 string starting at "s" and looking no further than "e - 1" are from
15431 this UTF-8 extension; otherwise it evaluates to 0. If non-zero,
15432 the value gives how many bytes starting at "s" comprise the code
15433 point's representation.
15434
15435 0 is returned if the bytes are not well-formed extended UTF-8, or
15436 if they represent a code point that cannot fit in a UV on the
15437 current platform. Hence this macro can give different results when
15438 run on a 64-bit word machine than on one with a 32-bit word size.
15439
15440 Note that it is illegal to have code points that are larger than
15441 what can fit in an IV on the current machine.
15442
15443 bool UTF8_IS_SUPER(const U8 *s, const U8 *e)
15444
15445 "UTF8_IS_SURROGATE"
15446 Evaluates to non-zero if the first few bytes of the string starting
15447 at "s" and looking no further than "e - 1" are well-formed UTF-8
15448 that represents one of the Unicode surrogate code points; otherwise
15449 it evaluates to 0. If non-zero, the value gives how many bytes
15450 starting at "s" comprise the code point's representation.
15451
15452 bool UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
15453
15454 "utf8_length"
15455 Returns the number of characters in the sequence of UTF-8-encoded
15456 bytes starting at "s" and ending at the byte just before "e". If
15457 <s> and <e> point to the same place, it returns 0 with no warning
15458 raised.
15459
15460 If "e < s" or if the scan would end up past "e", it raises a UTF8
15461 warning and returns the number of valid characters.
15462
15463 STRLEN utf8_length(const U8* s, const U8 *e)
15464
15465 "UTF8_MAXBYTES"
15466 The maximum width of a single UTF-8 encoded character, in bytes.
15467
15468 NOTE: Strictly speaking Perl's UTF-8 should not be called UTF-8
15469 since UTF-8 is an encoding of Unicode, and Unicode's upper limit,
15470 0x10FFFF, can be expressed with 4 bytes. However, Perl thinks of
15471 UTF-8 as a way to encode non-negative integers in a binary format,
15472 even those above Unicode.
15473
15474 "UTF8_MAXBYTES_CASE"
15475 The maximum number of UTF-8 bytes a single Unicode character can
15476 uppercase/lowercase/titlecase/fold into.
15477
15478 "UTF8_SAFE_SKIP"
15479 returns 0 if "s >= e"; otherwise returns the number of bytes in the
15480 UTF-8 encoded character whose first byte is pointed to by "s".
15481 But it never returns beyond "e". On DEBUGGING builds, it asserts
15482 that "s <= e".
15483
15484 STRLEN UTF8_SAFE_SKIP(char* s, char* e)
15485
15486 "UTF8_SKIP"
15487 This is a synonym for "UTF8SKIP"
15488
15489 STRLEN UTF8_SKIP(char* s)
15490
15491 "utf8_to_bytes"
15492 NOTE: "utf8_to_bytes" is experimental and may change or be removed
15493 without notice.
15494
15495 Converts a string "s" of length *lenp from UTF-8 into native byte
15496 encoding. Unlike "bytes_to_utf8", this over-writes the original
15497 string, and updates *lenp to contain the new length. Returns zero
15498 on failure (leaving "s" unchanged) setting *lenp to -1.
15499
15500 Upon successful return, the number of variants in the string can be
15501 computed by having saved the value of *lenp before the call, and
15502 subtracting the after-call value of *lenp from it.
15503
15504 If you need a copy of the string, see "bytes_from_utf8".
15505
15506 U8* utf8_to_bytes(U8 *s, STRLEN *lenp)
15507
15508 "utf8_to_uvchr"
15509 "DEPRECATED!" It is planned to remove "utf8_to_uvchr" from a
15510 future release of Perl. Do not use it for new code; remove it from
15511 existing code.
15512
15513 Returns the native code point of the first character in the string
15514 "s" which is assumed to be in UTF-8 encoding; "retlen" will be set
15515 to the length, in bytes, of that character.
15516
15517 Some, but not all, UTF-8 malformations are detected, and in fact,
15518 some malformed input could cause reading beyond the end of the
15519 input buffer, which is why this function is deprecated. Use
15520 "utf8_to_uvchr_buf" instead.
15521
15522 If "s" points to one of the detected malformations, and UTF8
15523 warnings are enabled, zero is returned and *retlen is set (if
15524 "retlen" isn't "NULL") to -1. If those warnings are off, the
15525 computed value if well-defined (or the Unicode REPLACEMENT
15526 CHARACTER, if not) is silently returned, and *retlen is set (if
15527 "retlen" isn't NULL) so that ("s" + *retlen) is the next possible
15528 position in "s" that could begin a non-malformed character. See
15529 "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is
15530 returned.
15531
15532 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
15533
15534 "utf8_to_uvchr_buf"
15535 Returns the native code point of the first character in the string
15536 "s" which is assumed to be in UTF-8 encoding; "send" points to 1
15537 beyond the end of "s". *retlen will be set to the length, in
15538 bytes, of that character.
15539
15540 If "s" does not point to a well-formed UTF-8 character and UTF8
15541 warnings are enabled, zero is returned and *retlen is set (if
15542 "retlen" isn't "NULL") to -1. If those warnings are off, the
15543 computed value, if well-defined (or the Unicode REPLACEMENT
15544 CHARACTER if not), is silently returned, and *retlen is set (if
15545 "retlen" isn't "NULL") so that ("s" + *retlen) is the next possible
15546 position in "s" that could begin a non-malformed character. See
15547 "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is
15548 returned.
15549
15550 UV utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen)
15551
15552 "UVCHR_IS_INVARIANT"
15553 Evaluates to 1 if the representation of code point "cp" is the same
15554 whether or not it is encoded in UTF-8; otherwise evaluates to 0.
15555 UTF-8 invariant characters can be copied as-is when converting
15556 to/from UTF-8, saving time. "cp" is Unicode if above 255;
15557 otherwise is platform-native.
15558
15559 bool UVCHR_IS_INVARIANT(UV cp)
15560
15561 "UVCHR_SKIP"
15562 returns the number of bytes required to represent the code point
15563 "cp" when encoded as UTF-8. "cp" is a native (ASCII or EBCDIC)
15564 code point if less than 255; a Unicode code point otherwise.
15565
15566 STRLEN UVCHR_SKIP(UV cp)
15567
15568 "uvchr_to_utf8"
15569 Adds the UTF-8 representation of the native code point "uv" to the
15570 end of the string "d"; "d" should have at least "UVCHR_SKIP(uv)+1"
15571 (up to "UTF8_MAXBYTES+1") free bytes available. The return value
15572 is the pointer to the byte after the end of the new character. In
15573 other words,
15574
15575 d = uvchr_to_utf8(d, uv);
15576
15577 is the recommended wide native character-aware way of saying
15578
15579 *(d++) = uv;
15580
15581 This function accepts any code point from 0.."IV_MAX" as input.
15582 "IV_MAX" is typically 0x7FFF_FFFF in a 32-bit word.
15583
15584 It is possible to forbid or warn on non-Unicode code points, or
15585 those that may be problematic by using "uvchr_to_utf8_flags".
15586
15587 U8* uvchr_to_utf8(U8 *d, UV uv)
15588
15589 "uvchr_to_utf8_flags"
15590 Adds the UTF-8 representation of the native code point "uv" to the
15591 end of the string "d"; "d" should have at least "UVCHR_SKIP(uv)+1"
15592 (up to "UTF8_MAXBYTES+1") free bytes available. The return value
15593 is the pointer to the byte after the end of the new character. In
15594 other words,
15595
15596 d = uvchr_to_utf8_flags(d, uv, flags);
15597
15598 or, in most cases,
15599
15600 d = uvchr_to_utf8_flags(d, uv, 0);
15601
15602 This is the Unicode-aware way of saying
15603
15604 *(d++) = uv;
15605
15606 If "flags" is 0, this function accepts any code point from
15607 0.."IV_MAX" as input. "IV_MAX" is typically 0x7FFF_FFFF in a
15608 32-bit word.
15609
15610 Specifying "flags" can further restrict what is allowed and not
15611 warned on, as follows:
15612
15613 If "uv" is a Unicode surrogate code point and
15614 "UNICODE_WARN_SURROGATE" is set, the function will raise a warning,
15615 provided UTF8 warnings are enabled. If instead
15616 "UNICODE_DISALLOW_SURROGATE" is set, the function will fail and
15617 return NULL. If both flags are set, the function will both warn
15618 and return NULL.
15619
15620 Similarly, the "UNICODE_WARN_NONCHAR" and
15621 "UNICODE_DISALLOW_NONCHAR" flags affect how the function handles a
15622 Unicode non-character.
15623
15624 And likewise, the "UNICODE_WARN_SUPER" and "UNICODE_DISALLOW_SUPER"
15625 flags affect the handling of code points that are above the Unicode
15626 maximum of 0x10FFFF. Languages other than Perl may not be able to
15627 accept files that contain these.
15628
15629 The flag "UNICODE_WARN_ILLEGAL_INTERCHANGE" selects all three of
15630 the above WARN flags; and "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE"
15631 selects all three DISALLOW flags.
15632 "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed inputs
15633 to the strict UTF-8 traditionally defined by Unicode. Similarly,
15634 "UNICODE_WARN_ILLEGAL_C9_INTERCHANGE" and
15635 "UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE" are shortcuts to select
15636 the above-Unicode and surrogate flags, but not the non-character
15637 ones, as defined in Unicode Corrigendum #9
15638 <https://www.unicode.org/versions/corrigendum9.html>. See
15639 "Noncharacter code points" in perlunicode.
15640
15641 Extremely high code points were never specified in any standard,
15642 and require an extension to UTF-8 to express, which Perl does. It
15643 is likely that programs written in something other than Perl would
15644 not be able to read files that contain these; nor would Perl
15645 understand files written by something that uses a different
15646 extension. For these reasons, there is a separate set of flags
15647 that can warn and/or disallow these extremely high code points,
15648 even if other above-Unicode ones are accepted. They are the
15649 "UNICODE_WARN_PERL_EXTENDED" and "UNICODE_DISALLOW_PERL_EXTENDED"
15650 flags. For more information see "UTF8_GOT_PERL_EXTENDED". Of
15651 course "UNICODE_DISALLOW_SUPER" will treat all above-Unicode code
15652 points, including these, as malformations. (Note that the Unicode
15653 standard considers anything above 0x10FFFF to be illegal, but there
15654 are standards predating it that allow up to 0x7FFF_FFFF (2**31 -1))
15655
15656 A somewhat misleadingly named synonym for
15657 "UNICODE_WARN_PERL_EXTENDED" is retained for backward
15658 compatibility: "UNICODE_WARN_ABOVE_31_BIT". Similarly,
15659 "UNICODE_DISALLOW_ABOVE_31_BIT" is usable instead of the more
15660 accurately named "UNICODE_DISALLOW_PERL_EXTENDED". The names are
15661 misleading because on EBCDIC platforms,these flags can apply to
15662 code points that actually do fit in 31 bits. The new names
15663 accurately describe the situation in all cases.
15664
15665 U8* uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
15666
15667 "uvchr_to_utf8_flags_msgs"
15668 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15669 CIRCUMSTANCES.
15670
15671 Most code should use ""uvchr_to_utf8_flags"()" rather than call
15672 this directly.
15673
15674 This function is for code that wants any warning and/or error
15675 messages to be returned to the caller rather than be displayed.
15676 All messages that would have been displayed if all lexical warnings
15677 are enabled will be returned.
15678
15679 It is just like "uvchr_to_utf8_flags" but it takes an extra
15680 parameter placed after all the others, "msgs". If this parameter
15681 is 0, this function behaves identically to "uvchr_to_utf8_flags".
15682 Otherwise, "msgs" should be a pointer to an "HV *" variable, in
15683 which this function creates a new HV to contain any appropriate
15684 messages. The hash has three key-value pairs, as follows:
15685
15686 "text"
15687 The text of the message as a "SVpv".
15688
15689 "warn_categories"
15690 The warning category (or categories) packed into a "SVuv".
15691
15692 "flag"
15693 A single flag bit associated with this message, in a "SVuv".
15694 The bit corresponds to some bit in the *errors return value,
15695 such as "UNICODE_GOT_SURROGATE".
15696
15697 It's important to note that specifying this parameter as non-null
15698 will cause any warnings this function would otherwise generate to
15699 be suppressed, and instead be placed in *msgs. The caller can
15700 check the lexical warnings state (or not) when choosing what to do
15701 with the returned messages.
15702
15703 The caller, of course, is responsible for freeing any returned HV.
15704
15705 U8* uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags, HV ** msgs)
15706
15708 "C_ARRAY_END"
15709 Returns a pointer to one element past the final element of the
15710 input C array.
15711
15712 void * C_ARRAY_END(void *a)
15713
15714 "C_ARRAY_LENGTH"
15715 Returns the number of elements in the input C array (so you want
15716 your zero-based indices to be less than but not equal to).
15717
15718 STRLEN C_ARRAY_LENGTH(void *a)
15719
15720 "getcwd_sv"
15721 Fill "sv" with current working directory
15722
15723 int getcwd_sv(SV* sv)
15724
15725 "IN_PERL_COMPILETIME"
15726 Returns 1 if this macro is being called during the compilation
15727 phase of the program; otherwise 0;
15728
15729 bool IN_PERL_COMPILETIME
15730
15731 "IN_PERL_RUNTIME"
15732 Returns 1 if this macro is being called during the execution phase
15733 of the program; otherwise 0;
15734
15735 bool IN_PERL_RUNTIME
15736
15737 "IS_SAFE_SYSCALL"
15738 Same as "is_safe_syscall".
15739
15740 bool IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
15741 NN const char *what, NN const char *op_name)
15742
15743 "is_safe_syscall"
15744 Test that the given "pv" (with length "len") doesn't contain any
15745 internal "NUL" characters. If it does, set "errno" to "ENOENT",
15746 optionally warn using the "syscalls" category, and return FALSE.
15747
15748 Return TRUE if the name is safe.
15749
15750 "what" and "op_name" are used in any warning.
15751
15752 Used by the "IS_SAFE_SYSCALL()" macro.
15753
15754 bool is_safe_syscall(const char *pv, STRLEN len,
15755 const char *what, const char *op_name)
15756
15757 "my_setenv"
15758 A wrapper for the C library setenv(3). Don't use the latter, as
15759 the perl version has desirable safeguards
15760
15761 void my_setenv(const char* nam, const char* val)
15762
15763 "Poison"
15764 PoisonWith(0xEF) for catching access to freed memory.
15765
15766 void Poison(void* dest, int nitems, type)
15767
15768 "PoisonFree"
15769 PoisonWith(0xEF) for catching access to freed memory.
15770
15771 void PoisonFree(void* dest, int nitems, type)
15772
15773 "PoisonNew"
15774 PoisonWith(0xAB) for catching access to allocated but uninitialized
15775 memory.
15776
15777 void PoisonNew(void* dest, int nitems, type)
15778
15779 "PoisonWith"
15780 Fill up memory with a byte pattern (a byte repeated over and over
15781 again) that hopefully catches attempts to access uninitialized
15782 memory.
15783
15784 void PoisonWith(void* dest, int nitems, type, U8 byte)
15785
15786 "StructCopy"
15787 This is an architecture-independent macro to copy one structure to
15788 another.
15789
15790 void StructCopy(type *src, type *dest, type)
15791
15792 "sv_destroyable"
15793 Dummy routine which reports that object can be destroyed when there
15794 is no sharing module present. It ignores its single SV argument,
15795 and returns 'true'. Exists to avoid test for a "NULL" function
15796 pointer and because it could potentially warn under some level of
15797 strict-ness.
15798
15799 bool sv_destroyable(SV *sv)
15800
15801 "sv_nosharing"
15802 Dummy routine which "shares" an SV when there is no sharing module
15803 present. Or "locks" it. Or "unlocks" it. In other words, ignores
15804 its single SV argument. Exists to avoid test for a "NULL" function
15805 pointer and because it could potentially warn under some level of
15806 strict-ness.
15807
15808 void sv_nosharing(SV *sv)
15809
15811 "new_version"
15812 Returns a new version object based on the passed in SV:
15813
15814 SV *sv = new_version(SV *ver);
15815
15816 Does not alter the passed in ver SV. See "upg_version" if you want
15817 to upgrade the SV.
15818
15819 SV* new_version(SV *ver)
15820
15821 "PERL_REVISION"
15822 "DEPRECATED!" It is planned to remove "PERL_REVISION" from a
15823 future release of Perl. Do not use it for new code; remove it from
15824 existing code.
15825
15826 The major number component of the perl interpreter currently being
15827 compiled or executing. This has been 5 from 1993 into 2020.
15828
15829 Instead use one of the version comparison macros. See
15830 "PERL_VERSION_EQ".
15831
15832 "PERL_SUBVERSION"
15833 "DEPRECATED!" It is planned to remove "PERL_SUBVERSION" from a
15834 future release of Perl. Do not use it for new code; remove it from
15835 existing code.
15836
15837 The micro number component of the perl interpreter currently being
15838 compiled or executing. In stable releases this gives the dot
15839 release number for maintenance updates. In development releases
15840 this gives a tag for a snapshot of the status at various points in
15841 the development cycle.
15842
15843 Instead use one of the version comparison macros. See
15844 "PERL_VERSION_EQ".
15845
15846 "PERL_VERSION"
15847 "DEPRECATED!" It is planned to remove "PERL_VERSION" from a future
15848 release of Perl. Do not use it for new code; remove it from
15849 existing code.
15850
15851 The minor number component of the perl interpreter currently being
15852 compiled or executing. Between 1993 into 2020, this has ranged
15853 from 0 to 33.
15854
15855 Instead use one of the version comparison macros. See
15856 "PERL_VERSION_EQ".
15857
15858 "PERL_VERSION_EQ"
15859 "PERL_VERSION_NE"
15860 "PERL_VERSION_LT"
15861 "PERL_VERSION_LE"
15862 "PERL_VERSION_GT"
15863 "PERL_VERSION_GE"
15864 Returns whether or not the perl currently being compiled has the
15865 specified relationship to the perl given by the parameters. For
15866 example,
15867
15868 #if PERL_VERSION_GT(5,24,2)
15869 code that will only be compiled on perls after v5.24.2
15870 #else
15871 fallback code
15872 #endif
15873
15874 Note that this is usable in making compile-time decisions
15875
15876 You may use the special value '*' for the final number to mean ALL
15877 possible values for it. Thus,
15878
15879 #if PERL_VERSION_EQ(5,31,'*')
15880
15881 means all perls in the 5.31 series. And
15882
15883 #if PERL_VERSION_NE(5,24,'*')
15884
15885 means all perls EXCEPT 5.24 ones. And
15886
15887 #if PERL_VERSION_LE(5,9,'*')
15888
15889 is effectively
15890
15891 #if PERL_VERSION_LT(5,10,0)
15892
15893 This means you don't have to think so much when converting from the
15894 existing deprecated "PERL_VERSION" to using this macro:
15895
15896 #if PERL_VERSION <= 9
15897
15898 becomes
15899
15900 #if PERL_VERSION_LE(5,9,'*')
15901
15902 bool PERL_VERSION_EQ(const U8 major, const U8 minor,
15903 const U8 patch)
15904
15905 "prescan_version"
15906 Validate that a given string can be parsed as a version object, but
15907 doesn't actually perform the parsing. Can use either strict or lax
15908 validation rules. Can optionally set a number of hint variables to
15909 save the parsing code some time when tokenizing.
15910
15911 const char* prescan_version(const char *s, bool strict,
15912 const char** errstr, bool *sqv,
15913 int *ssaw_decimal, int *swidth,
15914 bool *salpha)
15915
15916 "scan_version"
15917 Returns a pointer to the next character after the parsed version
15918 string, as well as upgrading the passed in SV to an RV.
15919
15920 Function must be called with an already existing SV like
15921
15922 sv = newSV(0);
15923 s = scan_version(s, SV *sv, bool qv);
15924
15925 Performs some preprocessing to the string to ensure that it has the
15926 correct characteristics of a version. Flags the object if it
15927 contains an underscore (which denotes this is an alpha version).
15928 The boolean qv denotes that the version should be interpreted as if
15929 it had multiple decimals, even if it doesn't.
15930
15931 const char* scan_version(const char *s, SV *rv, bool qv)
15932
15933 "upg_version"
15934 In-place upgrade of the supplied SV to a version object.
15935
15936 SV *sv = upg_version(SV *sv, bool qv);
15937
15938 Returns a pointer to the upgraded SV. Set the boolean qv if you
15939 want to force this SV to be interpreted as an "extended" version.
15940
15941 SV* upg_version(SV *ver, bool qv)
15942
15943 "vcmp"
15944 Version object aware cmp. Both operands must already have been
15945 converted into version objects.
15946
15947 int vcmp(SV *lhv, SV *rhv)
15948
15949 "vnormal"
15950 Accepts a version object and returns the normalized string
15951 representation. Call like:
15952
15953 sv = vnormal(rv);
15954
15955 NOTE: you can pass either the object directly or the SV contained
15956 within the RV.
15957
15958 The SV returned has a refcount of 1.
15959
15960 SV* vnormal(SV *vs)
15961
15962 "vnumify"
15963 Accepts a version object and returns the normalized floating point
15964 representation. Call like:
15965
15966 sv = vnumify(rv);
15967
15968 NOTE: you can pass either the object directly or the SV contained
15969 within the RV.
15970
15971 The SV returned has a refcount of 1.
15972
15973 SV* vnumify(SV *vs)
15974
15975 "vstringify"
15976 In order to maintain maximum compatibility with earlier versions of
15977 Perl, this function will return either the floating point notation
15978 or the multiple dotted notation, depending on whether the original
15979 version contained 1 or more dots, respectively.
15980
15981 The SV returned has a refcount of 1.
15982
15983 SV* vstringify(SV *vs)
15984
15985 "vverify"
15986 Validates that the SV contains valid internal structure for a
15987 version object. It may be passed either the version object (RV) or
15988 the hash itself (HV). If the structure is valid, it returns the
15989 HV. If the structure is invalid, it returns NULL.
15990
15991 SV *hv = vverify(sv);
15992
15993 Note that it only confirms the bare minimum structure (so as not to
15994 get confused by derived classes which may contain additional hash
15995 entries):
15996
15997 • The SV is an HV or a reference to an HV
15998
15999 • The hash contains a "version" key
16000
16001 • The "version" key has a reference to an AV as its value
16002
16003 SV* vverify(SV *vs)
16004
16006 In all these calls, the "U32 wn" parameters are warning category
16007 constants. You can see the ones currently available in "Category
16008 Hierarchy" in warnings, just capitalize all letters in the names and
16009 prefix them by "WARN_". So, for example, the category "void" used in a
16010 perl program becomes "WARN_VOID" when used in XS code and passed to one
16011 of the calls below.
16012
16013 "ckWARN"
16014 "ckWARN2"
16015 "ckWARN3"
16016 "ckWARN4"
16017 These return a boolean as to whether or not warnings are enabled
16018 for any of the warning category(ies) parameters: "w", "w1", ....
16019
16020 Should any of the categories by default be enabled even if not
16021 within the scope of "use warnings", instead use the "ckWARN_d"
16022 macros.
16023
16024 The categories must be completely independent, one may not be
16025 subclassed from the other.
16026
16027 bool ckWARN (U32 w)
16028 bool ckWARN2(U32 w1, U32 w2)
16029 bool ckWARN3(U32 w1, U32 w2, U32 w3)
16030 bool ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
16031
16032 "ckWARN_d"
16033 "ckWARN2_d"
16034 "ckWARN3_d"
16035 "ckWARN4_d"
16036 Like "ckWARN", but for use if and only if the warning category(ies)
16037 is by default enabled even if not within the scope of
16038 "use warnings".
16039
16040 bool ckWARN_d (U32 w)
16041 bool ckWARN2_d(U32 w1, U32 w2)
16042 bool ckWARN3_d(U32 w1, U32 w2, U32 w3)
16043 bool ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
16044
16045 "ck_warner"
16046 "ck_warner_d"
16047 If none of the warning categories given by "err" are enabled, do
16048 nothing; otherwise call "warner" or "warner_nocontext" with the
16049 passed-in parameters;.
16050
16051 "err" must be one of the "packWARN", "packWARN2", "packWARN3",
16052 "packWARN4" macros populated with the appropriate number of warning
16053 categories.
16054
16055 The two forms differ only in that "ck_warner_d" should be used if
16056 warnings for any of the categories are by default enabled.
16057
16058 NOTE: "ck_warner" must be explicitly called as "Perl_ck_warner"
16059 with an "aTHX_" parameter.
16060
16061 NOTE: "ck_warner_d" must be explicitly called as "Perl_ck_warner_d"
16062 with an "aTHX_" parameter.
16063
16064 void Perl_ck_warner(pTHX_ U32 err, const char* pat, ...)
16065
16066 "CLEAR_ERRSV"
16067 Clear the contents of $@, setting it to the empty string.
16068
16069 This replaces any read-only SV with a fresh SV and removes any
16070 magic.
16071
16072 void CLEAR_ERRSV()
16073
16074 "croak"
16075 "croak_nocontext"
16076 These are XS interfaces to Perl's "die" function.
16077
16078 They take a sprintf-style format pattern and argument list, which
16079 are used to generate a string message. If the message does not end
16080 with a newline, then it will be extended with some indication of
16081 the current location in the code, as described for "mess_sv".
16082
16083 The error message will be used as an exception, by default
16084 returning control to the nearest enclosing "eval", but subject to
16085 modification by a $SIG{__DIE__} handler. In any case, these croak
16086 functions never return normally.
16087
16088 For historical reasons, if "pat" is null then the contents of
16089 "ERRSV" ($@) will be used as an error message or object instead of
16090 building an error message from arguments. If you want to throw a
16091 non-string object, or build an error message in an SV yourself, it
16092 is preferable to use the "croak_sv" function, which does not
16093 involve clobbering "ERRSV".
16094
16095 The two forms differ only in that "croak_nocontext" does not take a
16096 thread context ("aTHX") parameter. It is usually preferred as it
16097 takes up fewer bytes of code than plain "Perl_croak", and time is
16098 rarely a critical resource when you are about to throw an
16099 exception.
16100
16101 NOTE: "croak" must be explicitly called as "Perl_croak" with an
16102 "aTHX_" parameter.
16103
16104 void Perl_croak (pTHX_ const char* pat, ...)
16105 void croak_nocontext(const char* pat, ...)
16106
16107 "croak_no_modify"
16108 This encapsulates a common reason for dying, generating terser
16109 object code than using the generic "Perl_croak". It is exactly
16110 equivalent to "Perl_croak(aTHX_ "%s", PL_no_modify)" (which expands
16111 to something like "Modification of a read-only value attempted").
16112
16113 Less code used on exception code paths reduces CPU cache pressure.
16114
16115 void croak_no_modify()
16116
16117 "croak_sv"
16118 This is an XS interface to Perl's "die" function.
16119
16120 "baseex" is the error message or object. If it is a reference, it
16121 will be used as-is. Otherwise it is used as a string, and if it
16122 does not end with a newline then it will be extended with some
16123 indication of the current location in the code, as described for
16124 "mess_sv".
16125
16126 The error message or object will be used as an exception, by
16127 default returning control to the nearest enclosing "eval", but
16128 subject to modification by a $SIG{__DIE__} handler. In any case,
16129 the "croak_sv" function never returns normally.
16130
16131 To die with a simple string message, the "croak" function may be
16132 more convenient.
16133
16134 void croak_sv(SV *baseex)
16135
16136 "die"
16137 Behaves the same as "croak", except for the return type. It should
16138 be used only where the "OP *" return type is required. The
16139 function never actually returns.
16140
16141 NOTE: "die" must be explicitly called as "Perl_die" with an "aTHX_"
16142 parameter.
16143
16144 OP* Perl_die(pTHX_ const char* pat, ...)
16145
16146 "die_sv"
16147 "die_nocontext"
16148 These ehave the same as "croak_sv", except for the return type. It
16149 should be used only where the "OP *" return type is required. The
16150 functions never actually return.
16151
16152 The two forms differ only in that "die_nocontext" does not take a
16153 thread context ("aTHX") parameter, so is used in situations where
16154 the caller doesn't already have the thread context.
16155
16156 OP* die_sv (SV *baseex)
16157 OP* die_nocontext(const char* pat, ...)
16158
16159 "ERRSV"
16160 Returns the SV for $@, creating it if needed.
16161
16162 SV * ERRSV
16163
16164 "packWARN"
16165 "packWARN2"
16166 "packWARN3"
16167 "packWARN4"
16168 These macros are used to pack warning categories into a single U32
16169 to pass to macros and functions that take a warning category
16170 parameter. The number of categories to pack is given by the name,
16171 with a corresponding number of category parameters passed.
16172
16173 U32 packWARN (U32 w1)
16174 U32 packWARN2(U32 w1, U32 w2)
16175 U32 packWARN3(U32 w1, U32 w2, U32 w3)
16176 U32 packWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
16177
16178 "PL_curcop"
16179 The currently active COP (control op) roughly representing the
16180 current statement in the source.
16181
16182 On threaded perls, each thread has an independent copy of this
16183 variable; each initialized at creation time with the current value
16184 of the creating thread's copy.
16185
16186 COP* PL_curcop
16187
16188 "PL_curstash"
16189 The stash for the package code will be compiled into.
16190
16191 On threaded perls, each thread has an independent copy of this
16192 variable; each initialized at creation time with the current value
16193 of the creating thread's copy.
16194
16195 HV* PL_curstash
16196
16197 "PL_defgv"
16198 The GV representing *_. Useful for access to $_.
16199
16200 On threaded perls, each thread has an independent copy of this
16201 variable; each initialized at creation time with the current value
16202 of the creating thread's copy.
16203
16204 GV * PL_defgv
16205
16206 "SANE_ERRSV"
16207 Clean up ERRSV so we can safely set it.
16208
16209 This replaces any read-only SV with a fresh writable copy and
16210 removes any magic.
16211
16212 void SANE_ERRSV()
16213
16214 "vcroak"
16215 This is an XS interface to Perl's "die" function.
16216
16217 "pat" and "args" are a sprintf-style format pattern and
16218 encapsulated argument list. These are used to generate a string
16219 message. If the message does not end with a newline, then it will
16220 be extended with some indication of the current location in the
16221 code, as described for "mess_sv".
16222
16223 The error message will be used as an exception, by default
16224 returning control to the nearest enclosing "eval", but subject to
16225 modification by a $SIG{__DIE__} handler. In any case, the "croak"
16226 function never returns normally.
16227
16228 For historical reasons, if "pat" is null then the contents of
16229 "ERRSV" ($@) will be used as an error message or object instead of
16230 building an error message from arguments. If you want to throw a
16231 non-string object, or build an error message in an SV yourself, it
16232 is preferable to use the "croak_sv" function, which does not
16233 involve clobbering "ERRSV".
16234
16235 void vcroak(const char* pat, va_list* args)
16236
16237 "vwarn"
16238 This is an XS interface to Perl's "warn" function.
16239
16240 This is like "warn", but "args" are an encapsulated argument list.
16241
16242 Unlike with "vcroak", "pat" is not permitted to be null.
16243
16244 void vwarn(const char* pat, va_list* args)
16245
16246 "vwarner"
16247 This is like "warner", but "args" are an encapsulated argument
16248 list.
16249
16250 void vwarner(U32 err, const char* pat, va_list* args)
16251
16252 "warn"
16253 "warn_nocontext"
16254 These are XS interfaces to Perl's "warn" function.
16255
16256 They take a sprintf-style format pattern and argument list, which
16257 are used to generate a string message. If the message does not end
16258 with a newline, then it will be extended with some indication of
16259 the current location in the code, as described for "mess_sv".
16260
16261 The error message or object will by default be written to standard
16262 error, but this is subject to modification by a $SIG{__WARN__}
16263 handler.
16264
16265 Unlike with "croak", "pat" is not permitted to be null.
16266
16267 The two forms differ only in that "warn_nocontext" does not take a
16268 thread context ("aTHX") parameter, so is used in situations where
16269 the caller doesn't already have the thread context.
16270
16271 NOTE: "warn" must be explicitly called as "Perl_warn" with an
16272 "aTHX_" parameter.
16273
16274 void Perl_warn (pTHX_ const char* pat, ...)
16275 void warn_nocontext(const char* pat, ...)
16276
16277 "warner"
16278 "warner_nocontext"
16279 These output a warning of the specified category (or categories)
16280 given by "err", using the sprintf-style format pattern "pat", and
16281 argument list.
16282
16283 "err" must be one of the "packWARN", "packWARN2", "packWARN3",
16284 "packWARN4" macros populated with the appropriate number of warning
16285 categories. If any of the warning categories they specify is
16286 fatal, a fatal exception is thrown.
16287
16288 In any event a message is generated by the pattern and arguments.
16289 If the message does not end with a newline, then it will be
16290 extended with some indication of the current location in the code,
16291 as described for "mess_sv".
16292
16293 The error message or object will by default be written to standard
16294 error, but this is subject to modification by a $SIG{__WARN__}
16295 handler.
16296
16297 "pat" is not permitted to be null.
16298
16299 The two forms differ only in that "warner_nocontext" does not take
16300 a thread context ("aTHX") parameter, so is used in situations where
16301 the caller doesn't already have the thread context.
16302
16303 These functions differ from the similarly named "warn" functions,
16304 in that the latter are for XS code to unconditionally display a
16305 warning, whereas these are for code that may be compiling a perl
16306 program, and does extra checking to see if the warning should be
16307 fatal.
16308
16309 NOTE: "warner" must be explicitly called as "Perl_warner" with an
16310 "aTHX_" parameter.
16311
16312 void Perl_warner (pTHX_ U32 err, const char* pat, ...)
16313 void warner_nocontext(U32 err, const char* pat, ...)
16314
16315 "warn_sv"
16316 This is an XS interface to Perl's "warn" function.
16317
16318 "baseex" is the error message or object. If it is a reference, it
16319 will be used as-is. Otherwise it is used as a string, and if it
16320 does not end with a newline then it will be extended with some
16321 indication of the current location in the code, as described for
16322 "mess_sv".
16323
16324 The error message or object will by default be written to standard
16325 error, but this is subject to modification by a $SIG{__WARN__}
16326 handler.
16327
16328 To warn with a simple string message, the "warn" function may be
16329 more convenient.
16330
16331 void warn_sv(SV *baseex)
16332
16334 xsubpp compiles XS code into C. See "xsubpp" in perlutil.
16335
16336 "ax"
16337 Variable which is setup by "xsubpp" to indicate the stack base
16338 offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros. The
16339 "dMARK" macro must be called prior to setup the "MARK" variable.
16340
16341 I32 ax
16342
16343 "CLASS"
16344 Variable which is setup by "xsubpp" to indicate the class name for
16345 a C++ XS constructor. This is always a "char*". See "THIS".
16346
16347 char* CLASS
16348
16349 "dAX"
16350 Sets up the "ax" variable. This is usually handled automatically
16351 by "xsubpp" by calling "dXSARGS".
16352
16353 dAX;
16354
16355 "dAXMARK"
16356 Sets up the "ax" variable and stack marker variable "mark". This
16357 is usually handled automatically by "xsubpp" by calling "dXSARGS".
16358
16359 dAXMARK;
16360
16361 "dITEMS"
16362 Sets up the "items" variable. This is usually handled
16363 automatically by "xsubpp" by calling "dXSARGS".
16364
16365 dITEMS;
16366
16367 "dMY_CXT_SV"
16368 Now a placeholder that declares nothing
16369
16370 dMY_CXT_SV;
16371
16372 "dUNDERBAR"
16373 Sets up any variable needed by the "UNDERBAR" macro. It used to
16374 define "padoff_du", but it is currently a noop. However, it is
16375 strongly advised to still use it for ensuring past and future
16376 compatibility.
16377
16378 dUNDERBAR;
16379
16380 "dXSARGS"
16381 Sets up stack and mark pointers for an XSUB, calling "dSP" and
16382 "dMARK". Sets up the "ax" and "items" variables by calling "dAX"
16383 and "dITEMS". This is usually handled automatically by "xsubpp".
16384
16385 dXSARGS;
16386
16387 "dXSI32"
16388 Sets up the "ix" variable for an XSUB which has aliases. This is
16389 usually handled automatically by "xsubpp".
16390
16391 dXSI32;
16392
16393 "items"
16394 Variable which is setup by "xsubpp" to indicate the number of items
16395 on the stack. See "Variable-length Parameter Lists" in perlxs.
16396
16397 I32 items
16398
16399 "ix"
16400 Variable which is setup by "xsubpp" to indicate which of an XSUB's
16401 aliases was used to invoke it. See "The ALIAS: Keyword" in perlxs.
16402
16403 I32 ix
16404
16405 "RETVAL"
16406 Variable which is setup by "xsubpp" to hold the return value for an
16407 XSUB. This is always the proper type for the XSUB. See "The
16408 RETVAL Variable" in perlxs.
16409
16410 type RETVAL
16411
16412 "ST"
16413 Used to access elements on the XSUB's stack.
16414
16415 SV* ST(int ix)
16416
16417 "THIS"
16418 Variable which is setup by "xsubpp" to designate the object in a
16419 C++ XSUB. This is always the proper type for the C++ object. See
16420 "CLASS" and "Using XS With C++" in perlxs.
16421
16422 type THIS
16423
16424 "UNDERBAR"
16425 The SV* corresponding to the $_ variable. Works even if there is a
16426 lexical $_ in scope.
16427
16428 "XS"
16429 Macro to declare an XSUB and its C parameter list. This is handled
16430 by "xsubpp". It is the same as using the more explicit
16431 "XS_EXTERNAL" macro; the latter is preferred.
16432
16433 "XS_EXTERNAL"
16434 Macro to declare an XSUB and its C parameter list explicitly
16435 exporting the symbols.
16436
16437 "XS_INTERNAL"
16438 Macro to declare an XSUB and its C parameter list without exporting
16439 the symbols. This is handled by "xsubpp" and generally preferable
16440 over exporting the XSUB symbols unnecessarily.
16441
16442 "XSPROTO"
16443 Macro used by "XS_INTERNAL" and "XS_EXTERNAL" to declare a function
16444 prototype. You probably shouldn't be using this directly yourself.
16445
16447 The following functions have been flagged as part of the public API,
16448 but are currently undocumented. Use them at your own risk, as the
16449 interfaces are subject to change. Functions that are not listed in
16450 this document are not intended for public use, and should NOT be used
16451 under any circumstances.
16452
16453 If you feel you need to use one of these functions, first send email to
16454 perl5-porters@perl.org <mailto:perl5-porters@perl.org>. It may be that
16455 there is a good reason for the function not being documented, and it
16456 should be removed from this list; or it may just be that no one has
16457 gotten around to documenting it. In the latter case, you will be asked
16458 to submit a patch to document the function. Once your patch is
16459 accepted, it will indicate that the interface is stable (unless it is
16460 explicitly marked otherwise) and usable by you.
16461
16462 amagic_call gv_name_set PerlIO_fill
16463 amagic_deref_call gv_SVadd PerlIO_unread
16464 any_dup he_dup pmop_dump
16465 atfork_lock hek_dup pop_scope
16466 atfork_unlock hv_delayfree_ent pregfree
16467 block_gimme hv_eiter_p ptr_table_fetch
16468 call_atexit hv_eiter_set ptr_table_free
16469 call_list hv_free_ent ptr_table_new
16470 clear_defarray hv_ksplit ptr_table_split
16471 clone_params_del hv_name_set ptr_table_store
16472 clone_params_new hv_placeholders_get push_scope
16473 CvDEPTH hv_placeholders_set re_compile
16474 deb hv_rand_set regdump
16475 deb_nocontext hv_riter_p repeatcpy
16476 debop hv_riter_set rsignal_state
16477 debprofdump init_stacks rvpv_dup
16478 debstack init_tm save_adelete
16479 debstackptrs is_lvalue_sub save_aelem
16480 dirp_dup leave_scope save_aelem_flags
16481 do_aspawn magic_dump save_alloc
16482 do_close markstack_grow save_generic_pvref
16483 do_join mfree save_generic_svref
16484 do_open mg_dup save_hdelete
16485 do_openn mg_size save_helem
16486 doref mro_get_from_name save_helem_flags
16487 do_spawn mro_set_mro save_hints
16488 do_spawn_nowait my_chsize save_op
16489 do_sprintf my_cxt_init save_padsv_and_mortalize
16490 dounwind my_dirfd save_pushi32ptr
16491 dowantarray my_failure_exit save_pushptr
16492 dump_eval my_fflush_all save_pushptrptr
16493 dump_form my_fork save_set_svflags
16494 dump_mstats my_pclose save_shared_pvref
16495 dump_sub my_popen savestack_grow
16496 filter_del my_popen_list savestack_grow_cnt
16497 fp_dup my_socketpair save_vptr
16498 get_context newANONATTRSUB scan_vstring
16499 get_mstats newANONHASH seed
16500 get_op_descs newANONLIST set_context
16501 get_op_names newANONSUB share_hek
16502 get_ppaddr newAVREF si_dup
16503 get_vtbl newCVREF ss_dup
16504 gp_dup newFORM start_subparse
16505 gp_free newGVgen sv_2pvbyte_flags
16506 gp_ref newGVgen_flags sv_2pvutf8_flags
16507 gv_add_by_type newGVREF SvAMAGIC_off
16508 Gv_AMupdate newHVhv SvAMAGIC_on
16509 gv_autoload_pv newHVREF sv_dup
16510 gv_autoload_pvn newIO sv_dup_inc
16511 gv_autoload_sv newMYSUB sv_peek
16512 gv_AVadd newPROG sys_intern_clear
16513 gv_dump new_stackinfo sys_intern_dup
16514 gv_efullname3 newSVREF sys_intern_init
16515 gv_efullname4 op_refcnt_lock taint_env
16516 gv_fullname3 op_refcnt_unlock taint_proper
16517 gv_fullname4 parser_dup unsharepvn
16518 gv_handler perl_alloc_using vdeb
16519 gv_HVadd perl_clone_using
16520 gv_IOadd PerlIO_context_layers
16521
16523 Until May 1997, this document was maintained by Jeff Okamoto
16524 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
16525
16526 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
16527 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
16528 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
16529 Stephen McCamant, and Gurusamy Sarathy.
16530
16531 API Listing originally by Dean Roehrich <roehrich@cray.com>.
16532
16533 Updated to be autogenerated from comments in the source by Benjamin
16534 Stuhl.
16535
16537 config.h, perlapio, perlcall, perlclib, perlfilter, perlguts,
16538 perlintern, perlinterp, perliol, perlmroapi, perlreguts, perlxs
16539
16540
16541
16542perl v5.34.0 2021-10-18 PERLAPI(1)