1PERLAPI(1) Perl Programmers Reference Guide PERLAPI(1)
2
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 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 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 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 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 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 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 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 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 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 The sections in this document currently are
76 "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 The listing below is alphabetical, case insensitive.
137
139 "AV"
140 Described in perlguts.
141 "AvARRAY"
143 Returns a pointer to the AV's internal SV* array.
144 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 SV** AvARRAY(AV* av)
149 "av_clear"
151 Frees all the elements of an array, leaving it empty. The XS
152 equivalent of "@array = ()". See also "av_undef".
153 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 void av_clear(AV *av)
162 "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 Size_t av_count(AV *av)
169 "av_create_and_push"
171 NOTE: "av_create_and_push" is experimental and may change or be
172 removed without notice.
173 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 NOTE: "av_create_and_push" must be explicitly called as
179 "Perl_av_create_and_push" with an "aTHX_" parameter.
180 void Perl_av_create_and_push(pTHX_ AV **const avp,
182 SV *const val)
183 "av_create_and_unshift_one"
185 NOTE: "av_create_and_unshift_one" is experimental and may change or
186 be removed without notice.
187 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 NOTE: "av_create_and_unshift_one" must be explicitly called as
193 "Perl_av_create_and_unshift_one" with an "aTHX_" parameter.
194 SV** Perl_av_create_and_unshift_one(pTHX_ AV **const avp,
196 SV *const val)
197 "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 Perl equivalent: "splice(@myarray, $key, 1, undef)" (with the
205 "splice" in void context if "G_DISCARD" is present).
206 SV* av_delete(AV *av, SSize_t key, I32 flags)
208 "av_exists"
210 Returns true if the element indexed by "key" has been initialized.
211 This relies on the fact that uninitialized array elements are set
213 to "NULL".
214 Perl equivalent: "exists($myarray[$key])".
216 bool av_exists(AV *av, SSize_t key)
218 "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 If the av argument is a tied array then will call the "EXTEND" tied
227 array method with an argument of "(key+1)".
228 void av_extend(AV *av, SSize_t key)
230 "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 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 The rough perl equivalent is $myarray[$key].
242 SV** av_fetch(AV *av, SSize_t key, I32 lval)
244 "AvFILL"
246 Same as "av_top_index" or "av_tindex".
247 SSize_t AvFILL(AV* av)
249 "av_fill"
251 Set the highest index in the array to the given number, equivalent
252 to Perl's "$#array = $fill;".
253 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 void av_fill(AV *av, SSize_t fill)
261 "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 To get the true number of elements in the array, instead use
268 "av_count".
269 SSize_t av_len(AV *av)
271 "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 Perl equivalent: "my @new_array = ($scalar1, $scalar2,
278 $scalar3...);"
279 AV* av_make(SSize_t size, SV **strp)
281 "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 Perl equivalent: "pop(@myarray);"
288 SV* av_pop(AV *av)
290 "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 Perl equivalent: "push @myarray, $val;".
297 void av_push(AV *av, SV *val)
299 "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 Perl equivalent: "shift(@myarray);"
306 SV* av_shift(AV *av)
308 "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 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 Approximate Perl equivalent: "splice(@myarray, $key, 1, $val)".
321 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 SV** av_store(AV *av, SSize_t key, SV *val)
326 "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 They process 'get' magic.
334 The Perl equivalent for these is $#av.
336 Use "av_count" to get the number of elements in an array.
338 SSize_t av_tindex(AV *av)
340 "av_undef"
342 Undefines the array. The XS equivalent of "undef(@array)".
343 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 See "av_clear" for a note about the array possibly being invalid on
349 return.
350 void av_undef(AV *av)
352 "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 Perl equivalent: "unshift @myarray, ((undef) x $num);"
359 void av_unshift(AV *av, SSize_t num)
361 "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 Perl equivalent: "@{"$name"}".
370 NOTE: the "perl_get_av()" form is deprecated.
372 AV* get_av(const char *name, I32 flags)
374 "newAV"
376 Creates a new AV. The reference count is set to 1.
377 Perl equivalent: "my @array;".
379 AV* newAV()
381 "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 Null AV pointer.
388 (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 Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
398 NOTE: the "perl_call_argv()" form is deprecated.
400 I32 call_argv(const char* sub_name, I32 flags, char** argv)
402 "call_method"
404 Performs a callback to the specified Perl method. The blessed
405 object must be on the stack. See perlcall.
406 NOTE: the "perl_call_method()" form is deprecated.
408 I32 call_method(const char* methname, I32 flags)
410 "call_pv"
412 Performs a callback to the specified Perl sub. See perlcall.
413 NOTE: the "perl_call_pv()" form is deprecated.
415 I32 call_pv(const char* sub_name, I32 flags)
417 "call_sv"
419 Performs a callback to the Perl sub specified by the SV.
420 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 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 If the "G_METHOD_NAMED" flag is supplied, "SvPV(sv)" will be used
429 as the name of the method to call.
430 Some other values are treated specially for internal use and should
432 not be depended on.
433 See perlcall.
435 NOTE: the "perl_call_sv()" form is deprecated.
437 I32 call_sv(SV* sv, volatile I32 flags)
439 "ENTER"
441 Opening bracket on a callback. See "LEAVE" and perlcall.
442 ENTER;
444 "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 ENTER_with_name("name");
450 "eval_pv"
452 Tells Perl to "eval" the given string in scalar context and return
453 an SV* result.
454 NOTE: the "perl_eval_pv()" form is deprecated.
456 SV* eval_pv(const char* p, I32 croak_on_error)
458 "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 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 NOTE: the "perl_eval_sv()" form is deprecated.
468 I32 eval_sv(SV* sv, I32 flags)
470 "FREETMPS"
472 Closing bracket for temporaries on a callback. See "SAVETMPS" and
473 perlcall.
474 FREETMPS;
476 "G_ARRAY"
478 Described in perlcall.
479 "G_DISCARD"
481 Described in perlcall.
482 "G_EVAL"
484 Described in perlcall.
485 "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 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 U32 GIMME
496 "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 U32 GIMME_V
503 "G_KEEPERR"
505 Described in perlcall.
506 "G_NOARGS"
508 Described in perlcall.
509 "G_SCALAR"
511 Described in perlcall.
512 "G_VOID"
514 Described in perlcall.
515 "LEAVE"
517 Closing bracket on a callback. See "ENTER" and perlcall.
518 LEAVE;
520 "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 LEAVE_with_name("name");
526 "PL_errgv"
528 Described in perlcall.
529 "SAVETMPS"
531 Opening bracket for temporaries on a callback. See "FREETMPS" and
532 perlcall.
533 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 "(bool)!!(cbool)" in a ternary triggers a bug in xlc on AIX
543 bool cBOOL(bool expr)
545 "I_32"
547 Cast an NV to I32 while avoiding undefined C behavior
548 I32 I_32(NV what)
550 "INT2PTR"
552 Described in perlguts.
553 type INT2PTR(type, int value)
555 "I_V"
557 Cast an NV to IV while avoiding undefined C behavior
558 IV I_V(NV what)
560 "Perl_cpeep_t"
562 Described in perlguts.
563 "PTR2IV"
565 Described in perlguts.
566 IV PTR2IV(void * ptr)
568 "PTR2nat"
570 Described in perlguts.
571 IV PTR2nat(void *)
573 "PTR2NV"
575 Described in perlguts.
576 NV PTR2NV(void * ptr)
578 "PTR2ul"
580 Described in perlguts.
581 unsigned long PTR2ul(void *)
583 "PTR2UV"
585 Described in perlguts.
586 UV PTR2UV(void * ptr)
588 "PTRV"
590 Described in perlguts.
591 "U_32"
593 Cast an NV to U32 while avoiding undefined C behavior
594 U32 U_32(NV what)
596 "U_V"
598 Cast an NV to UV while avoiding undefined C behavior
599 UV U_V(NV what)
601 "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 "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 U8 toFOLD(U8 ch)
626 "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 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 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 "toFOLD_utf8_safe" is now just a different spelling of plain
648 "toFOLD_utf8"
649 UV toFOLD_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
651 "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 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 UV toFOLD_uvchr(UV cp, U8* s, STRLEN* lenp)
665 "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 "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 "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 "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 "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 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 uc = toLOWER_uvchr(cp, s, &len);
715 if (len > UTF8SKIP(s)) { is multiple code points }
716 else { is a single code point }
717 "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 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 "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 U8 toTITLE(U8 ch)
747 "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 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 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 "toTITLE_utf8_safe" is now just a different spelling of plain
769 "toTITLE_utf8"
770 UV toTITLE_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
772 "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 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 UV toTITLE_uvchr(UV cp, U8* s, STRLEN* lenp)
786 "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 U8 toUPPER(int ch)
793 "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 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 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 "toUPPER_utf8_safe" is now just a different spelling of plain
815 "toUPPER_utf8"
816 UV toUPPER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
818 "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 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 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 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 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 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 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 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 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 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 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 "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 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 "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 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 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 "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 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 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 "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 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 "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 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 "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 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 "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 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 "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 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 "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 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 "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 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 "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 bool isOCTAL(UV ch)
1190 "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 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 "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 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 "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 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 "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 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 "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 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 "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 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 "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 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 "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 "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 "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 "HASATTRIBUTE_ALWAYS_INLINE"
1418 Can we handle "GCC" attribute for functions that should always be
1419 inlined.
1420 "HASATTRIBUTE_DEPRECATED"
1422 Can we handle "GCC" attribute for marking deprecated "APIs"
1423 "HASATTRIBUTE_FORMAT"
1425 Can we handle "GCC" attribute for checking printf-style formats
1426 "HASATTRIBUTE_NONNULL"
1428 Can we handle "GCC" attribute for nonnull function parms.
1429 "HASATTRIBUTE_NORETURN"
1431 Can we handle "GCC" attribute for functions that do not return
1432 "HASATTRIBUTE_PURE"
1434 Can we handle "GCC" attribute for pure functions
1435 "HASATTRIBUTE_UNUSED"
1437 Can we handle "GCC" attribute for unused variables and arguments
1438 "HASATTRIBUTE_WARN_UNUSED_RESULT"
1440 Can we handle "GCC" attribute for warning on unused results
1441 "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 "HAS_BUILTIN_CHOOSE_EXPR"
1447 Can we handle "GCC" builtin for compile-time ternary-like
1448 expressions
1449 "HAS_BUILTIN_EXPECT"
1451 Can we handle "GCC" builtin for telling that certain values are
1452 more likely
1453 "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 "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 "HAS_C99_VARIADIC_MACROS"
1465 If defined, the compiler supports C99 variadic macros.
1466 "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 "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 "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 static inline (c99)
1486 static __inline__ (gcc -ansi)
1487 static __inline (MSVC)
1488 static _inline (older MSVC)
1489 static (c89 compilers)
1490 "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 ASSUME(bool expr)
1507 "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 dNOOP;
1514 "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 END_EXTERN_C
1520 "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 Example usage:
1530 EXTERN_C int flock(int fd, int op);
1532 "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 LIKELY(bool expr)
1539 "NOOP"
1541 Do nothing; typically used as a placeholder to replace something
1542 that used to do something.
1543 NOOP;
1545 "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 PERL_UNUSED_ARG(void x);
1554 "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 PERL_UNUSED_CONTEXT;
1562 "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 Example usage:
1571 Signal_t
1573 Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
1574 void *uap PERL_UNUSED_DECL, bool safe)
1575 "PERL_UNUSED_RESULT"
1577 This macro indicates to discard the return value of the function
1578 call inside it, e.g.,
1579 PERL_UNUSED_RESULT(foo(a, b))
1581 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 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 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 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 PERL_UNUSED_RESULT(void x)
1601 "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 PERL_UNUSED_VAR(void x);
1609 "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 ({ statement ... })
1616 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 Example usage:
1624 #ifdef PERL_USE_GCC_BRACE_GROUPS
1626 ...
1627 #else
1628 ...
1629 #endif
1630 "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 START_EXTERN_C
1638 "STATIC"
1640 Described in perlguts.
1641 "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 if (x) STMT_START { ... } STMT_END else ...
1648 Note that you can't return a value out of them, which limits their
1650 utility. But see "PERL_USE_GCC_BRACE_GROUPS".
1651 "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 UNLIKELY(bool expr)
1658 "__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 __ASSERT_(bool expr)
1667
1669 "BhkDISABLE"
1670 NOTE: "BhkDISABLE" is experimental and may change or be removed
1671 without notice.
1672 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 void BhkDISABLE(BHK *hk, which)
1678 "BhkENABLE"
1680 NOTE: "BhkENABLE" is experimental and may change or be removed
1681 without notice.
1682 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 void BhkENABLE(BHK *hk, which)
1689 "BhkENTRY_set"
1691 NOTE: "BhkENTRY_set" is experimental and may change or be removed
1692 without notice.
1693 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 void BhkENTRY_set(BHK *hk, which, void *ptr)
1699 "blockhook_register"
1701 NOTE: "blockhook_register" is experimental and may change or be
1702 removed without notice.
1703 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 NOTE: "blockhook_register" must be explicitly called as
1709 "Perl_blockhook_register" with an "aTHX_" parameter.
1710 void Perl_blockhook_register(pTHX_ BHK *hk)
1712
1714 "aTHX"
1715 Described in perlguts.
1716 "aTHX_"
1718 Described in perlguts.
1719 "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 Now a no-op.
1726 void CPERLscope(void x)
1728 "dTHR"
1730 Described in perlguts.
1731 "dTHX"
1733 Described in perlguts.
1734 "dTHXa"
1736 On threaded perls, set "pTHX" to "a"; on unthreaded perls, do
1737 nothing
1738 "dTHXoa"
1740 Now a synonym for "dTHXa".
1741 "dVAR"
1743 This is now a synonym for dNOOP: declare nothing
1744 "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 "HAS_PTHREAD_ATFORK"
1756 This symbol, if defined, indicates that the "pthread_atfork"
1757 routine is available to setup fork handlers.
1758 "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 "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 "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 "I_MACH_CTHREADS"
1775 This symbol, if defined, indicates to the C program that it should
1776 include mach/cthreads.h.
1777 #ifdef I_MACH_CTHREADS
1779 #include <mach_cthreads.h>
1780 #endif
1781 "I_PTHREAD"
1783 This symbol, if defined, indicates to the C program that it should
1784 include pthread.h.
1785 #ifdef I_PTHREAD
1787 #include <pthread.h>
1788 #endif
1789 "MULTIPLICITY"
1791 This symbol, if defined, indicates that Perl should be built to use
1792 multiplicity.
1793 "OLD_PTHREADS_API"
1795 This symbol, if defined, indicates that Perl should be built to use
1796 the old draft "POSIX" threads "API".
1797 "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 "pTHX"
1806 Described in perlguts.
1807 "pTHX_"
1809 Described in perlguts.
1810 "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 "SVf"
1817 Described in perlguts.
1818 "SVfARG"
1820 Described in perlguts.
1821 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 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 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 const char * cop_fetch_label(COP *const cop, STRLEN *len,
1839 U32 *flags)
1840 "CopFILE"
1842 Returns the name of the file associated with the "COP" "c"
1843 const char * CopFILE(const COP * c)
1845 "CopFILEAV"
1847 Returns the AV associated with the "COP" "c"
1848 AV * CopFILEAV(const COP * c)
1850 "CopFILEGV"
1852 Returns the GV associated with the "COP" "c"
1853 GV * CopFILEGV(const COP * c)
1855 "CopFILEGV_set"
1857 Available only on unthreaded perls. Makes "pv" the name of the
1858 file associated with the "COP" "c"
1859 void CopFILEGV_set(COP * c, GV * gv)
1861 "CopFILE_set"
1863 Makes "pv" the name of the file associated with the "COP" "c"
1864 void CopFILE_set(COP * c, const char * pv)
1866 "CopFILESV"
1868 Returns the SV associated with the "COP" "c"
1869 SV * CopFILESV(const COP * c)
1871 "cophh_2hv"
1873 NOTE: "cophh_2hv" is experimental and may change or be removed
1874 without notice.
1875 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 HV * cophh_2hv(const COPHH *cophh, U32 flags)
1881 "cophh_copy"
1883 NOTE: "cophh_copy" is experimental and may change or be removed
1884 without notice.
1885 Make and return a complete copy of the cop hints hash "cophh".
1887 COPHH * cophh_copy(COPHH *cophh)
1889 "cophh_delete_pv"
1891 NOTE: "cophh_delete_pv" is experimental and may change or be
1892 removed without notice.
1893 Like "cophh_delete_pvn", but takes a nul-terminated string instead
1895 of a string/length pair.
1896 COPHH * cophh_delete_pv(COPHH *cophh, char *key, U32 hash,
1898 U32 flags)
1899 "cophh_delete_pvn"
1901 NOTE: "cophh_delete_pvn" is experimental and may change or be
1902 removed without notice.
1903 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 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 COPHH * cophh_delete_pvn(COPHH *cophh, const char *keypv,
1917 STRLEN keylen, U32 hash, U32 flags)
1918 "cophh_delete_pvs"
1920 NOTE: "cophh_delete_pvs" is experimental and may change or be
1921 removed without notice.
1922 Like "cophh_delete_pvn", but takes a literal string instead of a
1924 string/length pair, and no precomputed hash.
1925 COPHH * cophh_delete_pvs(COPHH *cophh, "key", U32 flags)
1927 "cophh_delete_sv"
1929 NOTE: "cophh_delete_sv" is experimental and may change or be
1930 removed without notice.
1931 Like "cophh_delete_pvn", but takes a Perl scalar instead of a
1933 string/length pair.
1934 COPHH * cophh_delete_sv(COPHH *cophh, SV *key, U32 hash,
1936 U32 flags)
1937 "cophh_exists_pv"
1939 NOTE: "cophh_exists_pv" is experimental and may change or be
1940 removed without notice.
1941 Like "cophh_exists_pvn", but takes a nul-terminated string instead
1943 of a string/length pair.
1944 bool cophh_exists_pv(const COPHH *cophh, const char *key,
1946 U32 hash, U32 flags)
1947 "cophh_exists_pvn"
1949 NOTE: "cophh_exists_pvn" is experimental and may change or be
1950 removed without notice.
1951 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 bool cophh_exists_pvn(const COPHH *cophh, const char *keypv,
1960 STRLEN keylen, U32 hash, U32 flags)
1961 "cophh_exists_pvs"
1963 NOTE: "cophh_exists_pvs" is experimental and may change or be
1964 removed without notice.
1965 Like "cophh_exists_pvn", but takes a literal string instead of a
1967 string/length pair, and no precomputed hash.
1968 bool cophh_exists_pvs(const COPHH *cophh, "key", U32 flags)
1970 "cophh_exists_sv"
1972 NOTE: "cophh_exists_sv" is experimental and may change or be
1973 removed without notice.
1974 Like "cophh_exists_pvn", but takes a Perl scalar instead of a
1976 string/length pair.
1977 bool cophh_exists_sv(const COPHH *cophh, SV *key, U32 hash,
1979 U32 flags)
1980 "cophh_fetch_pv"
1982 NOTE: "cophh_fetch_pv" is experimental and may change or be removed
1983 without notice.
1984 Like "cophh_fetch_pvn", but takes a nul-terminated string instead
1986 of a string/length pair.
1987 SV * cophh_fetch_pv(const COPHH *cophh, const char *key,
1989 U32 hash, U32 flags)
1990 "cophh_fetch_pvn"
1992 NOTE: "cophh_fetch_pvn" is experimental and may change or be
1993 removed without notice.
1994 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 SV * cophh_fetch_pvn(const COPHH *cophh, const char *keypv,
2004 STRLEN keylen, U32 hash, U32 flags)
2005 "cophh_fetch_pvs"
2007 NOTE: "cophh_fetch_pvs" is experimental and may change or be
2008 removed without notice.
2009 Like "cophh_fetch_pvn", but takes a literal string instead of a
2011 string/length pair, and no precomputed hash.
2012 SV * cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags)
2014 "cophh_fetch_sv"
2016 NOTE: "cophh_fetch_sv" is experimental and may change or be removed
2017 without notice.
2018 Like "cophh_fetch_pvn", but takes a Perl scalar instead of a
2020 string/length pair.
2021 SV * cophh_fetch_sv(const COPHH *cophh, SV *key, U32 hash,
2023 U32 flags)
2024 "cophh_free"
2026 NOTE: "cophh_free" is experimental and may change or be removed
2027 without notice.
2028 Discard the cop hints hash "cophh", freeing all resources
2030 associated with it.
2031 void cophh_free(COPHH *cophh)
2033 "cophh_new_empty"
2035 NOTE: "cophh_new_empty" is experimental and may change or be
2036 removed without notice.
2037 Generate and return a fresh cop hints hash containing no entries.
2039 COPHH * cophh_new_empty()
2041 "cophh_store_pv"
2043 NOTE: "cophh_store_pv" is experimental and may change or be removed
2044 without notice.
2045 Like "cophh_store_pvn", but takes a nul-terminated string instead
2047 of a string/length pair.
2048 COPHH * cophh_store_pv(COPHH *cophh, const char *key, U32 hash,
2050 SV *value, U32 flags)
2051 "cophh_store_pvn"
2053 NOTE: "cophh_store_pvn" is experimental and may change or be
2054 removed without notice.
2055 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 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 "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 COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
2076 STRLEN keylen, U32 hash, SV *value,
2077 U32 flags)
2078 "cophh_store_pvs"
2080 NOTE: "cophh_store_pvs" is experimental and may change or be
2081 removed without notice.
2082 Like "cophh_store_pvn", but takes a literal string instead of a
2084 string/length pair, and no precomputed hash.
2085 COPHH * cophh_store_pvs(COPHH *cophh, "key", SV *value,
2087 U32 flags)
2088 "cophh_store_sv"
2090 NOTE: "cophh_store_sv" is experimental and may change or be removed
2091 without notice.
2092 Like "cophh_store_pvn", but takes a Perl scalar instead of a
2094 string/length pair.
2095 COPHH * cophh_store_sv(COPHH *cophh, SV *key, U32 hash,
2097 SV *value, U32 flags)
2098 "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 HV * cop_hints_2hv(const COP *cop, U32 flags)
2105 "cop_hints_exists_pv"
2107 Like "cop_hints_exists_pvn", but takes a nul-terminated string
2108 instead of a string/length pair.
2109 bool cop_hints_exists_pv(const COP *cop, const char *key,
2111 U32 hash, U32 flags)
2112 "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 bool cop_hints_exists_pvn(const COP *cop, const char *keypv,
2122 STRLEN keylen, U32 hash, U32 flags)
2123 "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 bool cop_hints_exists_pvs(const COP *cop, "key", U32 flags)
2129 "cop_hints_exists_sv"
2131 Like "cop_hints_exists_pvn", but takes a Perl scalar instead of a
2132 string/length pair.
2133 bool cop_hints_exists_sv(const COP *cop, SV *key, U32 hash,
2135 U32 flags)
2136 "cop_hints_fetch_pv"
2138 Like "cop_hints_fetch_pvn", but takes a nul-terminated string
2139 instead of a string/length pair.
2140 SV * cop_hints_fetch_pv(const COP *cop, const char *key,
2142 U32 hash, U32 flags)
2143 "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 SV * cop_hints_fetch_pvn(const COP *cop, const char *keypv,
2154 STRLEN keylen, U32 hash, U32 flags)
2155 "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 SV * cop_hints_fetch_pvs(const COP *cop, "key", U32 flags)
2161 "cop_hints_fetch_sv"
2163 Like "cop_hints_fetch_pvn", but takes a Perl scalar instead of a
2164 string/length pair.
2165 SV * cop_hints_fetch_sv(const COP *cop, SV *key, U32 hash,
2167 U32 flags)
2168 "CopLABEL"
2170 Returns the label attached to a cop.
2171 const char * CopLABEL(COP *const cop)
2173 "CopLABEL_len"
2175 Returns the label attached to a cop, and stores its length in bytes
2176 into *len.
2177 const char * CopLABEL_len(COP *const cop, STRLEN *len)
2179 "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 const char * CopLABEL_len_flags(COP *const cop, STRLEN *len,
2186 U32 *flags)
2187 "CopLINE"
2189 Returns the line number in the source code associated with the
2190 "COP" "c"
2191 STRLEN CopLINE(const COP * c)
2193 "CopSTASH"
2195 Returns the stash associated with "c".
2196 HV * CopSTASH(const COP * c)
2198 "CopSTASH_eq"
2200 Returns a boolean as to whether or not "hv" is the stash associated
2201 with "c".
2202 bool CopSTASH_eq(const COP * c, const HV * hv)
2204 "CopSTASHPV"
2206 Returns the package name of the stash associated with "c", or
2207 "NULL" if no associated stash
2208 char * CopSTASHPV(const COP * c)
2210 "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 void CopSTASHPV_set(COP * c, const char * pv)
2216 "CopSTASH_set"
2218 Set the stash associated with "c" to "hv".
2219 bool CopSTASH_set(COP * c, HV * hv)
2221 "cop_store_label"
2223 NOTE: "cop_store_label" is experimental and may change or be
2224 removed without notice.
2225 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 void cop_store_label(COP *const cop, const char *label,
2230 STRLEN len, U32 flags)
2231 "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 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 const char * custom_op_desc(const OP *o)
2247 "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 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 const char * custom_op_name(const OP *o)
2258 "custom_op_register"
2260 Register a custom op. See "Custom Operators" in perlguts.
2261 NOTE: "custom_op_register" must be explicitly called as
2263 "Perl_custom_op_register" with an "aTHX_" parameter.
2264 void Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr,
2266 const XOP *xop)
2267 "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 const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
2275 "XopDISABLE"
2277 Temporarily disable a member of the XOP, by clearing the
2278 appropriate flag.
2279 void XopDISABLE(XOP *xop, which)
2281 "XopENABLE"
2283 Reenable a member of the XOP which has been disabled.
2284 void XopENABLE(XOP *xop, which)
2286 "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 XopENTRY(XOP *xop, which)
2296 "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 XopENTRYCUSTOM(const OP *o, which)
2303 "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 void XopENTRY_set(XOP *xop, which, value)
2311 "XopFLAGS"
2313 Return the XOP's flags.
2314 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 "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 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 const PERL_CONTEXT * caller_cx(I32 level,
2336 const PERL_CONTEXT **dbcxp)
2337 "CvGV"
2339 Returns the GV associated with the CV "sv", reifying it if
2340 necessary.
2341 GV * CvGV(CV *sv)
2343 "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 This also has a special use with XS AUTOLOAD subs. See
2350 "Autoloading with XSUBs" in perlguts.
2351 HV* CvSTASH(CV* cv)
2353 "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 CV* find_runcv(U32 *db_seqp)
2363 "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 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 NOTE: the "perl_get_cv()" form is deprecated.
2382 NOTE: the "perl_get_cvs()" form is deprecated.
2384 NOTE: the "perl_get_cvn_flags()" form is deprecated.
2386 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 "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 Null CV pointer.
2397 (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 void dump_all()
2407 "dump_c_backtrace"
2409 Dumps the C backtrace to the given "fp".
2410 Returns true if a backtrace could be retrieved, false if not.
2412 bool dump_c_backtrace(PerlIO* fp, int max_depth, int skip)
2414 "dump_packsubs"
2416 Dumps the optrees for all visible subroutines in "stash".
2417 void dump_packsubs(const HV* stash)
2419 "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 The appended output looks like:
2426 ...
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 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 The "util.c:1716" is the source code file and line number.
2439 The /usr/bin/perl is obvious (hopefully).
2441 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 SV* get_c_backtrace_dump(int max_depth, int skip)
2448 "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 "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 OPclass op_class(const OP *o)
2459 "op_dump"
2461 Dumps the optree starting at OP "o" to "STDERR".
2462 void op_dump(const OP *o)
2464 "sv_dump"
2466 Dumps the contents of an SV to the "STDERR" filehandle.
2467 For an example of its output, see Devel::Peek.
2469 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 (char *) Perl_form(pTHX_ const char* pat, ...)
2479 can be used any place a string (char *) is required:
2481 char * s = Perl_form("%d.%d",major,minor);
2483 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 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 NOTE: "form" must be explicitly called as "Perl_form" with an
2493 "aTHX_" parameter.
2494 char* Perl_form (pTHX_ const char* pat, ...)
2496 char* form_nocontext(const char* pat, ...)
2497 "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 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 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 NOTE: "mess" must be explicitly called as "Perl_mess" with an
2514 "aTHX_" parameter.
2515 SV* Perl_mess (pTHX_ const char* pat, ...)
2517 SV* mess_nocontext(const char* pat, ...)
2518 "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 "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 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 SV* mess_sv(SV* basemsg, bool consume)
2541 "pv_display"
2543 Similar to
2544 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
2546 except that an additional "\0" will be appended to the string when
2548 len > cur and pv[cur] is "\0".
2549 Note that the final string may be up to 7 chars longer than pvlim.
2551 char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len,
2553 STRLEN pvlim)
2554 "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 If flags contains "PERL_PV_ESCAPE_QUOTE" then any double quotes in
2565 the string will also be escaped.
2566 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 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 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 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 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 Returns a pointer to the escaped text as held by "dsv".
2596 char* pv_escape(SV *dsv, char const * const str,
2598 const STRLEN count, const STRLEN max,
2599 STRLEN * const escaped, const U32 flags)
2600 "pv_pretty"
2602 Converts a string into something presentable, handling escaping via
2603 "pv_escape()" and supporting quoting and ellipses.
2604 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 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 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 Returns a pointer to the prettified text as held by "dsv".
2620 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 "vform"
2627 Like "form" but but the arguments are an encapsulated argument
2628 list.
2629 char* vform(const char* pat, va_list* args)
2631 "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 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 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 CV* cv_clone(CV* proto)
2654 "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 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 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 SV * cv_name(CV *cv, SV *sv, U32 flags)
2671 "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 void cv_undef(CV* cv)
2680 "find_rundefsv"
2682 Returns the global variable $_.
2683 SV* find_rundefsv()
2685 "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 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 Now it always returns "NOT_IN_PAD".
2697 PADOFFSET find_rundefsvoffset()
2699 "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 U32 intro_my()
2706 "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 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 If "PERL_LOADMOD_DENY" is set, the module is loaded as if with "no"
2734 rather than "use".
2735 void load_module(U32 flags, SV* name, SV* ver, ...)
2737 "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 void load_module_nocontext(U32 flags, SV* name, SV* ver, ...)
2744 "my_exit"
2746 A wrapper for the C library exit(3), honoring what "PL_exit_flags"
2747 in perlapi say to do.
2748 void my_exit(U32 status)
2750 "newPADNAMELIST"
2752 NOTE: "newPADNAMELIST" is experimental and may change or be removed
2753 without notice.
2754 Creates a new pad name list. "max" is the highest index for which
2756 space is allocated.
2757 PADNAMELIST * newPADNAMELIST(size_t max)
2759 "newPADNAMEouter"
2761 NOTE: "newPADNAMEouter" is experimental and may change or be
2762 removed without notice.
2763 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 PADNAME * newPADNAMEouter(PADNAME *outer)
2770 "newPADNAMEpvn"
2772 NOTE: "newPADNAMEpvn" is experimental and may change or be removed
2773 without notice.
2774 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 PADNAME * newPADNAMEpvn(const char *s, STRLEN len)
2780 "nothreadhook"
2782 Stub that provides thread hook for perl_destruct when there are no
2783 threads.
2784 int nothreadhook()
2786 "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 One reference count is stolen, so you may need to do
2795 "SvREFCNT_inc(func)".
2796 "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 PADOFFSET pad_add_anon(CV* func, I32 optype)
2802 "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 PADOFFSET pad_add_name_pv(const char *name, const U32 flags,
2808 HV *typestash, HV *ourstash)
2809 "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 "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 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 PADOFFSET pad_add_name_pvn(const char *namepv, STRLEN namelen,
2827 U32 flags, HV *typestash,
2828 HV *ourstash)
2829 "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 PADOFFSET pad_add_name_sv(SV *name, U32 flags, HV *typestash,
2835 HV *ourstash)
2836 "pad_alloc"
2838 NOTE: "pad_alloc" is experimental and may change or be removed
2839 without notice.
2840 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 SVs_PADMY named lexical variable ("my", "our", "state")
2848 SVs_PADTMP unnamed temporary store
2849 SVf_READONLY constant shared between recursion levels
2850 "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 "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 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
2862 "pad_findmy_pv"
2864 Exactly like "pad_findmy_pvn", but takes a nul-terminated string
2865 instead of a string/length pair.
2866 PADOFFSET pad_findmy_pv(const char* name, U32 flags)
2868 "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 PADOFFSET pad_findmy_pvn(const char* namepv, STRLEN namelen,
2879 U32 flags)
2880 "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 PADOFFSET pad_findmy_sv(SV* name, U32 flags)
2886 "padnamelist_fetch"
2888 NOTE: "padnamelist_fetch" is experimental and may change or be
2889 removed without notice.
2890 Fetches the pad name from the given index.
2892 PADNAME * padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
2894 "padnamelist_store"
2896 NOTE: "padnamelist_store" is experimental and may change or be
2897 removed without notice.
2898 Stores the pad name (which may be null) at the given index, freeing
2900 any existing pad name in that slot.
2901 PADNAME ** padnamelist_store(PADNAMELIST *pnl, SSize_t key,
2903 PADNAME *val)
2904 "pad_tidy"
2906 NOTE: "pad_tidy" is experimental and may change or be removed
2907 without notice.
2908 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 padtidy_SUB ordinary subroutine
2915 padtidy_SUBCLONE prototype for lexical closure
2916 padtidy_FORMAT format
2917 void pad_tidy(padtidy_type type)
2919 "perl_alloc"
2921 Allocates a new Perl interpreter. See perlembed.
2922 PerlInterpreter* perl_alloc()
2924 "PERL_ASYNC_CHECK"
2926 Described in perlinterp.
2927 void PERL_ASYNC_CHECK()
2929 "perl_clone"
2931 Create and return a new interpreter by cloning the current one.
2932 "perl_clone" takes these flags as parameters:
2934 "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 "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 "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 PerlInterpreter* perl_clone(PerlInterpreter *proto_perl,
2959 UV flags)
2960 "perl_construct"
2962 Initializes a new Perl interpreter. See perlembed.
2963 void perl_construct(PerlInterpreter *my_perl)
2965 "perl_destruct"
2967 Shuts down a Perl interpreter. See perlembed for a tutorial.
2968 "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 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 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 int perl_destruct(PerlInterpreter *my_perl)
2997 "perl_free"
2999 Releases a Perl interpreter. See perlembed.
3000 void perl_free(PerlInterpreter *my_perl)
3002 "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 "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 "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 "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 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 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 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 int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit,
3063 int argc, char** argv, char** env)
3064 "perl_run"
3066 Tells a Perl interpreter to run its main program. See perlembed
3067 for a tutorial.
3068 "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 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 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 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 int perl_run(PerlInterpreter *my_perl)
3110 "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 void PERL_SYS_INIT(int *argc, char*** argv)
3117 "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 void PERL_SYS_INIT3(int *argc, char*** argv, char*** env)
3124 "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 void PERL_SYS_TERM()
3131 "PL_exit_flags"
3133 Contains flags controlling perl's behaviour on exit():
3134 • "PERL_EXIT_DESTRUCT_END"
3136 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 • "PERL_EXIT_ABORT"
3142 Call "abort()" on exit. This is used internally by perl itself
3144 to abort if exit is called while processing exit.
3145 • "PERL_EXIT_WARN"
3147 Warn on exit.
3149 • "PERL_EXIT_EXPECTED"
3151 Set by the "exit" in perlfunc operator.
3153 U8 PL_exit_flags
3155 "PL_perl_destruct_level"
3157 This value may be set when embedding for full cleanup.
3158 Possible values:
3160 • 0 - none
3162 • 1 - full
3164 • 2 or greater - full with checks.
3166 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 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 signed char PL_perl_destruct_level
3175 "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 NOTE: the "perl_require_pv()" form is deprecated.
3182 void require_pv(const char* pv)
3184 "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 Obsolete form of "UVuf", which you should convert to instead use
3190 const char * UVf
3192 "vload_module"
3194 Like "load_module" but the arguments are an encapsulated argument
3195 list.
3196 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 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 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 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 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 dXCPT;
3234 "JMPENV_JUMP"
3236 Described in perlinterp.
3237 void JMPENV_JUMP(int v)
3239 "JMPENV_PUSH"
3241 Described in perlinterp.
3242 void JMPENV_PUSH(int v)
3244 "PL_restartop"
3246 Described in perlinterp.
3247 "XCPT_CATCH"
3249 Introduces a catch block. See "Exception Handling" in perlguts.
3250 "XCPT_RETHROW"
3252 Rethrows a previously caught exception. See "Exception Handling"
3253 in perlguts.
3254 XCPT_RETHROW;
3256 "XCPT_TRY_END"
3258 Ends a try block. See "Exception Handling" in perlguts.
3259 "XCPT_TRY_START"
3261 Starts a try block. See "Exception Handling" in perlguts.
3262
3264 Also see "List of capability HAS_foo symbols".
3265 "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 "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 "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 "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 "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 "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 "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 void * FILE_base(FILE * f)
3312 "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 Size_t FILE_bufsiz(FILE *f)
3320 "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 Size_t FILE_cnt(FILE * f)
3327 "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 void * FILE_ptr(FILE * f)
3334 "FLEXFILENAMES"
3336 This symbol, if defined, indicates that the system supports
3337 filenames longer than 14 characters.
3338 "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 "HAS_DUP2"
3344 This symbol, if defined, indicates that the "dup2" routine is
3345 available to duplicate file descriptors.
3346 "HAS_DUP3"
3348 This symbol, if defined, indicates that the "dup3" routine is
3349 available to duplicate file descriptors.
3350 "HAS_FAST_STDIO"
3352 This symbol, if defined, indicates that the "fast stdio" is
3353 available to manipulate the stdio buffers directly.
3354 "HAS_FCHDIR"
3356 This symbol, if defined, indicates that the "fchdir" routine is
3357 available to change directory using a file descriptor.
3358 "HAS_FCNTL"
3360 This symbol, if defined, indicates to the C program that the
3361 "fcntl()" function exists.
3362 "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 "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 "HAS_FPOS64_T"
3374 This symbol will be defined if the C compiler supports "fpos64_t".
3375 "HAS_FSTATFS"
3377 This symbol, if defined, indicates that the "fstatfs" routine is
3378 available to stat filesystems by file descriptors.
3379 "HAS_FSTATVFS"
3381 This symbol, if defined, indicates that the "fstatvfs" routine is
3382 available to stat filesystems by file descriptors.
3383 "HAS_GETFSSTAT"
3385 This symbol, if defined, indicates that the "getfsstat" routine is
3386 available to stat filesystems in bulk.
3387 "HAS_GETMNT"
3389 This symbol, if defined, indicates that the "getmnt" routine is
3390 available to get filesystem mount info by filename.
3391 "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 "HAS_HASMNTOPT"
3398 This symbol, if defined, indicates that the "hasmntopt" routine is
3399 available to query the mount options of file systems.
3400 "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 extern off_t lseek(int, off_t, int);
3407 "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 "HAS_OFF64_T"
3414 This symbol will be defined if the C compiler supports "off64_t".
3415 "HAS_OPEN3"
3417 This manifest constant lets the C program know that the three
3418 argument form of open(2) is available.
3419 "HAS_OPENAT"
3421 This symbol is defined if the "openat()" routine is available.
3422 "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 "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 "HAS_READDIR64_R"
3434 This symbol, if defined, indicates that the "readdir64_r" routine
3435 is available to readdir64 re-entrantly.
3436 "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 "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 "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 "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 "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 "HAS_STDIO_STREAM_ARRAY"
3461 This symbol, if defined, tells that there is an array holding the
3462 stdio streams.
3463 "HAS_STRUCT_FS_DATA"
3465 This symbol, if defined, indicates that the "struct fs_data" to do
3466 "statfs()" is supported.
3467 "HAS_STRUCT_STATFS"
3469 This symbol, if defined, indicates that the "struct statfs" to do
3470 "statfs()" is supported.
3471 "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 "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 "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 "I_FCNTL"
3490 This manifest constant tells the C program to include fcntl.h.
3491 #ifdef I_FCNTL
3493 #include <fcntl.h>
3494 #endif
3495 "I_SYS_DIR"
3497 This symbol, if defined, indicates to the C program that it should
3498 include sys/dir.h.
3499 #ifdef I_SYS_DIR
3501 #include <sys_dir.h>
3502 #endif
3503 "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 #ifdef I_SYS_FILE
3509 #include <sys_file.h>
3510 #endif
3511 "I_SYS_NDIR"
3513 This symbol, if defined, indicates to the C program that it should
3514 include sys/ndir.h.
3515 #ifdef I_SYS_NDIR
3517 #include <sys_ndir.h>
3518 #endif
3519 "I_SYS_STATFS"
3521 This symbol, if defined, indicates that sys/statfs.h exists.
3522 #ifdef I_SYS_STATFS
3524 #include <sys_statfs.h>
3525 #endif
3526 "LSEEKSIZE"
3528 This symbol holds the number of bytes used by the "Off_t".
3529 "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 "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 "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 "STDIO_CNT_LVALUE"
3547 This symbol is defined if the "FILE_cnt" macro can be used as an
3548 lvalue.
3549 "STDIO_PTR_LVALUE"
3551 This symbol is defined if the "FILE_ptr" macro can be used as an
3552 lvalue.
3553 "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 "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 "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 "ST_INO_SIGN"
3568 This symbol holds the signedness of "struct stat"'s "st_ino". 1
3569 for unsigned, -1 for signed.
3570 "ST_INO_SIZE"
3572 This variable contains the size of "struct stat"'s "st_ino" in
3573 bytes.
3574 "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 "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 "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 "CASTFLAGS"
3597 This symbol contains flags that say what difficulties the compiler
3598 has casting odd floating values to unsigned long:
3599 0 = ok
3601 1 = couldn't cast < 0
3602 2 = couldn't cast >= 0x80000000
3603 4 = couldn't cast in argument expression list
3604 "CASTNEGFLOAT"
3606 This symbol is defined if the C compiler can cast negative numbers
3607 to unsigned longs, ints and shorts.
3608 "DOUBLE_HAS_INF"
3610 This symbol, if defined, indicates that the double has the
3611 infinity.
3612 "DOUBLE_HAS_NAN"
3614 This symbol, if defined, indicates that the double has the not-a-
3615 number.
3616 "DOUBLE_HAS_NEGATIVE_ZERO"
3618 This symbol, if defined, indicates that the double has the
3619 "negative_zero".
3620 "DOUBLE_HAS_SUBNORMALS"
3622 This symbol, if defined, indicates that the double has the
3623 subnormals (denormals).
3624 "DOUBLEINFBYTES"
3626 This symbol, if defined, is a comma-separated list of hexadecimal
3627 bytes for the double precision infinity.
3628 "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 "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 "DOUBLENANBYTES"
3652 This symbol, if defined, is a comma-separated list of hexadecimal
3653 bytes (0xHH) for the double precision not-a-number.
3654 "DOUBLESIZE"
3656 This symbol contains the size of a double, so that the C
3657 preprocessor can make decisions based on it.
3658 "DOUBLE_STYLE_CRAY"
3660 This symbol, if defined, indicates that the double is the 64-bit
3661 "CRAY" mainframe format.
3662 "DOUBLE_STYLE_IBM"
3664 This symbol, if defined, indicates that the double is the 64-bit
3665 "IBM" mainframe format.
3666 "DOUBLE_STYLE_IEEE"
3668 This symbol, if defined, indicates that the double is the 64-bit
3669 "IEEE" 754.
3670 "DOUBLE_STYLE_VAX"
3672 This symbol, if defined, indicates that the double is the 64-bit
3673 "VAX" format D or G.
3674 "HAS_ATOLF"
3676 This symbol, if defined, indicates that the "atolf" routine is
3677 available to convert strings into long doubles.
3678 "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 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 "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 "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 "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 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 "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 FP_NORMAL Normalized
3728 FP_ZERO Zero
3729 FP_INFINITE Infinity
3730 FP_SUBNORMAL Denormalized
3731 FP_NAN NaN
3732 "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 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 "HAS_FPGETROUND"
3750 This symbol, if defined, indicates that the "fpgetround" routine is
3751 available to get the floating point rounding mode.
3752 "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 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 "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 FP_NORMAL Normalized
3774 FP_ZERO Zero
3775 FP_INFINITE Infinity
3776 FP_SUBNORMAL Denormalized
3777 FP_NAN NaN
3778 "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 "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 "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 "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 "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 "HAS_ISINF"
3804 This symbol, if defined, indicates that the "isinf" routine is
3805 available to check whether a double is an infinity.
3806 "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 "HAS_ISNAN"
3812 This symbol, if defined, indicates that the "isnan" routine is
3813 available to check whether a double is a NaN.
3814 "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 "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 "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 "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 "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 "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 "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 "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 "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 "HAS_LONG_DOUBLE"
3861 This symbol will be defined if the C compiler supports long
3862 doubles.
3863 "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 "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 "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 "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 "HAS_NAN"
3885 This symbol, if defined, indicates that the "nan" routine is
3886 available to generate NaN.
3887 "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 "HAS_REMAINDER"
3894 This symbol, if defined, indicates that the "remainder" routine is
3895 available to return the floating-point "remainder".
3896 "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 "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 "HAS_SQRTL"
3912 This symbol, if defined, indicates that the "sqrtl" routine is
3913 available to do long double square roots.
3914 "HAS_STRTOD_L"
3916 This symbol, if defined, indicates that the "strtod_l" routine is
3917 available to convert strings to long doubles.
3918 "HAS_STRTOLD"
3920 This symbol, if defined, indicates that the "strtold" routine is
3921 available to convert strings to long doubles.
3922 "HAS_STRTOLD_L"
3924 This symbol, if defined, indicates that the "strtold_l" routine is
3925 available to convert strings to long doubles.
3926 "HAS_TRUNC"
3928 This symbol, if defined, indicates that the "trunc" routine is
3929 available to round doubles towards zero.
3930 "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 "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 #ifdef I_FENV
3941 #include <fenv.h>
3942 #endif
3943 "I_QUADMATH"
3945 This symbol, if defined, indicates that quadmath.h exists and
3946 should be included.
3947 #ifdef I_QUADMATH
3949 #include <quadmath.h>
3950 #endif
3951 "LONGDBLINFBYTES"
3953 This symbol, if defined, is a comma-separated list of hexadecimal
3954 bytes for the long double precision infinity.
3955 "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 "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 "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 "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 "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 "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
3995 This symbol, if defined, indicates that the long double is the
3996 128-bit double-double.
3997 "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 "LONG_DOUBLE_STYLE_IEEE_STD"
4004 This symbol, if defined, indicates that the long double is the
4005 128-bit "IEEE" 754.
4006 "LONG_DOUBLE_STYLE_VAX"
4008 This symbol, if defined, indicates that the long double is the
4009 128-bit "VAX" format H.
4010 "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 "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 "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 "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 "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 "NVTYPE"
4040 This symbol defines the C type used for Perl's NV.
4041 "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 Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\n", iv);
4051 use
4053 Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\n", iv);
4055 This keeps you from having to know if, say an IV, needs to be printed
4057 as %d, %ld, or something else.
4058 "IVdf"
4060 This symbol defines the format string used for printing a Perl IV
4061 as a signed decimal integer.
4062 "NVef"
4064 This symbol defines the format string used for printing a Perl NV
4065 using %e-ish floating point format.
4066 "NVff"
4068 This symbol defines the format string used for printing a Perl NV
4069 using %f-ish floating point format.
4070 "NVgf"
4072 This symbol defines the format string used for printing a Perl NV
4073 using %g-ish floating point format.
4074 "PERL_PRIeldbl"
4076 This symbol, if defined, contains the string used by stdio to
4077 format long doubles (format 'e') for output.
4078 "PERL_PRIfldbl"
4080 This symbol, if defined, contains the string used by stdio to
4081 format long doubles (format 'f') for output.
4082 "PERL_PRIgldbl"
4084 This symbol, if defined, contains the string used by stdio to
4085 format long doubles (format 'g') for output.
4086 "PERL_SCNfldbl"
4088 This symbol, if defined, contains the string used by stdio to
4089 format long doubles (format 'f') for input.
4090 "PRINTF_FORMAT_NULL_OK"
4092 Allows "__printf__" format to be null when checking printf-style
4093 "UTF8f"
4095 Described in perlguts.
4096 "UTF8fARG"
4098 Described in perlguts.
4099 UTF8fARG(bool is_utf8, Size_t byte_len, char *str)
4101 "UVof"
4103 This symbol defines the format string used for printing a Perl UV
4104 as an unsigned octal integer.
4105 "UVuf"
4107 This symbol defines the format string used for printing a Perl UV
4108 as an unsigned decimal integer.
4109 "UVXf"
4111 This symbol defines the format string used for printing a Perl UV
4112 as an unsigned hexadecimal integer in uppercase "ABCDEF".
4113 "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 "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 "CHARBITS"
4132 This symbol contains the size of a char, so that the C preprocessor
4133 can make decisions based on it.
4134 "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 "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 "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 "DEFAULT_INC_EXCLUDES_DOT"
4150 This symbol, if defined, removes the legacy default behavior of
4151 including '.' at the end of @"INC".
4152 "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 "EBCDIC"
4160 This symbol, if defined, indicates that this system uses "EBCDIC"
4161 encoding.
4162 "HAS_CSH"
4164 This symbol, if defined, indicates that the C-shell exists.
4165 "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 "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 "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 "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 "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 "HAS_PROCSELFEXE"
4191 This symbol is defined if "PROCSELFEXE_PATH" is a symlink to the
4192 absolute pathname of the executing program.
4193 "HAS_PSEUDOFORK"
4195 This symbol, if defined, indicates that an emulation of the fork
4196 routine is available.
4197 "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 "HAS_SETPGID"
4204 This symbol, if defined, indicates that the "setpgid(pid, gpid)"
4205 routine is available to set process group ID.
4206 "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 "HAS_STRUCT_CMSGHDR"
4215 This symbol, if defined, indicates that the "struct cmsghdr" is
4216 supported.
4217 "HAS_STRUCT_MSGHDR"
4219 This symbol, if defined, indicates that the "struct msghdr" is
4220 supported.
4221 "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 "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 "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 union semun {
4237 int val;
4238 struct semid_ds *buf;
4239 unsigned short *array;
4240 }
4241 "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 #ifdef I_DIRENT
4249 #include <dirent.h>
4250 #endif
4251 "I_POLL"
4253 This symbol, if defined, indicates that poll.h exists and should be
4254 included. (see also "HAS_POLL")
4255 #ifdef I_POLL
4257 #include <poll.h>
4258 #endif
4259 "I_SYS_RESOURCE"
4261 This symbol, if defined, indicates to the C program that it should
4262 include sys/resource.h.
4263 #ifdef I_SYS_RESOURCE
4265 #include <sys_resource.h>
4266 #endif
4267 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 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 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 "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 And, the reentrant capabilities:
4397 "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 Example usage:
4412 #ifdef HAS_STRNLEN
4414 use strnlen()
4415 #else
4416 use an alternative implementation
4417 #endif
4418 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 "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 Example usage:
4440 #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 "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 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 For thread safety, modules should not write directly to this array.
4484 Instead, use the function "wrap_op_checker".
4485 "PL_keyword_plugin"
4487 NOTE: "PL_keyword_plugin" is experimental and may change or be
4488 removed without notice.
4489 Function pointer, pointing at a function used to handle extended
4491 keywords. The function should be declared as
4492 int keyword_plugin_function(pTHX_
4494 char *keyword_ptr, STRLEN keyword_len,
4495 OP **op_ptr)
4496 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 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 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 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 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 For thread safety, modules should not set this variable directly.
4541 Instead, use the function "wrap_keyword_plugin".
4542 "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 For example, the following determines whether the interpreter is in
4550 global destruction:
4551 if (PL_phase == PERL_PHASE_DESTRUCT) {
4553 // we are in global destruction
4554 }
4555 "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 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 GVs are usually found as values in stashes (symbol table hashes) where
4568 Perl stores its global variables.
4569 "gv_autoload4"
4571 Equivalent to "gv_autoload_pvn".
4572 GV* gv_autoload4(HV* stash, const char* name, STRLEN len,
4574 I32 method)
4575 "GvAV"
4577 Return the AV from the GV.
4578 AV* GvAV(GV* gv)
4580 "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 SV* gv_const_sv(GV* gv)
4588 "GvCV"
4590 Return the CV from the GV.
4591 CV* GvCV(GV* gv)
4593 "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 There are currently exactly two differences between these
4600 functions.
4601 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 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 GV* gv_fetchfile (const char* name)
4614 GV* gv_fetchfile_flags(const char *const name, const STRLEN len,
4615 const U32 flags)
4616 "gv_fetchmeth"
4618 Like "gv_fetchmeth_pvn", but lacks a flags parameter.
4619 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len,
4621 I32 level)
4622 "gv_fetchmethod"
4624 See "gv_fetchmethod_autoload".
4625 GV* gv_fetchmethod(HV* stash, const char* name)
4627 "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 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 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 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 GV* gv_fetchmethod_autoload(HV* stash, const char* name,
4651 I32 autoload)
4652 "gv_fetchmeth_autoload"
4654 This is the old form of "gv_fetchmeth_pvn_autoload", which has no
4655 flags parameter.
4656 GV* gv_fetchmeth_autoload(HV* stash, const char* name,
4658 STRLEN len, I32 level)
4659 "gv_fetchmeth_pv"
4661 Exactly like "gv_fetchmeth_pvn", but takes a nul-terminated string
4662 instead of a string/length pair.
4663 GV* gv_fetchmeth_pv(HV* stash, const char* name, I32 level,
4665 U32 flags)
4666 "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 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 The only significant values for "flags" are "GV_SUPER",
4678 "GV_NOUNIVERSAL", and "SVf_UTF8".
4679 "GV_SUPER" indicates that we want to look up the method in the
4681 superclasses of the "stash".
4682 "GV_NOUNIVERSAL" indicates that we do not want to look up the
4684 method in the stash accessible by "UNIVERSAL::".
4685 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 GV* gv_fetchmeth_pvn(HV* stash, const char* name, STRLEN len,
4693 I32 level, U32 flags)
4694 "gv_fetchmeth_pvn_autoload"
4696 Same as "gv_fetchmeth_pvn()", but looks for autoloaded subroutines
4697 too. Returns a glob for the subroutine.
4698 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 Currently, the only significant value for "flags" is "SVf_UTF8".
4704 GV* gv_fetchmeth_pvn_autoload(HV* stash, const char* name,
4706 STRLEN len, I32 level, U32 flags)
4707 "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 GV* gv_fetchmeth_pv_autoload(HV* stash, const char* name,
4713 I32 level, U32 flags)
4714 "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 GV* gv_fetchmeth_sv(HV* stash, SV* namesv, I32 level, U32 flags)
4720 "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 GV* gv_fetchmeth_sv_autoload(HV* stash, SV* namesv, I32 level,
4726 U32 flags)
4727 "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 The only differences are how the input name is specified, and if
4739 'get' magic is normally used in getting that name.
4740 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 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 The flag "GV_NOADD_NOINIT" causes "gv_init_pvn" not be to called if
4757 the GV existed but isn't PVGV.
4758 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 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 In "gv_fetchpv", "nambeg" is a C string, NUL-terminated with no
4769 intermediate NULs.
4770 In "gv_fetchpvs", "name" is a literal C string, hence is enclosed
4772 in double quotes.
4773 "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 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 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 "GvHV"
4796 Return the HV from the GV.
4797 HV* GvHV(GV* gv)
4799 "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 void gv_init(GV* gv, HV* stash, const char* name, STRLEN len,
4806 int multi)
4807 "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 void gv_init_pv(GV* gv, HV* stash, const char* name, U32 flags)
4813 "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 "gv" is the scalar to be converted.
4822 "stash" is the parent stash/package, if any.
4824 "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 "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 void gv_init_pvn(GV* gv, HV* stash, const char* name, STRLEN len,
4837 U32 flags)
4838 "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 void gv_init_sv(GV* gv, HV* stash, SV* namesv, U32 flags)
4845 "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 HV* gv_stashpv(const char* name, I32 flags)
4852 "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 Flags may be one of:
4862 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 The most important of which are probably "GV_ADD" and "SVf_UTF8".
4872 Note, use of "gv_stashsv" instead of "gv_stashpvn" where possible
4874 is strongly recommended for performance reasons.
4875 HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
4877 "gv_stashpvs"
4879 Like "gv_stashpvn", but takes a literal string instead of a
4880 string/length pair.
4881 HV* gv_stashpvs("name", I32 create)
4883 "gv_stashsv"
4885 Returns a pointer to the stash for a specified package. See
4886 "gv_stashpvn".
4887 Note this interface is strongly preferred over "gv_stashpvn" for
4889 performance reasons.
4890 HV* gv_stashsv(SV* sv, I32 flags)
4892 "GvSV"
4894 Return the SV from the GV.
4895 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 SV* GvSV(GV* gv)
4901 "GvSVn"
4903 Like "GvSV", but creates an empty scalar if none already exists.
4904 SV* GvSVn(GV* gv)
4906 "save_gp"
4908 Saves the current GP of gv on the save stack to be restored on
4909 scope exit.
4910 If empty is true, replace the GP with a new GP.
4912 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 void save_gp(GV* gv, I32 empty)
4918 "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 void setdefout(GV* gv)
4927
4929 These functions provide convenient and thread-safe means of
4930 manipulating hook variables.
4931 "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 "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 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 Taken all together, XS code to hook an op checker should typically
4967 look something like this:
4968 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 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 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 "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 NOTE: the "perl_get_hv()" form is deprecated.
5001 HV* get_hv(const char *name, I32 flags)
5003 "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 "HeHASH"
5011 Returns the computed hash stored in the hash entry.
5012 U32 HeHASH(HE* he)
5014 "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 void* HeKEY(HE* he)
5023 "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 STRLEN HeKLEN(HE* he)
5031 "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 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 char* HePV(HE* he, STRLEN len)
5049 "HeSVKEY"
5051 Returns the key as an "SV*", or "NULL" if the hash entry does not
5052 contain an "SV*" key.
5053 SV* HeSVKEY(HE* he)
5055 "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 SV* HeSVKEY_force(HE* he)
5061 "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 SV* HeSVKEY_set(HE* he, SV* sv)
5068 "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 U32 HeUTF8(HE* he)
5077 "HeVAL"
5079 Returns the value slot (type "SV*") stored in the hash entry. Can
5080 be assigned to.
5081 SV *foo= HeVAL(hv);
5083 HeVAL(hv)= sv;
5084 SV* HeVAL(HE* he)
5086 "HV"
5088 Described in perlguts.
5089 "hv_assert"
5091 Check that a hash is in an internally consistent state.
5092 NOTE: "hv_assert" must be explicitly called as "Perl_hv_assert"
5094 with an "aTHX_" parameter.
5095 void Perl_hv_assert(pTHX_ HV *hv)
5097 "hv_bucket_ratio"
5099 NOTE: "hv_bucket_ratio" is experimental and may change or be
5100 removed without notice.
5101 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 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 SV* hv_bucket_ratio(HV *hv)
5113 "hv_clear"
5115 Frees all the elements of a hash, leaving it empty. The XS
5116 equivalent of "%hash = ()". See also "hv_undef".
5117 See "av_clear" for a note about the hash possibly being invalid on
5119 return.
5120 void hv_clear(HV *hv)
5122 "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 void hv_clear_placeholders(HV *hv)
5134 "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 HV * hv_copy_hints_hv(HV *const ohv)
5144 "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 SV* hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
5155 "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 SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
5165 "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 char* HvENAME(HV* stash)
5175 "HvENAMELEN"
5177 Returns the length of the stash's effective name.
5178 STRLEN HvENAMELEN(HV *stash)
5180 "HvENAMEUTF8"
5182 Returns true if the effective name is in UTF-8 encoding.
5183 unsigned char HvENAMEUTF8(HV *stash)
5185 "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 bool hv_exists(HV *hv, const char *key, I32 klen)
5192 "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 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
5199 "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 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 SV** hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
5214 "hv_fetchs"
5216 Like "hv_fetch", but takes a literal string instead of a
5217 string/length pair.
5218 SV** hv_fetchs(HV* tb, "key", I32 lval)
5220 "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 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 HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
5235 "HvFILL"
5237 See "hv_fill".
5238 STRLEN HvFILL(HV *const hv)
5240 "hv_fill"
5242 Returns the number of hash buckets that happen to be in use.
5243 This function is wrapped by the macro "HvFILL".
5245 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 NOTE: "hv_fill" must be explicitly called as "Perl_hv_fill" with an
5252 "aTHX_" parameter.
5253 STRLEN Perl_hv_fill(pTHX_ HV *const hv)
5255 "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 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 I32 hv_iterinit(HV *hv)
5267 "hv_iterkey"
5269 Returns the key from the current position of the hash iterator.
5270 See "hv_iterinit".
5271 char* hv_iterkey(HE* entry, I32* retlen)
5273 "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 SV* hv_iterkeysv(HE* entry)
5280 "hv_iternext"
5282 Returns entries from a hash iterator. See "hv_iterinit".
5283 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 HE* hv_iternext(HV *hv)
5294 "hv_iternextsv"
5296 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in one
5297 operation.
5298 SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
5300 "hv_iternext_flags"
5302 NOTE: "hv_iternext_flags" is experimental and may change or be
5303 removed without notice.
5304 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 HE* hv_iternext_flags(HV *hv, I32 flags)
5316 "hv_iterval"
5318 Returns the value from the current position of the hash iterator.
5319 See "hv_iterkey".
5320 SV* hv_iterval(HV *hv, HE *entry)
5322 "hv_magic"
5324 Adds magic to a hash. See "sv_magic".
5325 void hv_magic(HV *hv, GV *gv, int how)
5327 "HvNAME"
5329 Returns the package name of a stash, or "NULL" if "stash" isn't a
5330 stash. See "SvSTASH", "CvSTASH".
5331 char* HvNAME(HV* stash)
5333 "HvNAMELEN"
5335 Returns the length of the stash's name.
5336 Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them
5338 STRLEN HvNAMELEN(HV *stash)
5340 "HvNAMEUTF8"
5342 Returns true if the name is in UTF-8 encoding.
5343 unsigned char HvNAMEUTF8(HV *stash)
5345 "hv_scalar"
5347 Evaluates the hash in scalar context and returns the result.
5348 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 Note, prior to 5.25 this function returned what is now returned by
5354 the hv_bucket_ratio() function.
5355 SV* hv_scalar(HV *hv)
5357 "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 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 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 SV** hv_store(HV *hv, const char *key, I32 klen, SV *val,
5385 U32 hash)
5386 "hv_stores"
5388 Like "hv_store", but takes a literal string instead of a
5389 string/length pair and omits the hash parameter.
5390 SV** hv_stores(HV* tb, "key", SV* val)
5392 "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 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 HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
5422 "hv_undef"
5424 Undefines the hash. The XS equivalent of "undef(%hash)".
5425 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 See "av_clear" for a note about the hash possibly being invalid on
5431 return.
5432 void hv_undef(HV *hv)
5434 "MGVTBL"
5436 Described in perlguts.
5437 "newHV"
5439 Creates a new HV. The reference count is set to 1.
5440 HV* newHV()
5442 "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 Null HV pointer.
5449 (deprecated - use "(HV *)NULL" instead)
5451 "PERL_HASH"
5453 Described in perlguts.
5454 void PERL_HASH(U32 hash, char *key, STRLEN klen)
5456 "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 "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 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 HV* PL_modglobal
5516
5518 "PerlIO_apply_layers"
5519 Described in perlapio.
5520 int PerlIO_apply_layers(PerlIO *f, const char *mode,
5522 const char *layers)
5523 "PerlIO_binmode"
5525 Described in perlapio.
5526 int PerlIO_binmode(PerlIO *f, int ptype, int imode,
5528 const char *layers)
5529 "PerlIO_canset_cnt"
5531 Described in perlapio.
5532 int PerlIO_canset_cnt(PerlIO *f)
5534 "PerlIO_clearerr"
5536 Described in perlapio.
5537 void PerlIO_clearerr(PerlIO *f)
5539 "PerlIO_close"
5541 Described in perlapio.
5542 int PerlIO_close(PerlIO *f)
5544 "PerlIO_debug"
5546 Described in perlapio.
5547 void PerlIO_debug(const char *fmt, ...)
5549 "PerlIO_eof"
5551 Described in perlapio.
5552 int PerlIO_eof(PerlIO *f)
5554 "PerlIO_error"
5556 Described in perlapio.
5557 int PerlIO_error(PerlIO *f)
5559 "PerlIO_exportFILE"
5561 Described in perlapio.
5562 FILE * PerlIO_exportFILE(PerlIO *f, const char *mode)
5564 "PerlIO_fast_gets"
5566 Described in perlapio.
5567 int PerlIO_fast_gets(PerlIO *f)
5569 "PerlIO_fdopen"
5571 Described in perlapio.
5572 PerlIO* PerlIO_fdopen(int fd, const char *mode)
5574 "PerlIO_fileno"
5576 Described in perlapio.
5577 int PerlIO_fileno(PerlIO *f)
5579 "PerlIO_findFILE"
5581 Described in perlapio.
5582 FILE * PerlIO_findFILE(PerlIO *f)
5584 "PerlIO_flush"
5586 Described in perlapio.
5587 int PerlIO_flush(PerlIO *f)
5589 "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 "PerlIO_getc"
5608 Described in perlapio.
5609 int PerlIO_getc(PerlIO *d)
5611 "PerlIO_getpos"
5613 Described in perlapio.
5614 int PerlIO_getpos(PerlIO *f, SV *save)
5616 "PerlIO_get_base"
5618 Described in perlapio.
5619 STDCHAR * PerlIO_get_base(PerlIO *f)
5621 "PerlIO_get_bufsiz"
5623 Described in perlapio.
5624 SSize_t PerlIO_get_bufsiz(PerlIO *f)
5626 "PerlIO_get_cnt"
5628 Described in perlapio.
5629 SSize_t PerlIO_get_cnt(PerlIO *f)
5631 "PerlIO_get_ptr"
5633 Described in perlapio.
5634 STDCHAR * PerlIO_get_ptr(PerlIO *f)
5636 "PerlIO_has_base"
5638 Described in perlapio.
5639 int PerlIO_has_base(PerlIO *f)
5641 "PerlIO_has_cntptr"
5643 Described in perlapio.
5644 int PerlIO_has_cntptr(PerlIO *f)
5646 "PerlIO_importFILE"
5648 Described in perlapio.
5649 PerlIO* PerlIO_importFILE(FILE *stdio, const char *mode)
5651 "PERLIO_K_BUFFERED"
5653 "PERLIO_K_CANCRLF"
5654 "PERLIO_K_FASTGETS"
5655 "PERLIO_K_MULTIARG"
5656 "PERLIO_K_RAW"
5657 Described in perliol.
5658 "PerlIO_open"
5660 Described in perlapio.
5661 PerlIO* PerlIO_open(const char *path, const char *mode)
5663 "PerlIO_printf"
5665 Described in perlapio.
5666 int PerlIO_printf(PerlIO *f, const char *fmt, ...)
5668 "PerlIO_putc"
5670 Described in perlapio.
5671 int PerlIO_putc(PerlIO *f, int ch)
5673 "PerlIO_puts"
5675 Described in perlapio.
5676 int PerlIO_puts(PerlIO *f, const char *string)
5678 "PerlIO_read"
5680 Described in perlapio.
5681 SSize_t PerlIO_read(PerlIO *f, void *vbuf, Size_t count)
5683 "PerlIO_releaseFILE"
5685 Described in perlapio.
5686 void PerlIO_releaseFILE(PerlIO *f, FILE *stdio)
5688 "PerlIO_reopen"
5690 Described in perlapio.
5691 PerlIO * PerlIO_reopen(const char *path, const char *mode,
5693 PerlIO *old)
5694 "PerlIO_rewind"
5696 Described in perlapio.
5697 void PerlIO_rewind(PerlIO *f)
5699 "PerlIO_seek"
5701 Described in perlapio.
5702 int PerlIO_seek(PerlIO *f, Off_t offset, int whence)
5704 "PerlIO_setlinebuf"
5706 Described in perlapio.
5707 void PerlIO_setlinebuf(PerlIO *f)
5709 "PerlIO_setpos"
5711 Described in perlapio.
5712 int PerlIO_setpos(PerlIO *f, SV *saved)
5714 "PerlIO_set_cnt"
5716 Described in perlapio.
5717 void PerlIO_set_cnt(PerlIO *f, SSize_t cnt)
5719 "PerlIO_set_ptrcnt"
5721 Described in perlapio.
5722 void PerlIO_set_ptrcnt(PerlIO *f, STDCHAR *ptr, SSize_t cnt)
5724 "PerlIO_stderr"
5726 Described in perlapio.
5727 PerlIO * PerlIO_stderr()
5729 "PerlIO_stdin"
5731 Described in perlapio.
5732 PerlIO * PerlIO_stdin()
5734 "PerlIO_stdout"
5736 Described in perlapio.
5737 PerlIO * PerlIO_stdout()
5739 "PerlIO_stdoutf"
5741 Described in perlapio.
5742 int PerlIO_stdoutf(const char *fmt, ...)
5744 "PerlIO_tell"
5746 Described in perlapio.
5747 Off_t PerlIO_tell(PerlIO *f)
5749 "PerlIO_ungetc"
5751 Described in perlapio.
5752 int PerlIO_ungetc(PerlIO *f, int ch)
5754 "PerlIO_vprintf"
5756 Described in perlapio.
5757 int PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args)
5759 "PerlIO_write"
5761 Described in perlapio.
5762 SSize_t PerlIO_write(PerlIO *f, const void *vbuf, Size_t count)
5764 "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 "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 "HAS_LONG_LONG"
5779 This symbol will be defined if the C compiler supports long long.
5780 "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 "HE"
5788 Described in perlguts.
5789 "I8"
5791 "I16"
5792 "I32"
5793 "I64"
5794 "IV"
5795 Described in perlguts.
5796 "I32SIZE"
5798 This symbol contains the "sizeof(I32)".
5799 "I32TYPE"
5801 This symbol defines the C type used for Perl's I32.
5802 "I64SIZE"
5804 This symbol contains the "sizeof(I64)".
5805 "I64TYPE"
5807 This symbol defines the C type used for Perl's I64.
5808 "I16SIZE"
5810 This symbol contains the "sizeof(I16)".
5811 "I16TYPE"
5813 This symbol defines the C type used for Perl's I16.
5814 "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 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 I16 INT16_C(number)
5825 I32 INT32_C(number)
5826 I64 INT64_C(number)
5827 "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 -1LL
5834 See also, for example, "INT32_C".
5836 Use "IV" to declare variables of the maximum usable size on this
5838 platform.
5839 INTMAX_C(number)
5841 "INTSIZE"
5843 This symbol contains the value of "sizeof(int)" so that the C
5844 preprocessor can make decisions based on it.
5845 "I8SIZE"
5847 This symbol contains the "sizeof(I8)".
5848 "I8TYPE"
5850 This symbol defines the C type used for Perl's I8.
5851 "IV_MAX"
5853 The largest signed integer that fits in an IV on this platform.
5854 IV IV_MAX
5856 "IV_MIN"
5858 The negative signed integer furthest away from 0 that fits in an IV
5859 on this platform.
5860 IV IV_MIN
5862 "IVSIZE"
5864 This symbol contains the "sizeof(IV)".
5865 "IVTYPE"
5867 This symbol defines the C type used for Perl's IV.
5868 "line_t"
5870 The typedef to use to declare variables that are to hold line
5871 numbers.
5872 "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 "LONGSIZE"
5879 This symbol contains the value of "sizeof(long)" so that the C
5880 preprocessor can make decisions based on it.
5881 "memzero"
5883 Set the "l" bytes starting at *d to all zeroes.
5884 void memzero(void * d, Size_t l)
5886 "NV"
5888 Described in perlguts.
5889 "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 "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 For signed types, the smallest representable number is the most
5921 negative number, the one furthest away from zero.
5922 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 "SHORTSIZE"
5929 This symbol contains the value of "sizeof(short)" so that the C
5930 preprocessor can make decisions based on it.
5931 "STRLEN"
5933 Described in perlguts.
5934 "U8"
5936 "U16"
5937 "U32"
5938 "U64"
5939 "UV"
5940 Described in perlguts.
5941 "U32SIZE"
5943 This symbol contains the "sizeof(U32)".
5944 "U32TYPE"
5946 This symbol defines the C type used for Perl's U32.
5947 "U64SIZE"
5949 This symbol contains the "sizeof(U64)".
5950 "U64TYPE"
5952 This symbol defines the C type used for Perl's U64.
5953 "U16SIZE"
5955 This symbol contains the "sizeof(U16)".
5956 "U16TYPE"
5958 This symbol defines the C type used for Perl's U16.
5959 "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 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 U16 UINT16_C(number)
5971 U32 UINT32_C(number)
5972 U64 UINT64_C(number)
5973 "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 1UL
5980 See also, for example, "UINT32_C".
5982 Use "UV" to declare variables of the maximum usable size on this
5984 platform.
5985 UINTMAX_C(number)
5987 "U8SIZE"
5989 This symbol contains the "sizeof(U8)".
5990 "U8TYPE"
5992 This symbol defines the C type used for Perl's U8.
5993 "UV_MAX"
5995 The largest unsigned integer that fits in a UV on this platform.
5996 UV UV_MAX
5998 "UV_MIN"
6000 The smallest unsigned integer that fits in a UV on this platform.
6001 It should equal zero.
6002 UV UV_MIN
6004 "UVSIZE"
6006 This symbol contains the "sizeof(UV)".
6007 "UVTYPE"
6009 This symbol defines the C type used for Perl's UV.
6010 "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 WIDEST_UTYPE my_uv;
6016 or casts
6018 my_uv = (WIDEST_UTYPE) val;
6020
6022 This is the lower layer of the Perl parser, managing characters and
6023 tokens.
6024 "lex_bufutf8"
6026 NOTE: "lex_bufutf8" is experimental and may change or be removed
6027 without notice.
6028 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 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 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 bool lex_bufutf8()
6051 "lex_discard_to"
6053 NOTE: "lex_discard_to" is experimental and may change or be removed
6054 without notice.
6055 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 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 void lex_discard_to(char* ptr)
6072 "lex_grow_linestr"
6074 NOTE: "lex_grow_linestr" is experimental and may change or be
6075 removed without notice.
6076 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 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 char* lex_grow_linestr(STRLEN len)
6089 "lex_next_chunk"
6091 NOTE: "lex_next_chunk" is experimental and may change or be removed
6092 without notice.
6093 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 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 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 bool lex_next_chunk(U32 flags)
6112 "lex_peek_unichar"
6114 NOTE: "lex_peek_unichar" is experimental and may change or be
6115 removed without notice.
6116 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 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 If the input is being interpreted as UTF-8 and a UTF-8 encoding
6129 error is encountered, an exception is generated.
6130 I32 lex_peek_unichar(U32 flags)
6132 "lex_read_space"
6134 NOTE: "lex_read_space" is experimental and may change or be removed
6135 without notice.
6136 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 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 void lex_read_space(U32 flags)
6149 "lex_read_to"
6151 NOTE: "lex_read_to" is experimental and may change or be removed
6152 without notice.
6153 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 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 void lex_read_to(char* ptr)
6164 "lex_read_unichar"
6166 NOTE: "lex_read_unichar" is experimental and may change or be
6167 removed without notice.
6168 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 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 If the input is being interpreted as UTF-8 and a UTF-8 encoding
6183 error is encountered, an exception is generated.
6184 I32 lex_read_unichar(U32 flags)
6186 "lex_start"
6188 NOTE: "lex_start" is experimental and may change or be removed
6189 without notice.
6190 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 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 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 void lex_start(SV* line, PerlIO *rsfp, U32 flags)
6213 "lex_stuff_pv"
6215 NOTE: "lex_stuff_pv" is experimental and may change or be removed
6216 without notice.
6217 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 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 void lex_stuff_pv(const char* pv, U32 flags)
6235 "lex_stuff_pvn"
6237 NOTE: "lex_stuff_pvn" is experimental and may change or be removed
6238 without notice.
6239 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 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 void lex_stuff_pvn(const char* pv, STRLEN len, U32 flags)
6257 "lex_stuff_pvs"
6259 NOTE: "lex_stuff_pvs" is experimental and may change or be removed
6260 without notice.
6261 Like "lex_stuff_pvn", but takes a literal string instead of a
6263 string/length pair.
6264 void lex_stuff_pvs("pv", U32 flags)
6266 "lex_stuff_sv"
6268 NOTE: "lex_stuff_sv" is experimental and may change or be removed
6269 without notice.
6270 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 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 void lex_stuff_sv(SV* sv, U32 flags)
6286 "lex_unstuff"
6288 NOTE: "lex_unstuff" is experimental and may change or be removed
6289 without notice.
6290 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 This is not the normal way to consume lexed text. For that, use
6297 "lex_read_to".
6298 void lex_unstuff(char* ptr)
6300 "parse_arithexpr"
6302 NOTE: "parse_arithexpr" is experimental and may change or be
6303 removed without notice.
6304 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 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 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 OP* parse_arithexpr(U32 flags)
6328 "parse_barestmt"
6330 NOTE: "parse_barestmt" is experimental and may change or be removed
6331 without notice.
6332 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 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 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 The "flags" parameter is reserved for future use, and must always
6356 be zero.
6357 OP* parse_barestmt(U32 flags)
6359 "parse_block"
6361 NOTE: "parse_block" is experimental and may change or be removed
6362 without notice.
6363 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 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 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 The "flags" parameter is reserved for future use, and must always
6386 be zero.
6387 OP* parse_block(U32 flags)
6389 "parse_fullexpr"
6391 NOTE: "parse_fullexpr" is experimental and may change or be removed
6392 without notice.
6393 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 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 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 OP* parse_fullexpr(U32 flags)
6418 "parse_fullstmt"
6420 NOTE: "parse_fullstmt" is experimental and may change or be removed
6421 without notice.
6422 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 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 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 The "flags" parameter is reserved for future use, and must always
6444 be zero.
6445 OP* parse_fullstmt(U32 flags)
6447 "parse_label"
6449 NOTE: "parse_label" is experimental and may change or be removed
6450 without notice.
6451 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 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 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 SV* parse_label(U32 flags)
6469 "parse_listexpr"
6471 NOTE: "parse_listexpr" is experimental and may change or be removed
6472 without notice.
6473 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 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 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 OP* parse_listexpr(U32 flags)
6497 "parse_stmtseq"
6499 NOTE: "parse_stmtseq" is experimental and may change or be removed
6500 without notice.
6501 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 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 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 The "flags" parameter is reserved for future use, and must always
6526 be zero.
6527 OP* parse_stmtseq(U32 flags)
6529 "parse_subsignature"
6531 NOTE: "parse_subsignature" is experimental and may change or be
6532 removed without notice.
6533 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 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 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 The "flags" parameter is reserved for future use, and must always
6552 be zero.
6553 OP* parse_subsignature(U32 flags)
6555 "parse_termexpr"
6557 NOTE: "parse_termexpr" is experimental and may change or be removed
6558 without notice.
6559 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 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 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 OP* parse_termexpr(U32 flags)
6583 "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 "PL_parser->bufend"
6592 NOTE: "PL_parser->bufend" is experimental and may change or be
6593 removed without notice.
6594 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 "PL_parser->bufptr"
6602 NOTE: "PL_parser->bufptr" is experimental and may change or be
6603 removed without notice.
6604 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 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 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 "PL_parser->linestart"
6623 NOTE: "PL_parser->linestart" is experimental and may change or be
6624 removed without notice.
6625 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 "PL_parser->linestr"
6632 NOTE: "PL_parser->linestr" is experimental and may change or be
6633 removed without notice.
6634 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 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 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 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 "wrap_keyword_plugin"
6661 NOTE: "wrap_keyword_plugin" is experimental and may change or be
6662 removed without notice.
6663 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 "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 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 Taken all together, XS code to install a keyword plugin should
6697 typically look something like this:
6698 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 Direct access to "PL_keyword_plugin" should be avoided.
6716 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 void DECLARATION_FOR_LC_NUMERIC_MANIPULATION
6730 "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 I32 foldEQ_locale(const char* a, const char* b, I32 len)
6737 "HAS_DUPLOCALE"
6739 This symbol, if defined, indicates that the "duplocale" routine is
6740 available to duplicate a locale object.
6741 "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 "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 "HAS_LOCALECONV"
6753 This symbol, if defined, indicates that the "localeconv" routine is
6754 available for numeric and monetary formatting conventions.
6755 "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 "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 "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 "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 "HAS_SETLOCALE"
6775 This symbol, if defined, indicates that the "setlocale" routine is
6776 available to handle locale-specific ctype implementations.
6777 "HAS_SETLOCALE_R"
6779 This symbol, if defined, indicates that the "setlocale_r" routine
6780 is available to setlocale re-entrantly.
6781 "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 "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 "I_LANGINFO"
6791 This symbol, if defined, indicates that langinfo.h exists and
6792 should be included.
6793 #ifdef I_LANGINFO
6795 #include <langinfo.h>
6796 #endif
6797 "I_LOCALE"
6799 This symbol, if defined, indicates to the C program that it should
6800 include locale.h.
6801 #ifdef I_LOCALE
6803 #include <locale.h>
6804 #endif
6805 "IN_LOCALE"
6807 Evaluates to TRUE if the plain locale pragma without a parameter
6808 ("use locale") is in effect.
6809 bool IN_LOCALE
6811 "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 bool IN_LOCALE_COMPILETIME
6818 "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 bool IN_LOCALE_RUNTIME
6825 "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 #ifdef I_XLOCALE
6831 #include <xlocale.h>
6832 #endif
6833 "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 Expanding on these:
6843 • 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 • 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 • 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 • 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 • 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 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 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 When using "Perl_langinfo" on systems that don't have a native
6906 "nl_langinfo()", you must
6907 #include "perl_langinfo.h"
6909 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 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 const char* Perl_langinfo(const nl_item item)
6925 "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 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 Finally, "Perl_setlocale" works under all circumstances, whereas
6946 plain "setlocale" can be completely ineffective on some platforms
6947 under some configurations.
6948 "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 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 const char* Perl_setlocale(const int category,
6961 const char* locale)
6962 "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 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 {
6976 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
6977 ...
6978 RESTORE_LC_NUMERIC();
6979 ...
6980 }
6981 void RESTORE_LC_NUMERIC()
6983 "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 "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 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 {
7003 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7004 ...
7005 STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
7006 ...
7007 RESTORE_LC_NUMERIC();
7008 ...
7009 }
7010 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 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 void STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
7020 "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 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 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 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 {
7045 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7046 ...
7047 STORE_LC_NUMERIC_SET_TO_NEEDED();
7048 ...
7049 RESTORE_LC_NUMERIC();
7050 ...
7051 }
7052 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 void STORE_LC_NUMERIC_SET_TO_NEEDED()
7060 "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 void STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric)
7069 "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 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 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 POSIX::localeconv
7090 I18N::Langinfo, items "CRNCYSTR" and "THOUSEP"
7091 "Perl_langinfo" in perlapi, items "CRNCYSTR" and "THOUSEP"
7092 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 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 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 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 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 void switch_to_global_locale()
7118 "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 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 bool sync_locale()
7137 "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 WITH_LC_NUMERIC_SET_TO_NEEDED(
7144 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
7145 );
7146 is equivalent to:
7148 {
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 void WITH_LC_NUMERIC_SET_TO_NEEDED(block)
7161 "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 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 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 "mg_clear"
7189 Clear something magical that the SV represents. See "sv_magic".
7190 int mg_clear(SV* sv)
7192 "mg_copy"
7194 Copies the magic from one SV to another. See "sv_magic".
7195 int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
7197 "mg_find"
7199 Finds the magic pointer for "type" matching the SV. See
7200 "sv_magic".
7201 MAGIC* mg_find(const SV* sv, int type)
7203 "mg_findext"
7205 Finds the magic pointer of "type" with the given "vtbl" for the
7206 "SV". See "sv_magicext".
7207 MAGIC* mg_findext(const SV* sv, int type, const MGVTBL *vtbl)
7209 "mg_free"
7211 Free any magic storage used by the SV. See "sv_magic".
7212 int mg_free(SV* sv)
7214 "mg_freeext"
7216 Remove any magic of type "how" using virtual table "vtbl" from the
7217 SV "sv". See "sv_magic".
7218 "mg_freeext(sv, how, NULL)" is equivalent to "mg_free_type(sv,
7220 how)".
7221 void mg_freeext(SV* sv, int how, const MGVTBL *vtbl)
7223 "mg_free_type"
7225 Remove any magic of type "how" from the SV "sv". See "sv_magic".
7226 void mg_free_type(SV* sv, int how)
7228 "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 int mg_get(SV* sv)
7234 "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 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 U32 mg_length(SV* sv)
7247 "mg_magical"
7249 Turns on the magical status of an SV. See "sv_magic".
7250 void mg_magical(SV* sv)
7252 "mg_set"
7254 Do magic after a value is assigned to the SV. See "sv_magic".
7255 int mg_set(SV* sv)
7257 "SvTIED_obj"
7259 Described in perlinterp.
7260 SvTIED_obj(SV *sv, MAGIC *mg)
7262
7264 "HASATTRIBUTE_MALLOC"
7265 Can we handle "GCC" attribute for malloc-style functions.
7266 "HAS_MALLOC_GOOD_SIZE"
7268 This symbol, if defined, indicates that the "malloc_good_size"
7269 routine is available for use.
7270 "HAS_MALLOC_SIZE"
7272 This symbol, if defined, indicates that the "malloc_size" routine
7273 is available for use.
7274 "I_MALLOCMALLOC"
7276 This symbol, if defined, indicates to the C program that it should
7277 include malloc/malloc.h.
7278 #ifdef I_MALLOCMALLOC
7280 #include <mallocmalloc.h>
7281 #endif
7282 "MYMALLOC"
7284 This symbol, if defined, indicates that we're using our own malloc.
7285 "Newx"
7287 The XSUB-writer's interface to the C "malloc" function.
7288 Memory obtained by this should ONLY be freed with "Safefree".
7290 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 void Newx(void* ptr, int nitems, type)
7299 "Newxc"
7301 The XSUB-writer's interface to the C "malloc" function, with cast.
7302 See also "Newx".
7303 Memory obtained by this should ONLY be freed with "Safefree".
7305 void Newxc(void* ptr, int nitems, type, cast)
7307 "Newxz"
7309 The XSUB-writer's interface to the C "malloc" function. The
7310 allocated memory is zeroed with "memzero". See also "Newx".
7311 Memory obtained by this should ONLY be freed with "Safefree".
7313 void Newxz(void* ptr, int nitems, type)
7315 "PERL_MALLOC_WRAP"
7317 This symbol, if defined, indicates that we'd like malloc wrap
7318 checks.
7319 "Renew"
7321 The XSUB-writer's interface to the C "realloc" function.
7322 Memory obtained by this should ONLY be freed with "Safefree".
7324 void Renew(void* ptr, int nitems, type)
7326 "Renewc"
7328 The XSUB-writer's interface to the C "realloc" function, with cast.
7329 Memory obtained by this should ONLY be freed with "Safefree".
7331 void Renewc(void* ptr, int nitems, type, cast)
7333 "Safefree"
7335 The XSUB-writer's interface to the C "free" function.
7336 This should ONLY be used on memory obtained using "Newx" and
7338 friends.
7339 void Safefree(void* ptr)
7341 "safesyscalloc"
7343 Safe version of system's calloc()
7344 Malloc_t safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
7346 "safesysfree"
7348 Safe version of system's free()
7349 Free_t safesysfree(Malloc_t where)
7351 "safesysmalloc"
7353 Paranoid version of system's malloc()
7354 Malloc_t safesysmalloc(MEM_SIZE nbytes)
7356 "safesysrealloc"
7358 Paranoid version of system's realloc()
7359 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 "HvMROMETA"
7367 Described in perlmroapi.
7368 struct mro_meta * HvMROMETA(HV *hv)
7370 "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 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 AV* mro_get_linear_isa(HV* stash)
7382 "MRO_GET_PRIVATE_DATA"
7384 Described in perlmroapi.
7385 SV* MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta,
7387 const struct mro_alg *const which)
7388 "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 Ideally, all instances of "PL_sub_generation++" in perl source
7394 outside of mro.c should be replaced by calls to this.
7395 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 1) Directly manipulating the stash HV entries from XS code.
7402 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 This same method is available from pure perl via,
7408 "mro::method_changed_in(classname)".
7409 void mro_method_changed_in(HV* stash)
7411 "mro_register"
7413 Registers a custom mro plugin. See perlmroapi for details on this
7414 and other mro functions.
7415 NOTE: "mro_register" must be explicitly called as
7417 "Perl_mro_register" with an "aTHX_" parameter.
7418 void Perl_mro_register(pTHX_ const struct mro_alg *mro)
7420 "mro_set_private_data"
7422 Described in perlmroapi.
7423 NOTE: "mro_set_private_data" must be explicitly called as
7425 "Perl_mro_set_private_data" with an "aTHX_" parameter.
7426 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 dMULTICALL;
7438 "MULTICALL"
7440 Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in
7441 perlcall.
7442 MULTICALL;
7444 "POP_MULTICALL"
7446 Closing bracket for a lightweight callback. See "LIGHTWEIGHT
7447 CALLBACKS" in perlcall.
7448 POP_MULTICALL;
7450 "PUSH_MULTICALL"
7452 Opening bracket for a lightweight callback. See "LIGHTWEIGHT
7453 CALLBACKS" in perlcall.
7454 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 double Drand01()
7466 "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 d_Gconvert='gconvert((x),(n),(t),(b))'
7478 d_Gconvert='gcvt((x),(n),(b))'
7479 d_Gconvert='sprintf((b),"%.*g",(n),(x))'
7480 The last two assume trailing zeros should not be kept.
7482 char * Gconvert(double x, Size_t n, bool t, char * b)
7484 "grok_bin"
7486 converts a string representing a binary number to numeric form.
7487 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 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 The binary number may optionally be prefixed with "0b" or "b"
7504 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
7505 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 UV grok_bin(const char* start, STRLEN* len_p, I32* flags,
7511 NV *result)
7512 "grok_hex"
7514 converts a string representing a hex number to numeric form.
7515 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 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 The hex number may optionally be prefixed with "0x" or "x" unless
7532 "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
7533 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 UV grok_hex(const char* start, STRLEN* len_p, I32* flags,
7539 NV *result)
7540 "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 IS_NUMBER_INFINITY
7547 IS_NUMBER_NAN
7548 IS_NUMBER_INFINITY | IS_NUMBER_NEG
7549 IS_NUMBER_NAN | IS_NUMBER_NEG
7550 0
7551 possibly |-ed with "IS_NUMBER_TRAILING".
7553 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 int grok_infnan(const char** sp, const char *send)
7559 "grok_number"
7561 Identical to "grok_number_flags()" with "flags" set to zero.
7562 int grok_number(const char *pv, STRLEN len, UV *valuep)
7564 "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 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 "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 "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 int grok_number_flags(const char *pv, STRLEN len, UV *valuep,
7592 U32 flags)
7593 "GROK_NUMERIC_RADIX"
7595 A synonym for "grok_numeric_radix"
7596 bool GROK_NUMERIC_RADIX(NN const char **sp, NN const char *send)
7598 "grok_numeric_radix"
7600 Scan and skip for a numeric decimal separator (radix).
7601 bool grok_numeric_radix(const char **sp, const char *send)
7603 "grok_oct"
7605 converts a string representing an octal number to numeric form.
7606 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 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 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 The "PERL_SCAN_DISALLOW_PREFIX" flag is always treated as being set
7627 for this function.
7628 UV grok_oct(const char* start, STRLEN* len_p, I32* flags,
7630 NV *result)
7631 "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 This is also the logical inverse of Perl_isfinite().
7638 bool isinfnan(NV nv)
7640 "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 N.B. "s" must be NUL terminated.
7648 NV my_atof(const char *s)
7650 "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 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 The synonym Strtod() may be used instead.
7663 NV my_strtod(const char * const s, char ** e)
7665 "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 int PERL_ABS(int x)
7674 "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 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 "Perl_signbit"
7731 NOTE: "Perl_signbit" is experimental and may change or be removed
7732 without notice.
7733 Return a non-zero integer if the sign bit on an NV is set, and 0 if
7735 it is not.
7736 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 "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 int Perl_signbit(NV f)
7753 "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 "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 U8 READ_XDIGIT(char str*)
7772 "scan_bin"
7774 For backwards compatibility. Use "grok_bin" instead.
7775 NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
7777 "scan_hex"
7779 For backwards compatibility. Use "grok_hex" instead.
7780 NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
7782 "scan_oct"
7784 For backwards compatibility. Use "grok_oct" instead.
7785 NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
7787 "seedDrand01"
7789 This symbol defines the macro to be used in seeding the random
7790 number generator (see "Drand01").
7791 void seedDrand01(Rand_seed_t x)
7793 "Strtod"
7795 This is a synonym for "my_strtod".
7796 NV Strtod(NN const char * const s, NULLOK char ** e)
7798 "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 NV Strtol(NN const char * const s, NULLOK char ** e, int base)
7806 "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 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 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 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 OP* newASSIGNOP(I32 flags, OP* left, I32 optype, OP* right)
7836 "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 OP* newBINOP(I32 type, I32 flags, OP* first, OP* last)
7848 "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 OP* newCONDOP(I32 flags, OP* first, OP* trueop, OP* falseop)
7860 "newDEFSVOP"
7862 Constructs and returns an op to access $_.
7863 OP* newDEFSVOP()
7865 "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 "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 "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 OP* newFOROP(I32 flags, OP* sv, OP* expr, OP* block, OP* cont)
7886 "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 OP* newGIVENOP(OP* cond, OP* block, PADOFFSET defsv_off)
7896 "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 OP* newGVOP(I32 type, I32 flags, GV* gv)
7905 "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 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 OP* newLISTOP(I32 type, I32 flags, OP* first, OP* last)
7921 "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 OP* newLOGOP(I32 optype, I32 flags, OP *first, OP *other)
7933 "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 OP* newLOOPEX(I32 type, OP* label)
7941 "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 OP* newLOOPOP(I32 flags, I32 debuggable, OP* expr, OP* block)
7955 "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 OP* newMETHOP(I32 type, I32 flags, OP* dynamic_meth)
7967 "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 OP* newMETHOP_named(I32 type, I32 flags, SV* const_meth)
7977 "newNULLLIST"
7979 Constructs, checks, and returns a new "stub" op, which represents
7980 an empty list expression.
7981 OP* newNULLLIST()
7983 "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 OP* newOP(I32 optype, I32 flags)
7991 "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 This function only exists if Perl has been compiled to use
8000 ithreads.
8001 OP* newPADOP(I32 type, I32 flags, SV* sv)
8003 "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 OP* newPMOP(I32 type, I32 flags)
8010 "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 OP* newPVOP(I32 type, I32 flags, char* pv)
8020 "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 OP* newRANGE(I32 flags, OP* left, OP* right)
8032 "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 OP* newSLICEOP(I32 flags, OP* subscript, OP* listop)
8043 "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 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 OP* newSTATEOP(I32 flags, char* label, OP* o)
8060 "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 OP* newSVOP(I32 type, I32 flags, SV* sv)
8068 "newTRYCATCHOP"
8070 NOTE: "newTRYCATCHOP" is experimental and may change or be removed
8071 without notice.
8072 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 The "flags" argument is currently ignored.
8083 OP* newTRYCATCHOP(I32 flags, OP* tryblock, OP *catchvar,
8085 OP* catchblock)
8086 "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 OP* newUNOP(I32 type, I32 flags, OP* first)
8097 "newUNOP_AUX"
8099 Similar to "newUNOP", but creates an "UNOP_AUX" struct instead,
8100 with "op_aux" initialised to "aux"
8101 OP* newUNOP_AUX(I32 type, I32 flags, OP* first,
8103 UNOP_AUX_item *aux)
8104 "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 OP* newWHENOP(OP* cond, OP* block)
8114 "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 "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 "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 OP* newWHILEOP(I32 flags, I32 debuggable, LOOP* loop, OP* expr,
8136 OP* block, OP* cont, I32 has_my)
8137 "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 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 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 Perl_ophook_t PL_opfreehook
8154 "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 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 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 peep_t PL_peepp
8178 "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 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 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 peep_t PL_rpeepp
8202
8204 "alloccopstash"
8205 NOTE: "alloccopstash" is experimental and may change or be removed
8206 without notice.
8207 Available only under threaded builds, this function allocates an
8209 entry in "PL_stashpad" for the stash passed to it.
8210 PADOFFSET alloccopstash(HV *hv)
8212 "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 OP* block_end(I32 floor, OP* seq)
8219 "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 int block_start(int full)
8227 "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 OP* ck_entersub_args_list(OP *entersubop)
8237 "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 "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 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 OP* ck_entersub_args_proto(OP *entersubop, GV *namegv,
8263 SV *protosv)
8264 "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 "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 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 OP* ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
8291 SV *protosv)
8292 "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 Constant subs can be created with "newCONSTSUB" or as described in
8298 "Constant Functions" in perlsub.
8299 SV* cv_const_sv(const CV *const cv)
8301 "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 void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
8309 SV **ckobj_p)
8310 "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 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 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
8323 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 "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 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 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 "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 void cv_get_call_checker_flags(CV *cv, U32 gflags,
8361 Perl_call_checker *ckfun_p,
8362 SV **ckobj_p, U32 *ckflags_p)
8363 "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 void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
8371 SV *ckobj)
8372 "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 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 STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
8384 It is intended to be called in this manner:
8386 entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
8388 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 "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 "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 The current setting for a particular CV can be retrieved by
8407 "cv_get_call_checker_flags".
8408 void cv_set_call_checker_flags(CV *cv, Perl_call_checker ckfun,
8410 SV *ckobj, U32 ckflags)
8411 "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 OP* LINKLIST(OP *o)
8420 "newATTRSUB"
8422 Construct a Perl subroutine, also performing some surrounding jobs.
8423 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 CV* newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs, OP *block)
8431 "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 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
8438 "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 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 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 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 "flags" should not have bits set other than "SVf_UTF8".
8479 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 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 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 CV* newCONSTSUB_flags(HV* stash, const char* name, STRLEN len,
8509 U32 flags, SV* sv)
8510 "newSUB"
8512 Like "newATTRSUB", but without attributes.
8513 CV* newSUB(I32 floor, OP* o, OP* proto, OP* block)
8515 "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 "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 OP* op_append_elem(I32 optype, OP* first, OP* last)
8530 "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 OP* op_append_list(I32 optype, OP* first, OP* last)
8540 "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 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 U32 OP_CLASS(OP *o)
8553 "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 OP* op_contextualize(OP* o, I32 context)
8561 "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 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 OP* op_convert_list(I32 optype, I32 flags, OP* o)
8572 "OP_DESC"
8574 Return a short description of the provided OP.
8575 const char * OP_DESC(OP *o)
8577 "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 void op_free(OP* arg)
8583 "OpHAS_SIBLING"
8585 Returns true if "o" has a sibling
8586 bool OpHAS_SIBLING(OP *o)
8588 "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 void OpLASTSIB_set(OP *o, OP *parent)
8595 "op_linklist"
8597 This function is the implementation of the "LINKLIST" macro. It
8598 should not be called directly.
8599 OP* op_linklist(OP *o)
8601 "op_lvalue"
8603 NOTE: "op_lvalue" is experimental and may change or be removed
8604 without notice.
8605 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 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 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 OP* op_lvalue(OP* o, I32 type)
8622 "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 void OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
8629 "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 void OpMORESIB_set(OP *o, OP *sib)
8636 "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 const char * OP_NAME(OP *o)
8642 "op_null"
8644 Neutralizes an op when it is no longer needed, but is still linked
8645 to from other ops.
8646 void op_null(OP* o)
8648 "op_parent"
8650 Returns the parent OP of "o", if it has a parent. Returns "NULL"
8651 otherwise.
8652 OP* op_parent(OP *o)
8654 "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 OP* op_prepend_elem(I32 optype, OP* first, OP* last)
8664 "op_scope"
8666 NOTE: "op_scope" is experimental and may change or be removed
8667 without notice.
8668 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 OP* op_scope(OP* o)
8678 "OpSIBLING"
8680 Returns the sibling of "o", or "NULL" if there is no sibling
8681 OP* OpSIBLING(OP *o)
8683 "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 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 "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 "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 "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 "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 The head of the chain of deleted ops is returned, or "NULL" if no
8716 ops were deleted.
8717 For example:
8719 action before after returns
8721 ------ ----- ----- -------
8722 P P
8724 splice(P, A, 2, X-Y-Z) | | B-C
8725 A-B-C-D A-X-Y-Z-D
8726 P P
8728 splice(P, NULL, 1, X-Y) | | A
8729 A-B-C-D X-Y-B-C-D
8730 P P
8732 splice(P, NULL, 3, NULL) | | A-B-C
8733 A-B-C-D D
8734 P P
8736 splice(P, B, 0, X-Y) | | NULL
8737 A-B-C-D A-B-X-Y-C-D
8738 For lower-level direct manipulation of "op_sibparent" and
8740 "op_moresib", see "OpMORESIB_set", "OpLASTSIB_set",
8741 "OpMAYBESIB_set".
8742 OP* op_sibling_splice(OP *parent, OP *start, int del_count,
8744 OP* insert)
8745 "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 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 bool OP_TYPE_IS(OP *o, Optype type)
8755 "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 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 bool OP_TYPE_IS_OR_WAS(OP *o, Optype type)
8766 "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 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 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 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 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 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 void pack_cat(SV *cat, const char *pat, const char *patend,
8818 SV **beglist, SV **endlist, SV ***next_in_list,
8819 U32 flags)
8820 "packlist"
8822 The engine implementing "pack()" Perl function.
8823 void packlist(SV *cat, const char *pat, const char *patend,
8825 SV **beglist, SV **endlist)
8826 "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 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 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 "unpackstring"
8842 The engine implementing the "unpack()" Perl function.
8843 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 The "strend" and "patend" pointers should point to the byte
8851 following the last character of each string.
8852 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 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 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 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 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 The PADLIST has a C array where pads are stored.
8883 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 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 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 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 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 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 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 my ($x, $x); # '"my" variable $x masks earlier declaration'
8932 my $x = $x; # equal to my $x = $::x;
8933 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 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 If the 'name' is "&" the corresponding entry in the PAD is a CV
8951 representing a possible closure.
8952 Note that formats are treated as anon subs, and are cloned each
8954 time write is called (if necessary).
8955 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 { my $x = 1; sub f { eval '$x'} } f();
8961 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 PADLIST * CvPADLIST(CV *cv)
8967 "pad_add_name_pvs"
8969 Exactly like "pad_add_name_pvn", but takes a literal string instead
8970 of a string/length pair.
8971 PADOFFSET pad_add_name_pvs("name", U32 flags, HV *typestash,
8973 HV *ourstash)
8974 "PadARRAY"
8976 NOTE: "PadARRAY" is experimental and may change or be removed
8977 without notice.
8978 The C array of pad entries.
8980 SV ** PadARRAY(PAD * pad)
8982 "pad_findmy_pvs"
8984 Exactly like "pad_findmy_pvn", but takes a literal string instead
8985 of a string/length pair.
8986 PADOFFSET pad_findmy_pvs("name", U32 flags)
8988 "PadlistARRAY"
8990 NOTE: "PadlistARRAY" is experimental and may change or be removed
8991 without notice.
8992 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 PAD ** PadlistARRAY(PADLIST * padlist)
8998 "PadlistMAX"
9000 NOTE: "PadlistMAX" is experimental and may change or be removed
9001 without notice.
9002 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 SSize_t PadlistMAX(PADLIST * padlist)
9008 "PadlistNAMES"
9010 NOTE: "PadlistNAMES" is experimental and may change or be removed
9011 without notice.
9012 The names associated with pad entries.
9014 PADNAMELIST * PadlistNAMES(PADLIST * padlist)
9016 "PadlistNAMESARRAY"
9018 NOTE: "PadlistNAMESARRAY" is experimental and may change or be
9019 removed without notice.
9020 The C array of pad names.
9022 PADNAME ** PadlistNAMESARRAY(PADLIST * padlist)
9024 "PadlistNAMESMAX"
9026 NOTE: "PadlistNAMESMAX" is experimental and may change or be
9027 removed without notice.
9028 The index of the last pad name.
9030 SSize_t PadlistNAMESMAX(PADLIST * padlist)
9032 "PadlistREFCNT"
9034 NOTE: "PadlistREFCNT" is experimental and may change or be removed
9035 without notice.
9036 The reference count of the padlist. Currently this is always 1.
9038 U32 PadlistREFCNT(PADLIST * padlist)
9040 "PadMAX"
9042 NOTE: "PadMAX" is experimental and may change or be removed without
9043 notice.
9044 The index of the last pad entry.
9046 SSize_t PadMAX(PAD * pad)
9048 "PadnameLEN"
9050 NOTE: "PadnameLEN" is experimental and may change or be removed
9051 without notice.
9052 The length of the name.
9054 STRLEN PadnameLEN(PADNAME * pn)
9056 "PadnamelistARRAY"
9058 NOTE: "PadnamelistARRAY" is experimental and may change or be
9059 removed without notice.
9060 The C array of pad names.
9062 PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl)
9064 "PadnamelistMAX"
9066 NOTE: "PadnamelistMAX" is experimental and may change or be removed
9067 without notice.
9068 The index of the last pad name.
9070 SSize_t PadnamelistMAX(PADNAMELIST * pnl)
9072 "PadnamelistREFCNT"
9074 NOTE: "PadnamelistREFCNT" is experimental and may change or be
9075 removed without notice.
9076 The reference count of the pad name list.
9078 SSize_t PadnamelistREFCNT(PADNAMELIST * pnl)
9080 "PadnamelistREFCNT_dec"
9082 NOTE: "PadnamelistREFCNT_dec" is experimental and may change or be
9083 removed without notice.
9084 Lowers the reference count of the pad name list.
9086 void PadnamelistREFCNT_dec(PADNAMELIST * pnl)
9088 "PadnamePV"
9090 NOTE: "PadnamePV" is experimental and may change or be removed
9091 without notice.
9092 The name stored in the pad name struct. This returns "NULL" for a
9094 target slot.
9095 char * PadnamePV(PADNAME * pn)
9097 "PadnameREFCNT"
9099 NOTE: "PadnameREFCNT" is experimental and may change or be removed
9100 without notice.
9101 The reference count of the pad name.
9103 SSize_t PadnameREFCNT(PADNAME * pn)
9105 "PadnameREFCNT_dec"
9107 NOTE: "PadnameREFCNT_dec" is experimental and may change or be
9108 removed without notice.
9109 Lowers the reference count of the pad name.
9111 void PadnameREFCNT_dec(PADNAME * pn)
9113 "PadnameSV"
9115 NOTE: "PadnameSV" is experimental and may change or be removed
9116 without notice.
9117 Returns the pad name as a mortal SV.
9119 SV * PadnameSV(PADNAME * pn)
9121 "PadnameUTF8"
9123 NOTE: "PadnameUTF8" is experimental and may change or be removed
9124 without notice.
9125 Whether PadnamePV is in UTF-8. Currently, this is always true.
9127 bool PadnameUTF8(PADNAME * pn)
9129 "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 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 PADLIST* pad_new(int flags)
9140 "PL_comppad"
9142 NOTE: "PL_comppad" is experimental and may change or be removed
9143 without notice.
9144 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 "PL_comppad_name"
9153 NOTE: "PL_comppad_name" is experimental and may change or be
9154 removed without notice.
9155 During compilation, this points to the array containing the names
9157 part of the pad for the currently-compiling code.
9158 "PL_curpad"
9160 NOTE: "PL_curpad" is experimental and may change or be removed
9161 without notice.
9162 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 "HAS_ENDGRENT"
9172 This symbol, if defined, indicates that the getgrent routine is
9173 available for finalizing sequential access of the group database.
9174 "HAS_ENDGRENT_R"
9176 This symbol, if defined, indicates that the "endgrent_r" routine is
9177 available to endgrent re-entrantly.
9178 "HAS_ENDPWENT"
9180 This symbol, if defined, indicates that the getgrent routine is
9181 available for finalizing sequential access of the passwd database.
9182 "HAS_ENDPWENT_R"
9184 This symbol, if defined, indicates that the "endpwent_r" routine is
9185 available to endpwent re-entrantly.
9186 "HAS_GETGRENT"
9188 This symbol, if defined, indicates that the "getgrent" routine is
9189 available for sequential access of the group database.
9190 "HAS_GETGRENT_R"
9192 This symbol, if defined, indicates that the "getgrent_r" routine is
9193 available to getgrent re-entrantly.
9194 "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 "HAS_GETPWENT_R"
9201 This symbol, if defined, indicates that the "getpwent_r" routine is
9202 available to getpwent re-entrantly.
9203 "HAS_SETGRENT"
9205 This symbol, if defined, indicates that the "setgrent" routine is
9206 available for initializing sequential access of the group database.
9207 "HAS_SETGRENT_R"
9209 This symbol, if defined, indicates that the "setgrent_r" routine is
9210 available to setgrent re-entrantly.
9211 "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 "HAS_SETPWENT_R"
9218 This symbol, if defined, indicates that the "setpwent_r" routine is
9219 available to setpwent re-entrantly.
9220 "PWAGE"
9222 This symbol, if defined, indicates to the C program that "struct
9223 passwd" contains "pw_age".
9224 "PWCHANGE"
9226 This symbol, if defined, indicates to the C program that "struct
9227 passwd" contains "pw_change".
9228 "PWCLASS"
9230 This symbol, if defined, indicates to the C program that "struct
9231 passwd" contains "pw_class".
9232 "PWCOMMENT"
9234 This symbol, if defined, indicates to the C program that "struct
9235 passwd" contains "pw_comment".
9236 "PWEXPIRE"
9238 This symbol, if defined, indicates to the C program that "struct
9239 passwd" contains "pw_expire".
9240 "PWGECOS"
9242 This symbol, if defined, indicates to the C program that "struct
9243 passwd" contains "pw_gecos".
9244 "PWPASSWD"
9246 This symbol, if defined, indicates to the C program that "struct
9247 passwd" contains "pw_passwd".
9248 "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 "LOC_SED"
9258 This symbol holds the complete pathname to the sed program.
9259 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 extern int dbminit(char *);
9443 "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 extern double drand48(void);
9450 "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 extern int flock(int, int);
9457 "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 "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 "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 "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 "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 "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 extern void* sbrk(int);
9493 extern void* sbrk(size_t);
9494 "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 extern int setresgid(uid_t ruid, uid_t euid, uid_t suid);
9501 "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 extern int setresuid(uid_t ruid, uid_t euid, uid_t suid);
9508 "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 "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 extern int sockatmark(int);
9523 "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 extern int syscall(int, ...);
9530 extern int syscall(long, ...);
9531 "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 extern long telldir(DIR*);
9538 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 REGEXP* pregcomp(SV * const pattern, const U32 flags)
9621 "pregexec"
9623 Described in perlreguts.
9624 I32 pregexec(REGEXP * const prog, char* stringarg, char* strend,
9626 char* strbeg, SSize_t minend, SV* screamer,
9627 U32 nosave)
9628 "re_dup_guts"
9630 Duplicate a regexp.
9631 This routine is expected to clone a given regexp structure. It is
9633 only compiled under USE_ITHREADS.
9634 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 void re_dup_guts(const REGEXP *sstr, REGEXP *dstr,
9641 CLONE_PARAMS* param)
9642 "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 "SvRX"
9652 Convenience macro to get the REGEXP from a SV. This is
9653 approximately equivalent to the following snippet:
9654 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 "NULL" will be returned if a REGEXP* is not found.
9663 REGEXP * SvRX(SV *sv)
9665 "SvRXOK"
9667 Returns a boolean indicating whether the SV (or the one it
9668 references) is a REGEXP.
9669 If you want to do something with the REGEXP* later use SvRX instead
9671 and check for NULL.
9672 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 "HAS_SIGINFO_SI_BAND"
9681 This symbol, if defined, indicates that "siginfo_t" has the
9682 "si_band" member
9683 "HAS_SIGINFO_SI_ERRNO"
9685 This symbol, if defined, indicates that "siginfo_t" has the
9686 "si_errno" member
9687 "HAS_SIGINFO_SI_PID"
9689 This symbol, if defined, indicates that "siginfo_t" has the
9690 "si_pid" member
9691 "HAS_SIGINFO_SI_STATUS"
9693 This symbol, if defined, indicates that "siginfo_t" has the
9694 "si_status" member
9695 "HAS_SIGINFO_SI_UID"
9697 This symbol, if defined, indicates that "siginfo_t" has the
9698 "si_uid" member
9699 "HAS_SIGINFO_SI_VALUE"
9701 This symbol, if defined, indicates that "siginfo_t" has the
9702 "si_value" member
9703 "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 U32 PERL_SIGNALS_UNSAFE_FLAG
9710 "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 Sighandler_t rsignal(int i, Sighandler_t t)
9717 "Sigjmp_buf"
9719 This is the buffer type to be used with Sigsetjmp and Siglongjmp.
9720 "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 void Siglongjmp(jmp_buf env, int val)
9727 "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 char *sig_name[] = { SIG_NAME };
9734 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 "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 int sig_num[] = { SIG_NUM };
9752 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 "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 int Sigsetjmp(jmp_buf env, int savesigs)
9770 "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 "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 They differ only in the source of the signal name:
9783 "whichsig_pv" takes the name from the "NUL"-terminated string
9785 starting at "sig".
9786 "whichsig" is merely a different spelling, a synonym, of
9788 "whichsig_pv".
9789 "whichsig_pvn" takes the name from the string starting at "sig",
9791 with length "len" bytes.
9792 "whichsig_sv" takes the name from the PV stored in the SV "sigsv".
9794 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 "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 "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 "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 "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 "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 "INSTALL_USR_BIN_PERL"
9834 This symbol, if defined, indicates that Perl is to be installed
9835 also as /usr/bin/perl.
9836 "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 "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 "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 "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 "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 "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 "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 MakeMaker Makefile.PL INSTALLDIRS=vendor
9882 or equivalent. See "INSTALL" for details.
9884 "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 "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 "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 "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 "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 "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 MakeMaker Makefile.PL
9922 or equivalent. See "INSTALL" for details.
9924 "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 "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 MakeMaker Makefile.PL
9940 or equivalent. See "INSTALL" for details.
9942 "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 "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 "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 "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 "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 "USE_BSD_GETPGRP"
9977 This symbol, if defined, indicates that getpgrp needs one arguments
9978 whereas "USG" one needs none.
9979 "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 "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 "USE_CROSS_COMPILE"
9990 This symbol, if defined, indicates that Perl is being cross-
9991 compiled.
9992 "USE_C_BACKTRACE"
9994 This symbol, if defined, indicates that Perl should be built with
9995 support for backtrace.
9996 "USE_DTRACE"
9998 This symbol, if defined, indicates that Perl should be built with
9999 support for DTrace.
10000 "USE_DYNAMIC_LOADING"
10002 This symbol, if defined, indicates that dynamic loading of some
10003 sort is available.
10004 "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 "USE_ITHREADS"
10011 This symbol, if defined, indicates that Perl should be built to use
10012 the interpreter-based threading implementation.
10013 "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 "USE_LARGE_FILES"
10020 This symbol, if defined, indicates that large file support should
10021 be used when available.
10022 "USE_LONG_DOUBLE"
10024 This symbol, if defined, indicates that long doubles should be used
10025 when available.
10026 "USE_MORE_BITS"
10028 This symbol, if defined, indicates that 64-bit interfaces and long
10029 doubles should be used when available.
10030 "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 "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 "USE_QUADMATH"
10042 This symbol, if defined, indicates that the quadmath library should
10043 be used when available.
10044 "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 "USE_SEMCTL_SEMID_DS"
10051 This symbol, if defined, indicates that "struct semid_ds" * is used
10052 for semctl "IPC_STAT".
10053 "USE_SEMCTL_SEMUN"
10055 This symbol, if defined, indicates that "union semun" is used for
10056 semctl "IPC_STAT".
10057 "USE_SITECUSTOMIZE"
10059 This symbol, if defined, indicates that sitecustomize should be
10060 used.
10061 "USE_SOCKS"
10063 This symbol, if defined, indicates that Perl should be built to use
10064 socks.
10065 "USE_STAT_BLOCKS"
10067 This symbol is defined if this system has a stat structure
10068 declaring "st_blksize" and "st_blocks".
10069 "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 "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 "USE_STRICT_BY_DEFAULT"
10087 This symbol, if defined, enables additional defaults. At this time
10088 it only enables implicit strict by default.
10089 "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 "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 "HAS_SOCKADDR_STORAGE"
10107 This symbol, if defined, indicates the availability of "struct
10108 sockaddr_storage";
10109 "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 "HAS_SOCKET"
10115 This symbol, if defined, indicates that the "BSD" "socket"
10116 interface is supported.
10117 "HAS_SOCKETPAIR"
10119 This symbol, if defined, indicates that the "BSD" "socketpair()"
10120 call is supported.
10121 "HAS_SOCKS5_INIT"
10123 This symbol, if defined, indicates that the "socks5_init" routine
10124 is available to initialize "SOCKS" 5.
10125 "I_SOCKS"
10127 This symbol, if defined, indicates that socks.h exists and should
10128 be included.
10129 #ifdef I_SOCKS
10131 #include <socks.h>
10132 #endif
10133 "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 #ifdef I_SYS_SOCKIO
10139 #include <sys_sockio.h>
10140 #endif
10141
10143 "filter_add"
10144 Described in perlfilter.
10145 SV* filter_add(filter_t funcp, SV* datasv)
10147 "filter_read"
10149 Described in perlfilter.
10150 I32 filter_read(int idx, SV *buf_sv, int maxlen)
10152
10154 "BHK"
10155 Described in perlguts.
10156 "BINOP"
10158 Described in perlguts.
10159 "DESTRUCTORFUNC_NOCONTEXT_t"
10161 Described in perlguts.
10162 "DESTRUCTORFUNC_t"
10164 Described in perlguts.
10165 "dMARK"
10167 Declare a stack marker variable, "mark", for the XSUB. See "MARK"
10168 and "dORIGMARK".
10169 dMARK;
10171 "dORIGMARK"
10173 Saves the original stack mark for the XSUB. See "ORIGMARK".
10174 dORIGMARK;
10176 "dSP"
10178 Declares a local copy of perl's stack pointer for the XSUB,
10179 available via the "SP" macro. See "SP".
10180 dSP;
10182 "dTARGET"
10184 Declare that this function uses "TARG"
10185 dTARGET;
10187 "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 void EXTEND(SP, SSize_t nitems)
10194 "LISTOP"
10196 Described in perlguts.
10197 "LOGOP"
10199 Described in perlguts.
10200 "LOOP"
10202 Described in perlguts.
10203 "MARK"
10205 Stack marker variable for the XSUB. See "dMARK".
10206 "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 void mPUSHi(IV iv)
10213 "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 void mPUSHn(NV nv)
10220 "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 void mPUSHp(char* str, STRLEN len)
10227 "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 void mPUSHs(SV* sv)
10234 "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 void mPUSHu(UV uv)
10241 "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 void mXPUSHi(IV iv)
10247 "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 void mXPUSHn(NV nv)
10253 "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 void mXPUSHp(char* str, STRLEN len)
10260 "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 void mXPUSHs(SV* sv)
10267 "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 void mXPUSHu(UV uv)
10274 "newXSproto"
10276 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl
10277 prototypes to the subs.
10278 "OP"
10280 Described in perlguts.
10281 "ORIGMARK"
10283 The original stack mark for the XSUB. See "dORIGMARK".
10284 "peep_t"
10286 Described in perlguts.
10287 "PL_runops"
10289 Described in perlguts.
10290 "PMOP"
10292 Described in perlguts.
10293 "POPi"
10295 Pops an integer off the stack.
10296 IV POPi
10298 "POPl"
10300 Pops a long off the stack.
10301 long POPl
10303 "POPn"
10305 Pops a double off the stack.
10306 NV POPn
10308 "POPp"
10310 Pops a string off the stack.
10311 char* POPp
10313 "POPpbytex"
10315 Pops a string off the stack which must consist of bytes i.e.
10316 characters < 256.
10317 char* POPpbytex
10319 "POPpx"
10321 Pops a string off the stack. Identical to POPp. There are two
10322 names for historical reasons.
10323 char* POPpx
10325 "POPs"
10327 Pops an SV off the stack.
10328 SV* POPs
10330 "POPu"
10332 Pops an unsigned integer off the stack.
10333 UV POPu
10335 "POPul"
10337 Pops an unsigned long off the stack.
10338 long POPul
10340 "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 void PUSHi(IV iv)
10349 "PUSHMARK"
10351 Opening bracket for arguments on a callback. See "PUTBACK" and
10352 perlcall.
10353 void PUSHMARK(SP)
10355 "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 void PUSHmortal
10362 "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 void PUSHn(NV nv)
10371 "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 void PUSHp(char* str, STRLEN len)
10381 "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 void PUSHs(SV* sv)
10388 "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 void PUSHu(UV uv)
10397 "PUTBACK"
10399 Closing bracket for XSUB arguments. This is usually handled by
10400 "xsubpp". See "PUSHMARK" and perlcall for other uses.
10401 PUTBACK;
10403 "save_aptr"
10405 Described in perlguts.
10406 void save_aptr(AV** aptr)
10408 "save_ary"
10410 Described in perlguts.
10411 AV* save_ary(GV* gv)
10413 "SAVEBOOL"
10415 Described in perlguts.
10416 SAVEBOOL(bool i)
10418 "SAVEDELETE"
10420 Described in perlguts.
10421 SAVEDELETE(HV * hv, char * key, I32 length)
10423 "SAVEDESTRUCTOR"
10425 Described in perlguts.
10426 SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)
10428 "SAVEDESTRUCTOR_X"
10430 Described in perlguts.
10431 SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)
10433 "SAVEFREEOP"
10435 Described in perlguts.
10436 SAVEFREEOP(OP *op)
10438 "SAVEFREEPV"
10440 Described in perlguts.
10441 SAVEFREEPV(void * p)
10443 "SAVEFREESV"
10445 Described in perlguts.
10446 SAVEFREESV(SV* sv)
10448 "save_hash"
10450 Described in perlguts.
10451 HV* save_hash(GV* gv)
10453 "save_hptr"
10455 Described in perlguts.
10456 void save_hptr(HV** hptr)
10458 "SAVEI8"
10460 Described in perlguts.
10461 SAVEI8(I8 i)
10463 "SAVEI32"
10465 Described in perlguts.
10466 SAVEI32(I32 i)
10468 "SAVEI16"
10470 Described in perlguts.
10471 SAVEI16(I16 i)
10473 "SAVEINT"
10475 Described in perlguts.
10476 SAVEINT(int i)
10478 "save_item"
10480 Described in perlguts.
10481 void save_item(SV* item)
10483 "SAVEIV"
10485 Described in perlguts.
10486 SAVEIV(IV i)
10488 "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 Described in perlguts.
10495 void save_list(SV** sarg, I32 maxsarg)
10497 "SAVELONG"
10499 Described in perlguts.
10500 SAVELONG(long i)
10502 "SAVEMORTALIZESV"
10504 Described in perlguts.
10505 SAVEMORTALIZESV(SV* sv)
10507 "SAVEPPTR"
10509 Described in perlguts.
10510 SAVEPPTR(char * p)
10512 "save_scalar"
10514 Described in perlguts.
10515 SV* save_scalar(GV* gv)
10517 "SAVESPTR"
10519 Described in perlguts.
10520 SAVESPTR(SV * s)
10522 "SAVESTACK_POS"
10524 Described in perlguts.
10525 SAVESTACK_POS()
10527 "save_svref"
10529 Described in perlguts.
10530 SV* save_svref(SV** sptr)
10532 "SP"
10534 Stack pointer. This is usually handled by "xsubpp". See "dSP" and
10535 "SPAGAIN".
10536 "SPAGAIN"
10538 Refetch the stack pointer. Used after a callback. See perlcall.
10539 SPAGAIN;
10541 "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 TARG;
10548 "UNOP"
10550 Described in perlguts.
10551 "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 void XPUSHi(IV iv)
10560 "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 void XPUSHmortal
10567 "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 void XPUSHn(NV nv)
10576 "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 void XPUSHp(char* str, STRLEN len)
10586 "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 void XPUSHs(SV* sv)
10593 "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 void XPUSHu(UV uv)
10602 "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 XS_APIVERSION_BOOTCHECK;
10609 "XSRETURN"
10611 Return from XSUB, indicating number of items on the stack. This is
10612 usually handled by "xsubpp".
10613 void XSRETURN(int nitems)
10615 "XSRETURN_EMPTY"
10617 Return an empty list from an XSUB immediately.
10618 XSRETURN_EMPTY;
10620 "XSRETURN_IV"
10622 Return an integer from an XSUB immediately. Uses "XST_mIV".
10623 void XSRETURN_IV(IV iv)
10625 "XSRETURN_NO"
10627 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
10628 XSRETURN_NO;
10630 "XSRETURN_NV"
10632 Return a double from an XSUB immediately. Uses "XST_mNV".
10633 void XSRETURN_NV(NV nv)
10635 "XSRETURN_PV"
10637 Return a copy of a string from an XSUB immediately. Uses
10638 "XST_mPV".
10639 void XSRETURN_PV(char* str)
10641 "XSRETURN_UNDEF"
10643 Return &PL_sv_undef from an XSUB immediately. Uses "XST_mUNDEF".
10644 XSRETURN_UNDEF;
10646 "XSRETURN_UV"
10648 Return an integer from an XSUB immediately. Uses "XST_mUV".
10649 void XSRETURN_UV(IV uv)
10651 "XSRETURN_YES"
10653 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
10654 XSRETURN_YES;
10656 "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 void XST_mIV(int pos, IV iv)
10662 "XST_mNO"
10664 Place &PL_sv_no into the specified position "pos" on the stack.
10665 void XST_mNO(int pos)
10667 "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 void XST_mNV(int pos, NV nv)
10673 "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 void XST_mPV(int pos, char* str)
10679 "XST_mUNDEF"
10681 Place &PL_sv_undef into the specified position "pos" on the stack.
10682 void XST_mUNDEF(int pos)
10684 "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 void XST_mUV(int pos, UV uv)
10690 "XST_mYES"
10692 Place &PL_sv_yes into the specified position "pos" on the stack.
10693 void XST_mYES(int pos)
10695 "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 "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 XS_VERSION_BOOTCHECK;
10708
10710 See also "Unicode Support".
10711 "CAT2"
10713 This macro concatenates 2 tokens together.
10714 token CAT2(token x, token y)
10716 "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 void Copy(void* src, void* dest, int nitems, type)
10724 "CopyD"
10726 Like "Copy" but returns "dest". Useful for encouraging compilers
10727 to tail-call optimise.
10728 void * CopyD(void* src, void* dest, int nitems, type)
10730 "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 The number of bytes copied is written to *retlen.
10739 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 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 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 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 Source Destination
10759 abcxdef abc0
10760 provided the destination buffer is at least 4 bytes long.
10762 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 Source Destination
10768 abc\xdef abcxdef0
10769 (provided the destination buffer is at least 8 bytes long).
10771 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 Source Destination
10777 abc\xdef abcxdef0
10778 abc\\\xdef abc\\xdef0
10779 abc\\\\\xdef abc\\\\xdef0
10780 (as always, if the destination is large enough)
10782 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 Source Destination
10788 abcxdef abc0
10789 abc\\xdef abc\\0
10790 abc\\\\xdef abc\\\\0
10791 char* delimcpy(char* to, const char* to_end, const char* from,
10793 const char* from_end, const int delim,
10794 I32* retlen)
10795 "fbm_compile"
10797 Analyzes the string in order to make fast searches on it using
10798 "fbm_instr()" -- the Boyer-Moore algorithm.
10799 void fbm_compile(SV* sv, U32 flags)
10801 "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 char* fbm_instr(unsigned char* big, unsigned char* bigend,
10809 SV* littlestr, U32 flags)
10810 "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 I32 foldEQ(const char* a, const char* b, I32 len)
10819 "ibcmp"
10821 This is a synonym for "(! foldEQ())"
10822 I32 ibcmp(const char* a, const char* b, I32 len)
10824 "ibcmp_locale"
10826 This is a synonym for "(! foldEQ_locale())"
10827 I32 ibcmp_locale(const char* a, const char* b, I32 len)
10829 "ibcmp_utf8"
10831 This is a synonym for "(! foldEQ_utf8())"
10832 I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1,
10834 const char *s2, char **pe2, UV l2, bool u2)
10835 "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 char* instr(const char* big, const char* little)
10843 "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 bool memCHRs("list", char c)
10853 "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 bool memEQ(char* s1, char* s2, STRLEN len)
10861 "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 bool memEQs(char* s1, STRLEN l1, "s2")
10868 "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 bool memNE(char* s1, char* s2, STRLEN len)
10877 "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 bool memNEs(char* s1, STRLEN l1, "s2")
10884 "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 void Move(void* src, void* dest, int nitems, type)
10892 "MoveD"
10894 Like "Move" but returns "dest". Useful for encouraging compilers
10895 to tail-call optimise.
10896 void * MoveD(void* src, void* dest, int nitems, type)
10898 "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 int my_snprintf(char *buffer, const Size_t len,
10908 const char *format, ...)
10909 "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 Do NOT use this due to the possibility of overflowing "buffer".
10916 Instead use my_snprintf()
10917 int my_sprintf(NN char *buffer, NN const char *pat, ...)
10919 "my_strlcat"
10921 The C library "strlcat" if available, or a Perl implementation of
10922 it. This operates on C "NUL"-terminated strings.
10923 "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 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 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 Size_t my_strlcat(char *dst, const char *src, Size_t size)
10941 "my_strlcpy"
10943 The C library "strlcpy" if available, or a Perl implementation of
10944 it. This operates on C "NUL"-terminated strings.
10945 "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 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 Size_t my_strlcpy(char *dst, const char *src, Size_t size)
10954 "my_strnlen"
10956 The C library "strnlen" if available, or a Perl implementation of
10957 it.
10958 "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 Size_t my_strnlen(const char *str, Size_t maxlen)
10965 "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 int my_vsnprintf(char *buffer, const Size_t len,
10974 const char *format, va_list ap)
10975 "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 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 The function returns "NULL" if there is no occurrence of "little"
10992 within "big". If "little" is the empty string, "big" is returned.
10993 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 char* ninstr(const char* big, const char* bigend,
11000 const char* little, const char* lend)
11001 "Nullch"
11003 Null character pointer. (No longer available when "PERL_CORE" is
11004 defined.)
11005 "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 char* rninstr(const char* big, const char* bigend,
11012 const char* little, const char* lend)
11013 "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 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 char* savepv(const char* pv)
11029 "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 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 char* savepvn(const char* pv, Size_t len)
11043 "savepvs"
11045 Like "savepvn", but takes a literal string instead of a
11046 string/length pair.
11047 char* savepvs("literal string")
11049 "savesharedpv"
11051 A version of "savepv()" which allocates the duplicate string in
11052 memory which is shared between threads.
11053 char* savesharedpv(const char* pv)
11055 "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 char* savesharedpvn(const char *const pv, const STRLEN len)
11062 "savesharedpvs"
11064 A version of "savepvs()" which allocates the duplicate string in
11065 memory which is shared between threads.
11066 char* savesharedpvs("literal string")
11068 "savesharedsvpv"
11070 A version of "savesharedpv()" which allocates the duplicate string
11071 in memory which is shared between threads.
11072 char* savesharedsvpv(SV *sv)
11074 "savesvpv"
11076 A version of "savepv()"/"savepvn()" which gets the string to
11077 duplicate from the passed in SV using "SvPV()"
11078 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 char* savesvpv(SV* sv)
11085 "strEQ"
11087 Test two "NUL"-terminated strings to see if they are equal.
11088 Returns true or false.
11089 bool strEQ(char* s1, char* s2)
11091 "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 bool strGE(char* s1, char* s2)
11097 "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 bool strGT(char* s1, char* s2)
11103 "STRINGIFY"
11105 This macro surrounds its token with double quotes.
11106 string STRINGIFY(token x)
11108 "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 bool strLE(char* s1, char* s2)
11114 "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 bool strLT(char* s1, char* s2)
11120 "strNE"
11122 Test two "NUL"-terminated strings to see if they are different.
11123 Returns true or false.
11124 bool strNE(char* s1, char* s2)
11126 "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 bool strnEQ(char* s1, char* s2, STRLEN len)
11133 "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 bool strnNE(char* s1, char* s2, STRLEN len)
11140 "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 pair STR_WITH_LEN("literal string")
11150 "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 void Zero(void* dest, int nitems, type)
11157 "ZeroD"
11159 Like "Zero" but returns dest. Useful for encouraging compilers to
11160 tail-call optimise.
11161 void * ZeroD(void* dest, int nitems, type)
11163
11165 "SVt_IV"
11166 Type flag for scalars. See "svtype".
11167 "SVt_NULL"
11169 Type flag for scalars. See "svtype".
11170 "SVt_NV"
11172 Type flag for scalars. See "svtype".
11173 "SVt_PV"
11175 Type flag for scalars. See "svtype".
11176 "SVt_PVAV"
11178 Type flag for arrays. See "svtype".
11179 "SVt_PVCV"
11181 Type flag for subroutines. See "svtype".
11182 "SVt_PVFM"
11184 Type flag for formats. See "svtype".
11185 "SVt_PVGV"
11187 Type flag for typeglobs. See "svtype".
11188 "SVt_PVHV"
11190 Type flag for hashes. See "svtype".
11191 "SVt_PVIO"
11193 Type flag for I/O objects. See "svtype".
11194 "SVt_PVIV"
11196 Type flag for scalars. See "svtype".
11197 "SVt_PVLV"
11199 Type flag for scalars. See "svtype".
11200 "SVt_PVMG"
11202 Type flag for scalars. See "svtype".
11203 "SVt_PVNV"
11205 Type flag for scalars. See "svtype".
11206 "SVt_REGEXP"
11208 Type flag for regular expressions. See "svtype".
11209 "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 The types are:
11215 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 These are most easily explained from the bottom up.
11235 "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 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 Hence, checking "SvTYPE(sv) < SVt_PVAV" is the best way to see
11244 whether something is a scalar.
11245 "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 "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 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 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 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 The following global variables are associated with arenas:
11293 PL_sv_arenaroot pointer to list of SV arenas
11295 PL_sv_root pointer to list of free SV structures
11296 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 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 The SV arena serves the secondary purpose of allowing still-live SVs to
11307 be located and destroyed during final cleanup.
11308 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 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 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 sv_report_used() / do_report_used()
11327 dump all remaining SVs (debugging aid)
11328 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 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 Arena allocator API Summary
11350 Private API to rest of sv.c
11351 new_SV(), del_SV(),
11353 new_XPVNV(), del_XPVGV(),
11355 etc
11356 Public API:
11358 sv_report_used(), sv_clean_objs(), sv_clean_all(), sv_free_arenas()
11360 "boolSV"
11362 Returns a true SV if "b" is a true value, or a false SV if "b" is
11363 0.
11364 See also "PL_sv_yes" and "PL_sv_no".
11366 SV * boolSV(bool b)
11368 "croak_xs_usage"
11370 A specialised variant of "croak()" for emitting the usage message
11371 for xsubs
11372 croak_xs_usage(cv, "eee_yow");
11374 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 Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
11380 "eee_yow");
11381 void croak_xs_usage(const CV *const cv, const char *const params)
11383 "DEFSV"
11385 Returns the SV associated with $_
11386 SV * DEFSV
11388 "DEFSV_set"
11390 Associate "sv" with $_
11391 void DEFSV_set(SV * sv)
11393 "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 NOTE: the "perl_get_sv()" form is deprecated.
11401 SV* get_sv(const char *name, I32 flags)
11403 "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 bool isGV_with_GP(SV * sv)
11409 "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 I32 looks_like_number(SV *const sv)
11417 "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 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 "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 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 "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 SV* newRV(SV *const sv)
11452 "newRV_noinc"
11454 Creates an RV wrapper for an SV. The reference count for the
11455 original SV is not incremented.
11456 SV* newRV_noinc(SV *const tmpRef)
11458 "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 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 SV* newSV(const STRLEN len)
11473 "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 SV* newSVhek(const HEK *const hek)
11480 "newSViv"
11482 Creates a new SV and copies an integer into it. The reference
11483 count for the SV is set to 1.
11484 SV* newSViv(const IV i)
11486 "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 SV* newSVnv(const NV n)
11492 "newSVpadname"
11494 NOTE: "newSVpadname" is experimental and may change or be removed
11495 without notice.
11496 Creates a new SV containing the pad name.
11498 SV* newSVpadname(PADNAME *pn)
11500 "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 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 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 SV* newSVpv(const char *const s, const STRLEN len)
11520 "newSVpvf"
11522 Creates a new SV and initializes it with the string formatted like
11523 "sv_catpvf".
11524 NOTE: "newSVpvf" must be explicitly called as "Perl_newSVpvf" with
11526 an "aTHX_" parameter.
11527 SV* Perl_newSVpvf(pTHX_ const char *const pat, ...)
11529 "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 SV* newSVpvf_nocontext(const char *const pat, ...)
11536 "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 SV* newSVpvn(const char *const buffer, const STRLEN len)
11546 "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 #define newSVpvn_utf8(s, len, u) \
11561 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
11562 SV* newSVpvn_flags(const char *const s, const STRLEN len,
11564 const U32 flags)
11565 "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 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
11578 "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 SV* newSVpvn_utf8(const char* s, STRLEN len, U32 utf8)
11585 "newSVpvs"
11587 Like "newSVpvn", but takes a literal string instead of a
11588 string/length pair.
11589 SV* newSVpvs("literal string")
11591 "newSVpvs_flags"
11593 Like "newSVpvn_flags", but takes a literal string instead of a
11594 string/length pair.
11595 SV* newSVpvs_flags("literal string", U32 flags)
11597 "newSVpv_share"
11599 Like "newSVpvn_share", but takes a "NUL"-terminated string instead
11600 of a string/length pair.
11601 SV* newSVpv_share(const char* s, U32 hash)
11603 "newSVpvs_share"
11605 Like "newSVpvn_share", but takes a literal string instead of a
11606 string/length pair and omits the hash parameter.
11607 SV* newSVpvs_share("literal string")
11609 "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 SV* newSVrv(SV *const rv, const char *const classname)
11619 "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 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 SV* newSVsv (SV *const old)
11631 SV* newSVsv_nomg (SV *const old)
11632 SV* newSVsv_flags(SV *const old, I32 flags)
11633 "newSV_type"
11635 Creates a new SV, of the type specified. The reference count for
11636 the new SV is set to 1.
11637 SV* newSV_type(const svtype type)
11639 "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 SV* newSVuv(const UV u)
11645 "Nullsv"
11647 Null SV pointer. (No longer available when "PERL_CORE" is
11648 defined.)
11649 "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 STRLEN PL_na
11657 "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 SV PL_sv_no
11663 "PL_sv_undef"
11665 This is the "undef" SV. It is readonly. Always refer to this as
11666 &PL_sv_undef.
11667 SV PL_sv_undef
11669 "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 SV PL_sv_yes
11675 "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 SV PL_sv_zero
11683 "SAVE_DEFSV"
11685 Localize $_. See "Localizing changes" in perlguts.
11686 void SAVE_DEFSV
11688 "sortsv"
11690 In-place sort an array of SV pointers with the given comparison
11691 routine.
11692 Currently this always uses mergesort. See "sortsv_flags" for a
11694 more flexible routine.
11695 void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
11697 "sortsv_flags"
11699 In-place sort an array of SV pointers with the given comparison
11700 routine, with various SORTf_* flag options.
11701 void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp,
11703 U32 flags)
11704 "SV"
11706 Described in perlguts.
11707 "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 CV* sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)
11714 "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 'Get' magic is ignored on the "sv" passed in, but will be called on
11721 "SvRV(sv)" if "sv" is an RV.
11722 IO* sv_2io(SV *const sv)
11724 "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 IV sv_2iv_flags(SV *const sv, const I32 flags)
11732 "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 SV* sv_2mortal(SV *const sv)
11741 "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 NV sv_2nv_flags(SV *const sv, const I32 flags)
11749 "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 Processes 'get' magic.
11757 Usually accessed via the "SvPVbyte" macro.
11759 char* sv_2pvbyte(SV *sv, STRLEN *const lp)
11761 "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 Usually accessed via the "SvPVutf8" macro.
11768 char* sv_2pvutf8(SV *sv, STRLEN *const lp)
11770 "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 UV sv_2uv_flags(SV *const sv, const I32 flags)
11778 "sv_backoff"
11780 Remove any string offset. You should normally use the "SvOOK_off"
11781 macro wrapper instead.
11782 void sv_backoff(SV *const sv)
11784 "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 SV* sv_bless(SV *const sv, HV *const stash)
11791 "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 They differ only in how they handle magic:
11801 "sv_catpv_mg" performs both 'get' and 'set' magic.
11803 "sv_catpv" performs only 'get' magic.
11805 "sv_catpv_nomg" skips all magic.
11807 "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 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 "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 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 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 All perform 'get' magic, but only "sv_catpvf_mg" and
11839 "sv_catpvf_mg_nocontext" perform 'set' magic.
11840 "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 NOTE: "sv_catpvf" must be explicitly called as "Perl_sv_catpvf"
11846 with an "aTHX_" parameter.
11847 NOTE: "sv_catpvf_mg" must be explicitly called as
11849 "Perl_sv_catpvf_mg" with an "aTHX_" parameter.
11850 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 "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 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 They differ in that:
11873 "sv_catpvn_mg" performs both 'get' and 'set' magic on "dsv".
11875 "sv_catpvn" performs only 'get' magic.
11877 "sv_catpvn_nomg" skips all magic.
11879 "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 "sv_catpvn", "sv_catpvn_mg", and "sv_catpvn_nomg" are implemented
11889 in terms of "sv_catpvn_flags".
11890 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 "sv_catpvs"
11898 Like "sv_catpvn", but takes a literal string instead of a
11899 string/length pair.
11900 void sv_catpvs(SV* sv, "literal string")
11902 "sv_catpvs_flags"
11904 Like "sv_catpvn_flags", but takes a literal string instead of a
11905 string/length pair.
11906 void sv_catpvs_flags(SV* sv, "literal string", I32 flags)
11908 "sv_catpvs_mg"
11910 Like "sv_catpvn_mg", but takes a literal string instead of a
11911 string/length pair.
11912 void sv_catpvs_mg(SV* sv, "literal string")
11914 "sv_catpvs_nomg"
11916 Like "sv_catpvn_nomg", but takes a literal string instead of a
11917 string/length pair.
11918 void sv_catpvs_nomg(SV* sv, "literal string")
11920 "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 They differ only in what magic they perform:
11930 "sv_catsv_mg" performs 'get' magic on both SVs before the copy, and
11932 'set' magic on "dsv" afterwards.
11933 "sv_catsv" performs just 'get' magic, on both SVs.
11935 "sv_catsv_nomg" skips all magic.
11937 "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 "sv_catsv", "sv_catsv_mg", and "sv_catsv_nomg" are implemented in
11944 terms of "sv_catsv_flags".
11945 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 "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 Beware: after this function returns, "ptr" and SvPVX_const(sv) may
11961 no longer refer to the same chunk of data.
11962 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 void sv_chop(SV *const sv, const char *const ptr)
11968 "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 void sv_clear(SV *const orig_sv)
11979 "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 I32 sv_cmp(SV *const sv1, SV *const sv2)
11988 "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 I32 sv_cmp_flags(SV *const sv1, SV *const sv2, const U32 flags)
11998 "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 I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
12005 "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 I32 sv_cmp_locale_flags(SV *const sv1, SV *const sv2,
12013 const U32 flags)
12014 "sv_collxfrm"
12016 This calls "sv_collxfrm_flags" with the SV_GMAGIC flag. See
12017 "sv_collxfrm_flags".
12018 char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
12020 "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 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 char* sv_collxfrm_flags(SV *const sv, STRLEN *const nxp,
12031 I32 const flags)
12032 "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 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 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 "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 STRLEN SvCUR(SV* sv)
12061 "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 void SvCUR_set(SV* sv, STRLEN len)
12067 "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 They differ only in that:
12074 "sv_dec" handles 'get' magic; "sv_dec_nomg" skips 'get' magic.
12076 void sv_dec(SV *const sv)
12078 "sv_derived_from"
12080 Exactly like "sv_derived_from_pv", but doesn't take a "flags"
12081 parameter.
12082 bool sv_derived_from(SV* sv, const char *const name)
12084 "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 bool sv_derived_from_pv(SV* sv, const char *const name,
12090 U32 flags)
12091 "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 Currently, the only significant value for "flags" is SVf_UTF8.
12098 bool sv_derived_from_pvn(SV* sv, const char *const name,
12100 const STRLEN len, U32 flags)
12101 "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 bool sv_derived_from_sv(SV* sv, SV *namesv, U32 flags)
12108 "sv_does"
12110 Like "sv_does_pv", but doesn't take a "flags" parameter.
12111 bool sv_does(SV* sv, const char *const name)
12113 "sv_does_pv"
12115 Like "sv_does_sv", but takes a nul-terminated string instead of an
12116 SV.
12117 bool sv_does_pv(SV* sv, const char *const name, U32 flags)
12119 "sv_does_pvn"
12121 Like "sv_does_sv", but takes a string/length pair instead of an SV.
12122 bool sv_does_pvn(SV* sv, const char *const name,
12124 const STRLEN len, U32 flags)
12125 "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 bool sv_does_sv(SV* sv, SV* namesv, U32 flags)
12132 "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 Warning: If "SvCUR" is equal to "SvLEN", then "SvEND" points to
12140 unallocated memory.
12141 char* SvEND(SV* sv)
12143 "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 I32 sv_eq(SV* sv1, SV* sv2)
12150 "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 I32 sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)
12158 "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 void sv_force_normal(SV *sv)
12165 "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 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 void sv_force_normal_flags(SV *const sv, const U32 flags)
12184 "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 void sv_free(SV *const sv)
12192 "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 U32 SvGAMAGIC(SV* sv)
12202 "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 void SvGETMAGIC(SV* sv)
12209 "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 char* sv_gets(SV *const sv, PerlIO *const fp, I32 append)
12218 "sv_get_backrefs"
12220 NOTE: "sv_get_backrefs" is experimental and may change or be
12221 removed without notice.
12222 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 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 See also "Perl_sv_add_backref()", "Perl_sv_del_backref()",
12233 "Perl_sv_kill_backrefs()"
12234 SV* sv_get_backrefs(SV *const sv)
12236 "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 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 char * SvGROW(SV* sv, STRLEN len)
12250 "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 They differ only in that "sv_inc" performs 'get' magic;
12257 "sv_inc_nomg" skips any magic.
12258 void sv_inc(SV *const sv)
12260 "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 void sv_insert(SV *const bigstr, const STRLEN offset,
12268 const STRLEN len, const char *const little,
12269 const STRLEN littlelen)
12270 "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 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 "SvIOK"
12280 Returns a U32 value indicating whether the SV contains an integer.
12281 U32 SvIOK(SV* sv)
12283 "SvIOK_notUV"
12285 Returns a boolean indicating whether the SV contains a signed
12286 integer.
12287 bool SvIOK_notUV(SV* sv)
12289 "SvIOK_off"
12291 Unsets the IV status of an SV.
12292 void SvIOK_off(SV* sv)
12294 "SvIOK_on"
12296 Tells an SV that it is an integer.
12297 void SvIOK_on(SV* sv)
12299 "SvIOK_only"
12301 Tells an SV that it is an integer and disables all other "OK" bits.
12302 void SvIOK_only(SV* sv)
12304 "SvIOK_only_UV"
12306 Tells an SV that it is an unsigned integer and disables all other
12307 "OK" bits.
12308 void SvIOK_only_UV(SV* sv)
12310 "SvIOKp"
12312 Returns a U32 value indicating whether the SV contains an integer.
12313 Checks the private setting. Use "SvIOK" instead.
12314 U32 SvIOKp(SV* sv)
12316 "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 bool SvIOK_UV(SV* sv)
12324 "sv_isa"
12326 Returns a boolean indicating whether the SV is blessed into the
12327 specified class.
12328 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 int sv_isa(SV* sv, const char *const name)
12335 "sv_isa_sv"
12337 NOTE: "sv_isa_sv" is experimental and may change or be removed
12338 without notice.
12339 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 This is the function used to implement the behaviour of the "isa"
12346 operator.
12347 Does not invoke magic on "sv".
12349 Not to be confused with the older "sv_isa" function, which does not
12351 use an overloaded "isa()" method, nor will check subclassing.
12352 bool sv_isa_sv(SV* sv, SV* namesv)
12354 "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 U32 SvIsCOW(SV* sv)
12361 "SvIsCOW_shared_hash"
12363 Returns a boolean indicating whether the SV is Copy-On-Write shared
12364 hash key scalar.
12365 bool SvIsCOW_shared_hash(SV* sv)
12367 "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 int sv_isobject(SV* sv)
12374 "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 "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 "SvIV_nomg" is the same as "SvIV", but does not perform 'get'
12388 magic.
12389 IV SvIV(SV* sv)
12391 "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 void SvIV_set(SV* sv, IV val)
12399 "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 IV SvIVX(SV* sv)
12406 "SvLEN"
12408 Returns the size of the string buffer in the SV, not including any
12409 part attributable to "SvOOK". See "SvCUR".
12410 STRLEN SvLEN(SV* sv)
12412 "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 STRLEN sv_len(SV *const sv)
12419 "SvLEN_set"
12421 Set the size of the string buffer for the SV. See "SvLEN".
12422 void SvLEN_set(SV* sv, STRLEN len)
12424 "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 STRLEN sv_len_utf8(SV *const sv)
12431 "SvLOCK"
12433 Arranges for a mutual exclusion lock to be obtained on "sv" if a
12434 suitable module has been loaded.
12435 void SvLOCK(SV* sv)
12437 "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 See "sv_magicext" (which "sv_magic" now calls) for a description of
12444 the handling of the "name" and "namlen" arguments.
12445 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 void sv_magic(SV *const sv, SV *const obj, const int how,
12450 const char *const name, const I32 namlen)
12451 "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 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 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 (This is now used as a subroutine by "sv_magic".)
12467 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 "SvMAGIC_set"
12473 Set the value of the MAGIC pointer in "sv" to val. See "SvIV_set".
12474 void SvMAGIC_set(SV* sv, MAGIC* val)
12476 "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 SV* sv_mortalcopy(SV *const oldsv)
12485 "sv_mortalcopy_flags"
12487 Like "sv_mortalcopy", but the extra "flags" are passed to the
12488 "sv_setsv_flags".
12489 SV* sv_mortalcopy_flags(SV *const oldsv, U32 flags)
12491 "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 SV* sv_newmortal()
12499 "SvNIOK"
12501 Returns a U32 value indicating whether the SV contains a number,
12502 integer or double.
12503 U32 SvNIOK(SV* sv)
12505 "SvNIOK_off"
12507 Unsets the NV/IV status of an SV.
12508 void SvNIOK_off(SV* sv)
12510 "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 U32 SvNIOKp(SV* sv)
12517 "SvNOK"
12519 Returns a U32 value indicating whether the SV contains a double.
12520 U32 SvNOK(SV* sv)
12522 "SvNOK_off"
12524 Unsets the NV status of an SV.
12525 void SvNOK_off(SV* sv)
12527 "SvNOK_on"
12529 Tells an SV that it is a double.
12530 void SvNOK_on(SV* sv)
12532 "SvNOK_only"
12534 Tells an SV that it is a double and disables all other OK bits.
12535 void SvNOK_only(SV* sv)
12537 "SvNOKp"
12539 Returns a U32 value indicating whether the SV contains a double.
12540 Checks the private setting. Use "SvNOK" instead.
12541 U32 SvNOKp(SV* sv)
12543 "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 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 "Superseded" by "sv_nosharing()".
12554 void sv_nolocking(SV *sv)
12556 "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 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 "Superseded" by "sv_nosharing()".
12567 void sv_nounlocking(SV *sv)
12569 "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 "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 "SvNV_nomg" is the same as "SvNV", but does not perform 'get'
12583 magic.
12584 NV SvNV(SV* sv)
12586 "SvNV_set"
12588 Set the value of the NV pointer in "sv" to val. See "SvIV_set".
12589 void SvNV_set(SV* sv, NV val)
12591 "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 NV SvNVX(SV* sv)
12598 "SvOK"
12600 Returns a U32 value indicating whether the value is defined. This
12601 is only meaningful for scalars.
12602 U32 SvOK(SV* sv)
12604 "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 U32 SvOOK(SV* sv)
12615 "SvOOK_off"
12617 Remove any string offset.
12618 void SvOOK_off(SV * sv)
12620 "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 void SvOOK_offset(SV*sv, STRLEN len)
12630 "SvPOK"
12632 Returns a U32 value indicating whether the SV contains a character
12633 string.
12634 U32 SvPOK(SV* sv)
12636 "SvPOK_off"
12638 Unsets the PV status of an SV.
12639 void SvPOK_off(SV* sv)
12641 "SvPOK_on"
12643 Tells an SV that it is a string.
12644 void SvPOK_on(SV* sv)
12646 "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 void SvPOK_only(SV* sv)
12652 "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 void SvPOK_only_UTF8(SV* sv)
12658 "SvPOKp"
12660 Returns a U32 value indicating whether the SV contains a character
12661 string. Checks the private setting. Use "SvPOK" instead.
12662 U32 SvPOKp(SV* sv)
12664 "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 Use "sv_pos_b2u_flags" in preference, which correctly handles
12671 strings longer than 2Gb.
12672 void sv_pos_b2u(SV *const sv, I32 *const offsetp)
12674 "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 STRLEN sv_pos_b2u_flags(SV *const sv, STRLEN const offset,
12682 U32 flags)
12683 "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 Use "sv_pos_u2b_flags" in preference, which correctly handles
12692 strings longer than 2Gb.
12693 void sv_pos_u2b(SV *const sv, I32 *const offsetp,
12695 I32 *const lenp)
12696 "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 STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
12706 STRLEN *const lenp, U32 flags)
12707 "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 This is a very basic and common operation, so there are lots of
12742 slightly different versions of it.
12743 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 The differences between the forms are:
12755 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 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 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 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 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 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 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 "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 "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 "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 "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 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 "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 char* SvPVbyte(SV* sv, STRLEN len)
12849 "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 char* SvPVbyte_force(SV* sv, STRLEN len)
12856 "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 char* SvPVbyte_nolen(SV* sv)
12863 "SvPVbyte_nomg"
12865 Like "SvPVbyte", but does not process get magic.
12866 char* SvPVbyte_nomg(SV* sv, STRLEN len)
12868 "SvPVbyte_or_null"
12870 Like "SvPVbyte", but when "sv" is undef, returns "NULL".
12871 char* SvPVbyte_or_null(SV* sv, STRLEN len)
12873 "SvPVbyte_or_null_nomg"
12875 Like "SvPVbyte_or_null", but does not process get magic.
12876 char* SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
12878 "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 char * SvPVCLEAR(SV* sv)
12885 "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 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 The differences between the forms are:
12912 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 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 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 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 "SvPVutf8_force" is like "SvPV_force", but converts "sv" to UTF-8
12934 first if not already UTF-8.
12935 "SvPVutf8x_force" is like "SvPVutf8_force", but guarantees to
12937 evaluate "sv" only once; use the more efficient "SvPVutf8_force"
12938 otherwise.
12939 "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 "SvPVbytex_force" is like "SvPVbyte_force", but guarantees to
12945 evaluate "sv" only once; use the more efficient "SvPVbyte_force"
12946 otherwise.
12947 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 "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 void SvPV_free(SV * sv)
12967 "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 char* sv_pvn_force_flags(SV *const sv, STRLEN *const lp,
12976 const U32 flags)
12977 "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 void SvPV_renew(SV* sv, STRLEN len)
12988 "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 Set the value of the PV pointer in "sv" to the Perl allocated
12994 "NUL"-terminated string "val". See also "SvIV_set".
12995 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 void SvPV_set(SV* sv, char* val)
13004 "SvPVutf8"
13006 Like "SvPV", but converts "sv" to UTF-8 first if necessary.
13007 char* SvPVutf8(SV* sv, STRLEN len)
13009 "SvPVutf8_force"
13011 Like "SvPV_force", but converts "sv" to UTF-8 first if necessary.
13012 char* SvPVutf8_force(SV* sv, STRLEN len)
13014 "SvPVutf8_nolen"
13016 Like "SvPV_nolen", but converts "sv" to UTF-8 first if necessary.
13017 char* SvPVutf8_nolen(SV* sv)
13019 "SvPVutf8_nomg"
13021 Like "SvPVutf8", but does not process get magic.
13022 char* SvPVutf8_nomg(SV* sv, STRLEN len)
13024 "SvPVutf8_or_null"
13026 Like "SvPVutf8", but when "sv" is undef, returns "NULL".
13027 char* SvPVutf8_or_null(SV* sv, STRLEN len)
13029 "SvPVutf8_or_null_nomg"
13031 Like "SvPVutf8_or_null", but does not process get magic.
13032 char* SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
13034 "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 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 "SvPVXx" is identical to "SvPVX".
13048 "SvPVX_mutable" is merely a synonym for "SvPVX", but its name
13050 emphasizes that the string is modifiable by the caller.
13051 "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 char* SvPVX (SV* sv)
13057 char* SvPVXx (SV* sv)
13058 const char* SvPVX_const (SV* sv)
13059 char* SvPVX_mutable(SV* sv)
13060 "SvREADONLY"
13062 Returns true if the argument is readonly, otherwise returns false.
13063 Exposed to perl code via Internals::SvREADONLY().
13064 U32 SvREADONLY(SV* sv)
13066 "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 U32 SvREADONLY_off(SV* sv)
13072 "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 U32 SvREADONLY_on(SV* sv)
13078 "sv_ref"
13080 Returns a SV describing what the SV passed in is a reference to.
13081 dst can be a SV to be set to the description or NULL, in which case
13083 a mortal SV is returned.
13084 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 SV* sv_ref(SV *dst, const SV *const sv, const int ob)
13089 "SvREFCNT"
13091 Returns the value of the object's reference count. Exposed to perl
13092 code via Internals::SvREFCNT().
13093 U32 SvREFCNT(SV* sv)
13095 "SvREFCNT_dec"
13097 "SvREFCNT_dec_NN"
13098 These decrement the reference count of the given SV.
13099 "SvREFCNT_dec_NN" may only be used when "sv" is known to not be
13101 "NULL".
13102 void SvREFCNT_dec(SV *sv)
13104 "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 "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 "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 "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 "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 "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 "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 "SvREFCNT_inc_simple_void" can only be used with expressions
13141 without side effects and you don't need the return value.
13142 "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 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 "sv_reftype"
13157 Returns a string describing what the SV is a reference to.
13158 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 const char* sv_reftype(const SV *const sv, const int ob)
13163 "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 void sv_replace(SV *const sv, SV *const nsv)
13174 "sv_report_used"
13176 Dump the contents of all SVs not yet freed (debugging aid).
13177 void sv_report_used()
13179 "sv_reset"
13181 Underlying implementation for the "reset" Perl function. Note that
13182 the perl-level function is vaguely deprecated.
13183 void sv_reset(const char* s, HV *const stash)
13185 "SvROK"
13187 Tests if the SV is an RV.
13188 U32 SvROK(SV* sv)
13190 "SvROK_off"
13192 Unsets the RV status of an SV.
13193 void SvROK_off(SV* sv)
13195 "SvROK_on"
13197 Tells an SV that it is an RV.
13198 void SvROK_on(SV* sv)
13200 "SvRV"
13202 Dereferences an RV to return the SV.
13203 SV* SvRV(SV* sv)
13205 "SvRV_set"
13207 Set the value of the RV pointer in "sv" to val. See "SvIV_set".
13208 void SvRV_set(SV* sv, SV* val)
13210 "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 SV* sv_rvunweaken(SV *const sv)
13218 "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 SV* sv_rvweaken(SV *const sv)
13228 "sv_setiv"
13230 "sv_setiv_mg"
13231 These copy an integer into the given SV, upgrading first if
13232 necessary.
13233 They differ only in that "sv_setiv_mg" handles 'set' magic;
13235 "sv_setiv" does not.
13236 void sv_setiv (SV *const sv, const IV num)
13238 void sv_setiv_mg(SV *const sv, const IV i)
13239 "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 void SvSETMAGIC(SV* sv)
13247 "sv_setnv"
13249 "sv_setnv_mg"
13250 These copy a double into the given SV, upgrading first if
13251 necessary.
13252 They differ only in that "sv_setnv_mg" handles 'set' magic;
13254 "sv_setnv" does not.
13255 void sv_setnv(SV *const sv, const NV num)
13257 "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 They differ only in that:
13264 "sv_setpv" does not handle 'set' magic; "sv_setpv_mg" does.
13266 void sv_setpv(SV *const sv, const char *const ptr)
13268 "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 The differences between these are:
13277 "sv_setpvf" and "sv_setpvf_nocontext" do not handle 'set' magic;
13279 "sv_setpvf_mg" and "sv_setpvf_mg_nocontext" do.
13280 "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 NOTE: "sv_setpvf" must be explicitly called as "Perl_sv_setpvf"
13286 with an "aTHX_" parameter.
13287 NOTE: "sv_setpvf_mg" must be explicitly called as
13289 "Perl_sv_setpvf_mg" with an "aTHX_" parameter.
13290 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 "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 "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 These copy an integer into the given SV, also updating its string
13311 value.
13312 They differ only in that "sv_setpviv_mg" performs 'set' magic;
13314 "sv_setpviv" skips any magic.
13315 void sv_setpviv (SV *const sv, const IV num)
13317 void sv_setpviv_mg(SV *const sv, const IV iv)
13318 "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 The UTF-8 flag is not changed by these functions. A terminating
13327 NUL byte is guaranteed.
13328 They differ only in that:
13330 "sv_setpvn" does not handle 'set' magic; "sv_setpvn_mg" does.
13332 void sv_setpvn(SV *const sv, const char *const ptr,
13334 const STRLEN len)
13335 "sv_setpvs"
13337 Like "sv_setpvn", but takes a literal string instead of a
13338 string/length pair.
13339 void sv_setpvs(SV* sv, "literal string")
13341 "sv_setpvs_mg"
13343 Like "sv_setpvn_mg", but takes a literal string instead of a
13344 string/length pair.
13345 void sv_setpvs_mg(SV* sv, "literal string")
13347 "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 char * sv_setpv_bufsize(SV *const sv, const STRLEN cur,
13354 const STRLEN len)
13355 "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 SV* sv_setref_iv(SV *const rv, const char *const classname,
13365 const IV iv)
13366 "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 SV* sv_setref_nv(SV *const rv, const char *const classname,
13376 const NV nv)
13377 "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 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 Note that "sv_setref_pvn" copies the string while this copies the
13391 pointer.
13392 SV* sv_setref_pv(SV *const rv, const char *const classname,
13394 void *const pv)
13395 "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 Note that "sv_setref_pv" copies the pointer while this copies the
13406 string.
13407 SV* sv_setref_pvn(SV *const rv, const char *const classname,
13409 const char *const pv, const STRLEN n)
13410 "sv_setref_pvs"
13412 Like "sv_setref_pvn", but takes a literal string instead of a
13413 string/length pair.
13414 SV * sv_setref_pvs(SV *const rv, const char *const classname,
13416 "literal string")
13417 "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 SV* sv_setref_uv(SV *const rv, const char *const classname,
13427 const UV uv)
13428 "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 The only differences are:
13438 "SvSetMagicSV" and "SvSetMagicSV_nosteal" perform any required
13440 'set' magic afterwards on the destination SV; "SvSetSV" and
13441 "SvSetSV_nosteal" do not.
13442 "SvSetSV_nosteal" "SvSetMagicSV_nosteal" call a non-destructive
13444 version of "sv_setsv".
13445 void SvSetSV(SV* dsv, SV* ssv)
13447 "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 They differ only in that:
13459 "sv_setsv" calls 'get' magic on "ssv", but skips 'set' magic on
13461 "dsv".
13462 "sv_setsv_mg" calls both 'get' magic on "ssv" and 'set' magic on
13464 "dsv".
13465 "sv_setsv_nomg" skips all magic.
13467 "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 You probably want to instead use one of the assortment of wrappers,
13473 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
13474 "SvSetMagicSV_nosteal".
13475 "sv_setsv_flags" is the primary function for copying scalars, and
13477 most other copy-ish functions and macros use it underneath.
13478 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 "sv_setuv"
13485 "sv_setuv_mg"
13486 These copy an unsigned integer into the given SV, upgrading first
13487 if necessary.
13488 They differ only in that "sv_setuv_mg" handles 'set' magic;
13490 "sv_setuv" does not.
13491 void sv_setuv (SV *const sv, const UV num)
13493 void sv_setuv_mg(SV *const sv, const UV u)
13494 "sv_set_undef"
13496 Equivalent to "sv_setsv(sv, &PL_sv_undef)", but more efficient.
13497 Doesn't handle set magic.
13498 The perl equivalent is "$sv = undef;". Note that it doesn't free
13500 any string buffer, unlike "undef $sv".
13501 Introduced in perl 5.25.12.
13503 void sv_set_undef(SV *sv)
13505 "SvSHARE"
13507 Arranges for "sv" to be shared between threads if a suitable module
13508 has been loaded.
13509 void SvSHARE(SV* sv)
13511 "SvSHARED_HASH"
13513 Returns the hash for "sv" created by "newSVpvn_share".
13514 struct hek* SvSHARED_HASH(SV * sv)
13516 "SvSTASH"
13518 Returns the stash of the SV.
13519 HV* SvSTASH(SV* sv)
13521 "SvSTASH_set"
13523 Set the value of the STASH pointer in "sv" to val. See "SvIV_set".
13524 void SvSTASH_set(SV* sv, HV* val)
13526 "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 void SvTAINT(SV* sv)
13536 "SvTAINTED"
13538 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
13539 not.
13540 bool SvTAINTED(SV* sv)
13542 "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 void SvTAINTED_off(SV* sv)
13553 "SvTAINTED_on"
13555 Marks an SV as tainted if tainting is enabled.
13556 void SvTAINTED_on(SV* sv)
13558 "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 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 "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 "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 "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 bool SvTRUE(SV *sv)
13584 "SvTYPE"
13586 Returns the type of the SV. See "svtype".
13587 svtype SvTYPE(SV* sv)
13589 "SvUNLOCK"
13591 Releases a mutual exclusion lock on "sv" if a suitable module has
13592 been loaded.
13593 void SvUNLOCK(SV* sv)
13595 "sv_unmagic"
13597 Removes all magic of type "type" from an SV.
13598 int sv_unmagic(SV *const sv, const int type)
13600 "sv_unmagicext"
13602 Removes all magic of type "type" with the specified "vtbl" from an
13603 SV.
13604 int sv_unmagicext(SV *const sv, const int type, MGVTBL *vtbl)
13606 "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 void sv_unref(SV* sv)
13614 "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 void sv_unref_flags(SV *const ref, const U32 flags)
13625 "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 bool SvUOK(SV* sv)
13633 "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 void SvUPGRADE(SV* sv, svtype type)
13639 "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 void sv_upgrade(SV *const sv, svtype new_type)
13649 "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 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
13656 "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 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 void sv_usepvn_flags(SV *const sv, char* ptr, const STRLEN len,
13677 const U32 flags)
13678 "sv_usepvn_mg"
13680 Like "sv_usepvn", but also handles 'set' magic.
13681 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
13683 "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 If you want to take into account the bytes pragma, use "DO_UTF8"
13692 instead.
13693 U32 SvUTF8(SV* sv)
13695 "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 bool sv_utf8_decode(SV *const sv)
13704 "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 They are not a general purpose Unicode to byte encoding interface:
13714 use the "Encode" extension for that.
13715 They differ only in that:
13717 "sv_utf8_downgrade" processes 'get' magic on "sv".
13719 "sv_utf8_downgrade_nomg" does not.
13721 "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 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 "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 void sv_utf8_encode(SV *const sv)
13736 "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 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 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 These are not a general purpose byte encoding to Unicode interface:
13763 use the Encode extension for that.
13764 The "SV_FORCE_UTF8_UPGRADE" flag is now ignored.
13766 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 "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 void SvUTF8_off(SV *sv)
13778 "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 void SvUTF8_on(SV *sv)
13784 "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 "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 "SvUV_nomg" is the same as "SvUV", but does not perform 'get'
13798 magic.
13799 UV SvUV(SV* sv)
13801 "SvUV_set"
13803 Set the value of the UV pointer in "sv" to val. See "SvIV_set".
13804 void SvUV_set(SV* sv, UV val)
13806 "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 UV SvUVX(SV* sv)
13813 "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 This is an unnecessary synonym for "SvUVX"
13820 UV SvUVXx(SV* sv)
13822 "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 They differ only in that "sv_vcatpvf_mg" performs 'set' magic;
13830 "sv_vcatpvf" skips 'set' magic.
13831 Both perform 'get' magic.
13833 They are usually accessed via their frontends "sv_catpvf" and
13835 "sv_catpvf_mg".
13836 void sv_vcatpvf(SV *const sv, const char *const pat,
13838 va_list *const args)
13839 "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 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 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 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 They are usually used via one of the frontends "sv_vcatpvf" and
13863 "sv_vcatpvf_mg".
13864 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 "SvVOK"
13876 Returns a boolean indicating whether the SV contains a v-string.
13877 bool SvVOK(SV* sv)
13879 "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 They differ only in that "sv_vsetpvf_mg" performs 'set' magic;
13886 "sv_vsetpvf" skips all magic.
13887 They are usually used via their frontends, "sv_setpvf" and
13889 "sv_setpvf_mg".
13890 void sv_vsetpvf(SV *const sv, const char *const pat,
13892 va_list *const args)
13893 "sv_vsetpvfn"
13895 Works like "sv_vcatpvfn" but copies the text into the SV instead of
13896 appending it.
13897 Usually used via one of its frontends "sv_vsetpvf" and
13899 "sv_vsetpvf_mg".
13900 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 "SvVSTRING_mg"
13907 Returns the vstring magic, or NULL if none
13908 MAGIC* SvVSTRING_mg(SV * sv)
13910 "vnewSVpvf"
13912 Like "newSVpvf" but but the arguments are an encapsulated argument
13913 list.
13914 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 "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 "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 "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 "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 "HAS_ASCTIME64"
13942 This symbol, if defined, indicates that the "asctime64" () routine
13943 is available to do the 64bit variant of asctime ()
13944 "HAS_ASCTIME_R"
13946 This symbol, if defined, indicates that the "asctime_r" routine is
13947 available to asctime re-entrantly.
13948 "HAS_CTIME64"
13950 This symbol, if defined, indicates that the "ctime64" () routine is
13951 available to do the 64bit variant of ctime ()
13952 "HAS_CTIME_R"
13954 This symbol, if defined, indicates that the "ctime_r" routine is
13955 available to ctime re-entrantly.
13956 "HAS_DIFFTIME"
13958 This symbol, if defined, indicates that the "difftime" routine is
13959 available.
13960 "HAS_DIFFTIME64"
13962 This symbol, if defined, indicates that the "difftime64" () routine
13963 is available to do the 64bit variant of difftime ()
13964 "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 "HAS_GETITIMER"
13971 This symbol, if defined, indicates that the "getitimer" routine is
13972 available to return interval timers.
13973 "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 "HAS_GMTIME64"
13981 This symbol, if defined, indicates that the "gmtime64" () routine
13982 is available to do the 64bit variant of gmtime ()
13983 "HAS_GMTIME_R"
13985 This symbol, if defined, indicates that the "gmtime_r" routine is
13986 available to gmtime re-entrantly.
13987 "HAS_LOCALTIME64"
13989 This symbol, if defined, indicates that the "localtime64" ()
13990 routine is available to do the 64bit variant of localtime ()
13991 "HAS_LOCALTIME_R"
13993 This symbol, if defined, indicates that the "localtime_r" routine
13994 is available to localtime re-entrantly.
13995 "HAS_MKTIME"
13997 This symbol, if defined, indicates that the "mktime" routine is
13998 available.
13999 "HAS_MKTIME64"
14001 This symbol, if defined, indicates that the "mktime64" () routine
14002 is available to do the 64bit variant of mktime ()
14003 "HAS_NANOSLEEP"
14005 This symbol, if defined, indicates that the "nanosleep" system call
14006 is available to sleep with 1E-9 sec accuracy.
14007 "HAS_SETITIMER"
14009 This symbol, if defined, indicates that the "setitimer" routine is
14010 available to set interval timers.
14011 "HAS_STRFTIME"
14013 This symbol, if defined, indicates that the "strftime" routine is
14014 available to do time formatting.
14015 "HAS_TIME"
14017 This symbol, if defined, indicates that the "time()" routine
14018 exists.
14019 "HAS_TIMEGM"
14021 This symbol, if defined, indicates that the "timegm" routine is
14022 available to do the opposite of gmtime ()
14023 "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 "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 "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 "HAS_TZNAME"
14039 This symbol, if defined, indicates that the "tzname[]" array is
14040 available to access timezone names.
14041 "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 "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 extern int usleep(useconds_t);
14052 "I_TIME"
14054 This symbol is always defined, and indicates to the C program that
14055 it should include time.h.
14056 #ifdef I_TIME
14058 #include <time.h>
14059 #endif
14060 "I_UTIME"
14062 This symbol, if defined, indicates to the C program that it should
14063 include utime.h.
14064 #ifdef I_UTIME
14066 #include <utime.h>
14067 #endif
14068 "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 "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 "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 "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 "L_R_TZSET"
14089 If "localtime_r()" needs tzset, it is defined in this define
14090 "mini_mktime"
14092 normalise "struct tm" values without the localtime() semantics (and
14093 overhead) of mktime().
14094 void mini_mktime(struct tm *ptm)
14096 "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 Note that yday and wday effectively are ignored by this function,
14105 as mini_mktime() overwrites them
14106 Also note that this is always executed in the underlying locale of
14108 the program, giving localized results.
14109 NOTE: "my_strftime" must be explicitly called as "Perl_my_strftime"
14111 with an "aTHX_" parameter.
14112 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 "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 "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 "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 "Free_t"
14139 This variable contains the return type of "free()". It is usually
14140 void, but occasionally int.
14141 "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 "Gid_t_f"
14150 This symbol defines the format string used for printing a "Gid_t".
14151 "Gid_t_sign"
14153 This symbol holds the signedness of a "Gid_t". 1 for unsigned, -1
14154 for signed.
14155 "Gid_t_size"
14157 This symbol holds the size of a "Gid_t" in bytes.
14158 "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 "Malloc_t"
14168 This symbol is the type of pointer returned by malloc and realloc.
14169 "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 "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 "Netdb_hlen_t"
14182 This symbol holds the type used for the 2nd argument to
14183 "gethostbyaddr()".
14184 "Netdb_host_t"
14186 This symbol holds the type used for the 1st argument to
14187 "gethostbyaddr()".
14188 "Netdb_name_t"
14190 This symbol holds the type used for the argument to
14191 "gethostbyname()".
14192 "Netdb_net_t"
14194 This symbol holds the type used for the 1st argument to
14195 "getnetbyaddr()".
14196 "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 "Off_t_size"
14203 This symbol holds the number of bytes used by the "Off_t".
14204 "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 "Rand_seed_t"
14211 This symbol defines the type of the argument of the random seed
14212 function.
14213 "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 "Shmat_t"
14221 This symbol holds the return type of the "shmat()" system call.
14222 Usually set to 'void *' or 'char *'.
14223 "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 "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 "Size_t_size"
14237 This symbol holds the size of a "Size_t" in bytes.
14238 "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 "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 "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 "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 "Uid_t_f"
14262 This symbol defines the format string used for printing a "Uid_t".
14263 "Uid_t_sign"
14265 This symbol holds the signedness of a "Uid_t". 1 for unsigned, -1
14266 for signed.
14267 "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 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 "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 "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 -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 int bytes_cmp_utf8(const U8 *b, STRLEN blen, const U8 *u,
14298 STRLEN ulen)
14299 "bytes_from_utf8"
14301 NOTE: "bytes_from_utf8" is experimental and may change or be
14302 removed without notice.
14303 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 Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-
14309 destructive of the input string.
14310 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 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 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 U8* bytes_from_utf8(const U8 *s, STRLEN *lenp, bool *is_utf8p)
14327 "bytes_to_utf8"
14329 NOTE: "bytes_to_utf8" is experimental and may change or be removed
14330 without notice.
14331 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 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 A "NUL" character will be written after the end of the string.
14343 If you want to convert to UTF-8 from encodings other than the
14345 native (Latin1 or EBCDIC), see "sv_recode_to_utf8"().
14346 U8* bytes_to_utf8(const U8 *s, STRLEN *lenp)
14348 "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 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 bool DO_UTF8(SV* sv)
14358 "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 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 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 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 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 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 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 I32 foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1,
14401 const char *s2, char **pe2, UV l2, bool u2)
14402 "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 bool is_ascii_string(const U8* const s, STRLEN len)
14411 "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 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 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 bool is_c9strict_utf8_string(const U8 *s, STRLEN len)
14439 "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 See also "is_c9strict_utf8_string_loclen".
14446 bool is_c9strict_utf8_string_loc(const U8 *s, STRLEN len,
14448 const U8 **ep)
14449 "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 See also "is_c9strict_utf8_string_loc".
14457 bool is_c9strict_utf8_string_loclen(const U8 *s, STRLEN len,
14459 const U8 **ep, STRLEN *el)
14460 "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 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 Use "isUTF8_CHAR" to check for Perl's extended UTF-8; and
14479 "isUTF8_CHAR_flags" for a more customized definition.
14480 Use "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
14482 "is_c9strict_utf8_string_loclen" to check entire strings.
14483 Size_t isC9_STRICT_UTF8_CHAR(const U8 * const s0,
14485 const U8 * const e)
14486 "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 bool is_invariant_string(const U8* const s, STRLEN len)
14494 "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 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 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 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 Use "is_strict_utf8_string", "is_strict_utf8_string_loc", and
14518 "is_strict_utf8_string_loclen" to check entire strings.
14519 Size_t isSTRICT_UTF8_CHAR(const U8 * const s0,
14521 const U8 * const e)
14522 "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 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 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 bool is_strict_utf8_string(const U8 *s, STRLEN len)
14548 "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 See also "is_strict_utf8_string_loclen".
14555 bool is_strict_utf8_string_loc(const U8 *s, STRLEN len,
14557 const U8 **ep)
14558 "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 See also "is_strict_utf8_string_loc".
14566 bool is_strict_utf8_string_loclen(const U8 *s, STRLEN len,
14568 const U8 **ep, STRLEN *el)
14569 "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 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 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 STRLEN is_utf8_char(const U8 *s)
14586 "is_utf8_char_buf"
14588 This is identical to the macro "isUTF8_CHAR" in perlapi.
14589 STRLEN is_utf8_char_buf(const U8 *buf, const U8 *buf_end)
14591 "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 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 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 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 bool is_utf8_fixed_width_buf_flags(const U8 * const s,
14612 STRLEN len, const U32 flags)
14613 "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 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 "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 See also "is_utf8_fixed_width_buf_loclen_flags".
14632 bool is_utf8_fixed_width_buf_loc_flags(const U8 * const s,
14634 STRLEN len, const U8 **ep,
14635 const U32 flags)
14636 "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 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 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 bool is_utf8_invariant_string(const U8* const s, STRLEN len)
14661 "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 bool is_utf8_invariant_string_loc(const U8* const s, STRLEN len,
14669 const U8 ** ep)
14670 "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 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 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 bool is_utf8_string(const U8 *s, STRLEN len)
14693 "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 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 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 bool is_utf8_string_flags(const U8 *s, STRLEN len,
14723 const U32 flags)
14724 "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 See also "is_utf8_string_loclen".
14731 bool is_utf8_string_loc(const U8 *s, const STRLEN len,
14733 const U8 **ep)
14734 "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 See also "is_utf8_string_loc".
14742 bool is_utf8_string_loclen(const U8 *s, STRLEN len,
14744 const U8 **ep, STRLEN *el)
14745 "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 See also "is_utf8_string_loc_flags".
14753 bool is_utf8_string_loclen_flags(const U8 *s, STRLEN len,
14755 const U8 **ep, STRLEN *el,
14756 const U32 flags)
14757 "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 See also "is_utf8_string_loclen_flags".
14764 bool is_utf8_string_loc_flags(const U8 *s, STRLEN len,
14766 const U8 **ep, const U32 flags)
14767 "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 In other words this returns TRUE if "s" points to a partial
14778 UTF-8-encoded code point.
14779 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 bool is_utf8_valid_partial_char(const U8 * const s,
14792 const U8 * const e)
14793 "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 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 bool is_utf8_valid_partial_char_flags(const U8 * const s,
14812 const U8 * const e,
14813 const U32 flags)
14814 "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 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 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 Use "is_utf8_string", "is_utf8_string_loc", and
14838 "is_utf8_string_loclen" to check entire strings.
14839 Note also that a UTF-8 "invariant" character (i.e. ASCII on non-
14841 EBCDIC machines) is a valid UTF-8 character.
14842 Size_t isUTF8_CHAR(const U8 * const s0, const U8 * const e)
14844 "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 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 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 Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
14868 "is_utf8_string_loclen_flags" to check entire strings.
14869 STRLEN isUTF8_CHAR_flags(const U8 *s, const U8 *e,
14871 const U32 flags)
14872 "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 For conversion of code points potentially larger than will fit in a
14883 character, use "UNI_TO_NATIVE".
14884 U8 LATIN1_TO_NATIVE(U8 ch)
14886 "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 For conversion of code points potentially larger than will fit in a
14897 character, use "NATIVE_TO_UNI".
14898 U8 NATIVE_TO_LATIN1(U8 ch)
14900 "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 UV NATIVE_TO_UNI(UV ch)
14910 "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 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 Use ""PAD_COMPNAME_TYPE"" in perlintern instead.
14922 HV* pad_compname_type(const PADOFFSET po)
14924 "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 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 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 The pointer to the PV of the "dsv" is returned.
14944 See also "sv_uni_display".
14946 char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len,
14948 STRLEN pvlim, UV flags)
14949 "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 "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 Returns TRUE if the terminator was found, else returns FALSE.
14968 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset,
14970 char* tstr, int tlen)
14971 "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 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 The PV of "sv" is returned.
14983 char* sv_recode_to_utf8(SV* sv, SV *encoding)
14985 "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 The "flags" argument is as in "pv_uni_display"().
14992 The pointer to the PV of the "dsv" is returned.
14994 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
14996 "UNICODE_REPLACEMENT"
14998 Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT
14999 CHARACTER
15000 "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 UV UNI_TO_NATIVE(UV ch)
15010 "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 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 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 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 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 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 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 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 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 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 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 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen,
15119 const U32 flags)
15120 "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 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 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 "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 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 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 On both platforms, ASCII and EBCDIC, "UTF8_GOT_PERL_EXTENDED"
15167 is set if Perl extended UTF-8 is used.
15168 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 "UTF8_GOT_CONTINUATION"
15178 The input sequence was malformed in that the first byte was a
15179 UTF-8 continuation byte.
15180 "UTF8_GOT_EMPTY"
15182 The input "curlen" parameter was 0.
15183 "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 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 "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 "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 "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 "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 "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 • The "curlen" length parameter passed in was too small, and
15223 the function was prevented from examining all the necessary
15224 bytes.
15225 • 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 • This is a real error, and the partial sequence is all we're
15233 going to get.
15234 "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 "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 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 UV utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
15253 STRLEN *retlen, const U32 flags,
15254 U32 * errors)
15255 "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 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 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 "text"
15278 The text of the message as a "SVpv".
15279 "warn_categories"
15281 The warning category (or categories) packed into a "SVuv".
15282 "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 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 If the flag "UTF8_CHECK_ONLY" is passed, no warnings are generated,
15295 and hence no AV is created.
15296 The caller, of course, is responsible for freeing any returned AV.
15298 UV utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
15300 STRLEN *retlen, const U32 flags,
15301 U32 * errors, AV ** msgs)
15302 "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 If there is a possibility of malformed input, use instead:
15308 "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 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 STRLEN UTF8SKIP(char* s)
15319 "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 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 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 STRLEN UTF8_CHK_SKIP(char* s)
15339 "utf8_distance"
15341 Returns the number of UTF-8 characters between the UTF-8 pointers
15342 "a" and "b".
15343 WARNING: use only if you *know* that the pointers point inside the
15345 same UTF-8 buffer.
15346 IV utf8_distance(const U8 *a, const U8 *b)
15348 "utf8_hop"
15350 Return the UTF-8 pointer "s" displaced by "off" characters, either
15351 forward or backward.
15352 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 U8* utf8_hop(const U8 *s, SSize_t off)
15359 "utf8_hop_back"
15361 Return the UTF-8 pointer "s" displaced by up to "off" characters,
15362 backward.
15363 "off" must be non-positive.
15365 "s" must be after or equal to "start".
15367 When moving backward it will not move before "start".
15369 Will not exceed this limit even if the string is not valid "UTF-8".
15371 U8* utf8_hop_back(const U8 *s, SSize_t off, const U8 *start)
15373 "utf8_hop_forward"
15375 Return the UTF-8 pointer "s" displaced by up to "off" characters,
15376 forward.
15377 "off" must be non-negative.
15379 "s" must be before or equal to "end".
15381 When moving forward it will not move beyond "end".
15383 Will not exceed this limit even if the string is not valid "UTF-8".
15385 U8* utf8_hop_forward(const U8 *s, SSize_t off, const U8 *end)
15387 "utf8_hop_safe"
15389 Return the UTF-8 pointer "s" displaced by up to "off" characters,
15390 either forward or backward.
15391 When moving backward it will not move before "start".
15393 When moving forward it will not move beyond "end".
15395 Will not exceed those limits even if the string is not valid
15397 "UTF-8".
15398 U8* utf8_hop_safe(const U8 *s, SSize_t off, const U8 *start,
15400 const U8 *end)
15401 "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 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 See "UVCHR_IS_INVARIANT" for checking if a UV is invariant.
15412 bool UTF8_IS_INVARIANT(char c)
15414 "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 bool UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
15423 "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 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 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 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 bool UTF8_IS_SUPER(const U8 *s, const U8 *e)
15444 "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 bool UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
15453 "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 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 STRLEN utf8_length(const U8* s, const U8 *e)
15464 "UTF8_MAXBYTES"
15466 The maximum width of a single UTF-8 encoded character, in bytes.
15467 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 "UTF8_MAXBYTES_CASE"
15475 The maximum number of UTF-8 bytes a single Unicode character can
15476 uppercase/lowercase/titlecase/fold into.
15477 "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 STRLEN UTF8_SAFE_SKIP(char* s, char* e)
15485 "UTF8_SKIP"
15487 This is a synonym for "UTF8SKIP"
15488 STRLEN UTF8_SKIP(char* s)
15490 "utf8_to_bytes"
15492 NOTE: "utf8_to_bytes" is experimental and may change or be removed
15493 without notice.
15494 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 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 If you need a copy of the string, see "bytes_from_utf8".
15505 U8* utf8_to_bytes(U8 *s, STRLEN *lenp)
15507 "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 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 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 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 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
15533 "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 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 UV utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen)
15551 "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 bool UVCHR_IS_INVARIANT(UV cp)
15560 "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 STRLEN UVCHR_SKIP(UV cp)
15567 "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 d = uvchr_to_utf8(d, uv);
15576 is the recommended wide native character-aware way of saying
15578 *(d++) = uv;
15580 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 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 U8* uvchr_to_utf8(U8 *d, UV uv)
15588 "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 d = uvchr_to_utf8_flags(d, uv, flags);
15597 or, in most cases,
15599 d = uvchr_to_utf8_flags(d, uv, 0);
15601 This is the Unicode-aware way of saying
15603 *(d++) = uv;
15605 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 Specifying "flags" can further restrict what is allowed and not
15611 warned on, as follows:
15612 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 Similarly, the "UNICODE_WARN_NONCHAR" and
15621 "UNICODE_DISALLOW_NONCHAR" flags affect how the function handles a
15622 Unicode non-character.
15623 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 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 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 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 U8* uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
15666 "uvchr_to_utf8_flags_msgs"
15668 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15669 CIRCUMSTANCES.
15670 Most code should use ""uvchr_to_utf8_flags"()" rather than call
15672 this directly.
15673 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 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 "text"
15687 The text of the message as a "SVpv".
15688 "warn_categories"
15690 The warning category (or categories) packed into a "SVuv".
15691 "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 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 The caller, of course, is responsible for freeing any returned HV.
15704 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 void * C_ARRAY_END(void *a)
15713 "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 STRLEN C_ARRAY_LENGTH(void *a)
15719 "getcwd_sv"
15721 Fill "sv" with current working directory
15722 int getcwd_sv(SV* sv)
15724 "IN_PERL_COMPILETIME"
15726 Returns 1 if this macro is being called during the compilation
15727 phase of the program; otherwise 0;
15728 bool IN_PERL_COMPILETIME
15730 "IN_PERL_RUNTIME"
15732 Returns 1 if this macro is being called during the execution phase
15733 of the program; otherwise 0;
15734 bool IN_PERL_RUNTIME
15736 "IS_SAFE_SYSCALL"
15738 Same as "is_safe_syscall".
15739 bool IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
15741 NN const char *what, NN const char *op_name)
15742 "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 Return TRUE if the name is safe.
15749 "what" and "op_name" are used in any warning.
15751 Used by the "IS_SAFE_SYSCALL()" macro.
15753 bool is_safe_syscall(const char *pv, STRLEN len,
15755 const char *what, const char *op_name)
15756 "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 void my_setenv(const char* nam, const char* val)
15762 "Poison"
15764 PoisonWith(0xEF) for catching access to freed memory.
15765 void Poison(void* dest, int nitems, type)
15767 "PoisonFree"
15769 PoisonWith(0xEF) for catching access to freed memory.
15770 void PoisonFree(void* dest, int nitems, type)
15772 "PoisonNew"
15774 PoisonWith(0xAB) for catching access to allocated but uninitialized
15775 memory.
15776 void PoisonNew(void* dest, int nitems, type)
15778 "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 void PoisonWith(void* dest, int nitems, type, U8 byte)
15785 "StructCopy"
15787 This is an architecture-independent macro to copy one structure to
15788 another.
15789 void StructCopy(type *src, type *dest, type)
15791 "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 bool sv_destroyable(SV *sv)
15800 "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 void sv_nosharing(SV *sv)
15809
15811 "new_version"
15812 Returns a new version object based on the passed in SV:
15813 SV *sv = new_version(SV *ver);
15815 Does not alter the passed in ver SV. See "upg_version" if you want
15817 to upgrade the SV.
15818 SV* new_version(SV *ver)
15820 "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 The major number component of the perl interpreter currently being
15827 compiled or executing. This has been 5 from 1993 into 2020.
15828 Instead use one of the version comparison macros. See
15830 "PERL_VERSION_EQ".
15831 "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 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 Instead use one of the version comparison macros. See
15844 "PERL_VERSION_EQ".
15845 "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 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 Instead use one of the version comparison macros. See
15856 "PERL_VERSION_EQ".
15857 "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 #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 Note that this is usable in making compile-time decisions
15875 You may use the special value '*' for the final number to mean ALL
15877 possible values for it. Thus,
15878 #if PERL_VERSION_EQ(5,31,'*')
15880 means all perls in the 5.31 series. And
15882 #if PERL_VERSION_NE(5,24,'*')
15884 means all perls EXCEPT 5.24 ones. And
15886 #if PERL_VERSION_LE(5,9,'*')
15888 is effectively
15890 #if PERL_VERSION_LT(5,10,0)
15892 This means you don't have to think so much when converting from the
15894 existing deprecated "PERL_VERSION" to using this macro:
15895 #if PERL_VERSION <= 9
15897 becomes
15899 #if PERL_VERSION_LE(5,9,'*')
15901 bool PERL_VERSION_EQ(const U8 major, const U8 minor,
15903 const U8 patch)
15904 "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 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 "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 Function must be called with an already existing SV like
15921 sv = newSV(0);
15923 s = scan_version(s, SV *sv, bool qv);
15924 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 const char* scan_version(const char *s, SV *rv, bool qv)
15932 "upg_version"
15934 In-place upgrade of the supplied SV to a version object.
15935 SV *sv = upg_version(SV *sv, bool qv);
15937 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 SV* upg_version(SV *ver, bool qv)
15942 "vcmp"
15944 Version object aware cmp. Both operands must already have been
15945 converted into version objects.
15946 int vcmp(SV *lhv, SV *rhv)
15948 "vnormal"
15950 Accepts a version object and returns the normalized string
15951 representation. Call like:
15952 sv = vnormal(rv);
15954 NOTE: you can pass either the object directly or the SV contained
15956 within the RV.
15957 The SV returned has a refcount of 1.
15959 SV* vnormal(SV *vs)
15961 "vnumify"
15963 Accepts a version object and returns the normalized floating point
15964 representation. Call like:
15965 sv = vnumify(rv);
15967 NOTE: you can pass either the object directly or the SV contained
15969 within the RV.
15970 The SV returned has a refcount of 1.
15972 SV* vnumify(SV *vs)
15974 "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 The SV returned has a refcount of 1.
15982 SV* vstringify(SV *vs)
15984 "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 SV *hv = vverify(sv);
15992 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 • The SV is an HV or a reference to an HV
15998 • The hash contains a "version" key
16000 • The "version" key has a reference to an AV as its value
16002 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 "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 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 The categories must be completely independent, one may not be
16025 subclassed from the other.
16026 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 "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 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 "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 "err" must be one of the "packWARN", "packWARN2", "packWARN3",
16052 "packWARN4" macros populated with the appropriate number of warning
16053 categories.
16054 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 NOTE: "ck_warner" must be explicitly called as "Perl_ck_warner"
16059 with an "aTHX_" parameter.
16060 NOTE: "ck_warner_d" must be explicitly called as "Perl_ck_warner_d"
16062 with an "aTHX_" parameter.
16063 void Perl_ck_warner(pTHX_ U32 err, const char* pat, ...)
16065 "CLEAR_ERRSV"
16067 Clear the contents of $@, setting it to the empty string.
16068 This replaces any read-only SV with a fresh SV and removes any
16070 magic.
16071 void CLEAR_ERRSV()
16073 "croak"
16075 "croak_nocontext"
16076 These are XS interfaces to Perl's "die" function.
16077 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 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 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 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 NOTE: "croak" must be explicitly called as "Perl_croak" with an
16102 "aTHX_" parameter.
16103 void Perl_croak (pTHX_ const char* pat, ...)
16105 void croak_nocontext(const char* pat, ...)
16106 "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 Less code used on exception code paths reduces CPU cache pressure.
16114 void croak_no_modify()
16116 "croak_sv"
16118 This is an XS interface to Perl's "die" function.
16119 "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 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 To die with a simple string message, the "croak" function may be
16132 more convenient.
16133 void croak_sv(SV *baseex)
16135 "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 NOTE: "die" must be explicitly called as "Perl_die" with an "aTHX_"
16142 parameter.
16143 OP* Perl_die(pTHX_ const char* pat, ...)
16145 "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 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 OP* die_sv (SV *baseex)
16157 OP* die_nocontext(const char* pat, ...)
16158 "ERRSV"
16160 Returns the SV for $@, creating it if needed.
16161 SV * ERRSV
16163 "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 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 "PL_curcop"
16179 The currently active COP (control op) roughly representing the
16180 current statement in the source.
16181 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 COP* PL_curcop
16187 "PL_curstash"
16189 The stash for the package code will be compiled into.
16190 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 HV* PL_curstash
16196 "PL_defgv"
16198 The GV representing *_. Useful for access to $_.
16199 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 GV * PL_defgv
16205 "SANE_ERRSV"
16207 Clean up ERRSV so we can safely set it.
16208 This replaces any read-only SV with a fresh writable copy and
16210 removes any magic.
16211 void SANE_ERRSV()
16213 "vcroak"
16215 This is an XS interface to Perl's "die" function.
16216 "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 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 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 void vcroak(const char* pat, va_list* args)
16236 "vwarn"
16238 This is an XS interface to Perl's "warn" function.
16239 This is like "warn", but "args" are an encapsulated argument list.
16241 Unlike with "vcroak", "pat" is not permitted to be null.
16243 void vwarn(const char* pat, va_list* args)
16245 "vwarner"
16247 This is like "warner", but "args" are an encapsulated argument
16248 list.
16249 void vwarner(U32 err, const char* pat, va_list* args)
16251 "warn"
16253 "warn_nocontext"
16254 These are XS interfaces to Perl's "warn" function.
16255 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 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 Unlike with "croak", "pat" is not permitted to be null.
16266 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 NOTE: "warn" must be explicitly called as "Perl_warn" with an
16272 "aTHX_" parameter.
16273 void Perl_warn (pTHX_ const char* pat, ...)
16275 void warn_nocontext(const char* pat, ...)
16276 "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 "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 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 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 "pat" is not permitted to be null.
16298 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 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 NOTE: "warner" must be explicitly called as "Perl_warner" with an
16310 "aTHX_" parameter.
16311 void Perl_warner (pTHX_ U32 err, const char* pat, ...)
16313 void warner_nocontext(U32 err, const char* pat, ...)
16314 "warn_sv"
16316 This is an XS interface to Perl's "warn" function.
16317 "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 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 To warn with a simple string message, the "warn" function may be
16329 more convenient.
16330 void warn_sv(SV *baseex)
16332
16334 xsubpp compiles XS code into C. See "xsubpp" in perlutil.
16335 "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 I32 ax
16342 "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 char* CLASS
16348 "dAX"
16350 Sets up the "ax" variable. This is usually handled automatically
16351 by "xsubpp" by calling "dXSARGS".
16352 dAX;
16354 "dAXMARK"
16356 Sets up the "ax" variable and stack marker variable "mark". This
16357 is usually handled automatically by "xsubpp" by calling "dXSARGS".
16358 dAXMARK;
16360 "dITEMS"
16362 Sets up the "items" variable. This is usually handled
16363 automatically by "xsubpp" by calling "dXSARGS".
16364 dITEMS;
16366 "dMY_CXT_SV"
16368 Now a placeholder that declares nothing
16369 dMY_CXT_SV;
16371 "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 dUNDERBAR;
16379 "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 dXSARGS;
16386 "dXSI32"
16388 Sets up the "ix" variable for an XSUB which has aliases. This is
16389 usually handled automatically by "xsubpp".
16390 dXSI32;
16392 "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 I32 items
16398 "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 I32 ix
16404 "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 type RETVAL
16411 "ST"
16413 Used to access elements on the XSUB's stack.
16414 SV* ST(int ix)
16416 "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 type THIS
16423 "UNDERBAR"
16425 The SV* corresponding to the $_ variable. Works even if there is a
16426 lexical $_ in scope.
16427 "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 "XS_EXTERNAL"
16434 Macro to declare an XSUB and its C parameter list explicitly
16435 exporting the symbols.
16436 "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 "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 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 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 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 API Listing originally by Dean Roehrich <roehrich@cray.com>.
16532 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
16539perl v5.34.1 2022-03-15 PERLAPI(1)