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 "COPs and Hint Hashes"
87 "Custom Operators"
88 "CV Handling"
89 "Debugging"
90 "Display functions"
91 "Embedding, Threads, and Interpreter Cloning"
92 "Errno"
93 "Exception Handling (simple) Macros"
94 "Filesystem configuration values"
95 "Floating point"
96 "General Configuration"
97 "Global Variables"
98 "GV Handling and Stashes"
99 "Hook manipulation"
100 "HV Handling"
101 "Input/Output"
102 "Integer"
103 "I/O Formats"
104 "Lexer interface"
105 "Locales"
106 "Magic"
107 "Memory Management"
108 "MRO"
109 "Multicall Functions"
110 "Numeric Functions"
111 "Optrees"
112 "Pack and Unpack"
113 "Pad Data Structures"
114 "Password and Group access"
115 "Paths to system commands"
116 "Prototype information"
117 "REGEXP Functions"
118 "Reports and Formats"
119 "Signals"
120 "Site configuration"
121 "Sockets configuration values"
122 "Source Filters"
123 "Stack Manipulation Macros"
124 "String Handling"
125 "SV Flags"
126 "SV Handling"
127 "Tainting"
128 "Time"
129 "Typedef names"
130 "Unicode Support"
131 "Utility Functions"
132 "Versioning"
133 "Warning and Dieing"
134 "XS"
135 "Undocumented elements"
136 The listing below is alphabetical, case insensitive.
138
140 "AV"
141 Described in perlguts.
142 "AvALLOC"
144 Described in perlguts.
145 AvALLOC(AV* av)
147 "AvARRAY"
149 Returns a pointer to the AV's internal SV* array.
150 This is useful for doing pointer arithmetic on the array. If all
152 you need is to look up an array element, then prefer "av_fetch".
153 SV** AvARRAY(AV* av)
155 "av_clear"
157 Frees all the elements of an array, leaving it empty. The XS
158 equivalent of "@array = ()". See also "av_undef".
159 Note that it is possible that the actions of a destructor called
161 directly or indirectly by freeing an element of the array could
162 cause the reference count of the array itself to be reduced (e.g.
163 by deleting an entry in the symbol table). So it is a possibility
164 that the AV could have been freed (or even reallocated) on return
165 from the call unless you hold a reference to it.
166 void av_clear(AV *av)
168 "av_count"
170 Returns the number of elements in the array "av". This is the true
171 length of the array, including any undefined elements. It is
172 always the same as "av_top_index(av) + 1".
173 Size_t av_count(AV *av)
175 "av_create_and_push"
177 Push an SV onto the end of the array, creating the array if
178 necessary. A small internal helper function to remove a commonly
179 duplicated idiom.
180 NOTE: "av_create_and_push" must be explicitly called as
182 "Perl_av_create_and_push" with an "aTHX_" parameter.
183 void Perl_av_create_and_push(pTHX_ AV **const avp,
185 SV *const val)
186 "av_create_and_unshift_one"
188 Unshifts an SV onto the beginning of the array, creating the array
189 if necessary. A small internal helper function to remove a
190 commonly duplicated idiom.
191 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 (**strp, length
274 "size") of SVs. A copy is made of each SV, so their refcounts are
275 not changed. The new AV will have a reference count of 1.
276 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 "newAV_alloc_x"
377 "newAV_alloc_xz"
378 These all create a new AV, setting the reference count to 1. If
379 you also know the initial elements of the array with, see
380 ""av_make"".
381 As background, an array consists of three things:
383 1. A data structure containing information about the array as a
385 whole, such as its size and reference count.
386 2. A C language array of pointers to the individual elements.
388 These are treated as pointers to SVs, so all must be castable
389 to SV*.
390 3. The individual elements themselves. These could be, for
392 instance, SVs and/or AVs and/or HVs, etc.
393 An empty array need only have the first data structure, and all
395 these functions create that. They differ in what else they do, as
396 follows:
397 "newAV" form
399 This does nothing beyond creating the whole-array data
400 structure. The Perl equivalent is approximately "my @array;"
401 This is useful when the minimum size of the array could be zero
403 (perhaps there are likely code paths that will entirely skip
404 using it).
405 If the array does get used, the pointers data structure will
407 need to be allocated at that time. This will end up being done
408 by "av_extend">, either explicitly:
409 av_extend(av, len);
411 or implicitly when the first element is stored:
413 (void)av_store(av, 0, sv);
415 Unused array elements are typically initialized by "av_extend".
417 "newAV_alloc_x" form
419 This effectively does a "newAV" followed by also allocating
420 (uninitialized) space for the pointers array. This is used
421 when you know ahead of time the likely minimum size of the
422 array. It is more efficient to do this than doing a plain
423 "newAV" followed by an "av_extend".
424 Of course the array can be extended later should it become
426 necessary.
427 "size" must be at least 1.
429 "newAV_alloc_xz" form
431 This is "newAV_alloc_x", but initializes each pointer in it to
432 NULL. This gives added safety to guard against them being read
433 before being set.
434 "size" must be at least 1.
436 The following examples all result in an array that can fit four
438 elements (indexes 0 .. 3):
439 AV *av = newAV();
441 av_extend(av, 3);
442 AV *av = newAV_alloc_x(4);
444 AV *av = newAV_alloc_xz(4);
446 In contrast, the following examples allocate an array that is only
448 guaranteed to fit one element without extending:
449 AV *av = newAV_alloc_x(1);
451 AV *av = newAV_alloc_xz(1);
452 AV* newAV ()
454 AV* newAV_alloc_x (SSize_t size)
455 AV* newAV_alloc_xz(SSize_t size)
456 "Nullav"
458 "DEPRECATED!" It is planned to remove "Nullav" from a future
459 release of Perl. Do not use it for new code; remove it from
460 existing code.
461 Null AV pointer.
463 (deprecated - use "(AV *)NULL" instead)
465
467 "call_argv"
468 Performs a callback to the specified named and package-scoped Perl
469 subroutine with "argv" (a "NULL"-terminated array of strings) as
470 arguments. See perlcall.
471 Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
473 NOTE: the "perl_call_argv()" form is deprecated.
475 I32 call_argv(const char* sub_name, I32 flags, char** argv)
477 "call_method"
479 Performs a callback to the specified Perl method. The blessed
480 object must be on the stack. See perlcall.
481 NOTE: the "perl_call_method()" form is deprecated.
483 I32 call_method(const char* methname, I32 flags)
485 "call_pv"
487 Performs a callback to the specified Perl sub. See perlcall.
488 NOTE: the "perl_call_pv()" form is deprecated.
490 I32 call_pv(const char* sub_name, I32 flags)
492 "call_sv"
494 Performs a callback to the Perl sub specified by the SV.
495 If neither the "G_METHOD" nor "G_METHOD_NAMED" flag is supplied,
497 the SV may be any of a CV, a GV, a reference to a CV, a reference
498 to a GV or "SvPV(sv)" will be used as the name of the sub to call.
499 If the "G_METHOD" flag is supplied, the SV may be a reference to a
501 CV or "SvPV(sv)" will be used as the name of the method to call.
502 If the "G_METHOD_NAMED" flag is supplied, "SvPV(sv)" will be used
504 as the name of the method to call.
505 Some other values are treated specially for internal use and should
507 not be depended on.
508 See perlcall.
510 NOTE: the "perl_call_sv()" form is deprecated.
512 I32 call_sv(SV* sv, volatile I32 flags)
514 "DESTRUCTORFUNC_NOCONTEXT_t"
516 Described in perlguts.
517 "DESTRUCTORFUNC_t"
519 Described in perlguts.
520 "ENTER"
522 Opening bracket on a callback. See "LEAVE" and perlcall.
523 ENTER;
525 "ENTER_with_name"
527 Same as "ENTER", but when debugging is enabled it also associates
528 the given literal string with the new scope.
529 ENTER_with_name("name");
531 "eval_pv"
533 Tells Perl to "eval" the given string in scalar context and return
534 an SV* result.
535 NOTE: the "perl_eval_pv()" form is deprecated.
537 SV* eval_pv(const char* p, I32 croak_on_error)
539 "eval_sv"
541 Tells Perl to "eval" the string in the SV. It supports the same
542 flags as "call_sv", with the obvious exception of "G_EVAL". See
543 perlcall.
544 The "G_RETHROW" flag can be used if you only need eval_sv() to
546 execute code specified by a string, but not catch any errors.
547 NOTE: the "perl_eval_sv()" form is deprecated.
549 I32 eval_sv(SV* sv, I32 flags)
551 "FREETMPS"
553 Closing bracket for temporaries on a callback. See "SAVETMPS" and
554 perlcall.
555 FREETMPS;
557 "G_DISCARD"
559 Described in perlcall.
560 "G_EVAL"
562 Described in perlcall.
563 "GIMME"
565 "DEPRECATED!" It is planned to remove "GIMME" from a future
566 release of Perl. Do not use it for new code; remove it from
567 existing code.
568 A backward-compatible version of "GIMME_V" which can only return
570 "G_SCALAR" or "G_LIST"; in a void context, it returns "G_SCALAR".
571 Deprecated. Use "GIMME_V" instead.
572 U32 GIMME
574 "GIMME_V"
576 The XSUB-writer's equivalent to Perl's "wantarray". Returns
577 "G_VOID", "G_SCALAR" or "G_LIST" for void, scalar or list context,
578 respectively. See perlcall for a usage example.
579 U32 GIMME_V
581 "G_KEEPERR"
583 Described in perlcall.
584 "G_LIST"
586 Described in perlcall.
587 "G_NOARGS"
589 Described in perlcall.
590 "G_SCALAR"
592 Described in perlcall.
593 "G_VOID"
595 Described in perlcall.
596 "is_lvalue_sub"
598 Returns non-zero if the sub calling this function is being called
599 in an lvalue context. Returns 0 otherwise.
600 I32 is_lvalue_sub()
602 "LEAVE"
604 Closing bracket on a callback. See "ENTER" and perlcall.
605 LEAVE;
607 "LEAVE_with_name"
609 Same as "LEAVE", but when debugging is enabled it first checks that
610 the scope has the given name. "name" must be a literal string.
611 LEAVE_with_name("name");
613 "PL_errgv"
615 Described in perlcall.
616 "save_aptr"
618 Described in perlguts.
619 void save_aptr(AV** aptr)
621 "save_ary"
623 Described in perlguts.
624 AV* save_ary(GV* gv)
626 "SAVEBOOL"
628 Described in perlguts.
629 SAVEBOOL(bool i)
631 "SAVEDELETE"
633 Described in perlguts.
634 SAVEDELETE(HV * hv, char * key, I32 length)
636 "SAVEDESTRUCTOR"
638 Described in perlguts.
639 SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)
641 "SAVEDESTRUCTOR_X"
643 Described in perlguts.
644 SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)
646 "SAVEFREEOP"
648 Described in perlguts.
649 SAVEFREEOP(OP *op)
651 "SAVEFREEPV"
653 Described in perlguts.
654 SAVEFREEPV(void * p)
656 "SAVEFREESV"
658 Described in perlguts.
659 SAVEFREESV(SV* sv)
661 "save_hash"
663 Described in perlguts.
664 HV* save_hash(GV* gv)
666 "save_hptr"
668 Described in perlguts.
669 void save_hptr(HV** hptr)
671 "SAVEI8"
673 Described in perlguts.
674 SAVEI8(I8 i)
676 "SAVEI32"
678 Described in perlguts.
679 SAVEI32(I32 i)
681 "SAVEI16"
683 Described in perlguts.
684 SAVEI16(I16 i)
686 "SAVEINT"
688 Described in perlguts.
689 SAVEINT(int i)
691 "save_item"
693 Described in perlguts.
694 void save_item(SV* item)
696 "SAVEIV"
698 Described in perlguts.
699 SAVEIV(IV i)
701 "save_list"
703 "DEPRECATED!" It is planned to remove "save_list" from a future
704 release of Perl. Do not use it for new code; remove it from
705 existing code.
706 Described in perlguts.
708 void save_list(SV** sarg, I32 maxsarg)
710 "SAVELONG"
712 Described in perlguts.
713 SAVELONG(long i)
715 "SAVEMORTALIZESV"
717 Described in perlguts.
718 SAVEMORTALIZESV(SV* sv)
720 "SAVEPPTR"
722 Described in perlguts.
723 SAVEPPTR(char * p)
725 "save_scalar"
727 Described in perlguts.
728 SV* save_scalar(GV* gv)
730 "SAVESPTR"
732 Described in perlguts.
733 SAVESPTR(SV * s)
735 "SAVESTACK_POS"
737 Described in perlguts.
738 SAVESTACK_POS()
740 "SAVESTRLEN"
742 Described in perlguts.
743 SAVESTRLEN(STRLEN i)
745 "save_svref"
747 Described in perlguts.
748 SV* save_svref(SV** sptr)
750 "SAVETMPS"
752 Opening bracket for temporaries on a callback. See "FREETMPS" and
753 perlcall.
754 SAVETMPS;
756
758 "cBOOL"
759 Cast-to-bool. When Perl was able to be compiled on pre-C99
760 compilers, a "(bool)" cast didn't necessarily do the right thing,
761 so this macro was created (and made somewhat complicated to work
762 around bugs in old compilers). Now, many years later, and C99 is
763 used, this is no longer required, but is kept for backwards
764 compatibility.
765 bool cBOOL(bool expr)
767 "I_32"
769 Cast an NV to I32 while avoiding undefined C behavior
770 I32 I_32(NV what)
772 "INT2PTR"
774 Described in perlguts.
775 type INT2PTR(type, int value)
777 "I_V"
779 Cast an NV to IV while avoiding undefined C behavior
780 IV I_V(NV what)
782 "PTR2IV"
784 Described in perlguts.
785 IV PTR2IV(void * ptr)
787 "PTR2nat"
789 Described in perlguts.
790 IV PTR2nat(void *)
792 "PTR2NV"
794 Described in perlguts.
795 NV PTR2NV(void * ptr)
797 "PTR2ul"
799 Described in perlguts.
800 unsigned long PTR2ul(void *)
802 "PTR2UV"
804 Described in perlguts.
805 UV PTR2UV(void * ptr)
807 "PTRV"
809 Described in perlguts.
810 "U_32"
812 Cast an NV to U32 while avoiding undefined C behavior
813 U32 U_32(NV what)
815 "U_V"
817 Cast an NV to UV while avoiding undefined C behavior
818 UV U_V(NV what)
820
822 Perl uses "full" Unicode case mappings. This means that converting a
823 single character to another case may result in a sequence of more than
824 one character. For example, the uppercase of "ss" (LATIN SMALL LETTER
825 SHARP S) is the two character sequence "SS". This presents some
826 complications The lowercase of all characters in the range 0..255 is
827 a single character, and thus "toLOWER_L1" is furnished. But,
828 "toUPPER_L1" can't exist, as it couldn't return a valid result for all
829 legal inputs. Instead "toUPPER_uvchr" has an API that does allow every
830 possible legal result to be returned.) Likewise no other function that
831 is crippled by not being able to give the correct results for the full
832 range of possible inputs has been implemented here.
833 "toFOLD"
835 "toFOLD_A"
836 "toFOLD_uvchr"
837 "toFOLD_utf8"
838 "toFOLD_utf8_safe"
839 These all return the foldcase of a character. "foldcase" is an
840 internal case for "/i" pattern matching. If the foldcase of
841 character A and the foldcase of character B are the same, they
842 match caselessly; otherwise they don't.
843 The differences in the forms are what domain they operate on, and
845 whether the input is specified as a code point (those forms with a
846 "cp" parameter) or as a UTF-8 string (the others). In the latter
847 case, the code point to use is the first one in the buffer of UTF-8
848 encoded code points, delineated by the arguments "p .. e - 1".
849 "toFOLD" and "toFOLD_A" are synonyms of each other. They return
851 the foldcase of any ASCII-range code point. In this range, the
852 foldcase is identical to the lowercase. All other inputs are
853 returned unchanged. Since these are macros, the input type may be
854 any integral one, and the output will occupy the same number of
855 bits as the input.
856 There is no "toFOLD_L1" nor "toFOLD_LATIN1" as the foldcase of some
858 code points in the 0..255 range is above that range or consists of
859 multiple characters. Instead use "toFOLD_uvchr".
860 "toFOLD_uvchr" returns the foldcase of any Unicode code point. The
862 return value is identical to that of "toFOLD_A" for input code
863 points in the ASCII range. The foldcase of the vast majority of
864 Unicode code points is the same as the code point itself. For
865 these, and for code points above the legal Unicode maximum, this
866 returns the input code point unchanged. It additionally stores the
867 UTF-8 of the result into the buffer beginning at "s", and its
868 length in bytes into *lenp. The caller must have made "s" large
869 enough to contain at least "UTF8_MAXBYTES_CASE+1" bytes to avoid
870 possible overflow.
871 NOTE: the foldcase of a code point may be more than one code point.
873 The return value of this function is only the first of these. The
874 entire foldcase is returned in "s". To determine if the result is
875 more than a single code point, you can do something like this:
876 uc = toFOLD_uvchr(cp, s, &len);
878 if (len > UTF8SKIP(s)) { is multiple code points }
879 else { is a single code point }
880 "toFOLD_utf8" and "toFOLD_utf8_safe" are synonyms of each other.
882 The only difference between these and "toFOLD_uvchr" is that the
883 source for these is encoded in UTF-8, instead of being a code
884 point. It is passed as a buffer starting at "p", with "e" pointing
885 to one byte beyond its end. The "p" buffer may certainly contain
886 more than one code point; but only the first one (up through
887 "e - 1") is examined. If the UTF-8 for the input character is
888 malformed in some way, the program may croak, or the function may
889 return the REPLACEMENT CHARACTER, at the discretion of the
890 implementation, and subject to change in future releases.
891 UV toFOLD (UV cp)
893 UV toFOLD_A (UV cp)
894 UV toFOLD_uvchr (UV cp, U8* s, STRLEN* lenp)
895 UV toFOLD_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
896 UV toFOLD_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
897 "toLOWER"
899 "toLOWER_A"
900 "toLOWER_L1"
901 "toLOWER_LATIN1"
902 "toLOWER_LC"
903 "toLOWER_uvchr"
904 "toLOWER_utf8"
905 "toLOWER_utf8_safe"
906 These all return the lowercase of a character. The differences are
907 what domain they operate on, and whether the input is specified as
908 a code point (those forms with a "cp" parameter) or as a UTF-8
909 string (the others). In the latter case, the code point to use is
910 the first one in the buffer of UTF-8 encoded code points,
911 delineated by the arguments "p .. e - 1".
912 "toLOWER" and "toLOWER_A" are synonyms of each other. They return
914 the lowercase of any uppercase ASCII-range code point. All other
915 inputs are returned unchanged. Since these are macros, the input
916 type may be any integral one, and the output will occupy the same
917 number of bits as the input.
918 "toLOWER_L1" and "toLOWER_LATIN1" are synonyms of each other. They
920 behave identically as "toLOWER" for ASCII-range input. But
921 additionally will return the lowercase of any uppercase code point
922 in the entire 0..255 range, assuming a Latin-1 encoding (or the
923 EBCDIC equivalent on such platforms).
924 "toLOWER_LC" returns the lowercase of the input code point
926 according to the rules of the current POSIX locale. Input code
927 points outside the range 0..255 are returned unchanged.
928 "toLOWER_uvchr" returns the lowercase of any Unicode code point.
930 The return value is identical to that of "toLOWER_L1" for input
931 code points in the 0..255 range. The lowercase of the vast
932 majority of Unicode code points is the same as the code point
933 itself. For these, and for code points above the legal Unicode
934 maximum, this returns the input code point unchanged. It
935 additionally stores the UTF-8 of the result into the buffer
936 beginning at "s", and its length in bytes into *lenp. The caller
937 must have made "s" large enough to contain at least
938 "UTF8_MAXBYTES_CASE+1" bytes to avoid possible overflow.
939 NOTE: the lowercase of a code point may be more than one code
941 point. The return value of this function is only the first of
942 these. The entire lowercase is returned in "s". To determine if
943 the result is more than a single code point, you can do something
944 like this:
945 uc = toLOWER_uvchr(cp, s, &len);
947 if (len > UTF8SKIP(s)) { is multiple code points }
948 else { is a single code point }
949 "toLOWER_utf8" and "toLOWER_utf8_safe" are synonyms of each other.
951 The only difference between these and "toLOWER_uvchr" is that the
952 source for these is encoded in UTF-8, instead of being a code
953 point. It is passed as a buffer starting at "p", with "e" pointing
954 to one byte beyond its end. The "p" buffer may certainly contain
955 more than one code point; but only the first one (up through
956 "e - 1") is examined. If the UTF-8 for the input character is
957 malformed in some way, the program may croak, or the function may
958 return the REPLACEMENT CHARACTER, at the discretion of the
959 implementation, and subject to change in future releases.
960 UV toLOWER (UV cp)
962 UV toLOWER_A (UV cp)
963 UV toLOWER_L1 (UV cp)
964 UV toLOWER_LATIN1 (UV cp)
965 UV toLOWER_LC (UV cp)
966 UV toLOWER_uvchr (UV cp, U8* s, STRLEN* lenp)
967 UV toLOWER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
968 UV toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
969 "toTITLE"
971 "toTITLE_A"
972 "toTITLE_uvchr"
973 "toTITLE_utf8"
974 "toTITLE_utf8_safe"
975 These all return the titlecase of a character. The differences are
976 what domain they operate on, and whether the input is specified as
977 a code point (those forms with a "cp" parameter) or as a UTF-8
978 string (the others). In the latter case, the code point to use is
979 the first one in the buffer of UTF-8 encoded code points,
980 delineated by the arguments "p .. e - 1".
981 "toTITLE" and "toTITLE_A" are synonyms of each other. They return
983 the titlecase of any lowercase ASCII-range code point. In this
984 range, the titlecase is identical to the uppercase. All other
985 inputs are returned unchanged. Since these are macros, the input
986 type may be any integral one, and the output will occupy the same
987 number of bits as the input.
988 There is no "toTITLE_L1" nor "toTITLE_LATIN1" as the titlecase of
990 some code points in the 0..255 range is above that range or
991 consists of multiple characters. Instead use "toTITLE_uvchr".
992 "toTITLE_uvchr" returns the titlecase of any Unicode code point.
994 The return value is identical to that of "toTITLE_A" for input code
995 points in the ASCII range. The titlecase of the vast majority of
996 Unicode code points is the same as the code point itself. For
997 these, and for code points above the legal Unicode maximum, this
998 returns the input code point unchanged. It additionally stores the
999 UTF-8 of the result into the buffer beginning at "s", and its
1000 length in bytes into *lenp. The caller must have made "s" large
1001 enough to contain at least "UTF8_MAXBYTES_CASE+1" bytes to avoid
1002 possible overflow.
1003 NOTE: the titlecase of a code point may be more than one code
1005 point. The return value of this function is only the first of
1006 these. The entire titlecase is returned in "s". To determine if
1007 the result is more than a single code point, you can do something
1008 like this:
1009 uc = toTITLE_uvchr(cp, s, &len);
1011 if (len > UTF8SKIP(s)) { is multiple code points }
1012 else { is a single code point }
1013 "toTITLE_utf8" and "toTITLE_utf8_safe" are synonyms of each other.
1015 The only difference between these and "toTITLE_uvchr" is that the
1016 source for these is encoded in UTF-8, instead of being a code
1017 point. It is passed as a buffer starting at "p", with "e" pointing
1018 to one byte beyond its end. The "p" buffer may certainly contain
1019 more than one code point; but only the first one (up through
1020 "e - 1") is examined. If the UTF-8 for the input character is
1021 malformed in some way, the program may croak, or the function may
1022 return the REPLACEMENT CHARACTER, at the discretion of the
1023 implementation, and subject to change in future releases.
1024 UV toTITLE (UV cp)
1026 UV toTITLE_A (UV cp)
1027 UV toTITLE_uvchr (UV cp, U8* s, STRLEN* lenp)
1028 UV toTITLE_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1029 UV toTITLE_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1030 "toUPPER"
1032 "toUPPER_A"
1033 "toUPPER_uvchr"
1034 "toUPPER_utf8"
1035 "toUPPER_utf8_safe"
1036 These all return the uppercase of a character. The differences are
1037 what domain they operate on, and whether the input is specified as
1038 a code point (those forms with a "cp" parameter) or as a UTF-8
1039 string (the others). In the latter case, the code point to use is
1040 the first one in the buffer of UTF-8 encoded code points,
1041 delineated by the arguments "p .. e - 1".
1042 "toUPPER" and "toUPPER_A" are synonyms of each other. They return
1044 the uppercase of any lowercase ASCII-range code point. All other
1045 inputs are returned unchanged. Since these are macros, the input
1046 type may be any integral one, and the output will occupy the same
1047 number of bits as the input.
1048 There is no "toUPPER_L1" nor "toUPPER_LATIN1" as the uppercase of
1050 some code points in the 0..255 range is above that range or
1051 consists of multiple characters. Instead use "toUPPER_uvchr".
1052 "toUPPER_uvchr" returns the uppercase of any Unicode code point.
1054 The return value is identical to that of "toUPPER_A" for input code
1055 points in the ASCII range. The uppercase of the vast majority of
1056 Unicode code points is the same as the code point itself. For
1057 these, and for code points above the legal Unicode maximum, this
1058 returns the input code point unchanged. It additionally stores the
1059 UTF-8 of the result into the buffer beginning at "s", and its
1060 length in bytes into *lenp. The caller must have made "s" large
1061 enough to contain at least "UTF8_MAXBYTES_CASE+1" bytes to avoid
1062 possible overflow.
1063 NOTE: the uppercase of a code point may be more than one code
1065 point. The return value of this function is only the first of
1066 these. The entire uppercase is returned in "s". To determine if
1067 the result is more than a single code point, you can do something
1068 like this:
1069 uc = toUPPER_uvchr(cp, s, &len);
1071 if (len > UTF8SKIP(s)) { is multiple code points }
1072 else { is a single code point }
1073 "toUPPER_utf8" and "toUPPER_utf8_safe" are synonyms of each other.
1075 The only difference between these and "toUPPER_uvchr" is that the
1076 source for these is encoded in UTF-8, instead of being a code
1077 point. It is passed as a buffer starting at "p", with "e" pointing
1078 to one byte beyond its end. The "p" buffer may certainly contain
1079 more than one code point; but only the first one (up through
1080 "e - 1") is examined. If the UTF-8 for the input character is
1081 malformed in some way, the program may croak, or the function may
1082 return the REPLACEMENT CHARACTER, at the discretion of the
1083 implementation, and subject to change in future releases.
1084 UV toUPPER (UV cp)
1086 UV toUPPER_A (UV cp)
1087 UV toUPPER_uvchr (UV cp, U8* s, STRLEN* lenp)
1088 UV toUPPER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1089 UV toUPPER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1090
1092 This section is about functions (really macros) that classify
1093 characters into types, such as punctuation versus alphabetic, etc.
1094 Most of these are analogous to regular expression character classes.
1095 (See "POSIX Character Classes" in perlrecharclass.) There are several
1096 variants for each class. (Not all macros have all variants; each item
1097 below lists the ones valid for it.) None are affected by "use bytes",
1098 and only the ones with "LC" in the name are affected by the current
1099 locale.
1100 The base function, e.g., "isALPHA()", takes any signed or unsigned
1102 value, treating it as a code point, and returns a boolean as to whether
1103 or not the character represented by it is (or on non-ASCII platforms,
1104 corresponds to) an ASCII character in the named class based on
1105 platform, Unicode, and Perl rules. If the input is a number that
1106 doesn't fit in an octet, FALSE is returned.
1107 Variant "isFOO_A" (e.g., "isALPHA_A()") is identical to the base
1109 function with no suffix "_A". This variant is used to emphasize by its
1110 name that only ASCII-range characters can return TRUE.
1111 Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivalent) character
1113 set onto the platform. That is, the code points that are ASCII are
1114 unaffected, since ASCII is a subset of Latin-1. But the non-ASCII code
1115 points are treated as if they are Latin-1 characters. For example,
1116 "isWORDCHAR_L1()" will return true when called with the code point
1117 0xDF, which is a word character in both ASCII and EBCDIC (though it
1118 represents different characters in each). If the input is a number
1119 that doesn't fit in an octet, FALSE is returned. (Perl's documentation
1120 uses a colloquial definition of Latin-1, to include all code points
1121 below 256.)
1122 Variant "isFOO_uvchr" is exactly like the "isFOO_L1" variant, for
1124 inputs below 256, but if the code point is larger than 255, Unicode
1125 rules are used to determine if it is in the character class. For
1126 example, "isWORDCHAR_uvchr(0x100)" returns TRUE, since 0x100 is LATIN
1127 CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.
1128 Variants "isFOO_utf8" and "isFOO_utf8_safe" are like "isFOO_uvchr", but
1130 are used for UTF-8 encoded strings. The two forms are different names
1131 for the same thing. Each call to one of these classifies the first
1132 character of the string starting at "p". The second parameter, "e",
1133 points to anywhere in the string beyond the first character, up to one
1134 byte past the end of the entire string. Although both variants are
1135 identical, the suffix "_safe" in one name emphasizes that it will not
1136 attempt to read beyond "e - 1", provided that the constraint "s < e" is
1137 true (this is asserted for in "-DDEBUGGING" builds). If the UTF-8 for
1138 the input character is malformed in some way, the program may croak, or
1139 the function may return FALSE, at the discretion of the implementation,
1140 and subject to change in future releases.
1141 Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but
1143 the result is based on the current locale, which is what "LC" in the
1144 name stands for. If Perl can determine that the current locale is a
1145 UTF-8 locale, it uses the published Unicode rules; otherwise, it uses
1146 the C library function that gives the named classification. For
1147 example, "isDIGIT_LC()" when not in a UTF-8 locale returns the result
1148 of calling "isdigit()". FALSE is always returned if the input won't
1149 fit into an octet. On some platforms where the C library function is
1150 known to be defective, Perl changes its result to follow the POSIX
1151 standard's rules.
1152 Variant "isFOO_LC_uvchr" acts exactly like "isFOO_LC" for inputs less
1154 than 256, but for larger ones it returns the Unicode classification of
1155 the code point.
1156 Variants "isFOO_LC_utf8" and "isFOO_LC_utf8_safe" are like
1158 "isFOO_LC_uvchr", but are used for UTF-8 encoded strings. The two
1159 forms are different names for the same thing. Each call to one of
1160 these classifies the first character of the string starting at "p".
1161 The second parameter, "e", points to anywhere in the string beyond the
1162 first character, up to one byte past the end of the entire string.
1163 Although both variants are identical, the suffix "_safe" in one name
1164 emphasizes that it will not attempt to read beyond "e - 1", provided
1165 that the constraint "s < e" is true (this is asserted for in
1166 "-DDEBUGGING" builds). If the UTF-8 for the input character is
1167 malformed in some way, the program may croak, or the function may
1168 return FALSE, at the discretion of the implementation, and subject to
1169 change in future releases.
1170 "isALPHA"
1172 "isALPHA_A"
1173 "isALPHA_L1"
1174 "isALPHA_uvchr"
1175 "isALPHA_utf8_safe"
1176 "isALPHA_utf8"
1177 "isALPHA_LC"
1178 "isALPHA_LC_uvchr"
1179 "isALPHA_LC_utf8_safe"
1180 Returns a boolean indicating whether the specified input is one of
1181 "[A-Za-z]", analogous to "m/[[:alpha:]]/". See the top of this
1182 section for an explanation of the variants.
1183 bool isALPHA (UV ch)
1185 bool isALPHA_A (UV ch)
1186 bool isALPHA_L1 (UV ch)
1187 bool isALPHA_uvchr (UV ch)
1188 bool isALPHA_utf8_safe (U8 * s, U8 * end)
1189 bool isALPHA_utf8 (U8 * s, U8 * end)
1190 bool isALPHA_LC (UV ch)
1191 bool isALPHA_LC_uvchr (UV ch)
1192 bool isALPHA_LC_utf8_safe(U8 * s, U8 *end)
1193 "isALPHANUMERIC"
1195 "isALPHANUMERIC_A"
1196 "isALPHANUMERIC_L1"
1197 "isALPHANUMERIC_uvchr"
1198 "isALPHANUMERIC_utf8_safe"
1199 "isALPHANUMERIC_utf8"
1200 "isALPHANUMERIC_LC"
1201 "isALPHANUMERIC_LC_uvchr"
1202 "isALPHANUMERIC_LC_utf8_safe"
1203 "isALNUMC"
1204 "isALNUMC_A"
1205 "isALNUMC_L1"
1206 "isALNUMC_LC"
1207 "isALNUMC_LC_uvchr"
1208 Returns a boolean indicating whether the specified character is one
1209 of "[A-Za-z0-9]", analogous to "m/[[:alnum:]]/". See the top of
1210 this section for an explanation of the variants.
1211 A (discouraged from use) synonym is "isALNUMC" (where the "C"
1213 suffix means this corresponds to the C language alphanumeric
1214 definition). Also there are the variants "isALNUMC_A",
1215 "isALNUMC_L1" "isALNUMC_LC", and "isALNUMC_LC_uvchr".
1216 bool isALPHANUMERIC (UV ch)
1218 bool isALPHANUMERIC_A (UV ch)
1219 bool isALPHANUMERIC_L1 (UV ch)
1220 bool isALPHANUMERIC_uvchr (UV ch)
1221 bool isALPHANUMERIC_utf8_safe (U8 * s, U8 * end)
1222 bool isALPHANUMERIC_utf8 (U8 * s, U8 * end)
1223 bool isALPHANUMERIC_LC (UV ch)
1224 bool isALPHANUMERIC_LC_uvchr (UV ch)
1225 bool isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end)
1226 bool isALNUMC (UV ch)
1227 bool isALNUMC_A (UV ch)
1228 bool isALNUMC_L1 (UV ch)
1229 bool isALNUMC_LC (UV ch)
1230 bool isALNUMC_LC_uvchr (UV ch)
1231 "isASCII"
1233 "isASCII_A"
1234 "isASCII_L1"
1235 "isASCII_uvchr"
1236 "isASCII_utf8_safe"
1237 "isASCII_utf8"
1238 "isASCII_LC"
1239 "isASCII_LC_uvchr"
1240 "isASCII_LC_utf8_safe"
1241 Returns a boolean indicating whether the specified character is one
1242 of the 128 characters in the ASCII character set, analogous to
1243 "m/[[:ascii:]]/". On non-ASCII platforms, it returns TRUE iff this
1244 character corresponds to an ASCII character. Variants
1245 "isASCII_A()" and "isASCII_L1()" are identical to "isASCII()". See
1246 the top of this section for an explanation of the variants. Note,
1247 however, that some platforms do not have the C library routine
1248 "isascii()". In these cases, the variants whose names contain "LC"
1249 are the same as the corresponding ones without.
1250 Also note, that because all ASCII characters are UTF-8 invariant
1252 (meaning they have the exact same representation (always a single
1253 byte) whether encoded in UTF-8 or not), "isASCII" will give the
1254 correct results when called with any byte in any string encoded or
1255 not in UTF-8. And similarly "isASCII_utf8" and "isASCII_utf8_safe"
1256 will work properly on any string encoded or not in UTF-8.
1257 bool isASCII (UV ch)
1259 bool isASCII_A (UV ch)
1260 bool isASCII_L1 (UV ch)
1261 bool isASCII_uvchr (UV ch)
1262 bool isASCII_utf8_safe (U8 * s, U8 * end)
1263 bool isASCII_utf8 (U8 * s, U8 * end)
1264 bool isASCII_LC (UV ch)
1265 bool isASCII_LC_uvchr (UV ch)
1266 bool isASCII_LC_utf8_safe(U8 * s, U8 *end)
1267 "isBLANK"
1269 "isBLANK_A"
1270 "isBLANK_L1"
1271 "isBLANK_uvchr"
1272 "isBLANK_utf8_safe"
1273 "isBLANK_utf8"
1274 "isBLANK_LC"
1275 "isBLANK_LC_uvchr"
1276 "isBLANK_LC_utf8_safe"
1277 Returns a boolean indicating whether the specified character is a
1278 character considered to be a blank, analogous to "m/[[:blank:]]/".
1279 See the top of this section for an explanation of the variants.
1280 Note, however, that some platforms do not have the C library
1281 routine "isblank()". In these cases, the variants whose names
1282 contain "LC" are the same as the corresponding ones without.
1283 bool isBLANK (UV ch)
1285 bool isBLANK_A (UV ch)
1286 bool isBLANK_L1 (UV ch)
1287 bool isBLANK_uvchr (UV ch)
1288 bool isBLANK_utf8_safe (U8 * s, U8 * end)
1289 bool isBLANK_utf8 (U8 * s, U8 * end)
1290 bool isBLANK_LC (UV ch)
1291 bool isBLANK_LC_uvchr (UV ch)
1292 bool isBLANK_LC_utf8_safe(U8 * s, U8 *end)
1293 "isCNTRL"
1295 "isCNTRL_A"
1296 "isCNTRL_L1"
1297 "isCNTRL_uvchr"
1298 "isCNTRL_utf8_safe"
1299 "isCNTRL_utf8"
1300 "isCNTRL_LC"
1301 "isCNTRL_LC_uvchr"
1302 "isCNTRL_LC_utf8_safe"
1303 Returns a boolean indicating whether the specified character is a
1304 control character, analogous to "m/[[:cntrl:]]/". See the top of
1305 this section for an explanation of the variants. On EBCDIC
1306 platforms, you almost always want to use the "isCNTRL_L1" variant.
1307 bool isCNTRL (UV ch)
1309 bool isCNTRL_A (UV ch)
1310 bool isCNTRL_L1 (UV ch)
1311 bool isCNTRL_uvchr (UV ch)
1312 bool isCNTRL_utf8_safe (U8 * s, U8 * end)
1313 bool isCNTRL_utf8 (U8 * s, U8 * end)
1314 bool isCNTRL_LC (UV ch)
1315 bool isCNTRL_LC_uvchr (UV ch)
1316 bool isCNTRL_LC_utf8_safe(U8 * s, U8 *end)
1317 "isDIGIT"
1319 "isDIGIT_A"
1320 "isDIGIT_L1"
1321 "isDIGIT_uvchr"
1322 "isDIGIT_utf8_safe"
1323 "isDIGIT_utf8"
1324 "isDIGIT_LC"
1325 "isDIGIT_LC_uvchr"
1326 "isDIGIT_LC_utf8_safe"
1327 Returns a boolean indicating whether the specified character is a
1328 digit, analogous to "m/[[:digit:]]/". Variants "isDIGIT_A" and
1329 "isDIGIT_L1" are identical to "isDIGIT". See the top of this
1330 section for an explanation of the variants.
1331 bool isDIGIT (UV ch)
1333 bool isDIGIT_A (UV ch)
1334 bool isDIGIT_L1 (UV ch)
1335 bool isDIGIT_uvchr (UV ch)
1336 bool isDIGIT_utf8_safe (U8 * s, U8 * end)
1337 bool isDIGIT_utf8 (U8 * s, U8 * end)
1338 bool isDIGIT_LC (UV ch)
1339 bool isDIGIT_LC_uvchr (UV ch)
1340 bool isDIGIT_LC_utf8_safe(U8 * s, U8 *end)
1341 "isGRAPH"
1343 "isGRAPH_A"
1344 "isGRAPH_L1"
1345 "isGRAPH_uvchr"
1346 "isGRAPH_utf8_safe"
1347 "isGRAPH_utf8"
1348 "isGRAPH_LC"
1349 "isGRAPH_LC_uvchr"
1350 "isGRAPH_LC_utf8_safe"
1351 Returns a boolean indicating whether the specified character is a
1352 graphic character, analogous to "m/[[:graph:]]/". See the top of
1353 this section for an explanation of the variants.
1354 bool isGRAPH (UV ch)
1356 bool isGRAPH_A (UV ch)
1357 bool isGRAPH_L1 (UV ch)
1358 bool isGRAPH_uvchr (UV ch)
1359 bool isGRAPH_utf8_safe (U8 * s, U8 * end)
1360 bool isGRAPH_utf8 (U8 * s, U8 * end)
1361 bool isGRAPH_LC (UV ch)
1362 bool isGRAPH_LC_uvchr (UV ch)
1363 bool isGRAPH_LC_utf8_safe(U8 * s, U8 *end)
1364 "isIDCONT"
1366 "isIDCONT_A"
1367 "isIDCONT_L1"
1368 "isIDCONT_uvchr"
1369 "isIDCONT_utf8_safe"
1370 "isIDCONT_utf8"
1371 "isIDCONT_LC"
1372 "isIDCONT_LC_uvchr"
1373 "isIDCONT_LC_utf8_safe"
1374 Returns a boolean indicating whether the specified character can be
1375 the second or succeeding character of an identifier. This is very
1376 close to, but not quite the same as the official Unicode property
1377 "XID_Continue". The difference is that this returns true only if
1378 the input character also matches "isWORDCHAR". See the top of this
1379 section for an explanation of the variants.
1380 bool isIDCONT (UV ch)
1382 bool isIDCONT_A (UV ch)
1383 bool isIDCONT_L1 (UV ch)
1384 bool isIDCONT_uvchr (UV ch)
1385 bool isIDCONT_utf8_safe (U8 * s, U8 * end)
1386 bool isIDCONT_utf8 (U8 * s, U8 * end)
1387 bool isIDCONT_LC (UV ch)
1388 bool isIDCONT_LC_uvchr (UV ch)
1389 bool isIDCONT_LC_utf8_safe(U8 * s, U8 *end)
1390 "isIDFIRST"
1392 "isIDFIRST_A"
1393 "isIDFIRST_L1"
1394 "isIDFIRST_uvchr"
1395 "isIDFIRST_utf8_safe"
1396 "isIDFIRST_utf8"
1397 "isIDFIRST_LC"
1398 "isIDFIRST_LC_uvchr"
1399 "isIDFIRST_LC_utf8_safe"
1400 Returns a boolean indicating whether the specified character can be
1401 the first character of an identifier. This is very close to, but
1402 not quite the same as the official Unicode property "XID_Start".
1403 The difference is that this returns true only if the input
1404 character also matches "isWORDCHAR". See the top of this section
1405 for an explanation of the variants.
1406 bool isIDFIRST (UV ch)
1408 bool isIDFIRST_A (UV ch)
1409 bool isIDFIRST_L1 (UV ch)
1410 bool isIDFIRST_uvchr (UV ch)
1411 bool isIDFIRST_utf8_safe (U8 * s, U8 * end)
1412 bool isIDFIRST_utf8 (U8 * s, U8 * end)
1413 bool isIDFIRST_LC (UV ch)
1414 bool isIDFIRST_LC_uvchr (UV ch)
1415 bool isIDFIRST_LC_utf8_safe(U8 * s, U8 *end)
1416 "isLOWER"
1418 "isLOWER_A"
1419 "isLOWER_L1"
1420 "isLOWER_uvchr"
1421 "isLOWER_utf8_safe"
1422 "isLOWER_utf8"
1423 "isLOWER_LC"
1424 "isLOWER_LC_uvchr"
1425 "isLOWER_LC_utf8_safe"
1426 Returns a boolean indicating whether the specified character is a
1427 lowercase character, analogous to "m/[[:lower:]]/". See the top of
1428 this section for an explanation of the variants
1429 bool isLOWER (UV ch)
1431 bool isLOWER_A (UV ch)
1432 bool isLOWER_L1 (UV ch)
1433 bool isLOWER_uvchr (UV ch)
1434 bool isLOWER_utf8_safe (U8 * s, U8 * end)
1435 bool isLOWER_utf8 (U8 * s, U8 * end)
1436 bool isLOWER_LC (UV ch)
1437 bool isLOWER_LC_uvchr (UV ch)
1438 bool isLOWER_LC_utf8_safe(U8 * s, U8 *end)
1439 "isOCTAL"
1441 "isOCTAL_A"
1442 "isOCTAL_L1"
1443 Returns a boolean indicating whether the specified character is an
1444 octal digit, [0-7]. The only two variants are "isOCTAL_A" and
1445 "isOCTAL_L1"; each is identical to "isOCTAL".
1446 bool isOCTAL(UV ch)
1448 "isPRINT"
1450 "isPRINT_A"
1451 "isPRINT_L1"
1452 "isPRINT_uvchr"
1453 "isPRINT_utf8_safe"
1454 "isPRINT_utf8"
1455 "isPRINT_LC"
1456 "isPRINT_LC_uvchr"
1457 "isPRINT_LC_utf8_safe"
1458 Returns a boolean indicating whether the specified character is a
1459 printable character, analogous to "m/[[:print:]]/". See the top of
1460 this section for an explanation of the variants.
1461 bool isPRINT (UV ch)
1463 bool isPRINT_A (UV ch)
1464 bool isPRINT_L1 (UV ch)
1465 bool isPRINT_uvchr (UV ch)
1466 bool isPRINT_utf8_safe (U8 * s, U8 * end)
1467 bool isPRINT_utf8 (U8 * s, U8 * end)
1468 bool isPRINT_LC (UV ch)
1469 bool isPRINT_LC_uvchr (UV ch)
1470 bool isPRINT_LC_utf8_safe(U8 * s, U8 *end)
1471 "isPSXSPC"
1473 "isPSXSPC_A"
1474 "isPSXSPC_L1"
1475 "isPSXSPC_uvchr"
1476 "isPSXSPC_utf8_safe"
1477 "isPSXSPC_utf8"
1478 "isPSXSPC_LC"
1479 "isPSXSPC_LC_uvchr"
1480 "isPSXSPC_LC_utf8_safe"
1481 (short for Posix Space) Starting in 5.18, this is identical in all
1482 its forms to the corresponding "isSPACE()" macros. The locale
1483 forms of this macro are identical to their corresponding
1484 "isSPACE()" forms in all Perl releases. In releases prior to 5.18,
1485 the non-locale forms differ from their "isSPACE()" forms only in
1486 that the "isSPACE()" forms don't match a Vertical Tab, and the
1487 "isPSXSPC()" forms do. Otherwise they are identical. Thus this
1488 macro is analogous to what "m/[[:space:]]/" matches in a regular
1489 expression. See the top of this section for an explanation of the
1490 variants.
1491 bool isPSXSPC (UV ch)
1493 bool isPSXSPC_A (UV ch)
1494 bool isPSXSPC_L1 (UV ch)
1495 bool isPSXSPC_uvchr (UV ch)
1496 bool isPSXSPC_utf8_safe (U8 * s, U8 * end)
1497 bool isPSXSPC_utf8 (U8 * s, U8 * end)
1498 bool isPSXSPC_LC (UV ch)
1499 bool isPSXSPC_LC_uvchr (UV ch)
1500 bool isPSXSPC_LC_utf8_safe(U8 * s, U8 *end)
1501 "isPUNCT"
1503 "isPUNCT_A"
1504 "isPUNCT_L1"
1505 "isPUNCT_uvchr"
1506 "isPUNCT_utf8_safe"
1507 "isPUNCT_utf8"
1508 "isPUNCT_LC"
1509 "isPUNCT_LC_uvchr"
1510 "isPUNCT_LC_utf8_safe"
1511 Returns a boolean indicating whether the specified character is a
1512 punctuation character, analogous to "m/[[:punct:]]/". Note that
1513 the definition of what is punctuation isn't as straightforward as
1514 one might desire. See "POSIX Character Classes" in perlrecharclass
1515 for details. See the top of this section for an explanation of the
1516 variants.
1517 bool isPUNCT (UV ch)
1519 bool isPUNCT_A (UV ch)
1520 bool isPUNCT_L1 (UV ch)
1521 bool isPUNCT_uvchr (UV ch)
1522 bool isPUNCT_utf8_safe (U8 * s, U8 * end)
1523 bool isPUNCT_utf8 (U8 * s, U8 * end)
1524 bool isPUNCT_LC (UV ch)
1525 bool isPUNCT_LC_uvchr (UV ch)
1526 bool isPUNCT_LC_utf8_safe(U8 * s, U8 *end)
1527 "isSPACE"
1529 "isSPACE_A"
1530 "isSPACE_L1"
1531 "isSPACE_uvchr"
1532 "isSPACE_utf8_safe"
1533 "isSPACE_utf8"
1534 "isSPACE_LC"
1535 "isSPACE_LC_uvchr"
1536 "isSPACE_LC_utf8_safe"
1537 Returns a boolean indicating whether the specified character is a
1538 whitespace character. This is analogous to what "m/\s/" matches in
1539 a regular expression. Starting in Perl 5.18 this also matches what
1540 "m/[[:space:]]/" does. Prior to 5.18, only the locale forms of
1541 this macro (the ones with "LC" in their names) matched precisely
1542 what "m/[[:space:]]/" does. In those releases, the only
1543 difference, in the non-locale variants, was that "isSPACE()" did
1544 not match a vertical tab. (See "isPSXSPC" for a macro that matches
1545 a vertical tab in all releases.) See the top of this section for
1546 an explanation of the variants.
1547 bool isSPACE (UV ch)
1549 bool isSPACE_A (UV ch)
1550 bool isSPACE_L1 (UV ch)
1551 bool isSPACE_uvchr (UV ch)
1552 bool isSPACE_utf8_safe (U8 * s, U8 * end)
1553 bool isSPACE_utf8 (U8 * s, U8 * end)
1554 bool isSPACE_LC (UV ch)
1555 bool isSPACE_LC_uvchr (UV ch)
1556 bool isSPACE_LC_utf8_safe(U8 * s, U8 *end)
1557 "isUPPER"
1559 "isUPPER_A"
1560 "isUPPER_L1"
1561 "isUPPER_uvchr"
1562 "isUPPER_utf8_safe"
1563 "isUPPER_utf8"
1564 "isUPPER_LC"
1565 "isUPPER_LC_uvchr"
1566 "isUPPER_LC_utf8_safe"
1567 Returns a boolean indicating whether the specified character is an
1568 uppercase character, analogous to "m/[[:upper:]]/". See the top of
1569 this section for an explanation of the variants.
1570 bool isUPPER (UV ch)
1572 bool isUPPER_A (UV ch)
1573 bool isUPPER_L1 (UV ch)
1574 bool isUPPER_uvchr (UV ch)
1575 bool isUPPER_utf8_safe (U8 * s, U8 * end)
1576 bool isUPPER_utf8 (U8 * s, U8 * end)
1577 bool isUPPER_LC (UV ch)
1578 bool isUPPER_LC_uvchr (UV ch)
1579 bool isUPPER_LC_utf8_safe(U8 * s, U8 *end)
1580 "isWORDCHAR"
1582 "isWORDCHAR_A"
1583 "isWORDCHAR_L1"
1584 "isWORDCHAR_uvchr"
1585 "isWORDCHAR_utf8_safe"
1586 "isWORDCHAR_utf8"
1587 "isWORDCHAR_LC"
1588 "isWORDCHAR_LC_uvchr"
1589 "isWORDCHAR_LC_utf8_safe"
1590 "isALNUM"
1591 "isALNUM_A"
1592 "isALNUM_LC"
1593 "isALNUM_LC_uvchr"
1594 Returns a boolean indicating whether the specified character is a
1595 character that is a word character, analogous to what "m/\w/" and
1596 "m/[[:word:]]/" match in a regular expression. A word character is
1597 an alphabetic character, a decimal digit, a connecting punctuation
1598 character (such as an underscore), or a "mark" character that
1599 attaches to one of those (like some sort of accent). "isALNUM()"
1600 is a synonym provided for backward compatibility, even though a
1601 word character includes more than the standard C language meaning
1602 of alphanumeric. See the top of this section for an explanation of
1603 the variants. "isWORDCHAR_A", "isWORDCHAR_L1", "isWORDCHAR_uvchr",
1604 "isWORDCHAR_LC", "isWORDCHAR_LC_uvchr", "isWORDCHAR_LC_utf8", and
1605 "isWORDCHAR_LC_utf8_safe" are also as described there, but
1606 additionally include the platform's native underscore.
1607 bool isWORDCHAR (UV ch)
1609 bool isWORDCHAR_A (UV ch)
1610 bool isWORDCHAR_L1 (UV ch)
1611 bool isWORDCHAR_uvchr (UV ch)
1612 bool isWORDCHAR_utf8_safe (U8 * s, U8 * end)
1613 bool isWORDCHAR_utf8 (U8 * s, U8 * end)
1614 bool isWORDCHAR_LC (UV ch)
1615 bool isWORDCHAR_LC_uvchr (UV ch)
1616 bool isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end)
1617 bool isALNUM (UV ch)
1618 bool isALNUM_A (UV ch)
1619 bool isALNUM_LC (UV ch)
1620 bool isALNUM_LC_uvchr (UV ch)
1621 "isXDIGIT"
1623 "isXDIGIT_A"
1624 "isXDIGIT_L1"
1625 "isXDIGIT_uvchr"
1626 "isXDIGIT_utf8_safe"
1627 "isXDIGIT_utf8"
1628 "isXDIGIT_LC"
1629 "isXDIGIT_LC_uvchr"
1630 "isXDIGIT_LC_utf8_safe"
1631 Returns a boolean indicating whether the specified character is a
1632 hexadecimal digit. In the ASCII range these are "[0-9A-Fa-f]".
1633 Variants "isXDIGIT_A()" and "isXDIGIT_L1()" are identical to
1634 "isXDIGIT()". See the top of this section for an explanation of
1635 the variants.
1636 bool isXDIGIT (UV ch)
1638 bool isXDIGIT_A (UV ch)
1639 bool isXDIGIT_L1 (UV ch)
1640 bool isXDIGIT_uvchr (UV ch)
1641 bool isXDIGIT_utf8_safe (U8 * s, U8 * end)
1642 bool isXDIGIT_utf8 (U8 * s, U8 * end)
1643 bool isXDIGIT_LC (UV ch)
1644 bool isXDIGIT_LC_uvchr (UV ch)
1645 bool isXDIGIT_LC_utf8_safe(U8 * s, U8 *end)
1646
1648 "CPPLAST"
1649 This symbol is intended to be used along with "CPPRUN" in the same
1650 manner symbol "CPPMINUS" is used with "CPPSTDIN". It contains
1651 either "-" or "".
1652 "CPPMINUS"
1654 This symbol contains the second part of the string which will
1655 invoke the C preprocessor on the standard input and produce to
1656 standard output. This symbol will have the value "-" if "CPPSTDIN"
1657 needs a minus to specify standard input, otherwise the value is "".
1658 "CPPRUN"
1660 This symbol contains the string which will invoke a C preprocessor
1661 on the standard input and produce to standard output. It needs to
1662 end with "CPPLAST", after all other preprocessor flags have been
1663 specified. The main difference with "CPPSTDIN" is that this
1664 program will never be a pointer to a shell wrapper, i.e. it will be
1665 empty if no preprocessor is available directly to the user. Note
1666 that it may well be different from the preprocessor used to compile
1667 the C program.
1668 "CPPSTDIN"
1670 This symbol contains the first part of the string which will invoke
1671 the C preprocessor on the standard input and produce to standard
1672 output. Typical value of "cc -E" or "/lib/cpp", but it can also
1673 call a wrapper. See "CPPRUN".
1674 "HASATTRIBUTE_ALWAYS_INLINE"
1676 Can we handle "GCC" attribute for functions that should always be
1677 inlined.
1678 "HASATTRIBUTE_DEPRECATED"
1680 Can we handle "GCC" attribute for marking deprecated "APIs"
1681 "HASATTRIBUTE_FORMAT"
1683 Can we handle "GCC" attribute for checking printf-style formats
1684 "HASATTRIBUTE_NONNULL"
1686 Can we handle "GCC" attribute for nonnull function parms.
1687 "HASATTRIBUTE_NORETURN"
1689 Can we handle "GCC" attribute for functions that do not return
1690 "HASATTRIBUTE_PURE"
1692 Can we handle "GCC" attribute for pure functions
1693 "HASATTRIBUTE_UNUSED"
1695 Can we handle "GCC" attribute for unused variables and arguments
1696 "HASATTRIBUTE_WARN_UNUSED_RESULT"
1698 Can we handle "GCC" attribute for warning on unused results
1699 "HAS_BUILTIN_ADD_OVERFLOW"
1701 This symbol, if defined, indicates that the compiler supports
1702 "__builtin_add_overflow" for adding integers with overflow checks.
1703 "HAS_BUILTIN_CHOOSE_EXPR"
1705 Can we handle "GCC" builtin for compile-time ternary-like
1706 expressions
1707 "HAS_BUILTIN_EXPECT"
1709 Can we handle "GCC" builtin for telling that certain values are
1710 more likely
1711 "HAS_BUILTIN_MUL_OVERFLOW"
1713 This symbol, if defined, indicates that the compiler supports
1714 "__builtin_mul_overflow" for multiplying integers with overflow
1715 checks.
1716 "HAS_BUILTIN_SUB_OVERFLOW"
1718 This symbol, if defined, indicates that the compiler supports
1719 "__builtin_sub_overflow" for subtracting integers with overflow
1720 checks.
1721 "HAS_C99_VARIADIC_MACROS"
1723 If defined, the compiler supports C99 variadic macros.
1724 "HAS_STATIC_INLINE"
1726 This symbol, if defined, indicates that the C compiler supports
1727 C99-style static inline. That is, the function can't be called
1728 from another translation unit.
1729 "MEM_ALIGNBYTES"
1731 This symbol contains the number of bytes required to align a
1732 double, or a long double when applicable. Usual values are 2, 4 and
1733 8. The default is eight, for safety. For cross-compiling or
1734 multiarch support, Configure will set a minimum of 8.
1735 "PERL_STATIC_INLINE"
1737 This symbol gives the best-guess incantation to use for static
1738 inline functions. If "HAS_STATIC_INLINE" is defined, this will
1739 give C99-style inline. If "HAS_STATIC_INLINE" is not defined, this
1740 will give a plain 'static'. It will always be defined to something
1741 that gives static linkage. Possibilities include
1742 static inline (c99)
1744 static __inline__ (gcc -ansi)
1745 static __inline (MSVC)
1746 static _inline (older MSVC)
1747 static (c89 compilers)
1748 "PERL_THREAD_LOCAL"
1750 This symbol, if defined, gives a linkage specification for thread-
1751 local storage. For example, for a C11 compiler this will be
1752 "_Thread_local". Beware, some compilers are sensitive to the C
1753 language standard they are told to parse. For example, suncc
1754 defaults to C11, so our probe will report that "_Thread_local" can
1755 be used. However, if the -std=c99 is later added to the compiler
1756 flags, then "_Thread_local" will become a syntax error. Hence it is
1757 important for these flags to be consistent between probing and use.
1758 "U32_ALIGNMENT_REQUIRED"
1760 This symbol, if defined, indicates that you must access character
1761 data through U32-aligned pointers.
1762
1764 "ASSUME"
1765 "ASSUME" is like "assert()", but it has a benefit in a release
1766 build. It is a hint to a compiler about a statement of fact in a
1767 function call free expression, which allows the compiler to
1768 generate better machine code. In a debug build, ASSUME(x) is a
1769 synonym for assert(x). ASSUME(0) means the control path is
1770 unreachable. In a for loop, "ASSUME" can be used to hint that a
1771 loop will run at least X times. "ASSUME" is based off MSVC's
1772 "__assume" intrinsic function, see its documents for more details.
1773 ASSUME(bool expr)
1775 "dNOOP"
1777 Declare nothing; typically used as a placeholder to replace
1778 something that used to declare something. Works on compilers that
1779 require declarations before any code.
1780 dNOOP;
1782 "END_EXTERN_C"
1784 When not compiling using C++, expands to nothing. Otherwise ends a
1785 section of code already begun by a "START_EXTERN_C".
1786 END_EXTERN_C
1788 "EXTERN_C"
1790 When not compiling using C++, expands to nothing. Otherwise is
1791 used in a declaration of a function to indicate the function should
1792 have external C linkage. This is required for things to work for
1793 just about all functions with external linkage compiled into perl.
1794 Often, you can use "START_EXTERN_C" ... "END_EXTERN_C" blocks
1795 surrounding all your code that you need to have this linkage.
1796 Example usage:
1798 EXTERN_C int flock(int fd, int op);
1800 "LIKELY"
1802 Returns the input unchanged, but at the same time it gives a branch
1803 prediction hint to the compiler that this condition is likely to be
1804 true.
1805 LIKELY(bool expr)
1807 "NOOP"
1809 Do nothing; typically used as a placeholder to replace something
1810 that used to do something.
1811 NOOP;
1813 "PERL_UNUSED_ARG"
1815 This is used to suppress compiler warnings that a parameter to a
1816 function is not used. This situation can arise, for example, when
1817 a parameter is needed under some configuration conditions, but not
1818 others, so that C preprocessor conditional compilation causes it be
1819 used just some times.
1820 PERL_UNUSED_ARG(void x);
1822 "PERL_UNUSED_CONTEXT"
1824 This is used to suppress compiler warnings that the thread context
1825 parameter to a function is not used. This situation can arise, for
1826 example, when a C preprocessor conditional compilation causes it be
1827 used just some times.
1828 PERL_UNUSED_CONTEXT;
1830 "PERL_UNUSED_DECL"
1832 Tells the compiler that the parameter in the function prototype
1833 just before it is not necessarily expected to be used in the
1834 function. Not that many compilers understand this, so this should
1835 only be used in cases where "PERL_UNUSED_ARG" can't conveniently be
1836 used.
1837 Example usage:
1839 Signal_t
1841 Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
1842 void *uap PERL_UNUSED_DECL, bool safe)
1843 "PERL_UNUSED_RESULT"
1845 This macro indicates to discard the return value of the function
1846 call inside it, e.g.,
1847 PERL_UNUSED_RESULT(foo(a, b))
1849 The main reason for this is that the combination of "gcc
1851 -Wunused-result" (part of "-Wall") and the
1852 "__attribute__((warn_unused_result))" cannot be silenced with
1853 casting to "void". This causes trouble when the system header
1854 files use the attribute.
1855 Use "PERL_UNUSED_RESULT" sparingly, though, since usually the
1857 warning is there for a good reason: you might lose success/failure
1858 information, or leak resources, or changes in resources.
1859 But sometimes you just want to ignore the return value, e.g., on
1861 codepaths soon ending up in abort, or in "best effort" attempts, or
1862 in situations where there is no good way to handle failures.
1863 Sometimes "PERL_UNUSED_RESULT" might not be the most natural way:
1865 another possibility is that you can capture the return value and
1866 use "PERL_UNUSED_VAR" on that.
1867 PERL_UNUSED_RESULT(void x)
1869 "PERL_UNUSED_VAR"
1871 This is used to suppress compiler warnings that the variable x is
1872 not used. This situation can arise, for example, when a C
1873 preprocessor conditional compilation causes it be used just some
1874 times.
1875 PERL_UNUSED_VAR(void x);
1877 "PERL_USE_GCC_BRACE_GROUPS"
1879 This C pre-processor value, if defined, indicates that it is
1880 permissible to use the GCC brace groups extension. This extension,
1881 of the form
1882 ({ statement ... })
1884 turns the block consisting of statements ... into an expression
1886 with a value, unlike plain C language blocks. This can present
1887 optimization possibilities, BUT you generally need to specify an
1888 alternative in case this ability doesn't exist or has otherwise
1889 been forbidden.
1890 Example usage:
1892 #ifdef PERL_USE_GCC_BRACE_GROUPS
1894 ...
1895 #else
1896 ...
1897 #endif
1898 "START_EXTERN_C"
1900 When not compiling using C++, expands to nothing. Otherwise begins
1901 a section of code in which every function will effectively have
1902 "EXTERN_C" applied to it, that is to have external C linkage. The
1903 section is ended by a "END_EXTERN_C".
1904 START_EXTERN_C
1906 "STATIC"
1908 Described in perlguts.
1909 "STMT_START"
1911 "STMT_END"
1912 This allows a series of statements in a macro to be used as a
1913 single statement, as in
1914 if (x) STMT_START { ... } STMT_END else ...
1916 Note that you can't return a value out of them, which limits their
1918 utility. But see "PERL_USE_GCC_BRACE_GROUPS".
1919 "UNLIKELY"
1921 Returns the input unchanged, but at the same time it gives a branch
1922 prediction hint to the compiler that this condition is likely to be
1923 false.
1924 UNLIKELY(bool expr)
1926 "__ASSERT_"
1928 This is a helper macro to avoid preprocessor issues, replaced by
1929 nothing unless under DEBUGGING, where it expands to an assert of
1930 its argument, followed by a comma (hence the comma operator). If
1931 we just used a straight assert(), we would get a comma with nothing
1932 before it when not DEBUGGING.
1933 __ASSERT_(bool expr)
1935
1937 "BhkDISABLE"
1938 NOTE: "BhkDISABLE" is experimental and may change or be removed
1939 without notice.
1940 Temporarily disable an entry in this BHK structure, by clearing the
1942 appropriate flag. "which" is a preprocessor token indicating which
1943 entry to disable.
1944 void BhkDISABLE(BHK *hk, which)
1946 "BhkENABLE"
1948 NOTE: "BhkENABLE" is experimental and may change or be removed
1949 without notice.
1950 Re-enable an entry in this BHK structure, by setting the
1952 appropriate flag. "which" is a preprocessor token indicating which
1953 entry to enable. This will assert (under -DDEBUGGING) if the entry
1954 doesn't contain a valid pointer.
1955 void BhkENABLE(BHK *hk, which)
1957 "BhkENTRY_set"
1959 NOTE: "BhkENTRY_set" is experimental and may change or be removed
1960 without notice.
1961 Set an entry in the BHK structure, and set the flags to indicate it
1963 is valid. "which" is a preprocessing token indicating which entry
1964 to set. The type of "ptr" depends on the entry.
1965 void BhkENTRY_set(BHK *hk, which, void *ptr)
1967 "blockhook_register"
1969 NOTE: "blockhook_register" is experimental and may change or be
1970 removed without notice.
1971 Register a set of hooks to be called when the Perl lexical scope
1973 changes at compile time. See "Compile-time scope hooks" in
1974 perlguts.
1975 NOTE: "blockhook_register" must be explicitly called as
1977 "Perl_blockhook_register" with an "aTHX_" parameter.
1978 void Perl_blockhook_register(pTHX_ BHK *hk)
1980
1982 "aTHX"
1983 Described in perlguts.
1984 "aTHX_"
1986 Described in perlguts.
1987 "CPERLscope"
1989 "DEPRECATED!" It is planned to remove "CPERLscope" from a future
1990 release of Perl. Do not use it for new code; remove it from
1991 existing code.
1992 Now a no-op.
1994 void CPERLscope(void x)
1996 "dTHR"
1998 Described in perlguts.
1999 "dTHX"
2001 Described in perlguts.
2002 "dTHXa"
2004 On threaded perls, set "pTHX" to "a"; on unthreaded perls, do
2005 nothing
2006 "dTHXoa"
2008 Now a synonym for "dTHXa".
2009 "dVAR"
2011 This is now a synonym for dNOOP: declare nothing
2012 "GETENV_PRESERVES_OTHER_THREAD"
2014 This symbol, if defined, indicates that the getenv system call
2015 doesn't zap the static buffer of "getenv()" in a different thread.
2016 The typical "getenv()" implementation will return a pointer to the
2017 proper position in **environ. But some may instead copy them to a
2018 static buffer in "getenv()". If there is a per-thread instance of
2019 that buffer, or the return points to **environ, then a
2020 many-reader/1-writer mutex will work; otherwise an exclusive
2021 locking mutex is required to prevent races.
2022 "HAS_PTHREAD_ATFORK"
2024 This symbol, if defined, indicates that the "pthread_atfork"
2025 routine is available to setup fork handlers.
2026 "HAS_PTHREAD_ATTR_SETSCOPE"
2028 This symbol, if defined, indicates that the "pthread_attr_setscope"
2029 system call is available to set the contention scope attribute of a
2030 thread attribute object.
2031 "HAS_PTHREAD_YIELD"
2033 This symbol, if defined, indicates that the "pthread_yield" routine
2034 is available to yield the execution of the current thread.
2035 "sched_yield" is preferable to "pthread_yield".
2036 "HAS_SCHED_YIELD"
2038 This symbol, if defined, indicates that the "sched_yield" routine
2039 is available to yield the execution of the current thread.
2040 "sched_yield" is preferable to "pthread_yield".
2041 "I_MACH_CTHREADS"
2043 This symbol, if defined, indicates to the C program that it should
2044 include mach/cthreads.h.
2045 #ifdef I_MACH_CTHREADS
2047 #include <mach_cthreads.h>
2048 #endif
2049 "I_PTHREAD"
2051 This symbol, if defined, indicates to the C program that it should
2052 include pthread.h.
2053 #ifdef I_PTHREAD
2055 #include <pthread.h>
2056 #endif
2057 "MULTIPLICITY"
2059 This symbol, if defined, indicates that Perl should be built to use
2060 multiplicity.
2061 "OLD_PTHREADS_API"
2063 This symbol, if defined, indicates that Perl should be built to use
2064 the old draft "POSIX" threads "API".
2065 "OLD_PTHREAD_CREATE_JOINABLE"
2067 This symbol, if defined, indicates how to create pthread in
2068 joinable (aka undetached) state. "NOTE": not defined if pthread.h
2069 already has defined "PTHREAD_CREATE_JOINABLE" (the new version of
2070 the constant). If defined, known values are
2071 "PTHREAD_CREATE_UNDETACHED" and "__UNDETACHED".
2072 "PERL_IMPLICIT_CONTEXT"
2074 Described in perlguts.
2075 "pTHX"
2077 Described in perlguts.
2078 "pTHX_"
2080 Described in perlguts.
2081 "SCHED_YIELD"
2083 This symbol defines the way to yield the execution of the current
2084 thread. Known ways are "sched_yield", "pthread_yield", and
2085 "pthread_yield" with "NULL".
2086
2088 "cop_fetch_label"
2089 NOTE: "cop_fetch_label" is experimental and may change or be
2090 removed without notice.
2091 Returns the label attached to a cop, and stores its length in bytes
2093 into *len. Upon return, *flags will be set to either "SVf_UTF8" or
2094 0.
2095 Alternatively, use the macro "CopLABEL_len_flags"; or if you don't
2097 need to know if the label is UTF-8 or not, the macro
2098 "CopLABEL_len"; or if you additionally dont need to know the
2099 length, "CopLABEL".
2100 const char * cop_fetch_label(COP *const cop, STRLEN *len,
2102 U32 *flags)
2103 "CopFILE"
2105 Returns the name of the file associated with the "COP" "c"
2106 const char * CopFILE(const COP * c)
2108 "CopFILEAV"
2110 Returns the AV associated with the "COP" "c", creating it if
2111 necessary.
2112 AV * CopFILEAV(const COP * c)
2114 "CopFILEAVn"
2116 Returns the AV associated with the "COP" "c", returning NULL if it
2117 doesn't already exist.
2118 AV * CopFILEAVn(const COP * c)
2120 "CopFILEGV"
2122 Returns the GV associated with the "COP" "c"
2123 GV * CopFILEGV(const COP * c)
2125 "CopFILEGV_set"
2127 Available only on unthreaded perls. Makes "pv" the name of the
2128 file associated with the "COP" "c"
2129 void CopFILEGV_set(COP * c, GV * gv)
2131 "CopFILE_set"
2133 Makes "pv" the name of the file associated with the "COP" "c"
2134 void CopFILE_set(COP * c, const char * pv)
2136 "CopFILESV"
2138 Returns the SV associated with the "COP" "c"
2139 SV * CopFILESV(const COP * c)
2141 "cophh_2hv"
2143 NOTE: "cophh_2hv" is experimental and may change or be removed
2144 without notice.
2145 Generates and returns a standard Perl hash representing the full
2147 set of key/value pairs in the cop hints hash "cophh". "flags" is
2148 currently unused and must be zero.
2149 HV * cophh_2hv(const COPHH *cophh, U32 flags)
2151 "cophh_copy"
2153 NOTE: "cophh_copy" is experimental and may change or be removed
2154 without notice.
2155 Make and return a complete copy of the cop hints hash "cophh".
2157 COPHH * cophh_copy(COPHH *cophh)
2159 "cophh_delete_pvn"
2161 "cophh_delete_pv"
2162 "cophh_delete_pvs"
2163 "cophh_delete_sv"
2164 NOTE: all these forms are experimental and may change or be removed
2165 without notice.
2166 These delete a key and its associated value from the cop hints hash
2168 "cophh", and return the modified hash. The returned hash pointer
2169 is in general not the same as the hash pointer that was passed in.
2170 The input hash is consumed by the function, and the pointer to it
2171 must not be subsequently used. Use "cophh_copy" if you need both
2172 hashes.
2173 The forms differ in how the key is specified. In all forms, the
2175 key is pointed to by "key". In the plain "pv" form, the key is a C
2176 language NUL-terminated string. In the "pvs" form, the key is a C
2177 language string literal. In the "pvn" form, an additional
2178 parameter, "keylen", specifies the length of the string, which
2179 hence, may contain embedded-NUL characters. In the "sv" form, *key
2180 is an SV, and the key is the PV extracted from that. using
2181 "SvPV_const".
2182 "hash" is a precomputed hash of the key string, or zero if it has
2184 not been precomputed. This parameter is omitted from the "pvs"
2185 form, as it is computed automatically at compile time.
2186 The only flag currently used from the "flags" parameter is
2188 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2189 the "pv*" forms, it specifies whether the key octets are
2190 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2191 form uses the underlying SV to determine the UTF-8ness of the
2192 octets.
2193 COPHH * cophh_delete_pvn(COPHH *cophh, const char *key,
2195 STRLEN keylen, U32 hash, U32 flags)
2196 COPHH * cophh_delete_pv (COPHH *cophh, const char *key, U32 hash,
2197 U32 flags)
2198 COPHH * cophh_delete_pvs(COPHH *cophh, "key", U32 flags)
2199 COPHH * cophh_delete_sv (COPHH *cophh, SV *key, U32 hash,
2200 U32 flags)
2201 "cophh_exists_pvn"
2203 NOTE: "cophh_exists_pvn" is experimental and may change or be
2204 removed without notice.
2205 These look up the hint entry in the cop "cop" with the key
2207 specified by "key" (and "keylen" in the "pvn" form), returning true
2208 if a value exists, and false otherwise.
2209 The forms differ in how the key is specified. In the plain "pv"
2211 form, the key is a C language NUL-terminated string. In the "pvs"
2212 form, the key is a C language string literal. In the "pvn" form,
2213 an additional parameter, "keylen", specifies the length of the
2214 string, which hence, may contain embedded-NUL characters. In the
2215 "sv" form, *key is an SV, and the key is the PV extracted from
2216 that. using "SvPV_const".
2217 "hash" is a precomputed hash of the key string, or zero if it has
2219 not been precomputed. This parameter is omitted from the "pvs"
2220 form, as it is computed automatically at compile time.
2221 The only flag currently used from the "flags" parameter is
2223 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2224 the "pv*" forms, it specifies whether the key octets are
2225 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2226 form uses the underlying SV to determine the UTF-8ness of the
2227 octets.
2228 bool cophh_exists_pvn(const COPHH *cophh, const char *key,
2230 STRLEN keylen, U32 hash, U32 flags)
2231 "cophh_fetch_pvn"
2233 "cophh_fetch_pv"
2234 "cophh_fetch_pvs"
2235 "cophh_fetch_sv"
2236 NOTE: all these forms are experimental and may change or be removed
2237 without notice.
2238 These look up the entry in the cop hints hash "cophh" with the key
2240 specified by "key" (and "keylen" in the "pvn" form), returning that
2241 value as a mortal scalar copy, or &PL_sv_placeholder if there is no
2242 value associated with the key.
2243 The forms differ in how the key is specified. In the plain "pv"
2245 form, the key is a C language NUL-terminated string. In the "pvs"
2246 form, the key is a C language string literal. In the "pvn" form,
2247 an additional parameter, "keylen", specifies the length of the
2248 string, which hence, may contain embedded-NUL characters. In the
2249 "sv" form, *key is an SV, and the key is the PV extracted from
2250 that. using "SvPV_const".
2251 "hash" is a precomputed hash of the key string, or zero if it has
2253 not been precomputed. This parameter is omitted from the "pvs"
2254 form, as it is computed automatically at compile time.
2255 The only flag currently used from the "flags" parameter is
2257 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2258 the "pv*" forms, it specifies whether the key octets are
2259 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2260 form uses the underlying SV to determine the UTF-8ness of the
2261 octets.
2262 SV * cophh_fetch_pvn(const COPHH *cophh, const char *key,
2264 STRLEN keylen, U32 hash, U32 flags)
2265 SV * cophh_fetch_pv (const COPHH *cophh, const char *key,
2266 U32 hash, U32 flags)
2267 SV * cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags)
2268 SV * cophh_fetch_sv (const COPHH *cophh, SV *key, U32 hash,
2269 U32 flags)
2270 "cophh_free"
2272 NOTE: "cophh_free" is experimental and may change or be removed
2273 without notice.
2274 Discard the cop hints hash "cophh", freeing all resources
2276 associated with it.
2277 void cophh_free(COPHH *cophh)
2279 "cophh_new_empty"
2281 NOTE: "cophh_new_empty" is experimental and may change or be
2282 removed without notice.
2283 Generate and return a fresh cop hints hash containing no entries.
2285 COPHH * cophh_new_empty()
2287 "cophh_store_pvn"
2289 "cophh_store_pv"
2290 "cophh_store_pvs"
2291 "cophh_store_sv"
2292 NOTE: all these forms are experimental and may change or be removed
2293 without notice.
2294 These store a value, associated with a key, in the cop hints hash
2296 "cophh", and return the modified hash. The returned hash pointer
2297 is in general not the same as the hash pointer that was passed in.
2298 The input hash is consumed by the function, and the pointer to it
2299 must not be subsequently used. Use "cophh_copy" if you need both
2300 hashes.
2301 "value" is the scalar value to store for this key. "value" is
2303 copied by these functions, which thus do not take ownership of any
2304 reference to it, and hence later changes to the scalar will not be
2305 reflected in the value visible in the cop hints hash. Complex
2306 types of scalar will not be stored with referential integrity, but
2307 will be coerced to strings.
2308 The forms differ in how the key is specified. In all forms, the
2310 key is pointed to by "key". In the plain "pv" form, the key is a C
2311 language NUL-terminated string. In the "pvs" form, the key is a C
2312 language string literal. In the "pvn" form, an additional
2313 parameter, "keylen", specifies the length of the string, which
2314 hence, may contain embedded-NUL characters. In the "sv" form, *key
2315 is an SV, and the key is the PV extracted from that. using
2316 "SvPV_const".
2317 "hash" is a precomputed hash of the key string, or zero if it has
2319 not been precomputed. This parameter is omitted from the "pvs"
2320 form, as it is computed automatically at compile time.
2321 The only flag currently used from the "flags" parameter is
2323 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2324 the "pv*" forms, it specifies whether the key octets are
2325 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2326 form uses the underlying SV to determine the UTF-8ness of the
2327 octets.
2328 COPHH * cophh_store_pvn(COPHH *cophh, const char *key,
2330 STRLEN keylen, U32 hash, SV *value,
2331 U32 flags)
2332 COPHH * cophh_store_pv (COPHH *cophh, const char *key, U32 hash,
2333 SV *value, U32 flags)
2334 COPHH * cophh_store_pvs(COPHH *cophh, "key", SV *value,
2335 U32 flags)
2336 COPHH * cophh_store_sv (COPHH *cophh, SV *key, U32 hash,
2337 SV *value, U32 flags)
2338 "cop_hints_2hv"
2340 Generates and returns a standard Perl hash representing the full
2341 set of hint entries in the cop "cop". "flags" is currently unused
2342 and must be zero.
2343 HV * cop_hints_2hv(const COP *cop, U32 flags)
2345 "cop_hints_exists_pvn"
2347 "cop_hints_exists_pv"
2348 "cop_hints_exists_pvs"
2349 "cop_hints_exists_sv"
2350 These look up the hint entry in the cop "cop" with the key
2351 specified by "key" (and "keylen" in the "pvn" form), returning true
2352 if a value exists, and false otherwise.
2353 The forms differ in how the key is specified. In all forms, the
2355 key is pointed to by "key". In the plain "pv" form, the key is a C
2356 language NUL-terminated string. In the "pvs" form, the key is a C
2357 language string literal. In the "pvn" form, an additional
2358 parameter, "keylen", specifies the length of the string, which
2359 hence, may contain embedded-NUL characters. In the "sv" form, *key
2360 is an SV, and the key is the PV extracted from that. using
2361 "SvPV_const".
2362 "hash" is a precomputed hash of the key string, or zero if it has
2364 not been precomputed. This parameter is omitted from the "pvs"
2365 form, as it is computed automatically at compile time.
2366 The only flag currently used from the "flags" parameter is
2368 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2369 the "pv*" forms, it specifies whether the key octets are
2370 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2371 form uses the underlying SV to determine the UTF-8ness of the
2372 octets.
2373 bool cop_hints_exists_pvn(const COP *cop, const char *key,
2375 STRLEN keylen, U32 hash, U32 flags)
2376 bool cop_hints_exists_pv (const COP *cop, const char *key,
2377 U32 hash, U32 flags)
2378 bool cop_hints_exists_pvs(const COP *cop, "key", U32 flags)
2379 bool cop_hints_exists_sv (const COP *cop, SV *key, U32 hash,
2380 U32 flags)
2381 "cop_hints_fetch_pvn"
2383 "cop_hints_fetch_pv"
2384 "cop_hints_fetch_pvs"
2385 "cop_hints_fetch_sv"
2386 These look up the hint entry in the cop "cop" with the key
2387 specified by "key" (and "keylen" in the "pvn" form), returning that
2388 value as a mortal scalar copy, or &PL_sv_placeholder if there is no
2389 value associated with the key.
2390 The forms differ in how the key is specified. In the plain "pv"
2392 form, the key is a C language NUL-terminated string. In the "pvs"
2393 form, the key is a C language string literal. In the "pvn" form,
2394 an additional parameter, "keylen", specifies the length of the
2395 string, which hence, may contain embedded-NUL characters. In the
2396 "sv" form, *key is an SV, and the key is the PV extracted from
2397 that. using "SvPV_const".
2398 "hash" is a precomputed hash of the key string, or zero if it has
2400 not been precomputed. This parameter is omitted from the "pvs"
2401 form, as it is computed automatically at compile time.
2402 The only flag currently used from the "flags" parameter is
2404 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2405 the "pv*" forms, it specifies whether the key octets are
2406 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2407 form uses the underlying SV to determine the UTF-8ness of the
2408 octets.
2409 SV * cop_hints_fetch_pvn(const COP *cop, const char *key,
2411 STRLEN keylen, U32 hash, U32 flags)
2412 SV * cop_hints_fetch_pv (const COP *cop, const char *key,
2413 U32 hash, U32 flags)
2414 SV * cop_hints_fetch_pvs(const COP *cop, "key", U32 flags)
2415 SV * cop_hints_fetch_sv (const COP *cop, SV *key, U32 hash,
2416 U32 flags)
2417 "CopLABEL"
2419 "CopLABEL_len"
2420 "CopLABEL_len_flags"
2421 These return the label attached to a cop.
2422 "CopLABEL_len" and "CopLABEL_len_flags" additionally store the
2424 number of bytes comprising the returned label into *len.
2425 "CopLABEL_len_flags" additionally returns the UTF-8ness of the
2427 returned label, by setting *flags to 0 or "SVf_UTF8".
2428 const char * CopLABEL (COP *const cop)
2430 const char * CopLABEL_len (COP *const cop, STRLEN *len)
2431 const char * CopLABEL_len_flags(COP *const cop, STRLEN *len,
2432 U32 *flags)
2433 "CopLINE"
2435 Returns the line number in the source code associated with the
2436 "COP" "c"
2437 STRLEN CopLINE(const COP * c)
2439 "CopSTASH"
2441 Returns the stash associated with "c".
2442 HV * CopSTASH(const COP * c)
2444 "CopSTASH_eq"
2446 Returns a boolean as to whether or not "hv" is the stash associated
2447 with "c".
2448 bool CopSTASH_eq(const COP * c, const HV * hv)
2450 "CopSTASHPV"
2452 Returns the package name of the stash associated with "c", or
2453 "NULL" if no associated stash
2454 char * CopSTASHPV(const COP * c)
2456 "CopSTASHPV_set"
2458 Set the package name of the stash associated with "c", to the NUL-
2459 terminated C string "p", creating the package if necessary.
2460 void CopSTASHPV_set(COP * c, const char * pv)
2462 "CopSTASH_set"
2464 Set the stash associated with "c" to "hv".
2465 bool CopSTASH_set(COP * c, HV * hv)
2467 "cop_store_label"
2469 NOTE: "cop_store_label" is experimental and may change or be
2470 removed without notice.
2471 Save a label into a "cop_hints_hash". You need to set flags to
2473 "SVf_UTF8" for a UTF-8 label. Any other flag is ignored.
2474 void cop_store_label(COP *const cop, const char *label,
2476 STRLEN len, U32 flags)
2477 "PERL_SI"
2479 Use this typedef to declare variables that are to hold "struct
2480 stackinfo".
2481 "PL_curcop"
2483 The currently active COP (control op) roughly representing the
2484 current statement in the source.
2485 On threaded perls, each thread has an independent copy of this
2487 variable; each initialized at creation time with the current value
2488 of the creating thread's copy.
2489 COP* PL_curcop
2491
2493 "custom_op_desc"
2494 "DEPRECATED!" It is planned to remove "custom_op_desc" from a
2495 future release of Perl. Do not use it for new code; remove it from
2496 existing code.
2497 Return the description of a given custom op. This was once used by
2499 the "OP_DESC" macro, but is no longer: it has only been kept for
2500 compatibility, and should not be used.
2501 const char * custom_op_desc(const OP *o)
2503 "custom_op_name"
2505 "DEPRECATED!" It is planned to remove "custom_op_name" from a
2506 future release of Perl. Do not use it for new code; remove it from
2507 existing code.
2508 Return the name for a given custom op. This was once used by the
2510 "OP_NAME" macro, but is no longer: it has only been kept for
2511 compatibility, and should not be used.
2512 const char * custom_op_name(const OP *o)
2514 "custom_op_register"
2516 Register a custom op. See "Custom Operators" in perlguts.
2517 NOTE: "custom_op_register" must be explicitly called as
2519 "Perl_custom_op_register" with an "aTHX_" parameter.
2520 void Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr,
2522 const XOP *xop)
2523 "Perl_custom_op_xop"
2525 Return the XOP structure for a given custom op. This macro should
2526 be considered internal to "OP_NAME" and the other access macros:
2527 use them instead. This macro does call a function. Prior to
2528 5.19.6, this was implemented as a function.
2529 const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
2531 "XopDISABLE"
2533 Temporarily disable a member of the XOP, by clearing the
2534 appropriate flag.
2535 void XopDISABLE(XOP *xop, which)
2537 "XopENABLE"
2539 Reenable a member of the XOP which has been disabled.
2540 void XopENABLE(XOP *xop, which)
2542 "XopENTRY"
2544 Return a member of the XOP structure. "which" is a cpp token
2545 indicating which entry to return. If the member is not set this
2546 will return a default value. The return type depends on "which".
2547 This macro evaluates its arguments more than once. If you are
2548 using "Perl_custom_op_xop" to retrieve a "XOP *" from a "OP *", use
2549 the more efficient "XopENTRYCUSTOM" instead.
2550 XopENTRY(XOP *xop, which)
2552 "XopENTRYCUSTOM"
2554 Exactly like "XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o),
2555 which)" but more efficient. The "which" parameter is identical to
2556 "XopENTRY".
2557 XopENTRYCUSTOM(const OP *o, which)
2559 "XopENTRY_set"
2561 Set a member of the XOP structure. "which" is a cpp token
2562 indicating which entry to set. See "Custom Operators" in perlguts
2563 for details about the available members and how they are used.
2564 This macro evaluates its argument more than once.
2565 void XopENTRY_set(XOP *xop, which, value)
2567 "XopFLAGS"
2569 Return the XOP's flags.
2570 U32 XopFLAGS(XOP *xop)
2572
2574 This section documents functions to manipulate CVs which are code-
2575 values, meaning subroutines. For more information, see perlguts.
2576 "caller_cx"
2578 The XSUB-writer's equivalent of caller(). The returned
2579 "PERL_CONTEXT" structure can be interrogated to find all the
2580 information returned to Perl by "caller". Note that XSUBs don't
2581 get a stack frame, so "caller_cx(0, NULL)" will return information
2582 for the immediately-surrounding Perl code.
2583 This function skips over the automatic calls to &DB::sub made on
2585 the behalf of the debugger. If the stack frame requested was a sub
2586 called by "DB::sub", the return value will be the frame for the
2587 call to "DB::sub", since that has the correct line number/etc. for
2588 the call site. If dbcxp is non-"NULL", it will be set to a pointer
2589 to the frame for the sub call itself.
2590 const PERL_CONTEXT * caller_cx(I32 level,
2592 const PERL_CONTEXT **dbcxp)
2593 "CvDEPTH"
2595 Returns the recursion level of the CV "sv". Hence >= 2 indicates
2596 we are in a recursive call.
2597 I32 * CvDEPTH(const CV * const sv)
2599 "CvGV"
2601 Returns the GV associated with the CV "sv", reifying it if
2602 necessary.
2603 GV * CvGV(CV *sv)
2605 "CvSTASH"
2607 Returns the stash of the CV. A stash is the symbol table hash,
2608 containing the package-scoped variables in the package where the
2609 subroutine was defined. For more information, see perlguts.
2610 This also has a special use with XS AUTOLOAD subs. See
2612 "Autoloading with XSUBs" in perlguts.
2613 HV* CvSTASH(CV* cv)
2615 "find_runcv"
2617 Locate the CV corresponding to the currently executing sub or eval.
2618 If "db_seqp" is non_null, skip CVs that are in the DB package and
2619 populate *db_seqp with the cop sequence number at the point that
2620 the DB:: code was entered. (This allows debuggers to eval in the
2621 scope of the breakpoint rather than in the scope of the debugger
2622 itself.)
2623 CV* find_runcv(U32 *db_seqp)
2625 "get_cv"
2627 "get_cvs"
2628 "get_cvn_flags"
2629 These return the CV of the specified Perl subroutine. "flags" are
2630 passed to "gv_fetchpvn_flags". If "GV_ADD" is set and the Perl
2631 subroutine does not exist then it will be declared (which has the
2632 same effect as saying "sub name;"). If "GV_ADD" is not set and the
2633 subroutine does not exist, then NULL is returned.
2634 The forms differ only in how the subroutine is specified.. With
2636 "get_cvs", the name is a literal C string, enclosed in double
2637 quotes. With "get_cv", the name is given by the "name" parameter,
2638 which must be a NUL-terminated C string. With "get_cvn_flags", the
2639 name is also given by the "name" parameter, but it is a Perl string
2640 (possibly containing embedded NUL bytes), and its length in bytes
2641 is contained in the "len" parameter.
2642 NOTE: the "perl_get_cv()" form is deprecated.
2644 NOTE: the "perl_get_cvs()" form is deprecated.
2646 NOTE: the "perl_get_cvn_flags()" form is deprecated.
2648 CV* get_cv (const char* name, I32 flags)
2650 CV * get_cvs ("string", I32 flags)
2651 CV* get_cvn_flags(const char* name, STRLEN len, I32 flags)
2652 "Nullcv"
2654 "DEPRECATED!" It is planned to remove "Nullcv" from a future
2655 release of Perl. Do not use it for new code; remove it from
2656 existing code.
2657 Null CV pointer.
2659 (deprecated - use "(CV *)NULL" instead)
2661 "SvAMAGIC_off"
2663 Indicate that "sv" has overloading (active magic) disabled.
2664 void SvAMAGIC_off(SV *sv)
2666 "SvAMAGIC_on"
2668 Indicate that "sv" has overloading (active magic) enabled.
2669 void SvAMAGIC_on(SV *sv)
2671
2673 "deb"
2674 "deb_nocontext"
2675 When perl is compiled with "-DDEBUGGING", this prints to STDERR the
2676 information given by the arguments, prefaced by the name of the
2677 file containing the script causing the call, and the line number
2678 within that file.
2679 If the "v" (verbose) debugging option is in effect, the process id
2681 is also printed.
2682 The two forms differ only in that "deb_nocontext" does not take a
2684 thread context ("aTHX") parameter, so is used in situations where
2685 the caller doesn't already have the thread context.
2686 NOTE: "deb" must be explicitly called as "Perl_deb" with an "aTHX_"
2688 parameter.
2689 void Perl_deb (pTHX_ const char* pat, ...)
2691 void deb_nocontext(const char* pat, ...)
2692 "debstack"
2694 Dump the current stack
2695 I32 debstack()
2697 "dump_all"
2699 Dumps the entire optree of the current program starting at
2700 "PL_main_root" to "STDERR". Also dumps the optrees for all visible
2701 subroutines in "PL_defstash".
2702 void dump_all()
2704 "dump_c_backtrace"
2706 Dumps the C backtrace to the given "fp".
2707 Returns true if a backtrace could be retrieved, false if not.
2709 bool dump_c_backtrace(PerlIO* fp, int max_depth, int skip)
2711 "dump_eval"
2713 Described in perlguts.
2714 void dump_eval()
2716 "dump_form"
2718 Dumps the contents of the format contained in the GV "gv" to
2719 "STDERR", or a message that one doesn't exist.
2720 void dump_form(const GV* gv)
2722 "dump_packsubs"
2724 Dumps the optrees for all visible subroutines in "stash".
2725 void dump_packsubs(const HV* stash)
2727 "dump_sub"
2729 Described in perlguts.
2730 void dump_sub(const GV* gv)
2732 "get_c_backtrace_dump"
2734 Returns a SV containing a dump of "depth" frames of the call stack,
2735 skipping the "skip" innermost ones. "depth" of 20 is usually
2736 enough.
2737 The appended output looks like:
2739 ...
2741 1 10e004812:0082 Perl_croak util.c:1716 /usr/bin/perl
2742 2 10df8d6d2:1d72 perl_parse perl.c:3975 /usr/bin/perl
2743 ...
2744 The fields are tab-separated. The first column is the depth (zero
2746 being the innermost non-skipped frame). In the hex:offset, the hex
2747 is where the program counter was in "S_parse_body", and the :offset
2748 (might be missing) tells how much inside the "S_parse_body" the
2749 program counter was.
2750 The "util.c:1716" is the source code file and line number.
2752 The /usr/bin/perl is obvious (hopefully).
2754 Unknowns are "-". Unknowns can happen unfortunately quite easily:
2756 if the platform doesn't support retrieving the information; if the
2757 binary is missing the debug information; if the optimizer has
2758 transformed the code by for example inlining.
2759 SV* get_c_backtrace_dump(int max_depth, int skip)
2761 "gv_dump"
2763 Dump the name and, if they differ, the effective name of the GV
2764 "gv" to "STDERR".
2765 void gv_dump(GV* gv)
2767 "HAS_BACKTRACE"
2769 This symbol, if defined, indicates that the "backtrace()" routine
2770 is available to get a stack trace. The execinfo.h header must be
2771 included to use this routine.
2772 "magic_dump"
2774 Dumps the contents of the MAGIC "mg" to "STDERR".
2775 void magic_dump(const MAGIC *mg)
2777 "op_class"
2779 Given an op, determine what type of struct it has been allocated
2780 as. Returns one of the OPclass enums, such as OPclass_LISTOP.
2781 OPclass op_class(const OP *o)
2783 "op_dump"
2785 Dumps the optree starting at OP "o" to "STDERR".
2786 void op_dump(const OP *o)
2788 "PL_op"
2790 Described in perlhacktips.
2791 "PL_runops"
2793 Described in perlguts.
2794 "PL_sv_serial"
2796 Described in perlhacktips.
2797 "pmop_dump"
2799 Dump an OP that is related to Pattern Matching, such as
2800 "s/foo/bar/"; these require special handling.
2801 void pmop_dump(PMOP* pm)
2803 "sv_dump"
2805 Dumps the contents of an SV to the "STDERR" filehandle.
2806 For an example of its output, see Devel::Peek.
2808 void sv_dump(SV* sv)
2810 "vdeb"
2812 This is like "deb", but "args" are an encapsulated argument list.
2813 void vdeb(const char* pat, va_list* args)
2815
2817 "form"
2818 "form_nocontext"
2819 These take a sprintf-style format pattern and conventional (non-SV)
2820 arguments and return the formatted string.
2821 (char *) Perl_form(pTHX_ const char* pat, ...)
2823 can be used any place a string (char *) is required:
2825 char * s = Perl_form("%d.%d",major,minor);
2827 They use a single (per-thread) private buffer so if you want to
2829 format several strings you must explicitly copy the earlier strings
2830 away (and free the copies when you are done).
2831 The two forms differ only in that "form_nocontext" does not take a
2833 thread context ("aTHX") parameter, so is used in situations where
2834 the caller doesn't already have the thread context.
2835 NOTE: "form" must be explicitly called as "Perl_form" with an
2837 "aTHX_" parameter.
2838 char* Perl_form (pTHX_ const char* pat, ...)
2840 char* form_nocontext(const char* pat, ...)
2841 "mess"
2843 "mess_nocontext"
2844 These take a sprintf-style format pattern and argument list, which
2845 are used to generate a string message. If the message does not end
2846 with a newline, then it will be extended with some indication of
2847 the current location in the code, as described for "mess_sv".
2848 Normally, the resulting message is returned in a new mortal SV.
2850 But during global destruction a single SV may be shared between
2851 uses of this function.
2852 The two forms differ only in that "mess_nocontext" does not take a
2854 thread context ("aTHX") parameter, so is used in situations where
2855 the caller doesn't already have the thread context.
2856 NOTE: "mess" must be explicitly called as "Perl_mess" with an
2858 "aTHX_" parameter.
2859 SV* Perl_mess (pTHX_ const char* pat, ...)
2861 SV* mess_nocontext(const char* pat, ...)
2862 "mess_sv"
2864 Expands a message, intended for the user, to include an indication
2865 of the current location in the code, if the message does not
2866 already appear to be complete.
2867 "basemsg" is the initial message or object. If it is a reference,
2869 it will be used as-is and will be the result of this function.
2870 Otherwise it is used as a string, and if it already ends with a
2871 newline, it is taken to be complete, and the result of this
2872 function will be the same string. If the message does not end with
2873 a newline, then a segment such as "at foo.pl line 37" will be
2874 appended, and possibly other clauses indicating the current state
2875 of execution. The resulting message will end with a dot and a
2876 newline.
2877 Normally, the resulting message is returned in a new mortal SV.
2879 During global destruction a single SV may be shared between uses of
2880 this function. If "consume" is true, then the function is
2881 permitted (but not required) to modify and return "basemsg" instead
2882 of allocating a new SV.
2883 SV* mess_sv(SV* basemsg, bool consume)
2885 "pv_display"
2887 Similar to
2888 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
2890 except that an additional "\0" will be appended to the string when
2892 len > cur and pv[cur] is "\0".
2893 Note that the final string may be up to 7 chars longer than pvlim.
2895 char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len,
2897 STRLEN pvlim)
2898 "pv_escape"
2900 Escapes at most the first "count" chars of "pv" and puts the
2901 results into "dsv" such that the size of the escaped string will
2902 not exceed "max" chars and will not contain any incomplete escape
2903 sequences. The number of bytes escaped will be returned in the
2904 "STRLEN *escaped" parameter if it is not null. When the "dsv"
2905 parameter is null no escaping actually occurs, but the number of
2906 bytes that would be escaped were it not null will be calculated.
2907 If flags contains "PERL_PV_ESCAPE_QUOTE" then any double quotes in
2909 the string will also be escaped.
2910 Normally the SV will be cleared before the escaped string is
2912 prepared, but when "PERL_PV_ESCAPE_NOCLEAR" is set this will not
2913 occur.
2914 If "PERL_PV_ESCAPE_UNI" is set then the input string is treated as
2916 UTF-8 if "PERL_PV_ESCAPE_UNI_DETECT" is set then the input string
2917 is scanned using "is_utf8_string()" to determine if it is UTF-8.
2918 If "PERL_PV_ESCAPE_ALL" is set then all input chars will be output
2920 using "\x01F1" style escapes, otherwise if
2921 "PERL_PV_ESCAPE_NONASCII" is set, only non-ASCII chars will be
2922 escaped using this style; otherwise, only chars above 255 will be
2923 so escaped; other non printable chars will use octal or common
2924 escaped patterns like "\n". Otherwise, if
2925 "PERL_PV_ESCAPE_NOBACKSLASH" then all chars below 255 will be
2926 treated as printable and will be output as literals.
2927 If "PERL_PV_ESCAPE_FIRSTCHAR" is set then only the first char of
2929 the string will be escaped, regardless of max. If the output is to
2930 be in hex, then it will be returned as a plain hex sequence. Thus
2931 the output will either be a single char, an octal escape sequence,
2932 a special escape like "\n" or a hex value.
2933 If "PERL_PV_ESCAPE_RE" is set then the escape char used will be a
2935 "%" and not a "\\". This is because regexes very often contain
2936 backslashed sequences, whereas "%" is not a particularly common
2937 character in patterns.
2938 Returns a pointer to the escaped text as held by "dsv".
2940 char* pv_escape(SV *dsv, char const * const str,
2942 const STRLEN count, const STRLEN max,
2943 STRLEN * const escaped, const U32 flags)
2944 "pv_pretty"
2946 Converts a string into something presentable, handling escaping via
2947 "pv_escape()" and supporting quoting and ellipses.
2948 If the "PERL_PV_PRETTY_QUOTE" flag is set then the result will be
2950 double quoted with any double quotes in the string escaped.
2951 Otherwise if the "PERL_PV_PRETTY_LTGT" flag is set then the result
2952 be wrapped in angle brackets.
2953 If the "PERL_PV_PRETTY_ELLIPSES" flag is set and not all characters
2955 in string were output then an ellipsis "..." will be appended to
2956 the string. Note that this happens AFTER it has been quoted.
2957 If "start_color" is non-null then it will be inserted after the
2959 opening quote (if there is one) but before the escaped text. If
2960 "end_color" is non-null then it will be inserted after the escaped
2961 text but before any quotes or ellipses.
2962 Returns a pointer to the prettified text as held by "dsv".
2964 char* pv_pretty(SV *dsv, char const * const str,
2966 const STRLEN count, const STRLEN max,
2967 char const * const start_color,
2968 char const * const end_color, const U32 flags)
2969 "vform"
2971 Like "form" but but the arguments are an encapsulated argument
2972 list.
2973 char* vform(const char* pat, va_list* args)
2975 "vmess"
2977 "pat" and "args" are a sprintf-style format pattern and
2978 encapsulated argument list, respectively. These are used to
2979 generate a string message. If the message does not end with a
2980 newline, then it will be extended with some indication of the
2981 current location in the code, as described for "mess_sv".
2982 Normally, the resulting message is returned in a new mortal SV.
2984 During global destruction a single SV may be shared between uses of
2985 this function.
2986 SV* vmess(const char* pat, va_list* args)
2988
2990 "call_atexit"
2991 Add a function "fn" to the list of functions to be called at global
2992 destruction. "ptr" will be passed as an argument to "fn"; it can
2993 point to a "struct" so that you can pass anything you want.
2994 Note that under threads, "fn" may run multiple times. This is
2996 because the list is executed each time the current or any
2997 descendent thread terminates.
2998 void call_atexit(ATEXIT_t fn, void *ptr)
3000 "cv_clone"
3002 Clone a CV, making a lexical closure. "proto" supplies the
3003 prototype of the function: its code, pad structure, and other
3004 attributes. The prototype is combined with a capture of outer
3005 lexicals to which the code refers, which are taken from the
3006 currently-executing instance of the immediately surrounding code.
3007 CV* cv_clone(CV* proto)
3009 "cv_name"
3011 Returns an SV containing the name of the CV, mainly for use in
3012 error reporting. The CV may actually be a GV instead, in which
3013 case the returned SV holds the GV's name. Anything other than a GV
3014 or CV is treated as a string already holding the sub name, but this
3015 could change in the future.
3016 An SV may be passed as a second argument. If so, the name will be
3018 assigned to it and it will be returned. Otherwise the returned SV
3019 will be a new mortal.
3020 If "flags" has the "CV_NAME_NOTQUAL" bit set, then the package name
3022 will not be included. If the first argument is neither a CV nor a
3023 GV, this flag is ignored (subject to change).
3024 SV * cv_name(CV *cv, SV *sv, U32 flags)
3026 "cv_undef"
3028 Clear out all the active components of a CV. This can happen
3029 either by an explicit "undef &foo", or by the reference count going
3030 to zero. In the former case, we keep the "CvOUTSIDE" pointer, so
3031 that any anonymous children can still follow the full lexical scope
3032 chain.
3033 void cv_undef(CV* cv)
3035 "find_rundefsv"
3037 Returns the global variable $_.
3038 SV* find_rundefsv()
3040 "find_rundefsvoffset"
3042 "DEPRECATED!" It is planned to remove "find_rundefsvoffset" from a
3043 future release of Perl. Do not use it for new code; remove it from
3044 existing code.
3045 Until the lexical $_ feature was removed, this function would find
3047 the position of the lexical $_ in the pad of the currently-
3048 executing function and return the offset in the current pad, or
3049 "NOT_IN_PAD".
3050 Now it always returns "NOT_IN_PAD".
3052 PADOFFSET find_rundefsvoffset()
3054 "HAS_SKIP_LOCALE_INIT"
3056 Described in perlembed.
3057 "intro_my"
3059 "Introduce" "my" variables to visible status. This is called
3060 during parsing at the end of each statement to make lexical
3061 variables visible to subsequent statements.
3062 U32 intro_my()
3064 "load_module"
3066 "load_module_nocontext"
3067 These load the module whose name is pointed to by the string part
3068 of "name". Note that the actual module name, not its filename,
3069 should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver, if
3070 specified and not NULL, provides version semantics similar to "use
3071 Foo::Bar VERSION". The optional trailing arguments can be used to
3072 specify arguments to the module's "import()" method, similar to
3073 "use Foo::Bar VERSION LIST"; their precise handling depends on the
3074 flags. The flags argument is a bitwise-ORed collection of any of
3075 "PERL_LOADMOD_DENY", "PERL_LOADMOD_NOIMPORT", or
3076 "PERL_LOADMOD_IMPORT_OPS" (or 0 for no flags).
3077 If "PERL_LOADMOD_NOIMPORT" is set, the module is loaded as if with
3079 an empty import list, as in "use Foo::Bar ()"; this is the only
3080 circumstance in which the trailing optional arguments may be
3081 omitted entirely. Otherwise, if "PERL_LOADMOD_IMPORT_OPS" is set,
3082 the trailing arguments must consist of exactly one "OP*",
3083 containing the op tree that produces the relevant import arguments.
3084 Otherwise, the trailing arguments must all be "SV*" values that
3085 will be used as import arguments; and the list must be terminated
3086 with "(SV*) NULL". If neither "PERL_LOADMOD_NOIMPORT" nor
3087 "PERL_LOADMOD_IMPORT_OPS" is set, the trailing "NULL" pointer is
3088 needed even if no import arguments are desired. The reference count
3089 for each specified "SV*" argument is decremented. In addition, the
3090 "name" argument is modified.
3091 If "PERL_LOADMOD_DENY" is set, the module is loaded as if with "no"
3093 rather than "use".
3094 "load_module" and "load_module_nocontext" have the same apparent
3096 signature, but the former hides the fact that it is accessing a
3097 thread context parameter. So use the latter when you get a
3098 compilation error about "pTHX".
3099 void load_module (U32 flags, SV* name, SV* ver, ...)
3101 void load_module_nocontext(U32 flags, SV* name, SV* ver, ...)
3102 "my_exit"
3104 A wrapper for the C library exit(3), honoring what "PL_exit_flags"
3105 in perlapi say to do.
3106 void my_exit(U32 status)
3108 "newPADNAMELIST"
3110 NOTE: "newPADNAMELIST" is experimental and may change or be removed
3111 without notice.
3112 Creates a new pad name list. "max" is the highest index for which
3114 space is allocated.
3115 PADNAMELIST * newPADNAMELIST(size_t max)
3117 "newPADNAMEouter"
3119 NOTE: "newPADNAMEouter" is experimental and may change or be
3120 removed without notice.
3121 Constructs and returns a new pad name. Only use this function for
3123 names that refer to outer lexicals. (See also "newPADNAMEpvn".)
3124 "outer" is the outer pad name that this one mirrors. The returned
3125 pad name has the "PADNAMEt_OUTER" flag already set.
3126 PADNAME * newPADNAMEouter(PADNAME *outer)
3128 "newPADNAMEpvn"
3130 NOTE: "newPADNAMEpvn" is experimental and may change or be removed
3131 without notice.
3132 Constructs and returns a new pad name. "s" must be a UTF-8 string.
3134 Do not use this for pad names that point to outer lexicals. See
3135 "newPADNAMEouter".
3136 PADNAME * newPADNAMEpvn(const char *s, STRLEN len)
3138 "nothreadhook"
3140 Stub that provides thread hook for perl_destruct when there are no
3141 threads.
3142 int nothreadhook()
3144 "pad_add_anon"
3146 Allocates a place in the currently-compiling pad (via "pad_alloc")
3147 for an anonymous function that is lexically scoped inside the
3148 currently-compiling function. The function "func" is linked into
3149 the pad, and its "CvOUTSIDE" link to the outer scope is weakened to
3150 avoid a reference loop.
3151 One reference count is stolen, so you may need to do
3153 "SvREFCNT_inc(func)".
3154 "optype" should be an opcode indicating the type of operation that
3156 the pad entry is to support. This doesn't affect operational
3157 semantics, but is used for debugging.
3158 PADOFFSET pad_add_anon(CV* func, I32 optype)
3160 "pad_add_name_pv"
3162 Exactly like "pad_add_name_pvn", but takes a nul-terminated string
3163 instead of a string/length pair.
3164 PADOFFSET pad_add_name_pv(const char *name, const U32 flags,
3166 HV *typestash, HV *ourstash)
3167 "pad_add_name_pvn"
3169 Allocates a place in the currently-compiling pad for a named
3170 lexical variable. Stores the name and other metadata in the name
3171 part of the pad, and makes preparations to manage the variable's
3172 lexical scoping. Returns the offset of the allocated pad slot.
3173 "namepv"/"namelen" specify the variable's name, including leading
3175 sigil. If "typestash" is non-null, the name is for a typed
3176 lexical, and this identifies the type. If "ourstash" is non-null,
3177 it's a lexical reference to a package variable, and this identifies
3178 the package. The following flags can be OR'ed together:
3179 padadd_OUR redundantly specifies if it's a package var
3181 padadd_STATE variable will retain value persistently
3182 padadd_NO_DUP_CHECK skip check for lexical shadowing
3183 PADOFFSET pad_add_name_pvn(const char *namepv, STRLEN namelen,
3185 U32 flags, HV *typestash,
3186 HV *ourstash)
3187 "pad_add_name_sv"
3189 Exactly like "pad_add_name_pvn", but takes the name string in the
3190 form of an SV instead of a string/length pair.
3191 PADOFFSET pad_add_name_sv(SV *name, U32 flags, HV *typestash,
3193 HV *ourstash)
3194 "pad_alloc"
3196 NOTE: "pad_alloc" is experimental and may change or be removed
3197 without notice.
3198 Allocates a place in the currently-compiling pad, returning the
3200 offset of the allocated pad slot. No name is initially attached to
3201 the pad slot. "tmptype" is a set of flags indicating the kind of
3202 pad entry required, which will be set in the value SV for the
3203 allocated pad entry:
3204 SVs_PADMY named lexical variable ("my", "our", "state")
3206 SVs_PADTMP unnamed temporary store
3207 SVf_READONLY constant shared between recursion levels
3208 "SVf_READONLY" has been supported here only since perl 5.20. To
3210 work with earlier versions as well, use "SVf_READONLY|SVs_PADTMP".
3211 "SVf_READONLY" does not cause the SV in the pad slot to be marked
3212 read-only, but simply tells "pad_alloc" that it will be made read-
3213 only (by the caller), or at least should be treated as such.
3214 "optype" should be an opcode indicating the type of operation that
3216 the pad entry is to support. This doesn't affect operational
3217 semantics, but is used for debugging.
3218 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
3220 "pad_findmy_pv"
3222 Exactly like "pad_findmy_pvn", but takes a nul-terminated string
3223 instead of a string/length pair.
3224 PADOFFSET pad_findmy_pv(const char* name, U32 flags)
3226 "pad_findmy_pvn"
3228 Given the name of a lexical variable, find its position in the
3229 currently-compiling pad. "namepv"/"namelen" specify the variable's
3230 name, including leading sigil. "flags" is reserved and must be
3231 zero. If it is not in the current pad but appears in the pad of
3232 any lexically enclosing scope, then a pseudo-entry for it is added
3233 in the current pad. Returns the offset in the current pad, or
3234 "NOT_IN_PAD" if no such lexical is in scope.
3235 PADOFFSET pad_findmy_pvn(const char* namepv, STRLEN namelen,
3237 U32 flags)
3238 "pad_findmy_sv"
3240 Exactly like "pad_findmy_pvn", but takes the name string in the
3241 form of an SV instead of a string/length pair.
3242 PADOFFSET pad_findmy_sv(SV* name, U32 flags)
3244 "padnamelist_fetch"
3246 NOTE: "padnamelist_fetch" is experimental and may change or be
3247 removed without notice.
3248 Fetches the pad name from the given index.
3250 PADNAME * padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
3252 "padnamelist_store"
3254 NOTE: "padnamelist_store" is experimental and may change or be
3255 removed without notice.
3256 Stores the pad name (which may be null) at the given index, freeing
3258 any existing pad name in that slot.
3259 PADNAME ** padnamelist_store(PADNAMELIST *pnl, SSize_t key,
3261 PADNAME *val)
3262 "pad_tidy"
3264 NOTE: "pad_tidy" is experimental and may change or be removed
3265 without notice.
3266 Tidy up a pad at the end of compilation of the code to which it
3268 belongs. Jobs performed here are: remove most stuff from the pads
3269 of anonsub prototypes; give it a @_; mark temporaries as such.
3270 "type" indicates the kind of subroutine:
3271 padtidy_SUB ordinary subroutine
3273 padtidy_SUBCLONE prototype for lexical closure
3274 padtidy_FORMAT format
3275 void pad_tidy(padtidy_type type)
3277 "perl_alloc"
3279 Allocates a new Perl interpreter. See perlembed.
3280 PerlInterpreter* perl_alloc()
3282 "PERL_ASYNC_CHECK"
3284 Described in perlinterp.
3285 void PERL_ASYNC_CHECK()
3287 "perl_construct"
3289 Initializes a new Perl interpreter. See perlembed.
3290 void perl_construct(PerlInterpreter *my_perl)
3292 "perl_destruct"
3294 Shuts down a Perl interpreter. See perlembed for a tutorial.
3295 "my_perl" points to the Perl interpreter. It must have been
3297 previously created through the use of "perl_alloc" and
3298 "perl_construct". It may have been initialised through
3299 "perl_parse", and may have been used through "perl_run" and other
3300 means. This function should be called for any Perl interpreter
3301 that has been constructed with "perl_construct", even if subsequent
3302 operations on it failed, for example if "perl_parse" returned a
3303 non-zero value.
3304 If the interpreter's "PL_exit_flags" word has the
3306 "PERL_EXIT_DESTRUCT_END" flag set, then this function will execute
3307 code in "END" blocks before performing the rest of destruction. If
3308 it is desired to make any use of the interpreter between
3309 "perl_parse" and "perl_destruct" other than just calling
3310 "perl_run", then this flag should be set early on. This matters if
3311 "perl_run" will not be called, or if anything else will be done in
3312 addition to calling "perl_run".
3313 Returns a value be a suitable value to pass to the C library
3315 function "exit" (or to return from "main"), to serve as an exit
3316 code indicating the nature of the way the interpreter terminated.
3317 This takes into account any failure of "perl_parse" and any early
3318 exit from "perl_run". The exit code is of the type required by the
3319 host operating system, so because of differing exit code
3320 conventions it is not portable to interpret specific numeric values
3321 as having specific meanings.
3322 int perl_destruct(PerlInterpreter *my_perl)
3324 "perl_free"
3326 Releases a Perl interpreter. See perlembed.
3327 void perl_free(PerlInterpreter *my_perl)
3329 "PERL_GET_CONTEXT"
3331 Described in perlguts.
3332 "PerlInterpreter"
3334 Described in perlembed.
3335 "perl_parse"
3337 Tells a Perl interpreter to parse a Perl script. This performs
3338 most of the initialisation of a Perl interpreter. See perlembed
3339 for a tutorial.
3340 "my_perl" points to the Perl interpreter that is to parse the
3342 script. It must have been previously created through the use of
3343 "perl_alloc" and "perl_construct". "xsinit" points to a callback
3344 function that will be called to set up the ability for this Perl
3345 interpreter to load XS extensions, or may be null to perform no
3346 such setup.
3347 "argc" and "argv" supply a set of command-line arguments to the
3349 Perl interpreter, as would normally be passed to the "main"
3350 function of a C program. "argv[argc]" must be null. These
3351 arguments are where the script to parse is specified, either by
3352 naming a script file or by providing a script in a "-e" option. If
3353 $0 will be written to in the Perl interpreter, then the argument
3354 strings must be in writable memory, and so mustn't just be string
3355 constants.
3356 "env" specifies a set of environment variables that will be used by
3358 this Perl interpreter. If non-null, it must point to a null-
3359 terminated array of environment strings. If null, the Perl
3360 interpreter will use the environment supplied by the "environ"
3361 global variable.
3362 This function initialises the interpreter, and parses and compiles
3364 the script specified by the command-line arguments. This includes
3365 executing code in "BEGIN", "UNITCHECK", and "CHECK" blocks. It
3366 does not execute "INIT" blocks or the main program.
3367 Returns an integer of slightly tricky interpretation. The correct
3369 use of the return value is as a truth value indicating whether
3370 there was a failure in initialisation. If zero is returned, this
3371 indicates that initialisation was successful, and it is safe to
3372 proceed to call "perl_run" and make other use of it. If a non-zero
3373 value is returned, this indicates some problem that means the
3374 interpreter wants to terminate. The interpreter should not be just
3375 abandoned upon such failure; the caller should proceed to shut the
3376 interpreter down cleanly with "perl_destruct" and free it with
3377 "perl_free".
3378 For historical reasons, the non-zero return value also attempts to
3380 be a suitable value to pass to the C library function "exit" (or to
3381 return from "main"), to serve as an exit code indicating the nature
3382 of the way initialisation terminated. However, this isn't
3383 portable, due to differing exit code conventions. A historical bug
3384 is preserved for the time being: if the Perl built-in "exit" is
3385 called during this function's execution, with a type of exit
3386 entailing a zero exit code under the host operating system's
3387 conventions, then this function returns zero rather than a non-zero
3388 value. This bug, [perl #2754], leads to "perl_run" being called
3389 (and therefore "INIT" blocks and the main program running) despite
3390 a call to "exit". It has been preserved because a popular module-
3391 installing module has come to rely on it and needs time to be
3392 fixed. This issue is [perl #132577], and the original bug is due
3393 to be fixed in Perl 5.30.
3394 int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit,
3396 int argc, char** argv, char** env)
3397 "perl_run"
3399 Tells a Perl interpreter to run its main program. See perlembed
3400 for a tutorial.
3401 "my_perl" points to the Perl interpreter. It must have been
3403 previously created through the use of "perl_alloc" and
3404 "perl_construct", and initialised through "perl_parse". This
3405 function should not be called if "perl_parse" returned a non-zero
3406 value, indicating a failure in initialisation or compilation.
3407 This function executes code in "INIT" blocks, and then executes the
3409 main program. The code to be executed is that established by the
3410 prior call to "perl_parse". If the interpreter's "PL_exit_flags"
3411 word does not have the "PERL_EXIT_DESTRUCT_END" flag set, then this
3412 function will also execute code in "END" blocks. If it is desired
3413 to make any further use of the interpreter after calling this
3414 function, then "END" blocks should be postponed to "perl_destruct"
3415 time by setting that flag.
3416 Returns an integer of slightly tricky interpretation. The correct
3418 use of the return value is as a truth value indicating whether the
3419 program terminated non-locally. If zero is returned, this
3420 indicates that the program ran to completion, and it is safe to
3421 make other use of the interpreter (provided that the
3422 "PERL_EXIT_DESTRUCT_END" flag was set as described above). If a
3423 non-zero value is returned, this indicates that the interpreter
3424 wants to terminate early. The interpreter should not be just
3425 abandoned because of this desire to terminate; the caller should
3426 proceed to shut the interpreter down cleanly with "perl_destruct"
3427 and free it with "perl_free".
3428 For historical reasons, the non-zero return value also attempts to
3430 be a suitable value to pass to the C library function "exit" (or to
3431 return from "main"), to serve as an exit code indicating the nature
3432 of the way the program terminated. However, this isn't portable,
3433 due to differing exit code conventions. An attempt is made to
3434 return an exit code of the type required by the host operating
3435 system, but because it is constrained to be non-zero, it is not
3436 necessarily possible to indicate every type of exit. It is only
3437 reliable on Unix, where a zero exit code can be augmented with a
3438 set bit that will be ignored. In any case, this function is not
3439 the correct place to acquire an exit code: one should get that from
3440 "perl_destruct".
3441 int perl_run(PerlInterpreter *my_perl)
3443 "PERL_SET_CONTEXT"
3445 Described in perlguts.
3446 void PERL_SET_CONTEXT(PerlInterpreter* i)
3448 "PERL_SYS_INIT"
3450 "PERL_SYS_INIT3"
3451 These provide system-specific tune up of the C runtime environment
3452 necessary to run Perl interpreters. Only one should be used, and
3453 it should be called only once, before creating any Perl
3454 interpreters.
3455 They differ in that "PERL_SYS_INIT3" also initializes "env".
3457 void PERL_SYS_INIT (int *argc, char*** argv)
3459 void PERL_SYS_INIT3(int *argc, char*** argv, char*** env)
3460 "PERL_SYS_TERM"
3462 Provides system-specific clean up of the C runtime environment
3463 after running Perl interpreters. This should be called only once,
3464 after freeing any remaining Perl interpreters.
3465 void PERL_SYS_TERM()
3467 "PL_exit_flags"
3469 Contains flags controlling perl's behaviour on exit():
3470 • "PERL_EXIT_DESTRUCT_END"
3472 If set, END blocks are executed when the interpreter is
3474 destroyed. This is normally set by perl itself after the
3475 interpreter is constructed.
3476 • "PERL_EXIT_ABORT"
3478 Call "abort()" on exit. This is used internally by perl itself
3480 to abort if exit is called while processing exit.
3481 • "PERL_EXIT_WARN"
3483 Warn on exit.
3485 • "PERL_EXIT_EXPECTED"
3487 Set by the "exit" in perlfunc operator.
3489 U8 PL_exit_flags
3491 "PL_origalen"
3493 Described in perlembed.
3494 "PL_perl_destruct_level"
3496 This value may be set when embedding for full cleanup.
3497 Possible values:
3499 • 0 - none
3501 • 1 - full
3503 • 2 or greater - full with checks.
3505 If $ENV{PERL_DESTRUCT_LEVEL} is set to an integer greater than the
3507 value of "PL_perl_destruct_level" its value is used instead.
3508 On threaded perls, each thread has an independent copy of this
3510 variable; each initialized at creation time with the current value
3511 of the creating thread's copy.
3512 signed char PL_perl_destruct_level
3514 "require_pv"
3516 Tells Perl to "require" the file named by the string argument. It
3517 is analogous to the Perl code "eval "require '$file'"". It's even
3518 implemented that way; consider using load_module instead.
3519 NOTE: the "perl_require_pv()" form is deprecated.
3521 void require_pv(const char* pv)
3523 "vload_module"
3525 Like "load_module" but the arguments are an encapsulated argument
3526 list.
3527 void vload_module(U32 flags, SV* name, SV* ver, va_list* args)
3529
3531 "sv_string_from_errnum"
3532 Generates the message string describing an OS error and returns it
3533 as an SV. "errnum" must be a value that "errno" could take,
3534 identifying the type of error.
3535 If "tgtsv" is non-null then the string will be written into that SV
3537 (overwriting existing content) and it will be returned. If "tgtsv"
3538 is a null pointer then the string will be written into a new mortal
3539 SV which will be returned.
3540 The message will be taken from whatever locale would be used by $!,
3542 and will be encoded in the SV in whatever manner would be used by
3543 $!. The details of this process are subject to future change.
3544 Currently, the message is taken from the C locale by default
3545 (usually producing an English message), and from the currently
3546 selected locale when in the scope of the "use locale" pragma. A
3547 heuristic attempt is made to decode the message from the locale's
3548 character encoding, but it will only be decoded as either UTF-8 or
3549 ISO-8859-1. It is always correctly decoded in a UTF-8 locale,
3550 usually in an ISO-8859-1 locale, and never in any other locale.
3551 The SV is always returned containing an actual string, and with no
3553 other OK bits set. Unlike $!, a message is even yielded for
3554 "errnum" zero (meaning success), and if no useful message is
3555 available then a useless string (currently empty) is returned.
3556 SV* sv_string_from_errnum(int errnum, SV* tgtsv)
3558
3560 "dXCPT"
3561 Set up necessary local variables for exception handling. See
3562 "Exception Handling" in perlguts.
3563 dXCPT;
3565 "JMPENV_JUMP"
3567 Described in perlinterp.
3568 void JMPENV_JUMP(int v)
3570 "JMPENV_PUSH"
3572 Described in perlinterp.
3573 void JMPENV_PUSH(int v)
3575 "PL_restartop"
3577 Described in perlinterp.
3578 "XCPT_CATCH"
3580 Introduces a catch block. See "Exception Handling" in perlguts.
3581 "XCPT_RETHROW"
3583 Rethrows a previously caught exception. See "Exception Handling"
3584 in perlguts.
3585 XCPT_RETHROW;
3587 "XCPT_TRY_END"
3589 Ends a try block. See "Exception Handling" in perlguts.
3590 "XCPT_TRY_START"
3592 Starts a try block. See "Exception Handling" in perlguts.
3593
3595 Also see "List of capability HAS_foo symbols".
3596 "DIRNAMLEN"
3598 This symbol, if defined, indicates to the C program that the length
3599 of directory entry names is provided by a "d_namlen" field.
3600 Otherwise you need to do "strlen()" on the "d_name" field.
3601 "DOSUID"
3603 This symbol, if defined, indicates that the C program should check
3604 the script that it is executing for setuid/setgid bits, and attempt
3605 to emulate setuid/setgid on systems that have disabled setuid #!
3606 scripts because the kernel can't do it securely. It is up to the
3607 package designer to make sure that this emulation is done securely.
3608 Among other things, it should do an fstat on the script it just
3609 opened to make sure it really is a setuid/setgid script, it should
3610 make sure the arguments passed correspond exactly to the argument
3611 on the #! line, and it should not trust any subprocesses to which
3612 it must pass the filename rather than the file descriptor of the
3613 script to be executed.
3614 "EOF_NONBLOCK"
3616 This symbol, if defined, indicates to the C program that a "read()"
3617 on a non-blocking file descriptor will return 0 on "EOF", and not
3618 the value held in "RD_NODATA" (-1 usually, in that case!).
3619 "FCNTL_CAN_LOCK"
3621 This symbol, if defined, indicates that "fcntl()" can be used for
3622 file locking. Normally on Unix systems this is defined. It may be
3623 undefined on "VMS".
3624 "FFLUSH_ALL"
3626 This symbol, if defined, tells that to flush all pending stdio
3627 output one must loop through all the stdio file handles stored in
3628 an array and fflush them. Note that if "fflushNULL" is defined,
3629 fflushall will not even be probed for and will be left undefined.
3630 "FFLUSH_NULL"
3632 This symbol, if defined, tells that "fflush(NULL)" correctly
3633 flushes all pending stdio output without side effects. In
3634 particular, on some platforms calling "fflush(NULL)" *still*
3635 corrupts "STDIN" if it is a pipe.
3636 "FILE_base"
3638 This macro is used to access the "_base" field (or equivalent) of
3639 the "FILE" structure pointed to by its argument. This macro will
3640 always be defined if "USE_STDIO_BASE" is defined.
3641 void * FILE_base(FILE * f)
3643 "FILE_bufsiz"
3645 This macro is used to determine the number of bytes in the I/O
3646 buffer pointed to by "_base" field (or equivalent) of the "FILE"
3647 structure pointed to its argument. This macro will always be
3648 defined if "USE_STDIO_BASE" is defined.
3649 Size_t FILE_bufsiz(FILE *f)
3651 "FILE_cnt"
3653 This macro is used to access the "_cnt" field (or equivalent) of
3654 the "FILE" structure pointed to by its argument. This macro will
3655 always be defined if "USE_STDIO_PTR" is defined.
3656 Size_t FILE_cnt(FILE * f)
3658 "FILE_ptr"
3660 This macro is used to access the "_ptr" field (or equivalent) of
3661 the "FILE" structure pointed to by its argument. This macro will
3662 always be defined if "USE_STDIO_PTR" is defined.
3663 void * FILE_ptr(FILE * f)
3665 "FLEXFILENAMES"
3667 This symbol, if defined, indicates that the system supports
3668 filenames longer than 14 characters.
3669 "HAS_DIR_DD_FD"
3671 This symbol, if defined, indicates that the the "DIR"* dirstream
3672 structure contains a member variable named "dd_fd".
3673 "HAS_DUP2"
3675 This symbol, if defined, indicates that the "dup2" routine is
3676 available to duplicate file descriptors.
3677 "HAS_DUP3"
3679 This symbol, if defined, indicates that the "dup3" routine is
3680 available to duplicate file descriptors.
3681 "HAS_FAST_STDIO"
3683 This symbol, if defined, indicates that the "fast stdio" is
3684 available to manipulate the stdio buffers directly.
3685 "HAS_FCHDIR"
3687 This symbol, if defined, indicates that the "fchdir" routine is
3688 available to change directory using a file descriptor.
3689 "HAS_FCNTL"
3691 This symbol, if defined, indicates to the C program that the
3692 "fcntl()" function exists.
3693 "HAS_FDCLOSE"
3695 This symbol, if defined, indicates that the "fdclose" routine is
3696 available to free a "FILE" structure without closing the underlying
3697 file descriptor. This function appeared in "FreeBSD" 10.2.
3698 "HAS_FPATHCONF"
3700 This symbol, if defined, indicates that "pathconf()" is available
3701 to determine file-system related limits and options associated with
3702 a given open file descriptor.
3703 "HAS_FPOS64_T"
3705 This symbol will be defined if the C compiler supports "fpos64_t".
3706 "HAS_FSTATFS"
3708 This symbol, if defined, indicates that the "fstatfs" routine is
3709 available to stat filesystems by file descriptors.
3710 "HAS_FSTATVFS"
3712 This symbol, if defined, indicates that the "fstatvfs" routine is
3713 available to stat filesystems by file descriptors.
3714 "HAS_GETFSSTAT"
3716 This symbol, if defined, indicates that the "getfsstat" routine is
3717 available to stat filesystems in bulk.
3718 "HAS_GETMNT"
3720 This symbol, if defined, indicates that the "getmnt" routine is
3721 available to get filesystem mount info by filename.
3722 "HAS_GETMNTENT"
3724 This symbol, if defined, indicates that the "getmntent" routine is
3725 available to iterate through mounted file systems to get their
3726 info.
3727 "HAS_HASMNTOPT"
3729 This symbol, if defined, indicates that the "hasmntopt" routine is
3730 available to query the mount options of file systems.
3731 "HAS_LSEEK_PROTO"
3733 This symbol, if defined, indicates that the system provides a
3734 prototype for the "lseek()" function. Otherwise, it is up to the
3735 program to supply one. A good guess is
3736 extern off_t lseek(int, off_t, int);
3738 "HAS_MKDIR"
3740 This symbol, if defined, indicates that the "mkdir" routine is
3741 available to create directories. Otherwise you should fork off a
3742 new process to exec /bin/mkdir.
3743 "HAS_OFF64_T"
3745 This symbol will be defined if the C compiler supports "off64_t".
3746 "HAS_OPEN3"
3748 This manifest constant lets the C program know that the three
3749 argument form of open(2) is available.
3750 "HAS_OPENAT"
3752 This symbol is defined if the "openat()" routine is available.
3753 "HAS_POLL"
3755 This symbol, if defined, indicates that the "poll" routine is
3756 available to "poll" active file descriptors. Please check "I_POLL"
3757 and "I_SYS_POLL" to know which header should be included as well.
3758 "HAS_READDIR"
3760 This symbol, if defined, indicates that the "readdir" routine is
3761 available to read directory entries. You may have to include
3762 dirent.h. See "I_DIRENT".
3763 "HAS_READDIR64_R"
3765 This symbol, if defined, indicates that the "readdir64_r" routine
3766 is available to readdir64 re-entrantly.
3767 "HAS_REWINDDIR"
3769 This symbol, if defined, indicates that the "rewinddir" routine is
3770 available. You may have to include dirent.h. See "I_DIRENT".
3771 "HAS_RMDIR"
3773 This symbol, if defined, indicates that the "rmdir" routine is
3774 available to remove directories. Otherwise you should fork off a
3775 new process to exec /bin/rmdir.
3776 "HAS_SEEKDIR"
3778 This symbol, if defined, indicates that the "seekdir" routine is
3779 available. You may have to include dirent.h. See "I_DIRENT".
3780 "HAS_SELECT"
3782 This symbol, if defined, indicates that the "select" routine is
3783 available to "select" active file descriptors. If the timeout field
3784 is used, sys/time.h may need to be included.
3785 "HAS_SETVBUF"
3787 This symbol, if defined, indicates that the "setvbuf" routine is
3788 available to change buffering on an open stdio stream. to a line-
3789 buffered mode.
3790 "HAS_STDIO_STREAM_ARRAY"
3792 This symbol, if defined, tells that there is an array holding the
3793 stdio streams.
3794 "HAS_STRUCT_FS_DATA"
3796 This symbol, if defined, indicates that the "struct fs_data" to do
3797 "statfs()" is supported.
3798 "HAS_STRUCT_STATFS"
3800 This symbol, if defined, indicates that the "struct statfs" to do
3801 "statfs()" is supported.
3802 "HAS_STRUCT_STATFS_F_FLAGS"
3804 This symbol, if defined, indicates that the "struct statfs" does
3805 have the "f_flags" member containing the mount flags of the
3806 filesystem containing the file. This kind of "struct statfs" is
3807 coming from sys/mount.h ("BSD" 4.3), not from sys/statfs.h
3808 ("SYSV"). Older "BSDs" (like Ultrix) do not have "statfs()" and
3809 "struct statfs", they have "ustat()" and "getmnt()" with "struct
3810 ustat" and "struct fs_data".
3811 "HAS_TELLDIR"
3813 This symbol, if defined, indicates that the "telldir" routine is
3814 available. You may have to include dirent.h. See "I_DIRENT".
3815 "HAS_USTAT"
3817 This symbol, if defined, indicates that the "ustat" system call is
3818 available to query file system statistics by "dev_t".
3819 "I_FCNTL"
3821 This manifest constant tells the C program to include fcntl.h.
3822 #ifdef I_FCNTL
3824 #include <fcntl.h>
3825 #endif
3826 "I_SYS_DIR"
3828 This symbol, if defined, indicates to the C program that it should
3829 include sys/dir.h.
3830 #ifdef I_SYS_DIR
3832 #include <sys_dir.h>
3833 #endif
3834 "I_SYS_FILE"
3836 This symbol, if defined, indicates to the C program that it should
3837 include sys/file.h to get definition of "R_OK" and friends.
3838 #ifdef I_SYS_FILE
3840 #include <sys_file.h>
3841 #endif
3842 "I_SYS_NDIR"
3844 This symbol, if defined, indicates to the C program that it should
3845 include sys/ndir.h.
3846 #ifdef I_SYS_NDIR
3848 #include <sys_ndir.h>
3849 #endif
3850 "I_SYS_STATFS"
3852 This symbol, if defined, indicates that sys/statfs.h exists.
3853 #ifdef I_SYS_STATFS
3855 #include <sys_statfs.h>
3856 #endif
3857 "LSEEKSIZE"
3859 This symbol holds the number of bytes used by the "Off_t".
3860 "RD_NODATA"
3862 This symbol holds the return code from "read()" when no data is
3863 present on the non-blocking file descriptor. Be careful! If
3864 "EOF_NONBLOCK" is not defined, then you can't distinguish between
3865 no data and "EOF" by issuing a "read()". You'll have to find
3866 another way to tell for sure!
3867 "READDIR64_R_PROTO"
3869 This symbol encodes the prototype of "readdir64_r". It is zero if
3870 "d_readdir64_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
3871 macros of reentr.h if "d_readdir64_r" is defined.
3872 "STDCHAR"
3874 This symbol is defined to be the type of char used in stdio.h. It
3875 has the values "unsigned char" or "char".
3876 "STDIO_CNT_LVALUE"
3878 This symbol is defined if the "FILE_cnt" macro can be used as an
3879 lvalue.
3880 "STDIO_PTR_LVALUE"
3882 This symbol is defined if the "FILE_ptr" macro can be used as an
3883 lvalue.
3884 "STDIO_PTR_LVAL_NOCHANGE_CNT"
3886 This symbol is defined if using the "FILE_ptr" macro as an lvalue
3887 to increase the pointer by n leaves "File_cnt(fp)" unchanged.
3888 "STDIO_PTR_LVAL_SETS_CNT"
3890 This symbol is defined if using the "FILE_ptr" macro as an lvalue
3891 to increase the pointer by n has the side effect of decreasing the
3892 value of "File_cnt(fp)" by n.
3893 "STDIO_STREAM_ARRAY"
3895 This symbol tells the name of the array holding the stdio streams.
3896 Usual values include "_iob", "__iob", and "__sF".
3897 "ST_INO_SIGN"
3899 This symbol holds the signedness of "struct stat"'s "st_ino". 1
3900 for unsigned, -1 for signed.
3901 "ST_INO_SIZE"
3903 This variable contains the size of "struct stat"'s "st_ino" in
3904 bytes.
3905 "VAL_EAGAIN"
3907 This symbol holds the errno error code set by "read()" when no data
3908 was present on the non-blocking file descriptor.
3909 "VAL_O_NONBLOCK"
3911 This symbol is to be used during "open()" or "fcntl(F_SETFL)" to
3912 turn on non-blocking I/O for the file descriptor. Note that there
3913 is no way back, i.e. you cannot turn it blocking again this way. If
3914 you wish to alternatively switch between blocking and non-blocking,
3915 use the "ioctl(FIOSNBIO)" call instead, but that is not supported
3916 by all devices.
3917 "VOID_CLOSEDIR"
3919 This symbol, if defined, indicates that the "closedir()" routine
3920 does not return a value.
3921
3923 Also "List of capability HAS_foo symbols" lists capabilities that arent
3924 in this section. For example "HAS_ASINH", for the hyperbolic sine
3925 function.
3926 "CASTFLAGS"
3928 This symbol contains flags that say what difficulties the compiler
3929 has casting odd floating values to unsigned long:
3930 0 = ok
3932 1 = couldn't cast < 0
3933 2 = couldn't cast >= 0x80000000
3934 4 = couldn't cast in argument expression list
3935 "CASTNEGFLOAT"
3937 This symbol is defined if the C compiler can cast negative numbers
3938 to unsigned longs, ints and shorts.
3939 "DOUBLE_HAS_INF"
3941 This symbol, if defined, indicates that the double has the
3942 infinity.
3943 "DOUBLE_HAS_NAN"
3945 This symbol, if defined, indicates that the double has the not-a-
3946 number.
3947 "DOUBLE_HAS_NEGATIVE_ZERO"
3949 This symbol, if defined, indicates that the double has the
3950 "negative_zero".
3951 "DOUBLE_HAS_SUBNORMALS"
3953 This symbol, if defined, indicates that the double has the
3954 subnormals (denormals).
3955 "DOUBLEINFBYTES"
3957 This symbol, if defined, is a comma-separated list of hexadecimal
3958 bytes for the double precision infinity.
3959 "DOUBLEKIND"
3961 "DOUBLEKIND" will be one of
3962 "DOUBLE_IS_IEEE_754_32_BIT_LITTLE_ENDIAN"
3963 "DOUBLE_IS_IEEE_754_32_BIT_BIG_ENDIAN"
3964 "DOUBLE_IS_IEEE_754_64_BIT_LITTLE_ENDIAN"
3965 "DOUBLE_IS_IEEE_754_64_BIT_BIG_ENDIAN"
3966 "DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN"
3967 "DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN"
3968 "DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_LE_BE"
3969 "DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_BE_LE"
3970 "DOUBLE_IS_VAX_F_FLOAT" "DOUBLE_IS_VAX_D_FLOAT"
3971 "DOUBLE_IS_VAX_G_FLOAT" "DOUBLE_IS_IBM_SINGLE_32_BIT"
3972 "DOUBLE_IS_IBM_DOUBLE_64_BIT" "DOUBLE_IS_CRAY_SINGLE_64_BIT"
3973 "DOUBLE_IS_UNKNOWN_FORMAT"
3974 "DOUBLEMANTBITS"
3976 This symbol, if defined, tells how many mantissa bits there are in
3977 double precision floating point format. Note that this is usually
3978 "DBL_MANT_DIG" minus one, since with the standard "IEEE" 754
3979 formats "DBL_MANT_DIG" includes the implicit bit, which doesn't
3980 really exist.
3981 "DOUBLENANBYTES"
3983 This symbol, if defined, is a comma-separated list of hexadecimal
3984 bytes (0xHH) for the double precision not-a-number.
3985 "DOUBLESIZE"
3987 This symbol contains the size of a double, so that the C
3988 preprocessor can make decisions based on it.
3989 "DOUBLE_STYLE_CRAY"
3991 This symbol, if defined, indicates that the double is the 64-bit
3992 "CRAY" mainframe format.
3993 "DOUBLE_STYLE_IBM"
3995 This symbol, if defined, indicates that the double is the 64-bit
3996 "IBM" mainframe format.
3997 "DOUBLE_STYLE_IEEE"
3999 This symbol, if defined, indicates that the double is the 64-bit
4000 "IEEE" 754.
4001 "DOUBLE_STYLE_VAX"
4003 This symbol, if defined, indicates that the double is the 64-bit
4004 "VAX" format D or G.
4005 "HAS_ATOLF"
4007 This symbol, if defined, indicates that the "atolf" routine is
4008 available to convert strings into long doubles.
4009 "HAS_CLASS"
4011 This symbol, if defined, indicates that the "class" routine is
4012 available to classify doubles. Available for example in "AIX".
4013 The returned values are defined in float.h and are:
4014 FP_PLUS_NORM Positive normalized, nonzero
4016 FP_MINUS_NORM Negative normalized, nonzero
4017 FP_PLUS_DENORM Positive denormalized, nonzero
4018 FP_MINUS_DENORM Negative denormalized, nonzero
4019 FP_PLUS_ZERO +0.0
4020 FP_MINUS_ZERO -0.0
4021 FP_PLUS_INF +INF
4022 FP_MINUS_INF -INF
4023 FP_NANS Signaling Not a Number (NaNS)
4024 FP_NANQ Quiet Not a Number (NaNQ)
4025 "HAS_FINITE"
4027 This symbol, if defined, indicates that the "finite" routine is
4028 available to check whether a double is "finite" (non-infinity non-
4029 NaN).
4030 "HAS_FINITEL"
4032 This symbol, if defined, indicates that the "finitel" routine is
4033 available to check whether a long double is finite (non-infinity
4034 non-NaN).
4035 "HAS_FPCLASS"
4037 This symbol, if defined, indicates that the "fpclass" routine is
4038 available to classify doubles. Available for example in
4039 Solaris/"SVR4". The returned values are defined in ieeefp.h and
4040 are:
4041 FP_SNAN signaling NaN
4043 FP_QNAN quiet NaN
4044 FP_NINF negative infinity
4045 FP_PINF positive infinity
4046 FP_NDENORM negative denormalized non-zero
4047 FP_PDENORM positive denormalized non-zero
4048 FP_NZERO negative zero
4049 FP_PZERO positive zero
4050 FP_NNORM negative normalized non-zero
4051 FP_PNORM positive normalized non-zero
4052 "HAS_FPCLASSIFY"
4054 This symbol, if defined, indicates that the "fpclassify" routine is
4055 available to classify doubles. Available for example in HP-UX.
4056 The returned values are defined in math.h and are
4057 FP_NORMAL Normalized
4059 FP_ZERO Zero
4060 FP_INFINITE Infinity
4061 FP_SUBNORMAL Denormalized
4062 FP_NAN NaN
4063 "HAS_FPCLASSL"
4065 This symbol, if defined, indicates that the "fpclassl" routine is
4066 available to classify long doubles. Available for example in
4067 "IRIX". The returned values are defined in ieeefp.h and are:
4068 FP_SNAN signaling NaN
4070 FP_QNAN quiet NaN
4071 FP_NINF negative infinity
4072 FP_PINF positive infinity
4073 FP_NDENORM negative denormalized non-zero
4074 FP_PDENORM positive denormalized non-zero
4075 FP_NZERO negative zero
4076 FP_PZERO positive zero
4077 FP_NNORM negative normalized non-zero
4078 FP_PNORM positive normalized non-zero
4079 "HAS_FPGETROUND"
4081 This symbol, if defined, indicates that the "fpgetround" routine is
4082 available to get the floating point rounding mode.
4083 "HAS_FP_CLASS"
4085 This symbol, if defined, indicates that the "fp_class" routine is
4086 available to classify doubles. Available for example in Digital
4087 "UNIX". The returned values are defined in math.h and are:
4088 FP_SNAN Signaling NaN (Not-a-Number)
4090 FP_QNAN Quiet NaN (Not-a-Number)
4091 FP_POS_INF +infinity
4092 FP_NEG_INF -infinity
4093 FP_POS_NORM Positive normalized
4094 FP_NEG_NORM Negative normalized
4095 FP_POS_DENORM Positive denormalized
4096 FP_NEG_DENORM Negative denormalized
4097 FP_POS_ZERO +0.0 (positive zero)
4098 FP_NEG_ZERO -0.0 (negative zero)
4099 "HAS_FP_CLASSIFY"
4101 This symbol, if defined, indicates that the "fp_classify" routine
4102 is available to classify doubles. The values are defined in math.h
4103 FP_NORMAL Normalized
4105 FP_ZERO Zero
4106 FP_INFINITE Infinity
4107 FP_SUBNORMAL Denormalized
4108 FP_NAN NaN
4109 "HAS_FP_CLASSL"
4111 This symbol, if defined, indicates that the "fp_classl" routine is
4112 available to classify long doubles. Available for example in
4113 Digital "UNIX". See for possible values "HAS_FP_CLASS".
4114 "HAS_FREXPL"
4116 This symbol, if defined, indicates that the "frexpl" routine is
4117 available to break a long double floating-point number into a
4118 normalized fraction and an integral power of 2.
4119 "HAS_ILOGB"
4121 This symbol, if defined, indicates that the "ilogb" routine is
4122 available to get integer exponent of a floating-point value.
4123 "HAS_ISFINITE"
4125 This symbol, if defined, indicates that the "isfinite" routine is
4126 available to check whether a double is finite (non-infinity non-
4127 NaN).
4128 "HAS_ISFINITEL"
4130 This symbol, if defined, indicates that the "isfinitel" routine is
4131 available to check whether a long double is finite. (non-infinity
4132 non-NaN).
4133 "HAS_ISINF"
4135 This symbol, if defined, indicates that the "isinf" routine is
4136 available to check whether a double is an infinity.
4137 "HAS_ISINFL"
4139 This symbol, if defined, indicates that the "isinfl" routine is
4140 available to check whether a long double is an infinity.
4141 "HAS_ISNAN"
4143 This symbol, if defined, indicates that the "isnan" routine is
4144 available to check whether a double is a NaN.
4145 "HAS_ISNANL"
4147 This symbol, if defined, indicates that the "isnanl" routine is
4148 available to check whether a long double is a NaN.
4149 "HAS_ISNORMAL"
4151 This symbol, if defined, indicates that the "isnormal" routine is
4152 available to check whether a double is normal (non-zero
4153 normalized).
4154 "HAS_J0"
4156 This symbol, if defined, indicates to the C program that the "j0()"
4157 function is available for Bessel functions of the first kind of the
4158 order zero, for doubles.
4159 "HAS_J0L"
4161 This symbol, if defined, indicates to the C program that the
4162 "j0l()" function is available for Bessel functions of the first
4163 kind of the order zero, for long doubles.
4164 "HAS_LDBL_DIG"
4166 This symbol, if defined, indicates that this system's float.h or
4167 limits.h defines the symbol "LDBL_DIG", which is the number of
4168 significant digits in a long double precision number. Unlike for
4169 "DBL_DIG", there's no good guess for "LDBL_DIG" if it is undefined.
4170 "HAS_LDEXPL"
4172 This symbol, if defined, indicates that the "ldexpl" routine is
4173 available to shift a long double floating-point number by an
4174 integral power of 2.
4175 "HAS_LLRINT"
4177 This symbol, if defined, indicates that the "llrint" routine is
4178 available to return the long long value closest to a double
4179 (according to the current rounding mode).
4180 "HAS_LLRINTL"
4182 This symbol, if defined, indicates that the "llrintl" routine is
4183 available to return the long long value closest to a long double
4184 (according to the current rounding mode).
4185 "HAS_LLROUNDL"
4187 This symbol, if defined, indicates that the "llroundl" routine is
4188 available to return the nearest long long value away from zero of
4189 the long double argument value.
4190 "HAS_LONG_DOUBLE"
4192 This symbol will be defined if the C compiler supports long
4193 doubles.
4194 "HAS_LRINT"
4196 This symbol, if defined, indicates that the "lrint" routine is
4197 available to return the integral value closest to a double
4198 (according to the current rounding mode).
4199 "HAS_LRINTL"
4201 This symbol, if defined, indicates that the "lrintl" routine is
4202 available to return the integral value closest to a long double
4203 (according to the current rounding mode).
4204 "HAS_LROUNDL"
4206 This symbol, if defined, indicates that the "lroundl" routine is
4207 available to return the nearest integral value away from zero of
4208 the long double argument value.
4209 "HAS_MODFL"
4211 This symbol, if defined, indicates that the "modfl" routine is
4212 available to split a long double x into a fractional part f and an
4213 integer part i such that |f| < 1.0 and (f + i) = x.
4214 "HAS_NAN"
4216 This symbol, if defined, indicates that the "nan" routine is
4217 available to generate NaN.
4218 "HAS_NEXTTOWARD"
4220 This symbol, if defined, indicates that the "nexttoward" routine is
4221 available to return the next machine representable long double from
4222 x in direction y.
4223 "HAS_REMAINDER"
4225 This symbol, if defined, indicates that the "remainder" routine is
4226 available to return the floating-point "remainder".
4227 "HAS_SCALBN"
4229 This symbol, if defined, indicates that the "scalbn" routine is
4230 available to multiply floating-point number by integral power of
4231 radix.
4232 "HAS_SIGNBIT"
4234 This symbol, if defined, indicates that the "signbit" routine is
4235 available to check if the given number has the sign bit set. This
4236 should include correct testing of -0.0. This will only be set if
4237 the "signbit()" routine is safe to use with the NV type used
4238 internally in perl. Users should call "Perl_signbit()", which will
4239 be #defined to the system's "signbit()" function or macro if this
4240 symbol is defined.
4241 "HAS_SQRTL"
4243 This symbol, if defined, indicates that the "sqrtl" routine is
4244 available to do long double square roots.
4245 "HAS_STRTOD_L"
4247 This symbol, if defined, indicates that the "strtod_l" routine is
4248 available to convert strings to long doubles.
4249 "HAS_STRTOLD"
4251 This symbol, if defined, indicates that the "strtold" routine is
4252 available to convert strings to long doubles.
4253 "HAS_STRTOLD_L"
4255 This symbol, if defined, indicates that the "strtold_l" routine is
4256 available to convert strings to long doubles.
4257 "HAS_TRUNC"
4259 This symbol, if defined, indicates that the "trunc" routine is
4260 available to round doubles towards zero.
4261 "HAS_UNORDERED"
4263 This symbol, if defined, indicates that the "unordered" routine is
4264 available to check whether two doubles are "unordered"
4265 (effectively: whether either of them is NaN)
4266 "I_FENV"
4268 This symbol, if defined, indicates to the C program that it should
4269 include fenv.h to get the floating point environment definitions.
4270 #ifdef I_FENV
4272 #include <fenv.h>
4273 #endif
4274 "I_QUADMATH"
4276 This symbol, if defined, indicates that quadmath.h exists and
4277 should be included.
4278 #ifdef I_QUADMATH
4280 #include <quadmath.h>
4281 #endif
4282 "LONGDBLINFBYTES"
4284 This symbol, if defined, is a comma-separated list of hexadecimal
4285 bytes for the long double precision infinity.
4286 "LONGDBLMANTBITS"
4288 This symbol, if defined, tells how many mantissa bits there are in
4289 long double precision floating point format. Note that this can be
4290 "LDBL_MANT_DIG" minus one, since "LDBL_MANT_DIG" can include the
4291 "IEEE" 754 implicit bit. The common x86-style 80-bit long double
4292 does not have an implicit bit.
4293 "LONGDBLNANBYTES"
4295 This symbol, if defined, is a comma-separated list of hexadecimal
4296 bytes (0xHH) for the long double precision not-a-number.
4297 "LONG_DOUBLEKIND"
4299 "LONG_DOUBLEKIND" will be one of "LONG_DOUBLE_IS_DOUBLE"
4300 "LONG_DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN"
4301 "LONG_DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN"
4302 "LONG_DOUBLE_IS_X86_80_BIT_LITTLE_ENDIAN"
4303 "LONG_DOUBLE_IS_X86_80_BIT_BIG_ENDIAN"
4304 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_LE"
4305 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_BE"
4306 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_BE"
4307 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_LE"
4308 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LITTLE_ENDIAN"
4309 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BIG_ENDIAN"
4310 "LONG_DOUBLE_IS_VAX_H_FLOAT" "LONG_DOUBLE_IS_UNKNOWN_FORMAT" It is
4311 only defined if the system supports long doubles.
4312 "LONG_DOUBLESIZE"
4314 This symbol contains the size of a long double, so that the C
4315 preprocessor can make decisions based on it. It is only defined if
4316 the system supports long doubles. Note that this is "sizeof(long
4317 double)", which may include unused bytes.
4318 "LONG_DOUBLE_STYLE_IEEE"
4320 This symbol, if defined, indicates that the long double is any of
4321 the "IEEE" 754 style long doubles: "LONG_DOUBLE_STYLE_IEEE_STD",
4322 "LONG_DOUBLE_STYLE_IEEE_EXTENDED",
4323 "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE".
4324 "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
4326 This symbol, if defined, indicates that the long double is the
4327 128-bit double-double.
4328 "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
4330 This symbol, if defined, indicates that the long double is the
4331 80-bit "IEEE" 754. Note that despite the 'extended' this is less
4332 than the 'std', since this is an extension of the double precision.
4333 "LONG_DOUBLE_STYLE_IEEE_STD"
4335 This symbol, if defined, indicates that the long double is the
4336 128-bit "IEEE" 754.
4337 "LONG_DOUBLE_STYLE_VAX"
4339 This symbol, if defined, indicates that the long double is the
4340 128-bit "VAX" format H.
4341 "NV"
4343 Described in perlguts.
4344 "NVMANTBITS"
4346 This symbol, if defined, tells how many mantissa bits (not
4347 including implicit bit) there are in a Perl NV. This depends on
4348 which floating point type was chosen.
4349 "NV_OVERFLOWS_INTEGERS_AT"
4351 This symbol gives the largest integer value that NVs can hold. This
4352 value + 1.0 cannot be stored accurately. It is expressed as
4353 constant floating point expression to reduce the chance of
4354 decimal/binary conversion issues. If it can not be determined, the
4355 value 0 is given.
4356 "NV_PRESERVES_UV"
4358 This symbol, if defined, indicates that a variable of type "NVTYPE"
4359 can preserve all the bits of a variable of type "UVTYPE".
4360 "NV_PRESERVES_UV_BITS"
4362 This symbol contains the number of bits a variable of type "NVTYPE"
4363 can preserve of a variable of type "UVTYPE".
4364 "NVSIZE"
4366 This symbol contains the "sizeof(NV)". Note that some floating
4367 point formats have unused bytes. The most notable example is the
4368 x86* 80-bit extended precision which comes in byte sizes of 12 and
4369 16 (for 32 and 64 bit platforms, respectively), but which only uses
4370 10 bytes. Perl compiled with "-Duselongdouble" on x86* is like
4371 this.
4372 "NVTYPE"
4374 This symbol defines the C type used for Perl's NV.
4375 "NV_ZERO_IS_ALLBITS_ZERO"
4377 This symbol, if defined, indicates that a variable of type "NVTYPE"
4378 stores 0.0 in memory as all bits zero.
4379
4381 This section contains configuration information not otherwise found in
4382 the more specialized sections of this document. At the end is a list
4383 of "#defines" whose name should be enough to tell you what they do, and
4384 a list of #defines which tell you if you need to "#include" files to
4385 get the corresponding functionality.
4386 "BYTEORDER"
4388 This symbol holds the hexadecimal constant defined in byteorder, in
4389 a UV, i.e. 0x1234 or 0x4321 or 0x12345678, etc... If the compiler
4390 supports cross-compiling or multiple-architecture binaries, use
4391 compiler-defined macros to determine the byte order.
4392 "CHARBITS"
4394 This symbol contains the size of a char, so that the C preprocessor
4395 can make decisions based on it.
4396 "DB_VERSION_MAJOR_CFG"
4398 This symbol, if defined, defines the major version number of
4399 Berkeley DB found in the db.h header when Perl was configured.
4400 "DB_VERSION_MINOR_CFG"
4402 This symbol, if defined, defines the minor version number of
4403 Berkeley DB found in the db.h header when Perl was configured. For
4404 DB version 1 this is always 0.
4405 "DB_VERSION_PATCH_CFG"
4407 This symbol, if defined, defines the patch version number of
4408 Berkeley DB found in the db.h header when Perl was configured. For
4409 DB version 1 this is always 0.
4410 "DEFAULT_INC_EXCLUDES_DOT"
4412 This symbol, if defined, removes the legacy default behavior of
4413 including '.' at the end of @"INC".
4414 "DLSYM_NEEDS_UNDERSCORE"
4416 This symbol, if defined, indicates that we need to prepend an
4417 underscore to the symbol name before calling "dlsym()". This only
4418 makes sense if you *have* dlsym, which we will presume is the case
4419 if you're using dl_dlopen.xs.
4420 "EBCDIC"
4422 This symbol, if defined, indicates that this system uses "EBCDIC"
4423 encoding.
4424 "HAS_CSH"
4426 This symbol, if defined, indicates that the C-shell exists.
4427 "HAS_GETHOSTNAME"
4429 This symbol, if defined, indicates that the C program may use the
4430 "gethostname()" routine to derive the host name. See also
4431 "HAS_UNAME" and "PHOSTNAME".
4432 "HAS_GNULIBC"
4434 This symbol, if defined, indicates to the C program that the "GNU"
4435 C library is being used. A better check is to use the "__GLIBC__"
4436 and "__GLIBC_MINOR__" symbols supplied with glibc.
4437 "HAS_LGAMMA"
4439 This symbol, if defined, indicates that the "lgamma" routine is
4440 available to do the log gamma function. See also "HAS_TGAMMA" and
4441 "HAS_LGAMMA_R".
4442 "HAS_LGAMMA_R"
4444 This symbol, if defined, indicates that the "lgamma_r" routine is
4445 available to do the log gamma function without using the global
4446 signgam variable.
4447 "HAS_NON_INT_BITFIELDS"
4449 This symbol, if defined, indicates that the C compiler accepts,
4450 without error or warning, "struct bitfields" that are declared with
4451 sizes other than plain 'int'; for example 'unsigned char' is
4452 accepted.
4453 "HAS_PRCTL_SET_NAME"
4455 This symbol, if defined, indicates that the prctl routine is
4456 available to set process title and supports "PR_SET_NAME".
4457 "HAS_PROCSELFEXE"
4459 This symbol is defined if "PROCSELFEXE_PATH" is a symlink to the
4460 absolute pathname of the executing program.
4461 "HAS_PSEUDOFORK"
4463 This symbol, if defined, indicates that an emulation of the fork
4464 routine is available.
4465 "HAS_REGCOMP"
4467 This symbol, if defined, indicates that the "regcomp()" routine is
4468 available to do some regular pattern matching (usually on "POSIX".2
4469 conforming systems).
4470 "HAS_SETPGID"
4472 This symbol, if defined, indicates that the "setpgid(pid, gpid)"
4473 routine is available to set process group ID.
4474 "HAS_SIGSETJMP"
4476 This variable indicates to the C program that the "sigsetjmp()"
4477 routine is available to save the calling process's registers and
4478 stack environment for later use by "siglongjmp()", and to
4479 optionally save the process's signal mask. See "Sigjmp_buf",
4480 "Sigsetjmp", and "Siglongjmp".
4481 "HAS_STRUCT_CMSGHDR"
4483 This symbol, if defined, indicates that the "struct cmsghdr" is
4484 supported.
4485 "HAS_STRUCT_MSGHDR"
4487 This symbol, if defined, indicates that the "struct msghdr" is
4488 supported.
4489 "HAS_TGAMMA"
4491 This symbol, if defined, indicates that the "tgamma" routine is
4492 available to do the gamma function. See also "HAS_LGAMMA".
4493 "HAS_UNAME"
4495 This symbol, if defined, indicates that the C program may use the
4496 "uname()" routine to derive the host name. See also
4497 "HAS_GETHOSTNAME" and "PHOSTNAME".
4498 "HAS_UNION_SEMUN"
4500 This symbol, if defined, indicates that the "union semun" is
4501 defined by including sys/sem.h. If not, the user code probably
4502 needs to define it as:
4503 union semun {
4505 int val;
4506 struct semid_ds *buf;
4507 unsigned short *array;
4508 }
4509 "I_DIRENT"
4511 This symbol, if defined, indicates to the C program that it should
4512 include dirent.h. Using this symbol also triggers the definition of
4513 the "Direntry_t" define which ends up being '"struct dirent"' or
4514 '"struct direct"' depending on the availability of dirent.h.
4515 #ifdef I_DIRENT
4517 #include <dirent.h>
4518 #endif
4519 "I_POLL"
4521 This symbol, if defined, indicates that poll.h exists and should be
4522 included. (see also "HAS_POLL")
4523 #ifdef I_POLL
4525 #include <poll.h>
4526 #endif
4527 "I_SYS_RESOURCE"
4529 This symbol, if defined, indicates to the C program that it should
4530 include sys/resource.h.
4531 #ifdef I_SYS_RESOURCE
4533 #include <sys_resource.h>
4534 #endif
4535 "LIBM_LIB_VERSION"
4537 This symbol, if defined, indicates that libm exports "_LIB_VERSION"
4538 and that math.h defines the enum to manipulate it.
4539 "NEED_VA_COPY"
4541 This symbol, if defined, indicates that the system stores the
4542 variable argument list datatype, "va_list", in a format that cannot
4543 be copied by simple assignment, so that some other means must be
4544 used when copying is required. As such systems vary in their
4545 provision (or non-provision) of copying mechanisms, handy.h defines
4546 a platform- independent macro, "Perl_va_copy(src, dst)", to do the
4547 job.
4548 "OSNAME"
4550 This symbol contains the name of the operating system, as
4551 determined by Configure. You shouldn't rely on it too much; the
4552 specific feature tests from Configure are generally more reliable.
4553 "OSVERS"
4555 This symbol contains the version of the operating system, as
4556 determined by Configure. You shouldn't rely on it too much; the
4557 specific feature tests from Configure are generally more reliable.
4558 "PHOSTNAME"
4560 This symbol, if defined, indicates the command to feed to the
4561 "popen()" routine to derive the host name. See also
4562 "HAS_GETHOSTNAME" and "HAS_UNAME". Note that the command uses a
4563 fully qualified path, so that it is safe even if used by a process
4564 with super-user privileges.
4565 "PROCSELFEXE_PATH"
4567 If "HAS_PROCSELFEXE" is defined this symbol is the filename of the
4568 symbolic link pointing to the absolute pathname of the executing
4569 program.
4570 "PTRSIZE"
4572 This symbol contains the size of a pointer, so that the C
4573 preprocessor can make decisions based on it. It will be
4574 "sizeof(void *)" if the compiler supports (void *); otherwise it
4575 will be "sizeof(char *)".
4576 "RANDBITS"
4578 This symbol indicates how many bits are produced by the function
4579 used to generate normalized random numbers. Values include 15, 16,
4580 31, and 48.
4581 "SELECT_MIN_BITS"
4583 This symbol holds the minimum number of bits operated by select.
4584 That is, if you do "select(n, ...)", how many bits at least will be
4585 cleared in the masks if some activity is detected. Usually this is
4586 either n or 32*"ceil(n/32)", especially many little-endians do the
4587 latter. This is only useful if you have "select()", naturally.
4588 "SETUID_SCRIPTS_ARE_SECURE_NOW"
4590 This symbol, if defined, indicates that the bug that prevents
4591 setuid scripts from being secure is not present in this kernel.
4592 "ST_DEV_SIGN"
4594 This symbol holds the signedness of "struct stat"'s "st_dev". 1
4595 for unsigned, -1 for signed.
4596 "ST_DEV_SIZE"
4598 This variable contains the size of "struct stat"'s "st_dev" in
4599 bytes.
4600 List of capability "HAS_foo" symbols
4602 This is a list of those symbols that dont appear elsewhere in ths
4603 document that indicate if the current platform has a certain
4604 capability. Their names all begin with "HAS_". Only those symbols
4605 whose capability is directly derived from the name are listed here.
4606 All others have their meaning expanded out elsewhere in this document.
4607 This (relatively) compact list is because we think that the expansion
4608 would add little or no value and take up a lot of space (because there
4609 are so many). If you think certain ones should be expanded, send email
4610 to perl5-porters@perl.org <mailto:perl5-porters@perl.org>.
4611 Each symbol here will be "#define"d if and only if the platform has the
4613 capability. If you need more detail, see the corresponding entry in
4614 config.h. For convenience, the list is split so that the ones that
4615 indicate there is a reentrant version of a capability are listed
4616 separately
4617 "HAS_ACCEPT4", "HAS_ACCESS", "HAS_ACCESSX", "HAS_ACOSH",
4619 "HAS_AINTL", "HAS_ALARM", "HAS_ASINH", "HAS_ATANH", "HAS_ATOLL",
4620 "HAS_CBRT", "HAS_CHOWN", "HAS_CHROOT", "HAS_CHSIZE",
4621 "HAS_CLEARENV", "HAS_COPYSIGN", "HAS_COPYSIGNL", "HAS_CRYPT",
4622 "HAS_CTERMID", "HAS_CUSERID", "HAS_DIRFD", "HAS_DLADDR",
4623 "HAS_DLERROR", "HAS_EACCESS", "HAS_ENDHOSTENT", "HAS_ENDNETENT",
4624 "HAS_ENDPROTOENT", "HAS_ENDSERVENT", "HAS_ERF", "HAS_ERFC",
4625 "HAS_EXP2", "HAS_EXPM1", "HAS_FCHMOD", "HAS_FCHMODAT",
4626 "HAS_FCHOWN", "HAS_FDIM", "HAS_FD_SET", "HAS_FEGETROUND",
4627 "HAS_FFS", "HAS_FFSL", "HAS_FGETPOS", "HAS_FLOCK", "HAS_FMA",
4628 "HAS_FMAX", "HAS_FMIN", "HAS_FORK", "HAS_FSEEKO", "HAS_FSETPOS",
4629 "HAS_FSYNC", "HAS_FTELLO", "HAS_GAI_STRERROR", "HAS_GETADDRINFO",
4630 "HAS_GETCWD", "HAS_GETESPWNAM", "HAS_GETGROUPS",
4631 "HAS_GETHOSTBYADDR", "HAS_GETHOSTBYNAME", "HAS_GETHOSTENT",
4632 "HAS_GETLOGIN", "HAS_GETNAMEINFO", "HAS_GETNETBYADDR",
4633 "HAS_GETNETBYNAME", "HAS_GETNETENT", "HAS_GETPAGESIZE",
4634 "HAS_GETPGID", "HAS_GETPGRP", "HAS_GETPGRP2", "HAS_GETPPID",
4635 "HAS_GETPRIORITY", "HAS_GETPROTOBYNAME", "HAS_GETPROTOBYNUMBER",
4636 "HAS_GETPROTOENT", "HAS_GETPRPWNAM", "HAS_GETSERVBYNAME",
4637 "HAS_GETSERVBYPORT", "HAS_GETSERVENT", "HAS_GETSPNAM", "HAS_HTONL",
4638 "HAS_HTONS", "HAS_HYPOT", "HAS_ILOGBL", "HAS_INETNTOP",
4639 "HAS_INETPTON", "HAS_INET_ATON", "HAS_IPV6_MREQ",
4640 "HAS_IPV6_MREQ_SOURCE", "HAS_IP_MREQ", "HAS_IP_MREQ_SOURCE",
4641 "HAS_ISASCII", "HAS_ISBLANK", "HAS_ISLESS", "HAS_KILLPG",
4642 "HAS_LCHOWN", "HAS_LINK", "HAS_LINKAT", "HAS_LLROUND",
4643 "HAS_LOCKF", "HAS_LOG1P", "HAS_LOG2", "HAS_LOGB", "HAS_LROUND",
4644 "HAS_LSTAT", "HAS_MADVISE", "HAS_MBLEN", "HAS_MBRLEN",
4645 "HAS_MBRTOWC", "HAS_MBSTOWCS", "HAS_MBTOWC", "HAS_MEMMEM",
4646 "HAS_MEMRCHR", "HAS_MKDTEMP", "HAS_MKFIFO", "HAS_MKOSTEMP",
4647 "HAS_MKSTEMP", "HAS_MKSTEMPS", "HAS_MMAP", "HAS_MPROTECT",
4648 "HAS_MSG", "HAS_MSYNC", "HAS_MUNMAP", "HAS_NEARBYINT",
4649 "HAS_NEXTAFTER", "HAS_NICE", "HAS_NTOHL", "HAS_NTOHS",
4650 "HAS_PATHCONF", "HAS_PAUSE", "HAS_PHOSTNAME", "HAS_PIPE",
4651 "HAS_PIPE2", "HAS_PRCTL", "HAS_PTRDIFF_T", "HAS_READLINK",
4652 "HAS_READV", "HAS_RECVMSG", "HAS_REMQUO", "HAS_RENAME",
4653 "HAS_RENAMEAT", "HAS_RINT", "HAS_ROUND", "HAS_SCALBNL", "HAS_SEM",
4654 "HAS_SENDMSG", "HAS_SETEGID", "HAS_SETEUID", "HAS_SETGROUPS",
4655 "HAS_SETHOSTENT", "HAS_SETLINEBUF", "HAS_SETNETENT", "HAS_SETPGRP",
4656 "HAS_SETPGRP2", "HAS_SETPRIORITY", "HAS_SETPROCTITLE",
4657 "HAS_SETPROTOENT", "HAS_SETREGID", "HAS_SETRESGID",
4658 "HAS_SETRESUID", "HAS_SETREUID", "HAS_SETRGID", "HAS_SETRUID",
4659 "HAS_SETSERVENT", "HAS_SETSID", "HAS_SHM", "HAS_SIGACTION",
4660 "HAS_SIGPROCMASK", "HAS_SIN6_SCOPE_ID", "HAS_SNPRINTF", "HAS_STAT",
4661 "HAS_STRCOLL", "HAS_STRERROR_L", "HAS_STRLCAT", "HAS_STRLCPY",
4662 "HAS_STRNLEN", "HAS_STRTOD", "HAS_STRTOL", "HAS_STRTOLL",
4663 "HAS_STRTOQ", "HAS_STRTOUL", "HAS_STRTOULL", "HAS_STRTOUQ",
4664 "HAS_STRXFRM", "HAS_STRXFRM_L", "HAS_SYMLINK", "HAS_SYSCALL",
4665 "HAS_SYSCONF", "HAS_SYSTEM", "HAS_SYS_ERRLIST", "HAS_TCGETPGRP",
4666 "HAS_TCSETPGRP", "HAS_TOWLOWER", "HAS_TOWUPPER", "HAS_TRUNCATE",
4667 "HAS_TRUNCL", "HAS_UALARM", "HAS_UMASK", "HAS_UNLINKAT",
4668 "HAS_UNSETENV", "HAS_VFORK", "HAS_VSNPRINTF", "HAS_WAIT4",
4669 "HAS_WAITPID", "HAS_WCRTOMB", "HAS_WCSCMP", "HAS_WCSTOMBS",
4670 "HAS_WCSXFRM", "HAS_WCTOMB", "HAS_WRITEV", "HAS__FWALK"
4671 And, the reentrant capabilities:
4673 "HAS_CRYPT_R", "HAS_CTERMID_R", "HAS_DRAND48_R",
4675 "HAS_ENDHOSTENT_R", "HAS_ENDNETENT_R", "HAS_ENDPROTOENT_R",
4676 "HAS_ENDSERVENT_R", "HAS_GETGRGID_R", "HAS_GETGRNAM_R",
4677 "HAS_GETHOSTBYADDR_R", "HAS_GETHOSTBYNAME_R", "HAS_GETHOSTENT_R",
4678 "HAS_GETLOGIN_R", "HAS_GETNETBYADDR_R", "HAS_GETNETBYNAME_R",
4679 "HAS_GETNETENT_R", "HAS_GETPROTOBYNAME_R", "HAS_GETPROTOBYNUMBER_R",
4680 "HAS_GETPROTOENT_R", "HAS_GETPWNAM_R", "HAS_GETPWUID_R",
4681 "HAS_GETSERVBYNAME_R", "HAS_GETSERVBYPORT_R", "HAS_GETSERVENT_R",
4682 "HAS_GETSPNAM_R", "HAS_RANDOM_R", "HAS_READDIR_R",
4683 "HAS_SETHOSTENT_R", "HAS_SETNETENT_R", "HAS_SETPROTOENT_R",
4684 "HAS_SETSERVENT_R", "HAS_SRAND48_R", "HAS_SRANDOM_R",
4685 "HAS_STRERROR_R", "HAS_TMPNAM_R", "HAS_TTYNAME_R"
4686 Example usage:
4688 #ifdef HAS_STRNLEN
4690 use strnlen()
4691 #else
4692 use an alternative implementation
4693 #endif
4694 List of "#include" needed symbols
4696 This list contains symbols that indicate if certain "#include" files
4697 are present on the platform. If your code accesses the functionality
4698 that one of these is for, you will need to "#include" it if the symbol
4699 on this list is "#define"d. For more detail, see the corresponding
4700 entry in config.h.
4701 "I_ARPA_INET", "I_BFD", "I_CRYPT", "I_DBM", "I_DLFCN",
4703 "I_EXECINFO", "I_FP", "I_FP_CLASS", "I_GDBM", "I_GDBMNDBM",
4704 "I_GDBM_NDBM", "I_GRP", "I_IEEEFP", "I_INTTYPES", "I_LIBUTIL",
4705 "I_MNTENT", "I_NDBM", "I_NETDB", "I_NETINET_IN", "I_NETINET_TCP",
4706 "I_NET_ERRNO", "I_PROT", "I_PWD", "I_RPCSVC_DBM", "I_SGTTY",
4707 "I_SHADOW", "I_STDBOOL", "I_STDINT", "I_SUNMATH", "I_SYSLOG",
4708 "I_SYSMODE", "I_SYSUIO", "I_SYSUTSNAME", "I_SYS_ACCESS",
4709 "I_SYS_IOCTL", "I_SYS_MOUNT", "I_SYS_PARAM", "I_SYS_POLL",
4710 "I_SYS_SECURITY", "I_SYS_SELECT", "I_SYS_STAT", "I_SYS_STATVFS",
4711 "I_SYS_TIME", "I_SYS_TIMES", "I_SYS_TIME_KERNEL", "I_SYS_TYPES",
4712 "I_SYS_UN", "I_SYS_VFS", "I_SYS_WAIT", "I_TERMIO", "I_TERMIOS",
4713 "I_UNISTD", "I_USTAT", "I_VFORK", "I_WCHAR", "I_WCTYPE"
4714 Example usage:
4716 #ifdef I_WCHAR
4718 #include <wchar.h>
4719 #endif
4720
4722 These variables are global to an entire process. They are shared
4723 between all interpreters and all threads in a process. Any variables
4724 not documented here may be changed or removed without notice, so don't
4725 use them! If you feel you really do need to use an unlisted variable,
4726 first send email to perl5-porters@perl.org
4727 <mailto:perl5-porters@perl.org>. It may be that someone there will
4728 point out a way to accomplish what you need without using an internal
4729 variable. But if not, you should get a go-ahead to document and then
4730 use the variable.
4731 "PL_check"
4733 Array, indexed by opcode, of functions that will be called for the
4734 "check" phase of optree building during compilation of Perl code.
4735 For most (but not all) types of op, once the op has been initially
4736 built and populated with child ops it will be filtered through the
4737 check function referenced by the appropriate element of this array.
4738 The new op is passed in as the sole argument to the check function,
4739 and the check function returns the completed op. The check
4740 function may (as the name suggests) check the op for validity and
4741 signal errors. It may also initialise or modify parts of the ops,
4742 or perform more radical surgery such as adding or removing child
4743 ops, or even throw the op away and return a different op in its
4744 place.
4745 This array of function pointers is a convenient place to hook into
4747 the compilation process. An XS module can put its own custom check
4748 function in place of any of the standard ones, to influence the
4749 compilation of a particular type of op. However, a custom check
4750 function must never fully replace a standard check function (or
4751 even a custom check function from another module). A module
4752 modifying checking must instead wrap the preexisting check
4753 function. A custom check function must be selective about when to
4754 apply its custom behaviour. In the usual case where it decides not
4755 to do anything special with an op, it must chain the preexisting op
4756 function. Check functions are thus linked in a chain, with the
4757 core's base checker at the end.
4758 For thread safety, modules should not write directly to this array.
4760 Instead, use the function "wrap_op_checker".
4761 "PL_keyword_plugin"
4763 NOTE: "PL_keyword_plugin" is experimental and may change or be
4764 removed without notice.
4765 Function pointer, pointing at a function used to handle extended
4767 keywords. The function should be declared as
4768 int keyword_plugin_function(pTHX_
4770 char *keyword_ptr, STRLEN keyword_len,
4771 OP **op_ptr)
4772 The function is called from the tokeniser, whenever a possible
4774 keyword is seen. "keyword_ptr" points at the word in the parser's
4775 input buffer, and "keyword_len" gives its length; it is not null-
4776 terminated. The function is expected to examine the word, and
4777 possibly other state such as %^H, to decide whether it wants to
4778 handle it as an extended keyword. If it does not, the function
4779 should return "KEYWORD_PLUGIN_DECLINE", and the normal parser
4780 process will continue.
4781 If the function wants to handle the keyword, it first must parse
4783 anything following the keyword that is part of the syntax
4784 introduced by the keyword. See "Lexer interface" for details.
4785 When a keyword is being handled, the plugin function must build a
4787 tree of "OP" structures, representing the code that was parsed.
4788 The root of the tree must be stored in *op_ptr. The function then
4789 returns a constant indicating the syntactic role of the construct
4790 that it has parsed: "KEYWORD_PLUGIN_STMT" if it is a complete
4791 statement, or "KEYWORD_PLUGIN_EXPR" if it is an expression. Note
4792 that a statement construct cannot be used inside an expression
4793 (except via "do BLOCK" and similar), and an expression is not a
4794 complete statement (it requires at least a terminating semicolon).
4795 When a keyword is handled, the plugin function may also have
4797 (compile-time) side effects. It may modify "%^H", define
4798 functions, and so on. Typically, if side effects are the main
4799 purpose of a handler, it does not wish to generate any ops to be
4800 included in the normal compilation. In this case it is still
4801 required to supply an op tree, but it suffices to generate a single
4802 null op.
4803 That's how the *PL_keyword_plugin function needs to behave overall.
4805 Conventionally, however, one does not completely replace the
4806 existing handler function. Instead, take a copy of
4807 "PL_keyword_plugin" before assigning your own function pointer to
4808 it. Your handler function should look for keywords that it is
4809 interested in and handle those. Where it is not interested, it
4810 should call the saved plugin function, passing on the arguments it
4811 received. Thus "PL_keyword_plugin" actually points at a chain of
4812 handler functions, all of which have an opportunity to handle
4813 keywords, and only the last function in the chain (built into the
4814 Perl core) will normally return "KEYWORD_PLUGIN_DECLINE".
4815 For thread safety, modules should not set this variable directly.
4817 Instead, use the function "wrap_keyword_plugin".
4818 "PL_phase"
4820 A value that indicates the current Perl interpreter's phase.
4821 Possible values include "PERL_PHASE_CONSTRUCT", "PERL_PHASE_START",
4822 "PERL_PHASE_CHECK", "PERL_PHASE_INIT", "PERL_PHASE_RUN",
4823 "PERL_PHASE_END", and "PERL_PHASE_DESTRUCT".
4824 For example, the following determines whether the interpreter is in
4826 global destruction:
4827 if (PL_phase == PERL_PHASE_DESTRUCT) {
4829 // we are in global destruction
4830 }
4831 "PL_phase" was introduced in Perl 5.14; in prior perls you can use
4833 "PL_dirty" (boolean) to determine whether the interpreter is in
4834 global destruction. (Use of "PL_dirty" is discouraged since 5.14.)
4835 enum perl_phase PL_phase
4837
4839 A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
4840 It is a structure that holds a pointer to a scalar, an array, a hash
4841 etc, corresponding to $foo, @foo, %foo.
4842 GVs are usually found as values in stashes (symbol table hashes) where
4844 Perl stores its global variables.
4845 A stash is a hash that contains all variables that are defined within a
4847 package. See "Stashes and Globs" in perlguts
4848 "amagic_call"
4850 Perform the overloaded (active magic) operation given by "method".
4851 "method" is one of the values found in overload.h.
4852 "flags" affects how the operation is performed, as follows:
4854 "AMGf_noleft"
4856 "left" is not to be used in this operation.
4857 "AMGf_noright"
4859 "right" is not to be used in this operation.
4860 "AMGf_unary"
4862 The operation is done only on just one operand.
4863 "AMGf_assign"
4865 The operation changes one of the operands, e.g., $x += 1
4866 SV* amagic_call(SV* left, SV* right, int method, int dir)
4868 "amagic_deref_call"
4870 Perform "method" overloading dereferencing on "ref", returning the
4871 dereferenced result. "method" must be one of the dereference
4872 operations given in overload.h.
4873 If overloading is inactive on "ref", returns "ref" itself.
4875 SV * amagic_deref_call(SV *ref, int method)
4877 "gv_add_by_type"
4879 Make sure there is a slot of type "type" in the GV "gv".
4880 GV* gv_add_by_type(GV *gv, svtype type)
4882 "Gv_AMupdate"
4884 Recalculates overload magic in the package given by "stash".
4885 Returns:
4887 1 on success and there is some overload
4889 0 if there is no overload
4890 -1 if some error occurred and it couldn't croak (because
4891 "destructing" is true).
4892 int Gv_AMupdate(HV* stash, bool destructing)
4894 "gv_autoload4"
4896 Equivalent to "gv_autoload_pvn".
4897 GV* gv_autoload4(HV* stash, const char* name, STRLEN len,
4899 I32 method)
4900 "GvAV"
4902 Return the AV from the GV.
4903 AV* GvAV(GV* gv)
4905 "gv_AVadd"
4907 "gv_HVadd"
4908 "gv_IOadd"
4909 "gv_SVadd"
4910 Make sure there is a slot of the given type (AV, HV, IO, SV) in the
4911 GV "gv".
4912 GV* gv_AVadd(GV *gv)
4914 GV* gv_HVadd(GV *gv)
4915 GV* gv_IOadd(GV* gv)
4916 GV* gv_SVadd(GV *gv)
4917 "gv_const_sv"
4919 If "gv" is a typeglob whose subroutine entry is a constant sub
4920 eligible for inlining, or "gv" is a placeholder reference that
4921 would be promoted to such a typeglob, then returns the value
4922 returned by the sub. Otherwise, returns "NULL".
4923 SV* gv_const_sv(GV* gv)
4925 "GvCV"
4927 Return the CV from the GV.
4928 CV* GvCV(GV* gv)
4930 "gv_fetchfile"
4932 "gv_fetchfile_flags"
4933 These return the debugger glob for the file (compiled by Perl)
4934 whose name is given by the "name" parameter.
4935 There are currently exactly two differences between these
4937 functions.
4938 The "name" parameter to "gv_fetchfile" is a C string, meaning it is
4940 "NUL"-terminated; whereas the "name" parameter to
4941 "gv_fetchfile_flags" is a Perl string, whose length (in bytes) is
4942 passed in via the "namelen" parameter This means the name may
4943 contain embedded "NUL" characters. "namelen" doesn't exist in
4944 plain "gv_fetchfile").
4945 The other difference is that "gv_fetchfile_flags" has an extra
4947 "flags" parameter, which is currently completely ignored, but
4948 allows for possible future extensions.
4949 GV* gv_fetchfile (const char* name)
4951 GV* gv_fetchfile_flags(const char *const name, const STRLEN len,
4952 const U32 flags)
4953 "gv_fetchmeth"
4955 Like "gv_fetchmeth_pvn", but lacks a flags parameter.
4956 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len,
4958 I32 level)
4959 "gv_fetchmethod"
4961 See "gv_fetchmethod_autoload".
4962 GV* gv_fetchmethod(HV* stash, const char* name)
4964 "gv_fetchmethod_autoload"
4966 Returns the glob which contains the subroutine to call to invoke
4967 the method on the "stash". In fact in the presence of autoloading
4968 this may be the glob for "AUTOLOAD". In this case the
4969 corresponding variable $AUTOLOAD is already setup.
4970 The third parameter of "gv_fetchmethod_autoload" determines whether
4972 AUTOLOAD lookup is performed if the given method is not present:
4973 non-zero means yes, look for AUTOLOAD; zero means no, don't look
4974 for AUTOLOAD. Calling "gv_fetchmethod" is equivalent to calling
4975 "gv_fetchmethod_autoload" with a non-zero "autoload" parameter.
4976 These functions grant "SUPER" token as a prefix of the method name.
4978 Note that if you want to keep the returned glob for a long time,
4979 you need to check for it being "AUTOLOAD", since at the later time
4980 the call may load a different subroutine due to $AUTOLOAD changing
4981 its value. Use the glob created as a side effect to do this.
4982 These functions have the same side-effects as "gv_fetchmeth" with
4984 "level==0". The warning against passing the GV returned by
4985 "gv_fetchmeth" to "call_sv" applies equally to these functions.
4986 GV* gv_fetchmethod_autoload(HV* stash, const char* name,
4988 I32 autoload)
4989 "gv_fetchmeth_autoload"
4991 This is the old form of "gv_fetchmeth_pvn_autoload", which has no
4992 flags parameter.
4993 GV* gv_fetchmeth_autoload(HV* stash, const char* name,
4995 STRLEN len, I32 level)
4996 "gv_fetchmeth_pv"
4998 Exactly like "gv_fetchmeth_pvn", but takes a nul-terminated string
4999 instead of a string/length pair.
5000 GV* gv_fetchmeth_pv(HV* stash, const char* name, I32 level,
5002 U32 flags)
5003 "gv_fetchmeth_pvn"
5005 Returns the glob with the given "name" and a defined subroutine or
5006 "NULL". The glob lives in the given "stash", or in the stashes
5007 accessible via @ISA and "UNIVERSAL::".
5008 The argument "level" should be either 0 or -1. If "level==0", as a
5010 side-effect creates a glob with the given "name" in the given
5011 "stash" which in the case of success contains an alias for the
5012 subroutine, and sets up caching info for this glob.
5013 The only significant values for "flags" are "GV_SUPER",
5015 "GV_NOUNIVERSAL", and "SVf_UTF8".
5016 "GV_SUPER" indicates that we want to look up the method in the
5018 superclasses of the "stash".
5019 "GV_NOUNIVERSAL" indicates that we do not want to look up the
5021 method in the stash accessible by "UNIVERSAL::".
5022 The GV returned from "gv_fetchmeth" may be a method cache entry,
5024 which is not visible to Perl code. So when calling "call_sv", you
5025 should not use the GV directly; instead, you should use the
5026 method's CV, which can be obtained from the GV with the "GvCV"
5027 macro.
5028 GV* gv_fetchmeth_pvn(HV* stash, const char* name, STRLEN len,
5030 I32 level, U32 flags)
5031 "gv_fetchmeth_pvn_autoload"
5033 Same as "gv_fetchmeth_pvn()", but looks for autoloaded subroutines
5034 too. Returns a glob for the subroutine.
5035 For an autoloaded subroutine without a GV, will create a GV even if
5037 "level < 0". For an autoloaded subroutine without a stub, "GvCV()"
5038 of the result may be zero.
5039 Currently, the only significant value for "flags" is "SVf_UTF8".
5041 GV* gv_fetchmeth_pvn_autoload(HV* stash, const char* name,
5043 STRLEN len, I32 level, U32 flags)
5044 "gv_fetchmeth_pv_autoload"
5046 Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-
5047 terminated string instead of a string/length pair.
5048 GV* gv_fetchmeth_pv_autoload(HV* stash, const char* name,
5050 I32 level, U32 flags)
5051 "gv_fetchmeth_sv"
5053 Exactly like "gv_fetchmeth_pvn", but takes the name string in the
5054 form of an SV instead of a string/length pair.
5055 GV* gv_fetchmeth_sv(HV* stash, SV* namesv, I32 level, U32 flags)
5057 "gv_fetchmeth_sv_autoload"
5059 Exactly like "gv_fetchmeth_pvn_autoload", but takes the name string
5060 in the form of an SV instead of a string/length pair.
5061 GV* gv_fetchmeth_sv_autoload(HV* stash, SV* namesv, I32 level,
5063 U32 flags)
5064 "gv_fetchpv"
5066 "gv_fetchpvn"
5067 "gv_fetchpvn_flags"
5068 "gv_fetchpvs"
5069 "gv_fetchsv"
5070 "gv_fetchsv_nomg"
5071 These all return the GV of type "sv_type" whose name is given by
5072 the inputs, or NULL if no GV of that name and type could be found.
5073 See "Stashes and Globs" in perlguts.
5074 The only differences are how the input name is specified, and if
5076 'get' magic is normally used in getting that name.
5077 Don't be fooled by the fact that only one form has "flags" in its
5079 name. They all have a "flags" parameter in fact, and all the flag
5080 bits have the same meanings for all
5081 If any of the flags "GV_ADD", "GV_ADDMG", "GV_ADDWARN",
5083 "GV_ADDMULTI", or "GV_NOINIT" is set, a GV is created if none
5084 already exists for the input name and type. However, "GV_ADDMG"
5085 will only do the creation for magical GV's. For all of these flags
5086 except "GV_NOINIT", "gv_init_pvn" is called after the addition.
5087 "GV_ADDWARN" is used when the caller expects that adding won't be
5088 necessary because the symbol should already exist; but if not, add
5089 it anyway, with a warning that it was unexpectedly absent. The
5090 "GV_ADDMULTI" flag means to pretend that the GV has been seen
5091 before (i.e., suppress "Used once" warnings).
5092 The flag "GV_NOADD_NOINIT" causes "gv_init_pvn" not be to called if
5094 the GV existed but isn't PVGV.
5095 If the "SVf_UTF8" bit is set, the name is treated as being encoded
5097 in UTF-8; otherwise the name won't be considered to be UTF-8 in the
5098 "pv"-named forms, and the UTF-8ness of the underlying SVs will be
5099 used in the "sv" forms.
5100 If the flag "GV_NOTQUAL" is set, the caller warrants that the input
5102 name is a plain symbol name, not qualified with a package,
5103 otherwise the name is checked for being a qualified one.
5104 In "gv_fetchpv", "nambeg" is a C string, NUL-terminated with no
5106 intermediate NULs.
5107 In "gv_fetchpvs", "name" is a literal C string, hence is enclosed
5109 in double quotes.
5110 "gv_fetchpvn" and "gv_fetchpvn_flags" are identical. In these,
5112 <nambeg> is a Perl string whose byte length is given by "full_len",
5113 and may contain embedded NULs.
5114 In "gv_fetchsv" and "gv_fetchsv_nomg", the name is extracted from
5116 the PV of the input "name" SV. The only difference between these
5117 two forms is that 'get' magic is normally done on "name" in
5118 "gv_fetchsv", and always skipped with "gv_fetchsv_nomg". Including
5119 "GV_NO_SVGMAGIC" in the "flags" parameter to "gv_fetchsv" makes it
5120 behave identically to "gv_fetchsv_nomg".
5121 GV* gv_fetchpv (const char *nambeg, I32 flags,
5123 const svtype sv_type)
5124 GV * gv_fetchpvn (const char * nambeg, STRLEN full_len,
5125 I32 flags, const svtype sv_type)
5126 GV* gv_fetchpvn_flags(const char* name, STRLEN len, I32 flags,
5127 const svtype sv_type)
5128 GV * gv_fetchpvs ("name", I32 flags, const svtype sv_type)
5129 GV* gv_fetchsv (SV *name, I32 flags, const svtype sv_type)
5130 GV * gv_fetchsv_nomg (SV *name, I32 flags, const svtype sv_type)
5131 "gv_fullname3"
5133 "gv_fullname4"
5134 "gv_efullname3"
5135 "gv_efullname4"
5136 Place the full package name of "gv" into "sv". The "gv_e*" forms
5137 return instead the effective package name (see "HvENAME").
5138 If "prefix" is non-NULL, it is considered to be a C language NUL-
5140 terminated string, and the stored name will be prefaced with it.
5141 The other difference between the functions is that the *4 forms
5143 have an extra parameter, "keepmain". If "true" an initial "main::"
5144 in the name is kept; if "false" it is stripped. With the *3 forms,
5145 it is always kept.
5146 void gv_fullname3 (SV* sv, const GV* gv, const char* prefix)
5148 void gv_fullname4 (SV* sv, const GV* gv, const char* prefix,
5149 bool keepmain)
5150 void gv_efullname3(SV* sv, const GV* gv, const char* prefix)
5151 void gv_efullname4(SV* sv, const GV* gv, const char* prefix,
5152 bool keepmain)
5153 "GvHV"
5155 Return the HV from the GV.
5156 HV* GvHV(GV* gv)
5158 "gv_init"
5160 The old form of "gv_init_pvn()". It does not work with UTF-8
5161 strings, as it has no flags parameter. If the "multi" parameter is
5162 set, the "GV_ADDMULTI" flag will be passed to "gv_init_pvn()".
5163 void gv_init(GV* gv, HV* stash, const char* name, STRLEN len,
5165 int multi)
5166 "gv_init_pv"
5168 Same as "gv_init_pvn()", but takes a nul-terminated string for the
5169 name instead of separate char * and length parameters.
5170 void gv_init_pv(GV* gv, HV* stash, const char* name, U32 flags)
5172 "gv_init_pvn"
5174 Converts a scalar into a typeglob. This is an incoercible
5175 typeglob; assigning a reference to it will assign to one of its
5176 slots, instead of overwriting it as happens with typeglobs created
5177 by "SvSetSV". Converting any scalar that is "SvOK()" may produce
5178 unpredictable results and is reserved for perl's internal use.
5179 "gv" is the scalar to be converted.
5181 "stash" is the parent stash/package, if any.
5183 "name" and "len" give the name. The name must be unqualified; that
5185 is, it must not include the package name. If "gv" is a stash
5186 element, it is the caller's responsibility to ensure that the name
5187 passed to this function matches the name of the element. If it
5188 does not match, perl's internal bookkeeping will get out of sync.
5189 "flags" can be set to "SVf_UTF8" if "name" is a UTF-8 string, or
5191 the return value of SvUTF8(sv). It can also take the "GV_ADDMULTI"
5192 flag, which means to pretend that the GV has been seen before
5193 (i.e., suppress "Used once" warnings).
5194 void gv_init_pvn(GV* gv, HV* stash, const char* name, STRLEN len,
5196 U32 flags)
5197 "gv_init_sv"
5199 Same as "gv_init_pvn()", but takes an SV * for the name instead of
5200 separate char * and length parameters. "flags" is currently
5201 unused.
5202 void gv_init_sv(GV* gv, HV* stash, SV* namesv, U32 flags)
5204 "gv_stashpv"
5206 Returns a pointer to the stash for a specified package. Uses
5207 "strlen" to determine the length of "name", then calls
5208 "gv_stashpvn()".
5209 HV* gv_stashpv(const char* name, I32 flags)
5211 "gv_stashpvn"
5213 Returns a pointer to the stash for a specified package. The
5214 "namelen" parameter indicates the length of the "name", in bytes.
5215 "flags" is passed to "gv_fetchpvn_flags()", so if set to "GV_ADD"
5216 then the package will be created if it does not already exist. If
5217 the package does not exist and "flags" is 0 (or any other setting
5218 that does not create packages) then "NULL" is returned.
5219 Flags may be one of:
5221 GV_ADD Create and initialize the package if doesn't
5223 already exist
5224 GV_NOADD_NOINIT Don't create the package,
5225 GV_ADDMG GV_ADD iff the GV is magical
5226 GV_NOINIT GV_ADD, but don't initialize
5227 GV_NOEXPAND Don't expand SvOK() entries to PVGV
5228 SVf_UTF8 The name is in UTF-8
5229 The most important of which are probably "GV_ADD" and "SVf_UTF8".
5231 Note, use of "gv_stashsv" instead of "gv_stashpvn" where possible
5233 is strongly recommended for performance reasons.
5234 HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
5236 "gv_stashpvs"
5238 Like "gv_stashpvn", but takes a literal string instead of a
5239 string/length pair.
5240 HV* gv_stashpvs("name", I32 create)
5242 "gv_stashsv"
5244 Returns a pointer to the stash for a specified package. See
5245 "gv_stashpvn".
5246 Note this interface is strongly preferred over "gv_stashpvn" for
5248 performance reasons.
5249 HV* gv_stashsv(SV* sv, I32 flags)
5251 "GvSV"
5253 Return the SV from the GV.
5254 Prior to Perl v5.9.3, this would add a scalar if none existed.
5256 Nowadays, use "GvSVn" for that, or compile perl with
5257 "-DPERL_CREATE_GVSV". See perl5100delta.
5258 SV* GvSV(GV* gv)
5260 "GvSVn"
5262 Like "GvSV", but creates an empty scalar if none already exists.
5263 SV* GvSVn(GV* gv)
5265 "newGVgen"
5267 "newGVgen_flags"
5268 Create a new, guaranteed to be unique, GV in the package given by
5269 the NUL-terminated C language string "pack", and return a pointer
5270 to it.
5271 For "newGVgen" or if "flags" in "newGVgen_flags" is 0, "pack" is to
5273 be considered to be encoded in Latin-1. The only other legal
5274 "flags" value is "SVf_UTF8", which indicates "pack" is to be
5275 considered to be encoded in UTF-8.
5276 GV* newGVgen (const char* pack)
5278 GV* newGVgen_flags(const char* pack, U32 flags)
5279 "PL_curstash"
5281 The stash for the package code will be compiled into.
5282 On threaded perls, each thread has an independent copy of this
5284 variable; each initialized at creation time with the current value
5285 of the creating thread's copy.
5286 HV* PL_curstash
5288 "PL_defgv"
5290 The GV representing *_. Useful for access to $_.
5291 On threaded perls, each thread has an independent copy of this
5293 variable; each initialized at creation time with the current value
5294 of the creating thread's copy.
5295 GV * PL_defgv
5297 "PL_defstash"
5299 Described in perlguts.
5300 "save_gp"
5302 Saves the current GP of gv on the save stack to be restored on
5303 scope exit.
5304 If "empty" is true, replace the GP with a new GP.
5306 If "empty" is false, mark "gv" with "GVf_INTRO" so the next
5308 reference assigned is localized, which is how
5309 " local *foo = $someref; " works.
5310 void save_gp(GV* gv, I32 empty)
5312 "setdefout"
5314 Sets "PL_defoutgv", the default file handle for output, to the
5315 passed in typeglob. As "PL_defoutgv" "owns" a reference on its
5316 typeglob, the reference count of the passed in typeglob is
5317 increased by one, and the reference count of the typeglob that
5318 "PL_defoutgv" points to is decreased by one.
5319 void setdefout(GV* gv)
5321
5323 These functions provide convenient and thread-safe means of
5324 manipulating hook variables.
5325 "wrap_op_checker"
5327 Puts a C function into the chain of check functions for a specified
5328 op type. This is the preferred way to manipulate the "PL_check"
5329 array. "opcode" specifies which type of op is to be affected.
5330 "new_checker" is a pointer to the C function that is to be added to
5331 that opcode's check chain, and "old_checker_p" points to the
5332 storage location where a pointer to the next function in the chain
5333 will be stored. The value of "new_checker" is written into the
5334 "PL_check" array, while the value previously stored there is
5335 written to *old_checker_p.
5336 "PL_check" is global to an entire process, and a module wishing to
5338 hook op checking may find itself invoked more than once per
5339 process, typically in different threads. To handle that situation,
5340 this function is idempotent. The location *old_checker_p must
5341 initially (once per process) contain a null pointer. A C variable
5342 of static duration (declared at file scope, typically also marked
5343 "static" to give it internal linkage) will be implicitly
5344 initialised appropriately, if it does not have an explicit
5345 initialiser. This function will only actually modify the check
5346 chain if it finds *old_checker_p to be null. This function is also
5347 thread safe on the small scale. It uses appropriate locking to
5348 avoid race conditions in accessing "PL_check".
5349 When this function is called, the function referenced by
5351 "new_checker" must be ready to be called, except for *old_checker_p
5352 being unfilled. In a threading situation, "new_checker" may be
5353 called immediately, even before this function has returned.
5354 *old_checker_p will always be appropriately set before
5355 "new_checker" is called. If "new_checker" decides not to do
5356 anything special with an op that it is given (which is the usual
5357 case for most uses of op check hooking), it must chain the check
5358 function referenced by *old_checker_p.
5359 Taken all together, XS code to hook an op checker should typically
5361 look something like this:
5362 static Perl_check_t nxck_frob;
5364 static OP *myck_frob(pTHX_ OP *op) {
5365 ...
5366 op = nxck_frob(aTHX_ op);
5367 ...
5368 return op;
5369 }
5370 BOOT:
5371 wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
5372 If you want to influence compilation of calls to a specific
5374 subroutine, then use "cv_set_call_checker_flags" rather than
5375 hooking checking of all "entersub" ops.
5376 void wrap_op_checker(Optype opcode, Perl_check_t new_checker,
5378 Perl_check_t *old_checker_p)
5379
5381 A HV structure represents a Perl hash. It consists mainly of an array
5382 of pointers, each of which points to a linked list of HE structures.
5383 The array is indexed by the hash function of the key, so each linked
5384 list represents all the hash entries with the same hash value. Each HE
5385 contains a pointer to the actual value, plus a pointer to a HEK
5386 structure which holds the key and hash value.
5387 "get_hv"
5389 Returns the HV of the specified Perl hash. "flags" are passed to
5390 "gv_fetchpv". If "GV_ADD" is set and the Perl variable does not
5391 exist then it will be created. If "flags" is zero and the variable
5392 does not exist then "NULL" is returned.
5393 NOTE: the "perl_get_hv()" form is deprecated.
5395 HV* get_hv(const char *name, I32 flags)
5397 "HE"
5399 Described in perlguts.
5400 "HEf_SVKEY"
5402 This flag, used in the length slot of hash entries and magic
5403 structures, specifies the structure contains an "SV*" pointer where
5404 a "char*" pointer is to be expected. (For information only--not to
5405 be used).
5406 "HeHASH"
5408 Returns the computed hash stored in the hash entry.
5409 U32 HeHASH(HE* he)
5411 "HeKEY"
5413 Returns the actual pointer stored in the key slot of the hash
5414 entry. The pointer may be either "char*" or "SV*", depending on
5415 the value of "HeKLEN()". Can be assigned to. The "HePV()" or
5416 "HeSVKEY()" macros are usually preferable for finding the value of
5417 a key.
5418 void* HeKEY(HE* he)
5420 "HeKLEN"
5422 If this is negative, and amounts to "HEf_SVKEY", it indicates the
5423 entry holds an "SV*" key. Otherwise, holds the actual length of
5424 the key. Can be assigned to. The "HePV()" macro is usually
5425 preferable for finding key lengths.
5426 STRLEN HeKLEN(HE* he)
5428 "HePV"
5430 Returns the key slot of the hash entry as a "char*" value, doing
5431 any necessary dereferencing of possibly "SV*" keys. The length of
5432 the string is placed in "len" (this is a macro, so do not use
5433 &len). If you do not care about what the length of the key is, you
5434 may use the global variable "PL_na", though this is rather less
5435 efficient than using a local variable. Remember though, that hash
5436 keys in perl are free to contain embedded nulls, so using
5437 "strlen()" or similar is not a good way to find the length of hash
5438 keys. This is very similar to the "SvPV()" macro described
5439 elsewhere in this document. See also "HeUTF8".
5440 If you are using "HePV" to get values to pass to "newSVpvn()" to
5442 create a new SV, you should consider using
5443 "newSVhek(HeKEY_hek(he))" as it is more efficient.
5444 char* HePV(HE* he, STRLEN len)
5446 "HeSVKEY"
5448 Returns the key as an "SV*", or "NULL" if the hash entry does not
5449 contain an "SV*" key.
5450 SV* HeSVKEY(HE* he)
5452 "HeSVKEY_force"
5454 Returns the key as an "SV*". Will create and return a temporary
5455 mortal "SV*" if the hash entry contains only a "char*" key.
5456 SV* HeSVKEY_force(HE* he)
5458 "HeSVKEY_set"
5460 Sets the key to a given "SV*", taking care to set the appropriate
5461 flags to indicate the presence of an "SV*" key, and returns the
5462 same "SV*".
5463 SV* HeSVKEY_set(HE* he, SV* sv)
5465 "HeUTF8"
5467 Returns whether the "char *" value returned by "HePV" is encoded in
5468 UTF-8, doing any necessary dereferencing of possibly "SV*" keys.
5469 The value returned will be 0 or non-0, not necessarily 1 (or even a
5470 value with any low bits set), so do not blindly assign this to a
5471 "bool" variable, as "bool" may be a typedef for "char".
5472 U32 HeUTF8(HE* he)
5474 "HeVAL"
5476 Returns the value slot (type "SV*") stored in the hash entry. Can
5477 be assigned to.
5478 SV *foo= HeVAL(hv);
5480 HeVAL(hv)= sv;
5481 SV* HeVAL(HE* he)
5483 "HV"
5485 Described in perlguts.
5486 "hv_assert"
5488 Check that a hash is in an internally consistent state.
5489 NOTE: "hv_assert" must be explicitly called as "Perl_hv_assert"
5491 with an "aTHX_" parameter.
5492 void Perl_hv_assert(pTHX_ HV *hv)
5494 "hv_bucket_ratio"
5496 NOTE: "hv_bucket_ratio" is experimental and may change or be
5497 removed without notice.
5498 If the hash is tied dispatches through to the SCALAR tied method,
5500 otherwise if the hash contains no keys returns 0, otherwise returns
5501 a mortal sv containing a string specifying the number of used
5502 buckets, followed by a slash, followed by the number of available
5503 buckets.
5504 This function is expensive, it must scan all of the buckets to
5506 determine which are used, and the count is NOT cached. In a large
5507 hash this could be a lot of buckets.
5508 SV* hv_bucket_ratio(HV *hv)
5510 "hv_clear"
5512 Frees all the elements of a hash, leaving it empty. The XS
5513 equivalent of "%hash = ()". See also "hv_undef".
5514 See "av_clear" for a note about the hash possibly being invalid on
5516 return.
5517 void hv_clear(HV *hv)
5519 "hv_clear_placeholders"
5521 Clears any placeholders from a hash. If a restricted hash has any
5522 of its keys marked as readonly and the key is subsequently deleted,
5523 the key is not actually deleted but is marked by assigning it a
5524 value of &PL_sv_placeholder. This tags it so it will be ignored by
5525 future operations such as iterating over the hash, but will still
5526 allow the hash to have a value reassigned to the key at some future
5527 point. This function clears any such placeholder keys from the
5528 hash. See "Hash::Util::lock_keys()" for an example of its use.
5529 void hv_clear_placeholders(HV *hv)
5531 "hv_copy_hints_hv"
5533 A specialised version of "newHVhv" for copying "%^H". "ohv" must
5534 be a pointer to a hash (which may have "%^H" magic, but should be
5535 generally non-magical), or "NULL" (interpreted as an empty hash).
5536 The content of "ohv" is copied to a new hash, which has the
5537 "%^H"-specific magic added to it. A pointer to the new hash is
5538 returned.
5539 HV * hv_copy_hints_hv(HV *const ohv)
5541 "hv_delete"
5543 Deletes a key/value pair in the hash. The value's SV is removed
5544 from the hash, made mortal, and returned to the caller. The
5545 absolute value of "klen" is the length of the key. If "klen" is
5546 negative the key is assumed to be in UTF-8-encoded Unicode. The
5547 "flags" value will normally be zero; if set to "G_DISCARD" then
5548 "NULL" will be returned. "NULL" will also be returned if the key
5549 is not found.
5550 SV* hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
5552 "hv_delete_ent"
5554 Deletes a key/value pair in the hash. The value SV is removed from
5555 the hash, made mortal, and returned to the caller. The "flags"
5556 value will normally be zero; if set to "G_DISCARD" then "NULL" will
5557 be returned. "NULL" will also be returned if the key is not found.
5558 "hash" can be a valid precomputed hash value, or 0 to ask for it to
5559 be computed.
5560 SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
5562 "HvENAME"
5564 Returns the effective name of a stash, or NULL if there is none.
5565 The effective name represents a location in the symbol table where
5566 this stash resides. It is updated automatically when packages are
5567 aliased or deleted. A stash that is no longer in the symbol table
5568 has no effective name. This name is preferable to "HvNAME" for use
5569 in MRO linearisations and isa caches.
5570 char* HvENAME(HV* stash)
5572 "HvENAMELEN"
5574 Returns the length of the stash's effective name.
5575 STRLEN HvENAMELEN(HV *stash)
5577 "HvENAMEUTF8"
5579 Returns true if the effective name is in UTF-8 encoding.
5580 unsigned char HvENAMEUTF8(HV *stash)
5582 "hv_exists"
5584 Returns a boolean indicating whether the specified hash key exists.
5585 The absolute value of "klen" is the length of the key. If "klen"
5586 is negative the key is assumed to be in UTF-8-encoded Unicode.
5587 bool hv_exists(HV *hv, const char *key, I32 klen)
5589 "hv_exists_ent"
5591 Returns a boolean indicating whether the specified hash key exists.
5592 "hash" can be a valid precomputed hash value, or 0 to ask for it to
5593 be computed.
5594 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
5596 "hv_fetch"
5598 Returns the SV which corresponds to the specified key in the hash.
5599 The absolute value of "klen" is the length of the key. If "klen"
5600 is negative the key is assumed to be in UTF-8-encoded Unicode. If
5601 "lval" is set then the fetch will be part of a store. This means
5602 that if there is no value in the hash associated with the given
5603 key, then one is created and a pointer to it is returned. The
5604 "SV*" it points to can be assigned to. But always check that the
5605 return value is non-null before dereferencing it to an "SV*".
5606 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5608 for more information on how to use this function on tied hashes.
5609 SV** hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
5611 "hv_fetchs"
5613 Like "hv_fetch", but takes a literal string instead of a
5614 string/length pair.
5615 SV** hv_fetchs(HV* tb, "key", I32 lval)
5617 "hv_fetch_ent"
5619 Returns the hash entry which corresponds to the specified key in
5620 the hash. "hash" must be a valid precomputed hash number for the
5621 given "key", or 0 if you want the function to compute it. IF
5622 "lval" is set then the fetch will be part of a store. Make sure
5623 the return value is non-null before accessing it. The return value
5624 when "hv" is a tied hash is a pointer to a static location, so be
5625 sure to make a copy of the structure if you need to store it
5626 somewhere.
5627 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5629 for more information on how to use this function on tied hashes.
5630 HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
5632 "HvFILL"
5634 Returns the number of hash buckets that happen to be in use.
5635 As of perl 5.25 this function is used only for debugging purposes,
5637 and the number of used hash buckets is not in any way cached, thus
5638 this function can be costly to execute as it must iterate over all
5639 the buckets in the hash.
5640 STRLEN HvFILL(HV *const hv)
5642 "hv_iterinit"
5644 Prepares a starting point to traverse a hash table. Returns the
5645 number of keys in the hash, including placeholders (i.e. the same
5646 as "HvTOTALKEYS(hv)"). The return value is currently only
5647 meaningful for hashes without tie magic.
5648 NOTE: Before version 5.004_65, "hv_iterinit" used to return the
5650 number of hash buckets that happen to be in use. If you still need
5651 that esoteric value, you can get it through the macro "HvFILL(hv)".
5652 I32 hv_iterinit(HV *hv)
5654 "hv_iterkey"
5656 Returns the key from the current position of the hash iterator.
5657 See "hv_iterinit".
5658 char* hv_iterkey(HE* entry, I32* retlen)
5660 "hv_iterkeysv"
5662 Returns the key as an "SV*" from the current position of the hash
5663 iterator. The return value will always be a mortal copy of the
5664 key. Also see "hv_iterinit".
5665 SV* hv_iterkeysv(HE* entry)
5667 "hv_iternext"
5669 Returns entries from a hash iterator. See "hv_iterinit".
5670 You may call "hv_delete" or "hv_delete_ent" on the hash entry that
5672 the iterator currently points to, without losing your place or
5673 invalidating your iterator. Note that in this case the current
5674 entry is deleted from the hash with your iterator holding the last
5675 reference to it. Your iterator is flagged to free the entry on the
5676 next call to "hv_iternext", so you must not discard your iterator
5677 immediately else the entry will leak - call "hv_iternext" to
5678 trigger the resource deallocation.
5679 HE* hv_iternext(HV *hv)
5681 "hv_iternextsv"
5683 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in one
5684 operation.
5685 SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
5687 "hv_iternext_flags"
5689 NOTE: "hv_iternext_flags" is experimental and may change or be
5690 removed without notice.
5691 Returns entries from a hash iterator. See "hv_iterinit" and
5693 "hv_iternext". The "flags" value will normally be zero; if
5694 "HV_ITERNEXT_WANTPLACEHOLDERS" is set the placeholders keys (for
5695 restricted hashes) will be returned in addition to normal keys. By
5696 default placeholders are automatically skipped over. Currently a
5697 placeholder is implemented with a value that is &PL_sv_placeholder.
5698 Note that the implementation of placeholders and restricted hashes
5699 may change, and the implementation currently is insufficiently
5700 abstracted for any change to be tidy.
5701 HE* hv_iternext_flags(HV *hv, I32 flags)
5703 "hv_iterval"
5705 Returns the value from the current position of the hash iterator.
5706 See "hv_iterkey".
5707 SV* hv_iterval(HV *hv, HE *entry)
5709 "hv_magic"
5711 Adds magic to a hash. See "sv_magic".
5712 void hv_magic(HV *hv, GV *gv, int how)
5714 "HvNAME"
5716 Returns the package name of a stash, or "NULL" if "stash" isn't a
5717 stash. See "SvSTASH", "CvSTASH".
5718 char* HvNAME(HV* stash)
5720 "HvNAMELEN"
5722 Returns the length of the stash's name.
5723 Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them
5725 STRLEN HvNAMELEN(HV *stash)
5727 "HvNAMEUTF8"
5729 Returns true if the name is in UTF-8 encoding.
5730 unsigned char HvNAMEUTF8(HV *stash)
5732 "hv_scalar"
5734 Evaluates the hash in scalar context and returns the result.
5735 When the hash is tied dispatches through to the SCALAR method,
5737 otherwise returns a mortal SV containing the number of keys in the
5738 hash.
5739 Note, prior to 5.25 this function returned what is now returned by
5741 the hv_bucket_ratio() function.
5742 SV* hv_scalar(HV *hv)
5744 "hv_store"
5746 Stores an SV in a hash. The hash key is specified as "key" and the
5747 absolute value of "klen" is the length of the key. If "klen" is
5748 negative the key is assumed to be in UTF-8-encoded Unicode. The
5749 "hash" parameter is the precomputed hash value; if it is zero then
5750 Perl will compute it.
5751 The return value will be "NULL" if the operation failed or if the
5753 value did not need to be actually stored within the hash (as in the
5754 case of tied hashes). Otherwise it can be dereferenced to get the
5755 original "SV*". Note that the caller is responsible for suitably
5756 incrementing the reference count of "val" before the call, and
5757 decrementing it if the function returned "NULL". Effectively a
5758 successful "hv_store" takes ownership of one reference to "val".
5759 This is usually what you want; a newly created SV has a reference
5760 count of one, so if all your code does is create SVs then store
5761 them in a hash, "hv_store" will own the only reference to the new
5762 SV, and your code doesn't need to do anything further to tidy up.
5763 "hv_store" is not implemented as a call to "hv_store_ent", and does
5764 not create a temporary SV for the key, so if your key data is not
5765 already in SV form then use "hv_store" in preference to
5766 "hv_store_ent".
5767 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5769 for more information on how to use this function on tied hashes.
5770 SV** hv_store(HV *hv, const char *key, I32 klen, SV *val,
5772 U32 hash)
5773 "hv_stores"
5775 Like "hv_store", but takes a literal string instead of a
5776 string/length pair and omits the hash parameter.
5777 SV** hv_stores(HV* tb, "key", SV* val)
5779 "hv_store_ent"
5781 Stores "val" in a hash. The hash key is specified as "key". The
5782 "hash" parameter is the precomputed hash value; if it is zero then
5783 Perl will compute it. The return value is the new hash entry so
5784 created. It will be "NULL" if the operation failed or if the value
5785 did not need to be actually stored within the hash (as in the case
5786 of tied hashes). Otherwise the contents of the return value can be
5787 accessed using the "He?" macros described here. Note that the
5788 caller is responsible for suitably incrementing the reference count
5789 of "val" before the call, and decrementing it if the function
5790 returned NULL. Effectively a successful "hv_store_ent" takes
5791 ownership of one reference to "val". This is usually what you
5792 want; a newly created SV has a reference count of one, so if all
5793 your code does is create SVs then store them in a hash, "hv_store"
5794 will own the only reference to the new SV, and your code doesn't
5795 need to do anything further to tidy up. Note that "hv_store_ent"
5796 only reads the "key"; unlike "val" it does not take ownership of
5797 it, so maintaining the correct reference count on "key" is entirely
5798 the caller's responsibility. The reason it does not take
5799 ownership, is that "key" is not used after this function returns,
5800 and so can be freed immediately. "hv_store" is not implemented as
5801 a call to "hv_store_ent", and does not create a temporary SV for
5802 the key, so if your key data is not already in SV form then use
5803 "hv_store" in preference to "hv_store_ent".
5804 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
5806 for more information on how to use this function on tied hashes.
5807 HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
5809 "hv_undef"
5811 Undefines the hash. The XS equivalent of "undef(%hash)".
5812 As well as freeing all the elements of the hash (like
5814 "hv_clear()"), this also frees any auxiliary data and storage
5815 associated with the hash.
5816 See "av_clear" for a note about the hash possibly being invalid on
5818 return.
5819 void hv_undef(HV *hv)
5821 "newHV"
5823 Creates a new HV. The reference count is set to 1.
5824 HV* newHV()
5826 "newHVhv"
5828 The content of "ohv" is copied to a new hash. A pointer to the new
5829 hash is returned.
5830 HV* newHVhv(HV *hv)
5832 "Nullhv"
5834 "DEPRECATED!" It is planned to remove "Nullhv" from a future
5835 release of Perl. Do not use it for new code; remove it from
5836 existing code.
5837 Null HV pointer.
5839 (deprecated - use "(HV *)NULL" instead)
5841 "PERL_HASH"
5843 Described in perlguts.
5844 void PERL_HASH(U32 hash, char *key, STRLEN klen)
5846 "PL_modglobal"
5848 "PL_modglobal" is a general purpose, interpreter global HV for use
5849 by extensions that need to keep information on a per-interpreter
5850 basis. In a pinch, it can also be used as a symbol table for
5851 extensions to share data among each other. It is a good idea to
5852 use keys prefixed by the package name of the extension that owns
5853 the data.
5854 On threaded perls, each thread has an independent copy of this
5856 variable; each initialized at creation time with the current value
5857 of the creating thread's copy.
5858 HV* PL_modglobal
5860
5862 "IoDIRP"
5863 Described in perlguts.
5864 DIR * IoDIRP(IO *io)
5866 "IOf_FLUSH"
5868 Described in perlguts.
5869 "IoFLAGS"
5871 Described in perlguts.
5872 U8 IoFLAGS(IO *io)
5874 "IOf_UNTAINT"
5876 Described in perlguts.
5877 "IoIFP"
5879 Described in perlguts.
5880 PerlIO * IoIFP(IO *io)
5882 "IoOFP"
5884 Described in perlguts.
5885 PerlIO * IoOFP(IO *io)
5887 "IoTYPE"
5889 Described in perlguts.
5890 char IoTYPE(IO *io)
5892 "my_chsize"
5894 The C library chsize(3) if available, or a Perl implementation of
5895 it.
5896 I32 my_chsize(int fd, Off_t length)
5898 "my_dirfd"
5900 The C library dirfd(3) if available, or a Perl implementation of
5901 it, or die if not easily emulatable.
5902 int my_dirfd(DIR* dir)
5904 "my_pclose"
5906 A wrapper for the C library pclose(3). Don't use the latter, as
5907 the Perl version knows things that interact with the rest of the
5908 perl interpreter.
5909 I32 my_pclose(PerlIO* ptr)
5911 "my_popen"
5913 A wrapper for the C library popen(3). Don't use the latter, as the
5914 Perl version knows things that interact with the rest of the perl
5915 interpreter.
5916 PerlIO* my_popen(const char* cmd, const char* mode)
5918 "newIO"
5920 Create a new IO, setting the reference count to 1.
5921 IO* newIO()
5923 "PERL_FLUSHALL_FOR_CHILD"
5925 This defines a way to flush all output buffers. This may be a
5926 performance issue, so we allow people to disable it. Also, if we
5927 are using stdio, there are broken implementations of fflush(NULL)
5928 out there, Solaris being the most prominent.
5929 void PERL_FLUSHALL_FOR_CHILD
5931 "PerlIO_apply_layers"
5933 "PerlIO_binmode"
5934 "PerlIO_canset_cnt"
5935 "PerlIO_clearerr"
5936 "PerlIO_close"
5937 "PerlIO_debug"
5938 "PerlIO_eof"
5939 "PerlIO_error"
5940 "PerlIO_exportFILE"
5941 "PerlIO_fast_gets"
5942 "PerlIO_fdopen"
5943 "PerlIO_fileno"
5944 "PerlIO_fill"
5945 "PerlIO_findFILE"
5946 "PerlIO_flush"
5947 "PerlIO_get_base"
5948 "PerlIO_get_bufsiz"
5949 "PerlIO_getc"
5950 "PerlIO_get_cnt"
5951 "PerlIO_getpos"
5952 "PerlIO_get_ptr"
5953 "PerlIO_has_base"
5954 "PerlIO_has_cntptr"
5955 "PerlIO_importFILE"
5956 "PerlIO_open"
5957 "PerlIO_printf"
5958 "PerlIO_putc"
5959 "PerlIO_puts"
5960 "PerlIO_read"
5961 "PerlIO_releaseFILE"
5962 "PerlIO_reopen"
5963 "PerlIO_rewind"
5964 "PerlIO_seek"
5965 "PerlIO_set_cnt"
5966 "PerlIO_setlinebuf"
5967 "PerlIO_setpos"
5968 "PerlIO_set_ptrcnt"
5969 "PerlIO_stderr"
5970 "PerlIO_stdin"
5971 "PerlIO_stdout"
5972 "PerlIO_stdoutf"
5973 "PerlIO_tell"
5974 "PerlIO_ungetc"
5975 "PerlIO_unread"
5976 "PerlIO_vprintf"
5977 "PerlIO_write"
5978 Described in perlapio.
5979 int PerlIO_apply_layers(PerlIO *f, const char *mode,
5981 const char *layers)
5982 int PerlIO_binmode (PerlIO *f, int ptype, int imode,
5983 const char *layers)
5984 int PerlIO_canset_cnt (PerlIO *f)
5985 void PerlIO_clearerr (PerlIO *f)
5986 int PerlIO_close (PerlIO *f)
5987 void PerlIO_debug (const char *fmt, ...)
5988 int PerlIO_eof (PerlIO *f)
5989 int PerlIO_error (PerlIO *f)
5990 FILE * PerlIO_exportFILE (PerlIO *f, const char *mode)
5991 int PerlIO_fast_gets (PerlIO *f)
5992 PerlIO * PerlIO_fdopen (int fd, const char *mode)
5993 int PerlIO_fileno (PerlIO *f)
5994 int PerlIO_fill (PerlIO *f)
5995 FILE * PerlIO_findFILE (PerlIO *f)
5996 int PerlIO_flush (PerlIO *f)
5997 STDCHAR * PerlIO_get_base (PerlIO *f)
5998 SSize_t PerlIO_get_bufsiz (PerlIO *f)
5999 int PerlIO_getc (PerlIO *d)
6000 SSize_t PerlIO_get_cnt (PerlIO *f)
6001 int PerlIO_getpos (PerlIO *f, SV *save)
6002 STDCHAR * PerlIO_get_ptr (PerlIO *f)
6003 int PerlIO_has_base (PerlIO *f)
6004 int PerlIO_has_cntptr (PerlIO *f)
6005 PerlIO * PerlIO_importFILE (FILE *stdio, const char *mode)
6006 PerlIO * PerlIO_open (const char *path, const char *mode)
6007 int PerlIO_printf (PerlIO *f, const char *fmt, ...)
6008 int PerlIO_putc (PerlIO *f, int ch)
6009 int PerlIO_puts (PerlIO *f, const char *string)
6010 SSize_t PerlIO_read (PerlIO *f, void *vbuf,
6011 Size_t count)
6012 void PerlIO_releaseFILE (PerlIO *f, FILE *stdio)
6013 PerlIO * PerlIO_reopen (const char *path, const char *mode,
6014 PerlIO *old)
6015 void PerlIO_rewind (PerlIO *f)
6016 int PerlIO_seek (PerlIO *f, Off_t offset,
6017 int whence)
6018 void PerlIO_set_cnt (PerlIO *f, SSize_t cnt)
6019 void PerlIO_setlinebuf (PerlIO *f)
6020 int PerlIO_setpos (PerlIO *f, SV *saved)
6021 void PerlIO_set_ptrcnt (PerlIO *f, STDCHAR *ptr,
6022 SSize_t cnt)
6023 PerlIO * PerlIO_stderr (PerlIO *f, const char *mode,
6024 const char *layers)
6025 PerlIO * PerlIO_stdin (PerlIO *f, const char *mode,
6026 const char *layers)
6027 PerlIO * PerlIO_stdout (PerlIO *f, const char *mode,
6028 const char *layers)
6029 int PerlIO_stdoutf (const char *fmt, ...)
6030 Off_t PerlIO_tell (PerlIO *f)
6031 int PerlIO_ungetc (PerlIO *f, int ch)
6032 SSize_t PerlIO_unread (PerlIO *f, const void *vbuf,
6033 Size_t count)
6034 int PerlIO_vprintf (PerlIO *f, const char *fmt,
6035 va_list args)
6036 SSize_t PerlIO_write (PerlIO *f, const void *vbuf,
6037 Size_t count)
6038 "PERLIO_FUNCS_CAST"
6040 Cast the pointer "func" to be of type "PerlIO_funcs *".
6041 "PERLIO_FUNCS_DECL"
6043 Declare "ftab" to be a PerlIO function table, that is, of type
6044 "PerlIO_funcs".
6045 PERLIO_FUNCS_DECL(PerlIO * ftab)
6047 "PERLIO_F_APPEND"
6049 "PERLIO_F_CANREAD"
6050 "PERLIO_F_CANWRITE"
6051 "PERLIO_F_CRLF"
6052 "PERLIO_F_EOF"
6053 "PERLIO_F_ERROR"
6054 "PERLIO_F_FASTGETS"
6055 "PERLIO_F_LINEBUF"
6056 "PERLIO_F_OPEN"
6057 "PERLIO_F_RDBUF"
6058 "PERLIO_F_TEMP"
6059 "PERLIO_F_TRUNCATE"
6060 "PERLIO_F_UNBUF"
6061 "PERLIO_F_UTF8"
6062 "PERLIO_F_WRBUF"
6063 Described in perliol.
6064 "PERLIO_K_BUFFERED"
6066 "PERLIO_K_CANCRLF"
6067 "PERLIO_K_FASTGETS"
6068 "PERLIO_K_MULTIARG"
6069 "PERLIO_K_RAW"
6070 Described in perliol.
6071 "PERLIO_NOT_STDIO"
6073 Described in perlapio.
6074 "PL_maxsysfd"
6076 Described in perliol.
6077 "repeatcpy"
6079 Make "count" copies of the "len" bytes beginning at "from", placing
6080 them into memory beginning at "to", which must be big enough to
6081 accommodate them all.
6082 void repeatcpy(char* to, const char* from, I32 len, IV count)
6084 "USE_STDIO"
6086 Described in perlapio.
6087
6089 "CASTI32"
6090 This symbol is defined if the C compiler can cast negative or large
6091 floating point numbers to 32-bit ints.
6092 "HAS_INT64_T"
6094 This symbol will defined if the C compiler supports "int64_t".
6095 Usually the inttypes.h needs to be included, but sometimes
6096 sys/types.h is enough.
6097 "HAS_LONG_LONG"
6099 This symbol will be defined if the C compiler supports long long.
6100 "HAS_QUAD"
6102 This symbol, if defined, tells that there's a 64-bit integer type,
6103 "Quad_t", and its unsigned counterpart, "Uquad_t". "QUADKIND" will
6104 be one of "QUAD_IS_INT", "QUAD_IS_LONG", "QUAD_IS_LONG_LONG",
6105 "QUAD_IS_INT64_T", or "QUAD_IS___INT64".
6106 "I8"
6108 "I16"
6109 "I32"
6110 "I64"
6111 "IV"
6112 Described in perlguts.
6113 "I32SIZE"
6115 This symbol contains the "sizeof(I32)".
6116 "I32TYPE"
6118 This symbol defines the C type used for Perl's I32.
6119 "I64SIZE"
6121 This symbol contains the "sizeof(I64)".
6122 "I64TYPE"
6124 This symbol defines the C type used for Perl's I64.
6125 "I16SIZE"
6127 This symbol contains the "sizeof(I16)".
6128 "I16TYPE"
6130 This symbol defines the C type used for Perl's I16.
6131 "INT16_C"
6133 "INT32_C"
6134 "INT64_C"
6135 Returns a token the C compiler recognizes for the constant "number"
6136 of the corresponding integer type on the machine.
6137 If the machine does not have a 64-bit type, "INT64_C" is undefined.
6139 Use "INTMAX_C" to get the largest type available on the platform.
6140 I16 INT16_C(number)
6142 I32 INT32_C(number)
6143 I64 INT64_C(number)
6144 "INTMAX_C"
6146 Returns a token the C compiler recognizes for the constant "number"
6147 of the widest integer type on the machine. For example, if the
6148 machine has "long long"s, "INTMAX_C(-1)" would yield
6149 -1LL
6151 See also, for example, "INT32_C".
6153 Use "IV" to declare variables of the maximum usable size on this
6155 platform.
6156 INTMAX_C(number)
6158 "INTSIZE"
6160 This symbol contains the value of "sizeof(int)" so that the C
6161 preprocessor can make decisions based on it.
6162 "I8SIZE"
6164 This symbol contains the "sizeof(I8)".
6165 "I8TYPE"
6167 This symbol defines the C type used for Perl's I8.
6168 "IV_MAX"
6170 The largest signed integer that fits in an IV on this platform.
6171 IV IV_MAX
6173 "IV_MIN"
6175 The negative signed integer furthest away from 0 that fits in an IV
6176 on this platform.
6177 IV IV_MIN
6179 "IVSIZE"
6181 This symbol contains the "sizeof(IV)".
6182 "IVTYPE"
6184 This symbol defines the C type used for Perl's IV.
6185 "line_t"
6187 The typedef to use to declare variables that are to hold line
6188 numbers.
6189 "LONGLONGSIZE"
6191 This symbol contains the size of a long long, so that the C
6192 preprocessor can make decisions based on it. It is only defined if
6193 the system supports long long.
6194 "LONGSIZE"
6196 This symbol contains the value of "sizeof(long)" so that the C
6197 preprocessor can make decisions based on it.
6198 "memzero"
6200 Set the "l" bytes starting at *d to all zeroes.
6201 void memzero(void * d, Size_t l)
6203 "PERL_INT_FAST8_T"
6205 "PERL_INT_FAST16_T"
6206 "PERL_UINT_FAST8_T"
6207 "PERL_UINT_FAST16_T"
6208 These are equivalent to the correspondingly-named C99 typedefs on
6209 platforms that have those; they evaluate to "int" and "unsigned
6210 int" on platforms that don't, so that you can portably take
6211 advantage of this C99 feature.
6212 "PERL_INT_MAX"
6214 "PERL_INT_MIN"
6215 "PERL_LONG_MAX"
6216 "PERL_LONG_MIN"
6217 "PERL_SHORT_MAX"
6218 "PERL_SHORT_MIN"
6219 "PERL_UCHAR_MAX"
6220 "PERL_UCHAR_MIN"
6221 "PERL_UINT_MAX"
6222 "PERL_UINT_MIN"
6223 "PERL_ULONG_MAX"
6224 "PERL_ULONG_MIN"
6225 "PERL_USHORT_MAX"
6226 "PERL_USHORT_MIN"
6227 "PERL_QUAD_MAX"
6228 "PERL_QUAD_MIN"
6229 "PERL_UQUAD_MAX"
6230 "PERL_UQUAD_MIN"
6231 These give the largest and smallest number representable in the
6232 current platform in variables of the corresponding types.
6233 For signed types, the smallest representable number is the most
6235 negative number, the one furthest away from zero.
6236 For C99 and later compilers, these correspond to things like
6238 "INT_MAX", which are available to the C code. But these constants,
6239 furnished by Perl, allow code compiled on earlier compilers to
6240 portably have access to the same constants.
6241 "SHORTSIZE"
6243 This symbol contains the value of "sizeof(short)" so that the C
6244 preprocessor can make decisions based on it.
6245 "U8"
6247 "U16"
6248 "U32"
6249 "U64"
6250 "UV"
6251 Described in perlguts.
6252 "U32SIZE"
6254 This symbol contains the "sizeof(U32)".
6255 "U32TYPE"
6257 This symbol defines the C type used for Perl's U32.
6258 "U64SIZE"
6260 This symbol contains the "sizeof(U64)".
6261 "U64TYPE"
6263 This symbol defines the C type used for Perl's U64.
6264 "U16SIZE"
6266 This symbol contains the "sizeof(U16)".
6267 "U16TYPE"
6269 This symbol defines the C type used for Perl's U16.
6270 "UINT16_C"
6272 "UINT32_C"
6273 "UINT64_C"
6274 Returns a token the C compiler recognizes for the constant "number"
6275 of the corresponding unsigned integer type on the machine.
6276 If the machine does not have a 64-bit type, "UINT64_C" is
6278 undefined. Use "UINTMAX_C" to get the largest type available on
6279 the platform.
6280 U16 UINT16_C(number)
6282 U32 UINT32_C(number)
6283 U64 UINT64_C(number)
6284 "UINTMAX_C"
6286 Returns a token the C compiler recognizes for the constant "number"
6287 of the widest unsigned integer type on the machine. For example,
6288 if the machine has "long"s, UINTMAX_C(1) would yield
6289 1UL
6291 See also, for example, "UINT32_C".
6293 Use "UV" to declare variables of the maximum usable size on this
6295 platform.
6296 UINTMAX_C(number)
6298 "U8SIZE"
6300 This symbol contains the "sizeof(U8)".
6301 "U8TYPE"
6303 This symbol defines the C type used for Perl's U8.
6304 "UV_MAX"
6306 The largest unsigned integer that fits in a UV on this platform.
6307 UV UV_MAX
6309 "UV_MIN"
6311 The smallest unsigned integer that fits in a UV on this platform.
6312 It should equal zero.
6313 UV UV_MIN
6315 "UVSIZE"
6317 This symbol contains the "sizeof(UV)".
6318 "UVTYPE"
6320 This symbol defines the C type used for Perl's UV.
6321 "WIDEST_UTYPE"
6323 Yields the widest unsigned integer type on the platform, currently
6324 either "U32" or "U64". This can be used in declarations such as
6325 WIDEST_UTYPE my_uv;
6327 or casts
6329 my_uv = (WIDEST_UTYPE) val;
6331
6333 These are used for formatting the corresponding type For example,
6334 instead of saying
6335 Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\n", iv);
6337 use
6339 Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\n", iv);
6341 This keeps you from having to know if, say an IV, needs to be printed
6343 as %d, %ld, or something else.
6344 "IVdf"
6346 This symbol defines the format string used for printing a Perl IV
6347 as a signed decimal integer.
6348 "NVef"
6350 This symbol defines the format string used for printing a Perl NV
6351 using %e-ish floating point format.
6352 "NVff"
6354 This symbol defines the format string used for printing a Perl NV
6355 using %f-ish floating point format.
6356 "NVgf"
6358 This symbol defines the format string used for printing a Perl NV
6359 using %g-ish floating point format.
6360 "PERL_PRIeldbl"
6362 This symbol, if defined, contains the string used by stdio to
6363 format long doubles (format 'e') for output.
6364 "PERL_PRIfldbl"
6366 This symbol, if defined, contains the string used by stdio to
6367 format long doubles (format 'f') for output.
6368 "PERL_PRIgldbl"
6370 This symbol, if defined, contains the string used by stdio to
6371 format long doubles (format 'g') for output.
6372 "PERL_SCNfldbl"
6374 This symbol, if defined, contains the string used by stdio to
6375 format long doubles (format 'f') for input.
6376 "PRINTF_FORMAT_NULL_OK"
6378 Allows "__printf__" format to be null when checking printf-style
6379 "SVf"
6381 Described in perlguts.
6382 "SVfARG"
6384 Described in perlguts.
6385 SVfARG(SV *sv)
6387 "UTF8f"
6389 Described in perlguts.
6390 "UTF8fARG"
6392 Described in perlguts.
6393 UTF8fARG(bool is_utf8, Size_t byte_len, char *str)
6395 "UVf"
6397 "DEPRECATED!" It is planned to remove "UVf" from a future release
6398 of Perl. Do not use it for new code; remove it from existing code.
6399 Obsolete form of "UVuf", which you should convert to instead use
6401 const char * UVf
6403 "UVof"
6405 This symbol defines the format string used for printing a Perl UV
6406 as an unsigned octal integer.
6407 "UVuf"
6409 This symbol defines the format string used for printing a Perl UV
6410 as an unsigned decimal integer.
6411 "UVXf"
6413 This symbol defines the format string used for printing a Perl UV
6414 as an unsigned hexadecimal integer in uppercase "ABCDEF".
6415 "UVxf"
6417 This symbol defines the format string used for printing a Perl UV
6418 as an unsigned hexadecimal integer in lowercase abcdef.
6419
6421 This is the lower layer of the Perl parser, managing characters and
6422 tokens.
6423 "BHK"
6425 Described in perlguts.
6426 "lex_bufutf8"
6428 NOTE: "lex_bufutf8" is experimental and may change or be removed
6429 without notice.
6430 Indicates whether the octets in the lexer buffer
6432 ("PL_parser->linestr") should be interpreted as the UTF-8 encoding
6433 of Unicode characters. If not, they should be interpreted as
6434 Latin-1 characters. This is analogous to the "SvUTF8" flag for
6435 scalars.
6436 In UTF-8 mode, it is not guaranteed that the lexer buffer actually
6438 contains valid UTF-8. Lexing code must be robust in the face of
6439 invalid encoding.
6440 The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
6442 significant, but not the whole story regarding the input character
6443 encoding. Normally, when a file is being read, the scalar contains
6444 octets and its "SvUTF8" flag is off, but the octets should be
6445 interpreted as UTF-8 if the "use utf8" pragma is in effect. During
6446 a string eval, however, the scalar may have the "SvUTF8" flag on,
6447 and in this case its octets should be interpreted as UTF-8 unless
6448 the "use bytes" pragma is in effect. This logic may change in the
6449 future; use this function instead of implementing the logic
6450 yourself.
6451 bool lex_bufutf8()
6453 "lex_discard_to"
6455 NOTE: "lex_discard_to" is experimental and may change or be removed
6456 without notice.
6457 Discards the first part of the "PL_parser->linestr" buffer, up to
6459 "ptr". The remaining content of the buffer will be moved, and all
6460 pointers into the buffer updated appropriately. "ptr" must not be
6461 later in the buffer than the position of "PL_parser->bufptr": it is
6462 not permitted to discard text that has yet to be lexed.
6463 Normally it is not necessarily to do this directly, because it
6465 suffices to use the implicit discarding behaviour of
6466 "lex_next_chunk" and things based on it. However, if a token
6467 stretches across multiple lines, and the lexing code has kept
6468 multiple lines of text in the buffer for that purpose, then after
6469 completion of the token it would be wise to explicitly discard the
6470 now-unneeded earlier lines, to avoid future multi-line tokens
6471 growing the buffer without bound.
6472 void lex_discard_to(char* ptr)
6474 "lex_grow_linestr"
6476 NOTE: "lex_grow_linestr" is experimental and may change or be
6477 removed without notice.
6478 Reallocates the lexer buffer ("PL_parser->linestr") to accommodate
6480 at least "len" octets (including terminating "NUL"). Returns a
6481 pointer to the reallocated buffer. This is necessary before making
6482 any direct modification of the buffer that would increase its
6483 length. "lex_stuff_pvn" provides a more convenient way to insert
6484 text into the buffer.
6485 Do not use "SvGROW" or "sv_grow" directly on "PL_parser->linestr";
6487 this function updates all of the lexer's variables that point
6488 directly into the buffer.
6489 char* lex_grow_linestr(STRLEN len)
6491 "lex_next_chunk"
6493 NOTE: "lex_next_chunk" is experimental and may change or be removed
6494 without notice.
6495 Reads in the next chunk of text to be lexed, appending it to
6497 "PL_parser->linestr". This should be called when lexing code has
6498 looked to the end of the current chunk and wants to know more. It
6499 is usual, but not necessary, for lexing to have consumed the
6500 entirety of the current chunk at this time.
6501 If "PL_parser->bufptr" is pointing to the very end of the current
6503 chunk (i.e., the current chunk has been entirely consumed),
6504 normally the current chunk will be discarded at the same time that
6505 the new chunk is read in. If "flags" has the "LEX_KEEP_PREVIOUS"
6506 bit set, the current chunk will not be discarded. If the current
6507 chunk has not been entirely consumed, then it will not be discarded
6508 regardless of the flag.
6509 Returns true if some new text was added to the buffer, or false if
6511 the buffer has reached the end of the input text.
6512 bool lex_next_chunk(U32 flags)
6514 "lex_peek_unichar"
6516 NOTE: "lex_peek_unichar" is experimental and may change or be
6517 removed without notice.
6518 Looks ahead one (Unicode) character in the text currently being
6520 lexed. Returns the codepoint (unsigned integer value) of the next
6521 character, or -1 if lexing has reached the end of the input text.
6522 To consume the peeked character, use "lex_read_unichar".
6523 If the next character is in (or extends into) the next chunk of
6525 input text, the next chunk will be read in. Normally the current
6526 chunk will be discarded at the same time, but if "flags" has the
6527 "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
6528 discarded.
6529 If the input is being interpreted as UTF-8 and a UTF-8 encoding
6531 error is encountered, an exception is generated.
6532 I32 lex_peek_unichar(U32 flags)
6534 "lex_read_space"
6536 NOTE: "lex_read_space" is experimental and may change or be removed
6537 without notice.
6538 Reads optional spaces, in Perl style, in the text currently being
6540 lexed. The spaces may include ordinary whitespace characters and
6541 Perl-style comments. "#line" directives are processed if
6542 encountered. "PL_parser->bufptr" is moved past the spaces, so that
6543 it points at a non-space character (or the end of the input text).
6544 If spaces extend into the next chunk of input text, the next chunk
6546 will be read in. Normally the current chunk will be discarded at
6547 the same time, but if "flags" has the "LEX_KEEP_PREVIOUS" bit set,
6548 then the current chunk will not be discarded.
6549 void lex_read_space(U32 flags)
6551 "lex_read_to"
6553 NOTE: "lex_read_to" is experimental and may change or be removed
6554 without notice.
6555 Consume text in the lexer buffer, from "PL_parser->bufptr" up to
6557 "ptr". This advances "PL_parser->bufptr" to match "ptr",
6558 performing the correct bookkeeping whenever a newline character is
6559 passed. This is the normal way to consume lexed text.
6560 Interpretation of the buffer's octets can be abstracted out by
6562 using the slightly higher-level functions "lex_peek_unichar" and
6563 "lex_read_unichar".
6564 void lex_read_to(char* ptr)
6566 "lex_read_unichar"
6568 NOTE: "lex_read_unichar" is experimental and may change or be
6569 removed without notice.
6570 Reads the next (Unicode) character in the text currently being
6572 lexed. Returns the codepoint (unsigned integer value) of the
6573 character read, and moves "PL_parser->bufptr" past the character,
6574 or returns -1 if lexing has reached the end of the input text. To
6575 non-destructively examine the next character, use
6576 "lex_peek_unichar" instead.
6577 If the next character is in (or extends into) the next chunk of
6579 input text, the next chunk will be read in. Normally the current
6580 chunk will be discarded at the same time, but if "flags" has the
6581 "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
6582 discarded.
6583 If the input is being interpreted as UTF-8 and a UTF-8 encoding
6585 error is encountered, an exception is generated.
6586 I32 lex_read_unichar(U32 flags)
6588 "lex_start"
6590 NOTE: "lex_start" is experimental and may change or be removed
6591 without notice.
6592 Creates and initialises a new lexer/parser state object, supplying
6594 a context in which to lex and parse from a new source of Perl code.
6595 A pointer to the new state object is placed in "PL_parser". An
6596 entry is made on the save stack so that upon unwinding, the new
6597 state object will be destroyed and the former value of "PL_parser"
6598 will be restored. Nothing else need be done to clean up the
6599 parsing context.
6600 The code to be parsed comes from "line" and "rsfp". "line", if
6602 non-null, provides a string (in SV form) containing code to be
6603 parsed. A copy of the string is made, so subsequent modification
6604 of "line" does not affect parsing. "rsfp", if non-null, provides
6605 an input stream from which code will be read to be parsed. If both
6606 are non-null, the code in "line" comes first and must consist of
6607 complete lines of input, and "rsfp" supplies the remainder of the
6608 source.
6609 The "flags" parameter is reserved for future use. Currently it is
6611 only used by perl internally, so extensions should always pass
6612 zero.
6613 void lex_start(SV* line, PerlIO *rsfp, U32 flags)
6615 "lex_stuff_pv"
6617 NOTE: "lex_stuff_pv" is experimental and may change or be removed
6618 without notice.
6619 Insert characters into the lexer buffer ("PL_parser->linestr"),
6621 immediately after the current lexing point ("PL_parser->bufptr"),
6622 reallocating the buffer if necessary. This means that lexing code
6623 that runs later will see the characters as if they had appeared in
6624 the input. It is not recommended to do this as part of normal
6625 parsing, and most uses of this facility run the risk of the
6626 inserted characters being interpreted in an unintended manner.
6627 The string to be inserted is represented by octets starting at "pv"
6629 and continuing to the first nul. These octets are interpreted as
6630 either UTF-8 or Latin-1, according to whether the "LEX_STUFF_UTF8"
6631 flag is set in "flags". The characters are recoded for the lexer
6632 buffer, according to how the buffer is currently being interpreted
6633 ("lex_bufutf8"). If it is not convenient to nul-terminate a string
6634 to be inserted, the "lex_stuff_pvn" function is more appropriate.
6635 void lex_stuff_pv(const char* pv, U32 flags)
6637 "lex_stuff_pvn"
6639 NOTE: "lex_stuff_pvn" is experimental and may change or be removed
6640 without notice.
6641 Insert characters into the lexer buffer ("PL_parser->linestr"),
6643 immediately after the current lexing point ("PL_parser->bufptr"),
6644 reallocating the buffer if necessary. This means that lexing code
6645 that runs later will see the characters as if they had appeared in
6646 the input. It is not recommended to do this as part of normal
6647 parsing, and most uses of this facility run the risk of the
6648 inserted characters being interpreted in an unintended manner.
6649 The string to be inserted is represented by "len" octets starting
6651 at "pv". These octets are interpreted as either UTF-8 or Latin-1,
6652 according to whether the "LEX_STUFF_UTF8" flag is set in "flags".
6653 The characters are recoded for the lexer buffer, according to how
6654 the buffer is currently being interpreted ("lex_bufutf8"). If a
6655 string to be inserted is available as a Perl scalar, the
6656 "lex_stuff_sv" function is more convenient.
6657 void lex_stuff_pvn(const char* pv, STRLEN len, U32 flags)
6659 "lex_stuff_pvs"
6661 NOTE: "lex_stuff_pvs" is experimental and may change or be removed
6662 without notice.
6663 Like "lex_stuff_pvn", but takes a literal string instead of a
6665 string/length pair.
6666 void lex_stuff_pvs("pv", U32 flags)
6668 "lex_stuff_sv"
6670 NOTE: "lex_stuff_sv" is experimental and may change or be removed
6671 without notice.
6672 Insert characters into the lexer buffer ("PL_parser->linestr"),
6674 immediately after the current lexing point ("PL_parser->bufptr"),
6675 reallocating the buffer if necessary. This means that lexing code
6676 that runs later will see the characters as if they had appeared in
6677 the input. It is not recommended to do this as part of normal
6678 parsing, and most uses of this facility run the risk of the
6679 inserted characters being interpreted in an unintended manner.
6680 The string to be inserted is the string value of "sv". The
6682 characters are recoded for the lexer buffer, according to how the
6683 buffer is currently being interpreted ("lex_bufutf8"). If a string
6684 to be inserted is not already a Perl scalar, the "lex_stuff_pvn"
6685 function avoids the need to construct a scalar.
6686 void lex_stuff_sv(SV* sv, U32 flags)
6688 "lex_unstuff"
6690 NOTE: "lex_unstuff" is experimental and may change or be removed
6691 without notice.
6692 Discards text about to be lexed, from "PL_parser->bufptr" up to
6694 "ptr". Text following "ptr" will be moved, and the buffer
6695 shortened. This hides the discarded text from any lexing code that
6696 runs later, as if the text had never appeared.
6697 This is not the normal way to consume lexed text. For that, use
6699 "lex_read_to".
6700 void lex_unstuff(char* ptr)
6702 "parse_arithexpr"
6704 NOTE: "parse_arithexpr" is experimental and may change or be
6705 removed without notice.
6706 Parse a Perl arithmetic expression. This may contain operators of
6708 precedence down to the bit shift operators. The expression must be
6709 followed (and thus terminated) either by a comparison or lower-
6710 precedence operator or by something that would normally terminate
6711 an expression such as semicolon. If "flags" has the
6712 "PARSE_OPTIONAL" bit set, then the expression is optional,
6713 otherwise it is mandatory. It is up to the caller to ensure that
6714 the dynamic parser state ("PL_parser" et al) is correctly set to
6715 reflect the source of the code to be parsed and the lexical context
6716 for the expression.
6717 The op tree representing the expression is returned. If an
6719 optional expression is absent, a null pointer is returned,
6720 otherwise the pointer will be non-null.
6721 If an error occurs in parsing or compilation, in most cases a valid
6723 op tree is returned anyway. The error is reflected in the parser
6724 state, normally resulting in a single exception at the top level of
6725 parsing which covers all the compilation errors that occurred.
6726 Some compilation errors, however, will throw an exception
6727 immediately.
6728 OP* parse_arithexpr(U32 flags)
6730 "parse_barestmt"
6732 NOTE: "parse_barestmt" is experimental and may change or be removed
6733 without notice.
6734 Parse a single unadorned Perl statement. This may be a normal
6736 imperative statement or a declaration that has compile-time effect.
6737 It does not include any label or other affixture. It is up to the
6738 caller to ensure that the dynamic parser state ("PL_parser" et al)
6739 is correctly set to reflect the source of the code to be parsed and
6740 the lexical context for the statement.
6741 The op tree representing the statement is returned. This may be a
6743 null pointer if the statement is null, for example if it was
6744 actually a subroutine definition (which has compile-time side
6745 effects). If not null, it will be ops directly implementing the
6746 statement, suitable to pass to "newSTATEOP". It will not normally
6747 include a "nextstate" or equivalent op (except for those embedded
6748 in a scope contained entirely within the statement).
6749 If an error occurs in parsing or compilation, in most cases a valid
6751 op tree (most likely null) is returned anyway. The error is
6752 reflected in the parser state, normally resulting in a single
6753 exception at the top level of parsing which covers all the
6754 compilation errors that occurred. Some compilation errors,
6755 however, will throw an exception immediately.
6756 The "flags" parameter is reserved for future use, and must always
6758 be zero.
6759 OP* parse_barestmt(U32 flags)
6761 "parse_block"
6763 NOTE: "parse_block" is experimental and may change or be removed
6764 without notice.
6765 Parse a single complete Perl code block. This consists of an
6767 opening brace, a sequence of statements, and a closing brace. The
6768 block constitutes a lexical scope, so "my" variables and various
6769 compile-time effects can be contained within it. It is up to the
6770 caller to ensure that the dynamic parser state ("PL_parser" et al)
6771 is correctly set to reflect the source of the code to be parsed and
6772 the lexical context for the statement.
6773 The op tree representing the code block is returned. This is
6775 always a real op, never a null pointer. It will normally be a
6776 "lineseq" list, including "nextstate" or equivalent ops. No ops to
6777 construct any kind of runtime scope are included by virtue of it
6778 being a block.
6779 If an error occurs in parsing or compilation, in most cases a valid
6781 op tree (most likely null) is returned anyway. The error is
6782 reflected in the parser state, normally resulting in a single
6783 exception at the top level of parsing which covers all the
6784 compilation errors that occurred. Some compilation errors,
6785 however, will throw an exception immediately.
6786 The "flags" parameter is reserved for future use, and must always
6788 be zero.
6789 OP* parse_block(U32 flags)
6791 "parse_fullexpr"
6793 NOTE: "parse_fullexpr" is experimental and may change or be removed
6794 without notice.
6795 Parse a single complete Perl expression. This allows the full
6797 expression grammar, including the lowest-precedence operators such
6798 as "or". The expression must be followed (and thus terminated) by
6799 a token that an expression would normally be terminated by: end-of-
6800 file, closing bracketing punctuation, semicolon, or one of the
6801 keywords that signals a postfix expression-statement modifier. If
6802 "flags" has the "PARSE_OPTIONAL" bit set, then the expression is
6803 optional, otherwise it is mandatory. It is up to the caller to
6804 ensure that the dynamic parser state ("PL_parser" et al) is
6805 correctly set to reflect the source of the code to be parsed and
6806 the lexical context for the expression.
6807 The op tree representing the expression is returned. If an
6809 optional expression is absent, a null pointer is returned,
6810 otherwise the pointer will be non-null.
6811 If an error occurs in parsing or compilation, in most cases a valid
6813 op tree is returned anyway. The error is reflected in the parser
6814 state, normally resulting in a single exception at the top level of
6815 parsing which covers all the compilation errors that occurred.
6816 Some compilation errors, however, will throw an exception
6817 immediately.
6818 OP* parse_fullexpr(U32 flags)
6820 "parse_fullstmt"
6822 NOTE: "parse_fullstmt" is experimental and may change or be removed
6823 without notice.
6824 Parse a single complete Perl statement. This may be a normal
6826 imperative statement or a declaration that has compile-time effect,
6827 and may include optional labels. It is up to the caller to ensure
6828 that the dynamic parser state ("PL_parser" et al) is correctly set
6829 to reflect the source of the code to be parsed and the lexical
6830 context for the statement.
6831 The op tree representing the statement is returned. This may be a
6833 null pointer if the statement is null, for example if it was
6834 actually a subroutine definition (which has compile-time side
6835 effects). If not null, it will be the result of a "newSTATEOP"
6836 call, normally including a "nextstate" or equivalent op.
6837 If an error occurs in parsing or compilation, in most cases a valid
6839 op tree (most likely null) is returned anyway. The error is
6840 reflected in the parser state, normally resulting in a single
6841 exception at the top level of parsing which covers all the
6842 compilation errors that occurred. Some compilation errors,
6843 however, will throw an exception immediately.
6844 The "flags" parameter is reserved for future use, and must always
6846 be zero.
6847 OP* parse_fullstmt(U32 flags)
6849 "parse_label"
6851 NOTE: "parse_label" is experimental and may change or be removed
6852 without notice.
6853 Parse a single label, possibly optional, of the type that may
6855 prefix a Perl statement. It is up to the caller to ensure that the
6856 dynamic parser state ("PL_parser" et al) is correctly set to
6857 reflect the source of the code to be parsed. If "flags" has the
6858 "PARSE_OPTIONAL" bit set, then the label is optional, otherwise it
6859 is mandatory.
6860 The name of the label is returned in the form of a fresh scalar.
6862 If an optional label is absent, a null pointer is returned.
6863 If an error occurs in parsing, which can only occur if the label is
6865 mandatory, a valid label is returned anyway. The error is
6866 reflected in the parser state, normally resulting in a single
6867 exception at the top level of parsing which covers all the
6868 compilation errors that occurred.
6869 SV* parse_label(U32 flags)
6871 "parse_listexpr"
6873 NOTE: "parse_listexpr" is experimental and may change or be removed
6874 without notice.
6875 Parse a Perl list expression. This may contain operators of
6877 precedence down to the comma operator. The expression must be
6878 followed (and thus terminated) either by a low-precedence logic
6879 operator such as "or" or by something that would normally terminate
6880 an expression such as semicolon. If "flags" has the
6881 "PARSE_OPTIONAL" bit set, then the expression is optional,
6882 otherwise it is mandatory. It is up to the caller to ensure that
6883 the dynamic parser state ("PL_parser" et al) is correctly set to
6884 reflect the source of the code to be parsed and the lexical context
6885 for the expression.
6886 The op tree representing the expression is returned. If an
6888 optional expression is absent, a null pointer is returned,
6889 otherwise the pointer will be non-null.
6890 If an error occurs in parsing or compilation, in most cases a valid
6892 op tree is returned anyway. The error is reflected in the parser
6893 state, normally resulting in a single exception at the top level of
6894 parsing which covers all the compilation errors that occurred.
6895 Some compilation errors, however, will throw an exception
6896 immediately.
6897 OP* parse_listexpr(U32 flags)
6899 "parse_stmtseq"
6901 NOTE: "parse_stmtseq" is experimental and may change or be removed
6902 without notice.
6903 Parse a sequence of zero or more Perl statements. These may be
6905 normal imperative statements, including optional labels, or
6906 declarations that have compile-time effect, or any mixture thereof.
6907 The statement sequence ends when a closing brace or end-of-file is
6908 encountered in a place where a new statement could have validly
6909 started. It is up to the caller to ensure that the dynamic parser
6910 state ("PL_parser" et al) is correctly set to reflect the source of
6911 the code to be parsed and the lexical context for the statements.
6912 The op tree representing the statement sequence is returned. This
6914 may be a null pointer if the statements were all null, for example
6915 if there were no statements or if there were only subroutine
6916 definitions (which have compile-time side effects). If not null,
6917 it will be a "lineseq" list, normally including "nextstate" or
6918 equivalent ops.
6919 If an error occurs in parsing or compilation, in most cases a valid
6921 op tree is returned anyway. The error is reflected in the parser
6922 state, normally resulting in a single exception at the top level of
6923 parsing which covers all the compilation errors that occurred.
6924 Some compilation errors, however, will throw an exception
6925 immediately.
6926 The "flags" parameter is reserved for future use, and must always
6928 be zero.
6929 OP* parse_stmtseq(U32 flags)
6931 "parse_subsignature"
6933 NOTE: "parse_subsignature" is experimental and may change or be
6934 removed without notice.
6935 Parse a subroutine signature declaration. This is the contents of
6937 the parentheses following a named or anonymous subroutine
6938 declaration when the "signatures" feature is enabled. Note that
6939 this function neither expects nor consumes the opening and closing
6940 parentheses around the signature; it is the caller's job to handle
6941 these.
6942 This function must only be called during parsing of a subroutine;
6944 after "start_subparse" has been called. It might allocate lexical
6945 variables on the pad for the current subroutine.
6946 The op tree to unpack the arguments from the stack at runtime is
6948 returned. This op tree should appear at the beginning of the
6949 compiled function. The caller may wish to use "op_append_list" to
6950 build their function body after it, or splice it together with the
6951 body before calling "newATTRSUB".
6952 The "flags" parameter is reserved for future use, and must always
6954 be zero.
6955 OP* parse_subsignature(U32 flags)
6957 "parse_termexpr"
6959 NOTE: "parse_termexpr" is experimental and may change or be removed
6960 without notice.
6961 Parse a Perl term expression. This may contain operators of
6963 precedence down to the assignment operators. The expression must
6964 be followed (and thus terminated) either by a comma or lower-
6965 precedence operator or by something that would normally terminate
6966 an expression such as semicolon. If "flags" has the
6967 "PARSE_OPTIONAL" bit set, then the expression is optional,
6968 otherwise it is mandatory. It is up to the caller to ensure that
6969 the dynamic parser state ("PL_parser" et al) is correctly set to
6970 reflect the source of the code to be parsed and the lexical context
6971 for the expression.
6972 The op tree representing the expression is returned. If an
6974 optional expression is absent, a null pointer is returned,
6975 otherwise the pointer will be non-null.
6976 If an error occurs in parsing or compilation, in most cases a valid
6978 op tree is returned anyway. The error is reflected in the parser
6979 state, normally resulting in a single exception at the top level of
6980 parsing which covers all the compilation errors that occurred.
6981 Some compilation errors, however, will throw an exception
6982 immediately.
6983 OP* parse_termexpr(U32 flags)
6985 "PL_parser"
6987 Pointer to a structure encapsulating the state of the parsing
6988 operation currently in progress. The pointer can be locally
6989 changed to perform a nested parse without interfering with the
6990 state of an outer parse. Individual members of "PL_parser" have
6991 their own documentation.
6992 "PL_parser->bufend"
6994 NOTE: "PL_parser->bufend" is experimental and may change or be
6995 removed without notice.
6996 Direct pointer to the end of the chunk of text currently being
6998 lexed, the end of the lexer buffer. This is equal to
6999 "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)". A "NUL"
7000 character (zero octet) is always located at the end of the buffer,
7001 and does not count as part of the buffer's contents.
7002 "PL_parser->bufptr"
7004 NOTE: "PL_parser->bufptr" is experimental and may change or be
7005 removed without notice.
7006 Points to the current position of lexing inside the lexer buffer.
7008 Characters around this point may be freely examined, within the
7009 range delimited by "SvPVX("PL_parser->linestr")" and
7010 "PL_parser->bufend". The octets of the buffer may be intended to
7011 be interpreted as either UTF-8 or Latin-1, as indicated by
7012 "lex_bufutf8".
7013 Lexing code (whether in the Perl core or not) moves this pointer
7015 past the characters that it consumes. It is also expected to
7016 perform some bookkeeping whenever a newline character is consumed.
7017 This movement can be more conveniently performed by the function
7018 "lex_read_to", which handles newlines appropriately.
7019 Interpretation of the buffer's octets can be abstracted out by
7021 using the slightly higher-level functions "lex_peek_unichar" and
7022 "lex_read_unichar".
7023 "PL_parser->linestart"
7025 NOTE: "PL_parser->linestart" is experimental and may change or be
7026 removed without notice.
7027 Points to the start of the current line inside the lexer buffer.
7029 This is useful for indicating at which column an error occurred,
7030 and not much else. This must be updated by any lexing code that
7031 consumes a newline; the function "lex_read_to" handles this detail.
7032 "PL_parser->linestr"
7034 NOTE: "PL_parser->linestr" is experimental and may change or be
7035 removed without notice.
7036 Buffer scalar containing the chunk currently under consideration of
7038 the text currently being lexed. This is always a plain string
7039 scalar (for which "SvPOK" is true). It is not intended to be used
7040 as a scalar by normal scalar means; instead refer to the buffer
7041 directly by the pointer variables described below.
7042 The lexer maintains various "char*" pointers to things in the
7044 "PL_parser->linestr" buffer. If "PL_parser->linestr" is ever
7045 reallocated, all of these pointers must be updated. Don't attempt
7046 to do this manually, but rather use "lex_grow_linestr" if you need
7047 to reallocate the buffer.
7048 The content of the text chunk in the buffer is commonly exactly one
7050 complete line of input, up to and including a newline terminator,
7051 but there are situations where it is otherwise. The octets of the
7052 buffer may be intended to be interpreted as either UTF-8 or
7053 Latin-1. The function "lex_bufutf8" tells you which. Do not use
7054 the "SvUTF8" flag on this scalar, which may disagree with it.
7055 For direct examination of the buffer, the variable
7057 "PL_parser->bufend" points to the end of the buffer. The current
7058 lexing position is pointed to by "PL_parser->bufptr". Direct use
7059 of these pointers is usually preferable to examination of the
7060 scalar through normal scalar means.
7061 "wrap_keyword_plugin"
7063 NOTE: "wrap_keyword_plugin" is experimental and may change or be
7064 removed without notice.
7065 Puts a C function into the chain of keyword plugins. This is the
7067 preferred way to manipulate the "PL_keyword_plugin" variable.
7068 "new_plugin" is a pointer to the C function that is to be added to
7069 the keyword plugin chain, and "old_plugin_p" points to the storage
7070 location where a pointer to the next function in the chain will be
7071 stored. The value of "new_plugin" is written into the
7072 "PL_keyword_plugin" variable, while the value previously stored
7073 there is written to *old_plugin_p.
7074 "PL_keyword_plugin" is global to an entire process, and a module
7076 wishing to hook keyword parsing may find itself invoked more than
7077 once per process, typically in different threads. To handle that
7078 situation, this function is idempotent. The location *old_plugin_p
7079 must initially (once per process) contain a null pointer. A C
7080 variable of static duration (declared at file scope, typically also
7081 marked "static" to give it internal linkage) will be implicitly
7082 initialised appropriately, if it does not have an explicit
7083 initialiser. This function will only actually modify the plugin
7084 chain if it finds *old_plugin_p to be null. This function is also
7085 thread safe on the small scale. It uses appropriate locking to
7086 avoid race conditions in accessing "PL_keyword_plugin".
7087 When this function is called, the function referenced by
7089 "new_plugin" must be ready to be called, except for *old_plugin_p
7090 being unfilled. In a threading situation, "new_plugin" may be
7091 called immediately, even before this function has returned.
7092 *old_plugin_p will always be appropriately set before "new_plugin"
7093 is called. If "new_plugin" decides not to do anything special with
7094 the identifier that it is given (which is the usual case for most
7095 calls to a keyword plugin), it must chain the plugin function
7096 referenced by *old_plugin_p.
7097 Taken all together, XS code to install a keyword plugin should
7099 typically look something like this:
7100 static Perl_keyword_plugin_t next_keyword_plugin;
7102 static OP *my_keyword_plugin(pTHX_
7103 char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
7104 {
7105 if (memEQs(keyword_ptr, keyword_len,
7106 "my_new_keyword")) {
7107 ...
7108 } else {
7109 return next_keyword_plugin(aTHX_
7110 keyword_ptr, keyword_len, op_ptr);
7111 }
7112 }
7113 BOOT:
7114 wrap_keyword_plugin(my_keyword_plugin,
7115 &next_keyword_plugin);
7116 Direct access to "PL_keyword_plugin" should be avoided.
7118 void wrap_keyword_plugin(Perl_keyword_plugin_t new_plugin,
7120 Perl_keyword_plugin_t *old_plugin_p)
7121
7123 "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
7124 This macro should be used as a statement. It declares a private
7125 variable (whose name begins with an underscore) that is needed by
7126 the other macros in this section. Failing to include this
7127 correctly should lead to a syntax error. For compatibility with
7128 C89 C compilers it should be placed in a block before any
7129 executable statements.
7130 void DECLARATION_FOR_LC_NUMERIC_MANIPULATION
7132 "foldEQ_locale"
7134 Returns true if the leading "len" bytes of the strings "s1" and
7135 "s2" are the same case-insensitively in the current locale; false
7136 otherwise.
7137 I32 foldEQ_locale(const char* a, const char* b, I32 len)
7139 "HAS_DUPLOCALE"
7141 This symbol, if defined, indicates that the "duplocale" routine is
7142 available to duplicate a locale object.
7143 "HAS_FREELOCALE"
7145 This symbol, if defined, indicates that the "freelocale" routine is
7146 available to deallocates the resources associated with a locale
7147 object.
7148 "HAS_LC_MONETARY_2008"
7150 This symbol, if defined, indicates that the localeconv routine is
7151 available and has the additional members added in "POSIX"
7152 1003.1-2008.
7153 "HAS_LOCALECONV"
7155 This symbol, if defined, indicates that the "localeconv" routine is
7156 available for numeric and monetary formatting conventions.
7157 "HAS_LOCALECONV_L"
7159 This symbol, if defined, indicates that the "localeconv_l" routine
7160 is available to query certain information about a locale.
7161 "HAS_NEWLOCALE"
7163 This symbol, if defined, indicates that the "newlocale" routine is
7164 available to return a new locale object or modify an existing
7165 locale object.
7166 "HAS_NL_LANGINFO"
7168 This symbol, if defined, indicates that the "nl_langinfo" routine
7169 is available to return local data. You will also need langinfo.h
7170 and therefore "I_LANGINFO".
7171 "HAS_NL_LANGINFO_L"
7173 This symbol, when defined, indicates presence of the
7174 "nl_langinfo_l()" function
7175 "HAS_QUERYLOCALE"
7177 This symbol, if defined, indicates that the "querylocale" routine
7178 is available to return the name of the locale for a category mask.
7179 "HAS_SETLOCALE"
7181 This symbol, if defined, indicates that the "setlocale" routine is
7182 available to handle locale-specific ctype implementations.
7183 "HAS_SETLOCALE_R"
7185 This symbol, if defined, indicates that the "setlocale_r" routine
7186 is available to setlocale re-entrantly.
7187 "HAS_THREAD_SAFE_NL_LANGINFO_L"
7189 This symbol, when defined, indicates presence of the
7190 "nl_langinfo_l()" function, and that it is thread-safe.
7191 "HAS_USELOCALE"
7193 This symbol, if defined, indicates that the "uselocale" routine is
7194 available to set the current locale for the calling thread.
7195 "I_LANGINFO"
7197 This symbol, if defined, indicates that langinfo.h exists and
7198 should be included.
7199 #ifdef I_LANGINFO
7201 #include <langinfo.h>
7202 #endif
7203 "I_LOCALE"
7205 This symbol, if defined, indicates to the C program that it should
7206 include locale.h.
7207 #ifdef I_LOCALE
7209 #include <locale.h>
7210 #endif
7211 "IN_LOCALE"
7213 Evaluates to TRUE if the plain locale pragma without a parameter
7214 ("use locale") is in effect.
7215 bool IN_LOCALE
7217 "IN_LOCALE_COMPILETIME"
7219 Evaluates to TRUE if, when compiling a perl program (including an
7220 "eval") if the plain locale pragma without a parameter
7221 ("use locale") is in effect.
7222 bool IN_LOCALE_COMPILETIME
7224 "IN_LOCALE_RUNTIME"
7226 Evaluates to TRUE if, when executing a perl program (including an
7227 "eval") if the plain locale pragma without a parameter
7228 ("use locale") is in effect.
7229 bool IN_LOCALE_RUNTIME
7231 "I_XLOCALE"
7233 This symbol, if defined, indicates to the C program that the header
7234 xlocale.h is available. See also "NEED_XLOCALE_H"
7235 #ifdef I_XLOCALE
7237 #include <xlocale.h>
7238 #endif
7239 "NEED_XLOCALE_H"
7241 This symbol, if defined, indicates that the C program should
7242 include xlocale.h to get "newlocale()" and its friends.
7243 "Perl_langinfo"
7245 This is an (almost) drop-in replacement for the system
7246 nl_langinfo(3), taking the same "item" parameter values, and
7247 returning the same information. But it is more thread-safe than
7248 regular "nl_langinfo()", and hides the quirks of Perl's locale
7249 handling from your code, and can be used on systems that lack a
7250 native "nl_langinfo".
7251 Expanding on these:
7253 • The reason it isn't quite a drop-in replacement is actually an
7255 advantage. The only difference is that it returns
7256 "const char *", whereas plain "nl_langinfo()" returns "char *",
7257 but you are (only by documentation) forbidden to write into the
7258 buffer. By declaring this "const", the compiler enforces this
7259 restriction, so if it is violated, you know at compilation
7260 time, rather than getting segfaults at runtime.
7261 • It delivers the correct results for the "RADIXCHAR" and
7263 "THOUSEP" items, without you having to write extra code. The
7264 reason for the extra code would be because these are from the
7265 "LC_NUMERIC" locale category, which is normally kept set by
7266 Perl so that the radix is a dot, and the separator is the empty
7267 string, no matter what the underlying locale is supposed to be,
7268 and so to get the expected results, you have to temporarily
7269 toggle into the underlying locale, and later toggle back. (You
7270 could use plain "nl_langinfo" and
7271 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" for this but then you
7272 wouldn't get the other advantages of "Perl_langinfo()"; not
7273 keeping "LC_NUMERIC" in the C (or equivalent) locale would
7274 break a lot of CPAN, which is expecting the radix (decimal
7275 point) character to be a dot.)
7276 • The system function it replaces can have its static return
7278 buffer trashed, not only by a subsequent call to that function,
7279 but by a "freelocale", "setlocale", or other locale change.
7280 The returned buffer of this function is not changed until the
7281 next call to it, so the buffer is never in a trashed state.
7282 • Its return buffer is per-thread, so it also is never
7284 overwritten by a call to this function from another thread;
7285 unlike the function it replaces.
7286 • But most importantly, it works on systems that don't have
7288 "nl_langinfo", such as Windows, hence makes your code more
7289 portable. Of the fifty-some possible items specified by the
7290 POSIX 2008 standard,
7291 <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
7292 only one is completely unimplemented, though on non-Windows
7293 platforms, another significant one is also not implemented).
7294 It uses various techniques to recover the other items,
7295 including calling localeconv(3), and strftime(3), both of which
7296 are specified in C89, so should be always be available. Later
7297 "strftime()" versions have additional capabilities; "" is
7298 returned for those not available on your system.
7299 It is important to note that when called with an item that is
7301 recovered by using "localeconv", the buffer from any previous
7302 explicit call to "localeconv" will be overwritten. This means
7303 you must save that buffer's contents if you need to access them
7304 after a call to this function. (But note that you might not
7305 want to be using "localeconv()" directly anyway, because of
7306 issues like the ones listed in the second item of this list
7307 (above) for "RADIXCHAR" and "THOUSEP". You can use the methods
7308 given in perlcall to call "localeconv" in POSIX and avoid all
7309 the issues, but then you have a hash to unpack).
7310 The details for those items which may deviate from what this
7312 emulation returns and what a native "nl_langinfo()" would
7313 return are specified in I18N::Langinfo.
7314 When using "Perl_langinfo" on systems that don't have a native
7316 "nl_langinfo()", you must
7317 #include "perl_langinfo.h"
7319 before the "perl.h" "#include". You can replace your "langinfo.h"
7321 "#include" with this one. (Doing it this way keeps out the symbols
7322 that plain "langinfo.h" would try to import into the namespace for
7323 code that doesn't need it.)
7324 The original impetus for "Perl_langinfo()" was so that code that
7326 needs to find out the current currency symbol, floating point radix
7327 character, or digit grouping separator can use, on all systems, the
7328 simpler and more thread-friendly "nl_langinfo" API instead of
7329 localeconv(3) which is a pain to make thread-friendly. For other
7330 fields returned by "localeconv", it is better to use the methods
7331 given in perlcall to call "POSIX::localeconv()", which is thread-
7332 friendly.
7333 const char* Perl_langinfo(const nl_item item)
7335 "Perl_setlocale"
7337 This is an (almost) drop-in replacement for the system
7338 setlocale(3), taking the same parameters, and returning the same
7339 information, except that it returns the correct underlying
7340 "LC_NUMERIC" locale. Regular "setlocale" will instead return "C"
7341 if the underlying locale has a non-dot decimal point character, or
7342 a non-empty thousands separator for displaying floating point
7343 numbers. This is because perl keeps that locale category such that
7344 it has a dot and empty separator, changing the locale briefly
7345 during the operations where the underlying one is required.
7346 "Perl_setlocale" knows about this, and compensates; regular
7347 "setlocale" doesn't.
7348 Another reason it isn't completely a drop-in replacement is that it
7350 is declared to return "const char *", whereas the system setlocale
7351 omits the "const" (presumably because its API was specified long
7352 ago, and can't be updated; it is illegal to change the information
7353 "setlocale" returns; doing so leads to segfaults.)
7354 Finally, "Perl_setlocale" works under all circumstances, whereas
7356 plain "setlocale" can be completely ineffective on some platforms
7357 under some configurations.
7358 "Perl_setlocale" should not be used to change the locale except on
7360 systems where the predefined variable "${^SAFE_LOCALES}" is 1. On
7361 some such systems, the system "setlocale()" is ineffective,
7362 returning the wrong information, and failing to actually change the
7363 locale. "Perl_setlocale", however works properly in all
7364 circumstances.
7365 The return points to a per-thread static buffer, which is
7367 overwritten the next time "Perl_setlocale" is called from the same
7368 thread.
7369 const char* Perl_setlocale(const int category,
7371 const char* locale)
7372 "RESTORE_LC_NUMERIC"
7374 This is used in conjunction with one of the macros
7375 "STORE_LC_NUMERIC_SET_TO_NEEDED" and
7376 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
7377 "LC_NUMERIC" state.
7378 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
7380 made to declare at compile time a private variable used by this
7381 macro and the two "STORE" ones. This macro should be called as a
7382 single statement, not an expression, but with an empty argument
7383 list, like this:
7384 {
7386 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7387 ...
7388 RESTORE_LC_NUMERIC();
7389 ...
7390 }
7391 void RESTORE_LC_NUMERIC()
7393 "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
7395 This symbol, if defined, indicates that the setlocale routine is
7396 available and it accepts any input locale name as valid.
7397 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
7399 This is used by XS code that is "LC_NUMERIC" locale-aware to force
7400 the locale for category "LC_NUMERIC" to be what perl thinks is the
7401 current underlying locale. (The perl interpreter could be wrong
7402 about what the underlying locale actually is if some C or XS code
7403 has called the C library function setlocale(3) behind its back;
7404 calling "sync_locale" before calling this macro will update perl's
7405 records.)
7406 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
7408 made to declare at compile time a private variable used by this
7409 macro. This macro should be called as a single statement, not an
7410 expression, but with an empty argument list, like this:
7411 {
7413 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7414 ...
7415 STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
7416 ...
7417 RESTORE_LC_NUMERIC();
7418 ...
7419 }
7420 The private variable is used to save the current locale state, so
7422 that the requisite matching call to "RESTORE_LC_NUMERIC" can
7423 restore it.
7424 On threaded perls not operating with thread-safe functionality,
7426 this macro uses a mutex to force a critical section. Therefore the
7427 matching RESTORE should be close by, and guaranteed to be called.
7428 void STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
7430 "STORE_LC_NUMERIC_SET_TO_NEEDED"
7432 This is used to help wrap XS or C code that is "LC_NUMERIC" locale-
7433 aware. This locale category is generally kept set to a locale
7434 where the decimal radix character is a dot, and the separator
7435 between groups of digits is empty. This is because most XS code
7436 that reads floating point numbers is expecting them to have this
7437 syntax.
7438 This macro makes sure the current "LC_NUMERIC" state is set
7440 properly, to be aware of locale if the call to the XS or C code
7441 from the Perl program is from within the scope of a "use locale";
7442 or to ignore locale if the call is instead from outside such scope.
7443 This macro is the start of wrapping the C or XS code; the wrap
7445 ending is done by calling the "RESTORE_LC_NUMERIC" macro after the
7446 operation. Otherwise the state can be changed that will adversely
7447 affect other XS code.
7448 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
7450 made to declare at compile time a private variable used by this
7451 macro. This macro should be called as a single statement, not an
7452 expression, but with an empty argument list, like this:
7453 {
7455 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7456 ...
7457 STORE_LC_NUMERIC_SET_TO_NEEDED();
7458 ...
7459 RESTORE_LC_NUMERIC();
7460 ...
7461 }
7462 On threaded perls not operating with thread-safe functionality,
7464 this macro uses a mutex to force a critical section. Therefore the
7465 matching RESTORE should be close by, and guaranteed to be called;
7466 see "WITH_LC_NUMERIC_SET_TO_NEEDED" for a more contained way to
7467 ensure that.
7468 void STORE_LC_NUMERIC_SET_TO_NEEDED()
7470 "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
7472 Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
7473 provided as the precalculated value of "IN_LC(LC_NUMERIC)". It is
7474 the caller's responsibility to ensure that the status of
7475 "PL_compiling" and "PL_hints" cannot have changed since the
7476 precalculation.
7477 void STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric)
7479 "switch_to_global_locale"
7481 On systems without locale support, or on typical single-threaded
7482 builds, or on platforms that do not support per-thread locale
7483 operations, this function does nothing. On such systems that do
7484 have locale support, only a locale global to the whole program is
7485 available.
7486 On multi-threaded builds on systems that do have per-thread locale
7488 operations, this function converts the thread it is running in to
7489 use the global locale. This is for code that has not yet or cannot
7490 be updated to handle multi-threaded locale operation. As long as
7491 only a single thread is so-converted, everything works fine, as all
7492 the other threads continue to ignore the global one, so only this
7493 thread looks at it.
7494 However, on Windows systems this isn't quite true prior to Visual
7496 Studio 15, at which point Microsoft fixed a bug. A race can occur
7497 if you use the following operations on earlier Windows platforms:
7498 POSIX::localeconv
7500 I18N::Langinfo, items "CRNCYSTR" and "THOUSEP"
7501 "Perl_langinfo" in perlapi, items "CRNCYSTR" and "THOUSEP"
7502 The first item is not fixable (except by upgrading to a later
7504 Visual Studio release), but it would be possible to work around the
7505 latter two items by using the Windows API functions
7506 "GetNumberFormat" and "GetCurrencyFormat"; patches welcome.
7507 Without this function call, threads that use the setlocale(3)
7509 system function will not work properly, as all the locale-sensitive
7510 functions will look at the per-thread locale, and "setlocale" will
7511 have no effect on this thread.
7512 Perl code should convert to either call "Perl_setlocale" (which is
7514 a drop-in for the system "setlocale") or use the methods given in
7515 perlcall to call "POSIX::setlocale". Either one will transparently
7516 properly handle all cases of single- vs multi-thread, POSIX
7517 2008-supported or not.
7518 Non-Perl libraries, such as "gtk", that call the system "setlocale"
7520 can continue to work if this function is called before transferring
7521 control to the library.
7522 Upon return from the code that needs to use the global locale,
7524 "sync_locale()" should be called to restore the safe multi-thread
7525 operation.
7526 void switch_to_global_locale()
7528 "sync_locale"
7530 "Perl_setlocale" can be used at any time to query or change the
7531 locale (though changing the locale is antisocial and dangerous on
7532 multi-threaded systems that don't have multi-thread safe locale
7533 operations. (See "Multi-threaded operation" in perllocale). Using
7534 the system setlocale(3) should be avoided. Nevertheless, certain
7535 non-Perl libraries called from XS, such as "Gtk" do so, and this
7536 can't be changed. When the locale is changed by XS code that
7537 didn't use "Perl_setlocale", Perl needs to be told that the locale
7538 has changed. Use this function to do so, before returning to Perl.
7539 The return value is a boolean: TRUE if the global locale at the
7541 time of call was in effect; and FALSE if a per-thread locale was in
7542 effect. This can be used by the caller that needs to restore
7543 things as-they-were to decide whether or not to call
7544 "Perl_switch_to_global_locale".
7545 bool sync_locale()
7547 "WITH_LC_NUMERIC_SET_TO_NEEDED"
7549 This macro invokes the supplied statement or block within the
7550 context of a "STORE_LC_NUMERIC_SET_TO_NEEDED" ..
7551 "RESTORE_LC_NUMERIC" pair if required, so eg:
7552 WITH_LC_NUMERIC_SET_TO_NEEDED(
7554 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
7555 );
7556 is equivalent to:
7558 {
7560 #ifdef USE_LOCALE_NUMERIC
7561 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
7562 STORE_LC_NUMERIC_SET_TO_NEEDED();
7563 #endif
7564 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
7565 #ifdef USE_LOCALE_NUMERIC
7566 RESTORE_LC_NUMERIC();
7567 #endif
7568 }
7569 void WITH_LC_NUMERIC_SET_TO_NEEDED(block)
7571 "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
7573 Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
7574 as the precalculated value of "IN_LC(LC_NUMERIC)". It is the
7575 caller's responsibility to ensure that the status of "PL_compiling"
7576 and "PL_hints" cannot have changed since the precalculation.
7577 void WITH_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric, block)
7579
7581 "Magic" is special data attached to SV structures in order to give them
7582 "magical" properties. When any Perl code tries to read from, or assign
7583 to, an SV marked as magical, it calls the 'get' or 'set' function
7584 associated with that SV's magic. A get is called prior to reading an
7585 SV, in order to give it a chance to update its internal value (get on
7586 $. writes the line number of the last read filehandle into the SV's IV
7587 slot), while set is called after an SV has been written to, in order to
7588 allow it to make use of its changed value (set on $/ copies the SV's
7589 new value to the PL_rs global variable).
7590 Magic is implemented as a linked list of MAGIC structures attached to
7592 the SV. Each MAGIC struct holds the type of the magic, a pointer to an
7593 array of functions that implement the get(), set(), length() etc
7594 functions, plus space for some flags and pointers. For example, a tied
7595 variable has a MAGIC structure that contains a pointer to the object
7596 associated with the tie.
7597 "mg_clear"
7599 Clear something magical that the SV represents. See "sv_magic".
7600 int mg_clear(SV* sv)
7602 "mg_copy"
7604 Copies the magic from one SV to another. See "sv_magic".
7605 int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
7607 "MGf_COPY"
7609 "MGf_DUP"
7610 "MGf_LOCAL"
7611 Described in perlguts.
7612 "mg_find"
7614 Finds the magic pointer for "type" matching the SV. See
7615 "sv_magic".
7616 MAGIC* mg_find(const SV* sv, int type)
7618 "mg_findext"
7620 Finds the magic pointer of "type" with the given "vtbl" for the
7621 "SV". See "sv_magicext".
7622 MAGIC* mg_findext(const SV* sv, int type, const MGVTBL *vtbl)
7624 "mg_free"
7626 Free any magic storage used by the SV. See "sv_magic".
7627 int mg_free(SV* sv)
7629 "mg_freeext"
7631 Remove any magic of type "how" using virtual table "vtbl" from the
7632 SV "sv". See "sv_magic".
7633 "mg_freeext(sv, how, NULL)" is equivalent to "mg_free_type(sv,
7635 how)".
7636 void mg_freeext(SV* sv, int how, const MGVTBL *vtbl)
7638 "mg_free_type"
7640 Remove any magic of type "how" from the SV "sv". See "sv_magic".
7641 void mg_free_type(SV* sv, int how)
7643 "mg_get"
7645 Do magic before a value is retrieved from the SV. The type of SV
7646 must be >= "SVt_PVMG". See "sv_magic".
7647 int mg_get(SV* sv)
7649 "mg_length"
7651 "DEPRECATED!" It is planned to remove "mg_length" from a future
7652 release of Perl. Do not use it for new code; remove it from
7653 existing code.
7654 Reports on the SV's length in bytes, calling length magic if
7656 available, but does not set the UTF8 flag on "sv". It will fall
7657 back to 'get' magic if there is no 'length' magic, but with no
7658 indication as to whether it called 'get' magic. It assumes "sv" is
7659 a "PVMG" or higher. Use "sv_len()" instead.
7660 U32 mg_length(SV* sv)
7662 "mg_magical"
7664 Turns on the magical status of an SV. See "sv_magic".
7665 void mg_magical(SV* sv)
7667 "mg_set"
7669 Do magic after a value is assigned to the SV. See "sv_magic".
7670 int mg_set(SV* sv)
7672 "MGVTBL"
7674 Described in perlguts.
7675 "perl_clone"
7677 Create and return a new interpreter by cloning the current one.
7678 "perl_clone" takes these flags as parameters:
7680 "CLONEf_COPY_STACKS" - is used to, well, copy the stacks also,
7682 without it we only clone the data and zero the stacks, with it we
7683 copy the stacks and the new perl interpreter is ready to run at the
7684 exact same point as the previous one. The pseudo-fork code uses
7685 "COPY_STACKS" while the threads->create doesn't.
7686 "CLONEf_KEEP_PTR_TABLE" - "perl_clone" keeps a ptr_table with the
7688 pointer of the old variable as a key and the new variable as a
7689 value, this allows it to check if something has been cloned and not
7690 clone it again, but rather just use the value and increase the
7691 refcount. If "KEEP_PTR_TABLE" is not set then "perl_clone" will
7692 kill the ptr_table using the function
7693 "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;". A reason to
7694 keep it around is if you want to dup some of your own variables
7695 which are outside the graph that perl scans.
7696 "CLONEf_CLONE_HOST" - This is a win32 thing, it is ignored on unix,
7698 it tells perl's win32host code (which is c++) to clone itself, this
7699 is needed on win32 if you want to run two threads at the same time,
7700 if you just want to do some stuff in a separate perl interpreter
7701 and then throw it away and return to the original one, you don't
7702 need to do anything.
7703 PerlInterpreter* perl_clone(PerlInterpreter *proto_perl,
7705 UV flags)
7706 "PERL_MAGIC_arylen"
7708 "PERL_MAGIC_arylen_p"
7709 "PERL_MAGIC_backref"
7710 "PERL_MAGIC_bm"
7711 "PERL_MAGIC_checkcall"
7712 "PERL_MAGIC_collxfrm"
7713 "PERL_MAGIC_dbfile"
7714 "PERL_MAGIC_dbline"
7715 "PERL_MAGIC_debugvar"
7716 "PERL_MAGIC_defelem"
7717 "PERL_MAGIC_env"
7718 "PERL_MAGIC_envelem"
7719 "PERL_MAGIC_ext"
7720 "PERL_MAGIC_fm"
7721 "PERL_MAGIC_hints"
7722 "PERL_MAGIC_hintselem"
7723 "PERL_MAGIC_isa"
7724 "PERL_MAGIC_isaelem"
7725 "PERL_MAGIC_lvref"
7726 "PERL_MAGIC_nkeys"
7727 "PERL_MAGIC_nonelem"
7728 "PERL_MAGIC_overload_table"
7729 "PERL_MAGIC_pos"
7730 "PERL_MAGIC_qr"
7731 "PERL_MAGIC_regdata"
7732 "PERL_MAGIC_regdatum"
7733 "PERL_MAGIC_regex_global"
7734 "PERL_MAGIC_rhash"
7735 "PERL_MAGIC_shared"
7736 "PERL_MAGIC_shared_scalar"
7737 "PERL_MAGIC_sig"
7738 "PERL_MAGIC_sigelem"
7739 "PERL_MAGIC_substr"
7740 "PERL_MAGIC_sv"
7741 "PERL_MAGIC_symtab"
7742 "PERL_MAGIC_taint"
7743 "PERL_MAGIC_tied"
7744 "PERL_MAGIC_tiedelem"
7745 "PERL_MAGIC_tiedscalar"
7746 "PERL_MAGIC_utf8"
7747 "PERL_MAGIC_uvar"
7748 "PERL_MAGIC_uvar_elem"
7749 "PERL_MAGIC_vec"
7750 "PERL_MAGIC_vstring"
7751 Described in perlguts.
7752 "ptr_table_fetch"
7754 Look for "sv" in the pointer-mapping table "tbl", returning its
7755 value, or NULL if not found.
7756 void* ptr_table_fetch(PTR_TBL_t *const tbl, const void *const sv)
7758 "ptr_table_free"
7760 Clear and free a ptr table
7761 void ptr_table_free(PTR_TBL_t *const tbl)
7763 "ptr_table_new"
7765 Create a new pointer-mapping table
7766 PTR_TBL_t* ptr_table_new()
7768 "ptr_table_split"
7770 Double the hash bucket size of an existing ptr table
7771 void ptr_table_split(PTR_TBL_t *const tbl)
7773 "ptr_table_store"
7775 Add a new entry to a pointer-mapping table "tbl". In hash terms,
7776 "oldsv" is the key; Cnewsv> is the value.
7777 The names "old" and "new" are specific to the core's typical use of
7779 ptr_tables in thread cloning.
7780 void ptr_table_store(PTR_TBL_t *const tbl,
7782 const void *const oldsv, void *const newsv)
7783 "SvTIED_obj"
7785 Described in perlinterp.
7786 SvTIED_obj(SV *sv, MAGIC *mg)
7788
7790 "dump_mstats"
7791 When enabled by compiling with "-DDEBUGGING_MSTATS", print out
7792 statistics about malloc as two lines of numbers, one showing the
7793 length of the free list for each size category, the second showing
7794 the number of mallocs - frees for each size category.
7795 "s", if not NULL, is used as a phrase to include in the output,
7797 such as "after compilation".
7798 void dump_mstats(const char* s)
7800 "HASATTRIBUTE_MALLOC"
7802 Can we handle "GCC" attribute for malloc-style functions.
7803 "HAS_MALLOC_GOOD_SIZE"
7805 This symbol, if defined, indicates that the "malloc_good_size"
7806 routine is available for use.
7807 "HAS_MALLOC_SIZE"
7809 This symbol, if defined, indicates that the "malloc_size" routine
7810 is available for use.
7811 "I_MALLOCMALLOC"
7813 This symbol, if defined, indicates to the C program that it should
7814 include malloc/malloc.h.
7815 #ifdef I_MALLOCMALLOC
7817 #include <mallocmalloc.h>
7818 #endif
7819 "MYMALLOC"
7821 This symbol, if defined, indicates that we're using our own malloc.
7822 "Newx"
7824 "safemalloc"
7825 The XSUB-writer's interface to the C "malloc" function.
7826 Memory obtained by this should ONLY be freed with "Safefree".
7828 In 5.9.3, Newx() and friends replace the older New() API, and drops
7830 the first parameter, x, a debug aid which allowed callers to
7831 identify themselves. This aid has been superseded by a new build
7832 option, PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhacktips). The
7833 older API is still there for use in XS modules supporting older
7834 perls.
7835 void Newx (void* ptr, int nitems, type)
7837 void* safemalloc(size_t size)
7838 "Newxc"
7840 The XSUB-writer's interface to the C "malloc" function, with cast.
7841 See also "Newx".
7842 Memory obtained by this should ONLY be freed with "Safefree".
7844 void Newxc(void* ptr, int nitems, type, cast)
7846 "Newxz"
7848 "safecalloc"
7849 The XSUB-writer's interface to the C "malloc" function. The
7850 allocated memory is zeroed with "memzero". See also "Newx".
7851 Memory obtained by this should ONLY be freed with "Safefree".
7853 void Newxz (void* ptr, int nitems, type)
7855 void* safecalloc(size_t nitems, size_t item_size)
7856 "PERL_MALLOC_WRAP"
7858 This symbol, if defined, indicates that we'd like malloc wrap
7859 checks.
7860 "Renew"
7862 "saferealloc"
7863 The XSUB-writer's interface to the C "realloc" function.
7864 Memory obtained by this should ONLY be freed with "Safefree".
7866 void Renew (void* ptr, int nitems, type)
7868 void* saferealloc(void *ptr, size_t size)
7869 "Renewc"
7871 The XSUB-writer's interface to the C "realloc" function, with cast.
7872 Memory obtained by this should ONLY be freed with "Safefree".
7874 void Renewc(void* ptr, int nitems, type, cast)
7876 "Safefree"
7878 The XSUB-writer's interface to the C "free" function.
7879 This should ONLY be used on memory obtained using "Newx" and
7881 friends.
7882 void Safefree(void* ptr)
7884 "safesyscalloc"
7886 Safe version of system's calloc()
7887 Malloc_t safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
7889 "safesysfree"
7891 Safe version of system's free()
7892 Free_t safesysfree(Malloc_t where)
7894 "safesysmalloc"
7896 Paranoid version of system's malloc()
7897 Malloc_t safesysmalloc(MEM_SIZE nbytes)
7899 "safesysrealloc"
7901 Paranoid version of system's realloc()
7902 Malloc_t safesysrealloc(Malloc_t where, MEM_SIZE nbytes)
7904
7906 These functions are related to the method resolution order of perl
7907 classes Also see perlmroapi.
7908 "HvMROMETA"
7910 Described in perlmroapi.
7911 struct mro_meta * HvMROMETA(HV *hv)
7913 "mro_get_from_name"
7915 Returns the previously registered mro with the given "name", or
7916 NULL if not registered. See ""mro_register"".
7917 NOTE: "mro_get_from_name" must be explicitly called as
7919 "Perl_mro_get_from_name" with an "aTHX_" parameter.
7920 const struct mro_alg * Perl_mro_get_from_name(pTHX_ SV *name)
7922 "mro_get_linear_isa"
7924 Returns the mro linearisation for the given stash. By default,
7925 this will be whatever "mro_get_linear_isa_dfs" returns unless some
7926 other MRO is in effect for the stash. The return value is a read-
7927 only AV*.
7928 You are responsible for "SvREFCNT_inc()" on the return value if you
7930 plan to store it anywhere semi-permanently (otherwise it might be
7931 deleted out from under you the next time the cache is invalidated).
7932 AV* mro_get_linear_isa(HV* stash)
7934 "MRO_GET_PRIVATE_DATA"
7936 Described in perlmroapi.
7937 SV* MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta,
7939 const struct mro_alg *const which)
7940 "mro_method_changed_in"
7942 Invalidates method caching on any child classes of the given stash,
7943 so that they might notice the changes in this one.
7944 Ideally, all instances of "PL_sub_generation++" in perl source
7946 outside of mro.c should be replaced by calls to this.
7947 Perl automatically handles most of the common ways a method might
7949 be redefined. However, there are a few ways you could change a
7950 method in a stash without the cache code noticing, in which case
7951 you need to call this method afterwards:
7952 1) Directly manipulating the stash HV entries from XS code.
7954 2) Assigning a reference to a readonly scalar constant into a stash
7956 entry in order to create a constant subroutine (like constant.pm
7957 does).
7958 This same method is available from pure perl via,
7960 "mro::method_changed_in(classname)".
7961 void mro_method_changed_in(HV* stash)
7963 "mro_register"
7965 Registers a custom mro plugin. See perlmroapi for details on this
7966 and other mro functions.
7967 NOTE: "mro_register" must be explicitly called as
7969 "Perl_mro_register" with an "aTHX_" parameter.
7970 void Perl_mro_register(pTHX_ const struct mro_alg *mro)
7972 "mro_set_mro"
7974 Set "meta" to the value contained in the registered mro plugin
7975 whose name is "name".
7976 Croaks if "name" hasn't been registered
7978 NOTE: "mro_set_mro" must be explicitly called as "Perl_mro_set_mro"
7980 with an "aTHX_" parameter.
7981 void Perl_mro_set_mro(pTHX_ struct mro_meta *const meta,
7983 SV *const name)
7984 "mro_set_private_data"
7986 Described in perlmroapi.
7987 NOTE: "mro_set_private_data" must be explicitly called as
7989 "Perl_mro_set_private_data" with an "aTHX_" parameter.
7990 SV* Perl_mro_set_private_data(pTHX_
7992 struct mro_meta *const smeta,
7993 const struct mro_alg *const which,
7994 SV *const data)
7995
7997 "dMULTICALL"
7998 Declare local variables for a multicall. See "LIGHTWEIGHT
7999 CALLBACKS" in perlcall.
8000 dMULTICALL;
8002 "MULTICALL"
8004 Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in
8005 perlcall.
8006 MULTICALL;
8008 "POP_MULTICALL"
8010 Closing bracket for a lightweight callback. See "LIGHTWEIGHT
8011 CALLBACKS" in perlcall.
8012 POP_MULTICALL;
8014 "PUSH_MULTICALL"
8016 Opening bracket for a lightweight callback. See "LIGHTWEIGHT
8017 CALLBACKS" in perlcall.
8018 PUSH_MULTICALL(CV* the_cv);
8020
8022 "Atol"
8023 "DEPRECATED!" It is planned to remove "Atol" from a future release
8024 of Perl. Do not use it for new code; remove it from existing code.
8025 Described in perlhacktips.
8027 Atol(const char * nptr)
8029 "Atoul"
8031 "DEPRECATED!" It is planned to remove "Atoul" from a future
8032 release of Perl. Do not use it for new code; remove it from
8033 existing code.
8034 Described in perlhacktips.
8036 Atoul(const char * nptr)
8038 "Drand01"
8040 This macro is to be used to generate uniformly distributed random
8041 numbers over the range [0., 1.[. You may have to supply an 'extern
8042 double "drand48()";' in your program since SunOS 4.1.3 doesn't
8043 provide you with anything relevant in its headers. See
8044 "HAS_DRAND48_PROTO".
8045 double Drand01()
8047 "Gconvert"
8049 This preprocessor macro is defined to convert a floating point
8050 number to a string without a trailing decimal point. This emulates
8051 the behavior of "sprintf("%g")", but is sometimes much more
8052 efficient. If "gconvert()" is not available, but "gcvt()" drops
8053 the trailing decimal point, then "gcvt()" is used. If all else
8054 fails, a macro using "sprintf("%g")" is used. Arguments for the
8055 Gconvert macro are: value, number of digits, whether trailing zeros
8056 should be retained, and the output buffer. The usual values are:
8057 d_Gconvert='gconvert((x),(n),(t),(b))'
8059 d_Gconvert='gcvt((x),(n),(b))'
8060 d_Gconvert='sprintf((b),"%.*g",(n),(x))'
8061 The last two assume trailing zeros should not be kept.
8063 char * Gconvert(double x, Size_t n, bool t, char * b)
8065 "grok_atoUV"
8067 parse a string, looking for a decimal unsigned integer.
8068 On entry, "pv" points to the beginning of the string; "valptr"
8070 points to a UV that will receive the converted value, if found;
8071 "endptr" is either NULL or points to a variable that points to one
8072 byte beyond the point in "pv" that this routine should examine. If
8073 "endptr" is NULL, "pv" is assumed to be NUL-terminated.
8074 Returns FALSE if "pv" doesn't represent a valid unsigned integer
8076 value (with no leading zeros). Otherwise it returns TRUE, and sets
8077 *valptr to that value.
8078 If you constrain the portion of "pv" that is looked at by this
8080 function (by passing a non-NULL "endptr"), and if the intial bytes
8081 of that portion form a valid value, it will return TRUE, setting
8082 *endptr to the byte following the final digit of the value. But if
8083 there is no constraint at what's looked at, all of "pv" must be
8084 valid in order for TRUE to be returned. *endptr is unchanged from
8085 its value on input if FALSE is returned;
8086 The only characters this accepts are the decimal digits '0'..'9'.
8088 As opposed to atoi(3) or strtol(3), "grok_atoUV" does NOT allow
8090 optional leading whitespace, nor negative inputs. If such features
8091 are required, the calling code needs to explicitly implement those.
8092 Note that this function returns FALSE for inputs that would
8094 overflow a UV, or have leading zeros. Thus a single 0 is accepted,
8095 but not 00 nor 01, 002, etc.
8096 Background: "atoi" has severe problems with illegal inputs, it
8098 cannot be used for incremental parsing, and therefore should be
8099 avoided "atoi" and "strtol" are also affected by locale settings,
8100 which can also be seen as a bug (global state controlled by user
8101 environment).
8102 bool grok_atoUV(const char* pv, UV* valptr, const char** endptr)
8104 "grok_bin"
8106 converts a string representing a binary number to numeric form.
8107 On entry "start" and *len_p give the string to scan, *flags gives
8109 conversion flags, and "result" should be "NULL" or a pointer to an
8110 NV. The scan stops at the end of the string, or at just before the
8111 first invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
8112 in *flags, encountering an invalid character (except NUL) will also
8113 trigger a warning. On return *len_p is set to the length of the
8114 scanned string, and *flags gives output flags.
8115 If the value is <= "UV_MAX" it is returned as a UV, the output
8117 flags are clear, and nothing is written to *result. If the value
8118 is > "UV_MAX", "grok_bin" returns "UV_MAX", sets
8119 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
8120 approximation of the correct value into *result (which is an NV; or
8121 the approximation is discarded if "result" is NULL).
8122 The binary number may optionally be prefixed with "0b" or "b"
8124 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
8125 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
8127 pairs of digits may be separated from each other by a single
8128 underscore; also a single leading underscore is accepted.
8129 UV grok_bin(const char* start, STRLEN* len_p, I32* flags,
8131 NV *result)
8132 "grok_hex"
8134 converts a string representing a hex number to numeric form.
8135 On entry "start" and *len_p give the string to scan, *flags gives
8137 conversion flags, and "result" should be "NULL" or a pointer to an
8138 NV. The scan stops at the end of the string, or at just before the
8139 first invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
8140 in *flags, encountering an invalid character (except NUL) will also
8141 trigger a warning. On return *len_p is set to the length of the
8142 scanned string, and *flags gives output flags.
8143 If the value is <= "UV_MAX" it is returned as a UV, the output
8145 flags are clear, and nothing is written to *result. If the value
8146 is > "UV_MAX", "grok_hex" returns "UV_MAX", sets
8147 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
8148 approximation of the correct value into *result (which is an NV; or
8149 the approximation is discarded if "result" is NULL).
8150 The hex number may optionally be prefixed with "0x" or "x" unless
8152 "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
8153 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
8155 pairs of digits may be separated from each other by a single
8156 underscore; also a single leading underscore is accepted.
8157 UV grok_hex(const char* start, STRLEN* len_p, I32* flags,
8159 NV *result)
8160 "grok_infnan"
8162 Helper for "grok_number()", accepts various ways of spelling
8163 "infinity" or "not a number", and returns one of the following flag
8164 combinations:
8165 IS_NUMBER_INFINITY
8167 IS_NUMBER_NAN
8168 IS_NUMBER_INFINITY | IS_NUMBER_NEG
8169 IS_NUMBER_NAN | IS_NUMBER_NEG
8170 0
8171 possibly |-ed with "IS_NUMBER_TRAILING".
8173 If an infinity or a not-a-number is recognized, *sp will point to
8175 one byte past the end of the recognized string. If the recognition
8176 fails, zero is returned, and *sp will not move.
8177 int grok_infnan(const char** sp, const char *send)
8179 "grok_number"
8181 Identical to "grok_number_flags()" with "flags" set to zero.
8182 int grok_number(const char *pv, STRLEN len, UV *valuep)
8184 "grok_number_flags"
8186 Recognise (or not) a number. The type of the number is returned (0
8187 if unrecognised), otherwise it is a bit-ORed combination of
8188 "IS_NUMBER_IN_UV", "IS_NUMBER_GREATER_THAN_UV_MAX",
8189 "IS_NUMBER_NOT_INT", "IS_NUMBER_NEG", "IS_NUMBER_INFINITY",
8190 "IS_NUMBER_NAN" (defined in perl.h).
8191 If the value of the number can fit in a UV, it is returned in
8193 *valuep. "IS_NUMBER_IN_UV" will be set to indicate that *valuep is
8194 valid, "IS_NUMBER_IN_UV" will never be set unless *valuep is valid,
8195 but *valuep may have been assigned to during processing even though
8196 "IS_NUMBER_IN_UV" is not set on return. If "valuep" is "NULL",
8197 "IS_NUMBER_IN_UV" will be set for the same cases as when "valuep"
8198 is non-"NULL", but no actual assignment (or SEGV) will occur.
8199 "IS_NUMBER_NOT_INT" will be set with "IS_NUMBER_IN_UV" if trailing
8201 decimals were seen (in which case *valuep gives the true value
8202 truncated to an integer), and "IS_NUMBER_NEG" if the number is
8203 negative (in which case *valuep holds the absolute value).
8204 "IS_NUMBER_IN_UV" is not set if "e" notation was used or the number
8205 is larger than a UV.
8206 "flags" allows only "PERL_SCAN_TRAILING", which allows for trailing
8208 non-numeric text on an otherwise successful grok, setting
8209 "IS_NUMBER_TRAILING" on the result.
8210 int grok_number_flags(const char *pv, STRLEN len, UV *valuep,
8212 U32 flags)
8213 "GROK_NUMERIC_RADIX"
8215 A synonym for "grok_numeric_radix"
8216 bool GROK_NUMERIC_RADIX(NN const char **sp, NN const char *send)
8218 "grok_numeric_radix"
8220 Scan and skip for a numeric decimal separator (radix).
8221 bool grok_numeric_radix(const char **sp, const char *send)
8223 "grok_oct"
8225 converts a string representing an octal number to numeric form.
8226 On entry "start" and *len_p give the string to scan, *flags gives
8228 conversion flags, and "result" should be "NULL" or a pointer to an
8229 NV. The scan stops at the end of the string, or at just before the
8230 first invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
8231 in *flags, encountering an invalid character (except NUL) will also
8232 trigger a warning. On return *len_p is set to the length of the
8233 scanned string, and *flags gives output flags.
8234 If the value is <= "UV_MAX" it is returned as a UV, the output
8236 flags are clear, and nothing is written to *result. If the value
8237 is > "UV_MAX", "grok_oct" returns "UV_MAX", sets
8238 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
8239 approximation of the correct value into *result (which is an NV; or
8240 the approximation is discarded if "result" is NULL).
8241 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
8243 pairs of digits may be separated from each other by a single
8244 underscore; also a single leading underscore is accepted.
8245 The "PERL_SCAN_DISALLOW_PREFIX" flag is always treated as being set
8247 for this function.
8248 UV grok_oct(const char* start, STRLEN* len_p, I32* flags,
8250 NV *result)
8251 "isinfnan"
8253 "Perl_isinfnan()" is a utility function that returns true if the NV
8254 argument is either an infinity or a "NaN", false otherwise. To
8255 test in more detail, use "Perl_isinf()" and "Perl_isnan()".
8256 This is also the logical inverse of Perl_isfinite().
8258 bool isinfnan(NV nv)
8260 "my_atof"
8262 "atof"(3), but properly works with Perl locale handling, accepting
8263 a dot radix character always, but also the current locale's radix
8264 character if and only if called from within the lexical scope of a
8265 Perl "use locale" statement.
8266 N.B. "s" must be NUL terminated.
8268 NV my_atof(const char *s)
8270 "my_strtod"
8272 This function is equivalent to the libc strtod() function, and is
8273 available even on platforms that lack plain strtod(). Its return
8274 value is the best available precision depending on platform
8275 capabilities and Configure options.
8276 It properly handles the locale radix character, meaning it expects
8278 a dot except when called from within the scope of "use locale", in
8279 which case the radix character should be that specified by the
8280 current locale.
8281 The synonym Strtod() may be used instead.
8283 NV my_strtod(const char * const s, char ** e)
8285 "PERL_ABS"
8287 Typeless "abs" or "fabs", etc. (The usage below indicates it is
8288 for integers, but it works for any type.) Use instead of these,
8289 since the C library ones force their argument to be what it is
8290 expecting, potentially leading to disaster. But also beware that
8291 this evaluates its argument twice, so no "x++".
8292 int PERL_ABS(int x)
8294 "Perl_acos"
8296 "Perl_asin"
8297 "Perl_atan"
8298 "Perl_atan2"
8299 "Perl_ceil"
8300 "Perl_cos"
8301 "Perl_cosh"
8302 "Perl_exp"
8303 "Perl_floor"
8304 "Perl_fmod"
8305 "Perl_frexp"
8306 "Perl_isfinite"
8307 "Perl_isinf"
8308 "Perl_isnan"
8309 "Perl_ldexp"
8310 "Perl_log"
8311 "Perl_log10"
8312 "Perl_modf"
8313 "Perl_pow"
8314 "Perl_sin"
8315 "Perl_sinh"
8316 "Perl_sqrt"
8317 "Perl_tan"
8318 "Perl_tanh"
8319 These perform the corresponding mathematical operation on the
8320 operand(s), using the libc function designed for the task that has
8321 just enough precision for an NV on this platform. If no such
8322 function with sufficient precision exists, the highest precision
8323 one available is used.
8324 NV Perl_acos (NV x)
8326 NV Perl_asin (NV x)
8327 NV Perl_atan (NV x)
8328 NV Perl_atan2 (NV x, NV y)
8329 NV Perl_ceil (NV x)
8330 NV Perl_cos (NV x)
8331 NV Perl_cosh (NV x)
8332 NV Perl_exp (NV x)
8333 NV Perl_floor (NV x)
8334 NV Perl_fmod (NV x, NV y)
8335 NV Perl_frexp (NV x, int *exp)
8336 IV Perl_isfinite(NV x)
8337 IV Perl_isinf (NV x)
8338 IV Perl_isnan (NV x)
8339 NV Perl_ldexp (NV x, int exp)
8340 NV Perl_log (NV x)
8341 NV Perl_log10 (NV x)
8342 NV Perl_modf (NV x, NV *iptr)
8343 NV Perl_pow (NV x, NV y)
8344 NV Perl_sin (NV x)
8345 NV Perl_sinh (NV x)
8346 NV Perl_sqrt (NV x)
8347 NV Perl_tan (NV x)
8348 NV Perl_tanh (NV x)
8349 "Perl_signbit"
8351 NOTE: "Perl_signbit" is experimental and may change or be removed
8352 without notice.
8353 Return a non-zero integer if the sign bit on an NV is set, and 0 if
8355 it is not.
8356 If Configure detects this system has a "signbit()" that will work
8358 with our NVs, then we just use it via the "#define" in perl.h.
8359 Otherwise, fall back on this implementation. The main use of this
8360 function is catching "-0.0".
8361 "Configure" notes: This function is called 'Perl_signbit' instead
8363 of a plain 'signbit' because it is easy to imagine a system having
8364 a "signbit()" function or macro that doesn't happen to work with
8365 our particular choice of NVs. We shouldn't just re-"#define"
8366 "signbit" as "Perl_signbit" and expect the standard system headers
8367 to be happy. Also, this is a no-context function (no "pTHX_")
8368 because "Perl_signbit()" is usually re-"#defined" in perl.h as a
8369 simple macro call to the system's "signbit()". Users should just
8370 always call "Perl_signbit()".
8371 int Perl_signbit(NV f)
8373 "PL_hexdigit"
8375 This array, indexed by an integer, converts that value into the
8376 character that represents it. For example, if the input is 8, the
8377 return will be a string whose first character is '8'. What is
8378 actually returned is a pointer into a string. All you are
8379 interested in is the first character of that string. To get
8380 uppercase letters (for the values 10..15), add 16 to the index.
8381 Hence, "PL_hexdigit[11]" is 'b', and "PL_hexdigit[11+16]" is 'B'.
8382 Adding 16 to an index whose representation is '0'..'9' yields the
8383 same as not adding 16. Indices outside the range 0..31 result in
8384 (bad) undedefined behavior.
8385 "READ_XDIGIT"
8387 Returns the value of an ASCII-range hex digit and advances the
8388 string pointer. Behaviour is only well defined when isXDIGIT(*str)
8389 is true.
8390 U8 READ_XDIGIT(char str*)
8392 "scan_bin"
8394 For backwards compatibility. Use "grok_bin" instead.
8395 NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
8397 "scan_hex"
8399 For backwards compatibility. Use "grok_hex" instead.
8400 NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
8402 "scan_oct"
8404 For backwards compatibility. Use "grok_oct" instead.
8405 NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
8407 "seedDrand01"
8409 This symbol defines the macro to be used in seeding the random
8410 number generator (see "Drand01").
8411 void seedDrand01(Rand_seed_t x)
8413 "Strtod"
8415 This is a synonym for "my_strtod".
8416 NV Strtod(NN const char * const s, NULLOK char ** e)
8418 "Strtol"
8420 Platform and configuration independent "strtol". This expands to
8421 the appropriate "strotol"-like function based on the platform and
8422 Configure options>. For example it could expand to "strtoll" or
8423 "strtoq" instead of "strtol".
8424 NV Strtol(NN const char * const s, NULLOK char ** e, int base)
8426 "Strtoul"
8428 Platform and configuration independent "strtoul". This expands to
8429 the appropriate "strotoul"-like function based on the platform and
8430 Configure options>. For example it could expand to "strtoull" or
8431 "strtouq" instead of "strtoul".
8432 NV Strtoul(NN const char * const s, NULLOK char ** e, int base)
8434
8436 "alloccopstash"
8437 NOTE: "alloccopstash" is experimental and may change or be removed
8438 without notice.
8439 Available only under threaded builds, this function allocates an
8441 entry in "PL_stashpad" for the stash passed to it.
8442 PADOFFSET alloccopstash(HV *hv)
8444 "BINOP"
8446 Described in perlguts.
8447 "block_end"
8449 Handles compile-time scope exit. "floor" is the savestack index
8450 returned by "block_start", and "seq" is the body of the block.
8451 Returns the block, possibly modified.
8452 OP* block_end(I32 floor, OP* seq)
8454 "block_start"
8456 Handles compile-time scope entry. Arranges for hints to be
8457 restored on block exit and also handles pad sequence numbers to
8458 make lexical variables scope right. Returns a savestack index for
8459 use with "block_end".
8460 int block_start(int full)
8462 "ck_entersub_args_list"
8464 Performs the default fixup of the arguments part of an "entersub"
8465 op tree. This consists of applying list context to each of the
8466 argument ops. This is the standard treatment used on a call marked
8467 with "&", or a method call, or a call through a subroutine
8468 reference, or any other call where the callee can't be identified
8469 at compile time, or a call where the callee has no prototype.
8470 OP* ck_entersub_args_list(OP *entersubop)
8472 "ck_entersub_args_proto"
8474 Performs the fixup of the arguments part of an "entersub" op tree
8475 based on a subroutine prototype. This makes various modifications
8476 to the argument ops, from applying context up to inserting "refgen"
8477 ops, and checking the number and syntactic types of arguments, as
8478 directed by the prototype. This is the standard treatment used on
8479 a subroutine call, not marked with "&", where the callee can be
8480 identified at compile time and has a prototype.
8481 "protosv" supplies the subroutine prototype to be applied to the
8483 call. It may be a normal defined scalar, of which the string value
8484 will be used. Alternatively, for convenience, it may be a
8485 subroutine object (a "CV*" that has been cast to "SV*") which has a
8486 prototype. The prototype supplied, in whichever form, does not
8487 need to match the actual callee referenced by the op tree.
8488 If the argument ops disagree with the prototype, for example by
8490 having an unacceptable number of arguments, a valid op tree is
8491 returned anyway. The error is reflected in the parser state,
8492 normally resulting in a single exception at the top level of
8493 parsing which covers all the compilation errors that occurred. In
8494 the error message, the callee is referred to by the name defined by
8495 the "namegv" parameter.
8496 OP* ck_entersub_args_proto(OP *entersubop, GV *namegv,
8498 SV *protosv)
8499 "ck_entersub_args_proto_or_list"
8501 Performs the fixup of the arguments part of an "entersub" op tree
8502 either based on a subroutine prototype or using default list-
8503 context processing. This is the standard treatment used on a
8504 subroutine call, not marked with "&", where the callee can be
8505 identified at compile time.
8506 "protosv" supplies the subroutine prototype to be applied to the
8508 call, or indicates that there is no prototype. It may be a normal
8509 scalar, in which case if it is defined then the string value will
8510 be used as a prototype, and if it is undefined then there is no
8511 prototype. Alternatively, for convenience, it may be a subroutine
8512 object (a "CV*" that has been cast to "SV*"), of which the
8513 prototype will be used if it has one. The prototype (or lack
8514 thereof) supplied, in whichever form, does not need to match the
8515 actual callee referenced by the op tree.
8516 If the argument ops disagree with the prototype, for example by
8518 having an unacceptable number of arguments, a valid op tree is
8519 returned anyway. The error is reflected in the parser state,
8520 normally resulting in a single exception at the top level of
8521 parsing which covers all the compilation errors that occurred. In
8522 the error message, the callee is referred to by the name defined by
8523 the "namegv" parameter.
8524 OP* ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
8526 SV *protosv)
8527 "cv_const_sv"
8529 If "cv" is a constant sub eligible for inlining, returns the
8530 constant value returned by the sub. Otherwise, returns "NULL".
8531 Constant subs can be created with "newCONSTSUB" or as described in
8533 "Constant Functions" in perlsub.
8534 SV* cv_const_sv(const CV *const cv)
8536 "cv_get_call_checker"
8538 The original form of "cv_get_call_checker_flags", which does not
8539 return checker flags. When using a checker function returned by
8540 this function, it is only safe to call it with a genuine GV as its
8541 "namegv" argument.
8542 void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
8544 SV **ckobj_p)
8545 "cv_get_call_checker_flags"
8547 Retrieves the function that will be used to fix up a call to "cv".
8548 Specifically, the function is applied to an "entersub" op tree for
8549 a subroutine call, not marked with "&", where the callee can be
8550 identified at compile time as "cv".
8551 The C-level function pointer is returned in *ckfun_p, an SV
8553 argument for it is returned in *ckobj_p, and control flags are
8554 returned in *ckflags_p. The function is intended to be called in
8555 this manner:
8556 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
8558 In this call, "entersubop" is a pointer to the "entersub" op, which
8560 may be replaced by the check function, and "namegv" supplies the
8561 name that should be used by the check function to refer to the
8562 callee of the "entersub" op if it needs to emit any diagnostics.
8563 It is permitted to apply the check function in non-standard
8564 situations, such as to a call to a different subroutine or to a
8565 method call.
8566 "namegv" may not actually be a GV. If the
8568 "CALL_CHECKER_REQUIRE_GV" bit is clear in *ckflags_p, it is
8569 permitted to pass a CV or other SV instead, anything that can be
8570 used as the first argument to "cv_name". If the
8571 "CALL_CHECKER_REQUIRE_GV" bit is set in *ckflags_p then the check
8572 function requires "namegv" to be a genuine GV.
8573 By default, the check function is
8575 Perl_ck_entersub_args_proto_or_list, the SV parameter is "cv"
8576 itself, and the "CALL_CHECKER_REQUIRE_GV" flag is clear. This
8577 implements standard prototype processing. It can be changed, for a
8578 particular subroutine, by "cv_set_call_checker_flags".
8579 If the "CALL_CHECKER_REQUIRE_GV" bit is set in "gflags" then it
8581 indicates that the caller only knows about the genuine GV version
8582 of "namegv", and accordingly the corresponding bit will always be
8583 set in *ckflags_p, regardless of the check function's recorded
8584 requirements. If the "CALL_CHECKER_REQUIRE_GV" bit is clear in
8585 "gflags" then it indicates the caller knows about the possibility
8586 of passing something other than a GV as "namegv", and accordingly
8587 the corresponding bit may be either set or clear in *ckflags_p,
8588 indicating the check function's recorded requirements.
8589 "gflags" is a bitset passed into "cv_get_call_checker_flags", in
8591 which only the "CALL_CHECKER_REQUIRE_GV" bit currently has a
8592 defined meaning (for which see above). All other bits should be
8593 clear.
8594 void cv_get_call_checker_flags(CV *cv, U32 gflags,
8596 Perl_call_checker *ckfun_p,
8597 SV **ckobj_p, U32 *ckflags_p)
8598 "cv_set_call_checker"
8600 The original form of "cv_set_call_checker_flags", which passes it
8601 the "CALL_CHECKER_REQUIRE_GV" flag for backward-compatibility. The
8602 effect of that flag setting is that the check function is
8603 guaranteed to get a genuine GV as its "namegv" argument.
8604 void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
8606 SV *ckobj)
8607 "cv_set_call_checker_flags"
8609 Sets the function that will be used to fix up a call to "cv".
8610 Specifically, the function is applied to an "entersub" op tree for
8611 a subroutine call, not marked with "&", where the callee can be
8612 identified at compile time as "cv".
8613 The C-level function pointer is supplied in "ckfun", an SV argument
8615 for it is supplied in "ckobj", and control flags are supplied in
8616 "ckflags". The function should be defined like this:
8617 STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
8619 It is intended to be called in this manner:
8621 entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
8623 In this call, "entersubop" is a pointer to the "entersub" op, which
8625 may be replaced by the check function, and "namegv" supplies the
8626 name that should be used by the check function to refer to the
8627 callee of the "entersub" op if it needs to emit any diagnostics.
8628 It is permitted to apply the check function in non-standard
8629 situations, such as to a call to a different subroutine or to a
8630 method call.
8631 "namegv" may not actually be a GV. For efficiency, perl may pass a
8633 CV or other SV instead. Whatever is passed can be used as the
8634 first argument to "cv_name". You can force perl to pass a GV by
8635 including "CALL_CHECKER_REQUIRE_GV" in the "ckflags".
8636 "ckflags" is a bitset, in which only the "CALL_CHECKER_REQUIRE_GV"
8638 bit currently has a defined meaning (for which see above). All
8639 other bits should be clear.
8640 The current setting for a particular CV can be retrieved by
8642 "cv_get_call_checker_flags".
8643 void cv_set_call_checker_flags(CV *cv, Perl_call_checker ckfun,
8645 SV *ckobj, U32 ckflags)
8646 "LINKLIST"
8648 Given the root of an optree, link the tree in execution order using
8649 the "op_next" pointers and return the first op executed. If this
8650 has already been done, it will not be redone, and "o->op_next" will
8651 be returned. If "o->op_next" is not already set, "o" should be at
8652 least an "UNOP".
8653 OP* LINKLIST(OP *o)
8655 "LISTOP"
8657 Described in perlguts.
8658 "LOGOP"
8660 Described in perlguts.
8661 "LOOP"
8663 Described in perlguts.
8664 "newASSIGNOP"
8666 Constructs, checks, and returns an assignment op. "left" and
8667 "right" supply the parameters of the assignment; they are consumed
8668 by this function and become part of the constructed op tree.
8669 If "optype" is "OP_ANDASSIGN", "OP_ORASSIGN", or "OP_DORASSIGN",
8671 then a suitable conditional optree is constructed. If "optype" is
8672 the opcode of a binary operator, such as "OP_BIT_OR", then an op is
8673 constructed that performs the binary operation and assigns the
8674 result to the left argument. Either way, if "optype" is non-zero
8675 then "flags" has no effect.
8676 If "optype" is zero, then a plain scalar or list assignment is
8678 constructed. Which type of assignment it is is automatically
8679 determined. "flags" gives the eight bits of "op_flags", except
8680 that "OPf_KIDS" will be set automatically, and, shifted up eight
8681 bits, the eight bits of "op_private", except that the bit with
8682 value 1 or 2 is automatically set as required.
8683 OP* newASSIGNOP(I32 flags, OP* left, I32 optype, OP* right)
8685 "newATTRSUB"
8687 Construct a Perl subroutine, also performing some surrounding jobs.
8688 This is the same as ""newATTRSUB_x"" in perlintern with its
8690 "o_is_gv" parameter set to FALSE. This means that if "o" is null,
8691 the new sub will be anonymous; otherwise the name will be derived
8692 from "o" in the way described (as with all other details) in
8693 ""newATTRSUB_x"" in perlintern.
8694 CV* newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs, OP *block)
8696 "newBINOP"
8698 Constructs, checks, and returns an op of any binary type. "type"
8699 is the opcode. "flags" gives the eight bits of "op_flags", except
8700 that "OPf_KIDS" will be set automatically, and, shifted up eight
8701 bits, the eight bits of "op_private", except that the bit with
8702 value 1 or 2 is automatically set as required. "first" and "last"
8703 supply up to two ops to be the direct children of the binary op;
8704 they are consumed by this function and become part of the
8705 constructed op tree.
8706 OP* newBINOP(I32 type, I32 flags, OP* first, OP* last)
8708 "newCONDOP"
8710 Constructs, checks, and returns a conditional-expression
8711 ("cond_expr") op. "flags" gives the eight bits of "op_flags",
8712 except that "OPf_KIDS" will be set automatically, and, shifted up
8713 eight bits, the eight bits of "op_private", except that the bit
8714 with value 1 is automatically set. "first" supplies the expression
8715 selecting between the two branches, and "trueop" and "falseop"
8716 supply the branches; they are consumed by this function and become
8717 part of the constructed op tree.
8718 OP* newCONDOP(I32 flags, OP* first, OP* trueop, OP* falseop)
8720 "newCONSTSUB"
8722 Behaves like "newCONSTSUB_flags", except that "name" is nul-
8723 terminated rather than of counted length, and no flags are set.
8724 (This means that "name" is always interpreted as Latin-1.)
8725 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
8727 "newCONSTSUB_flags"
8729 Construct a constant subroutine, also performing some surrounding
8730 jobs. A scalar constant-valued subroutine is eligible for inlining
8731 at compile-time, and in Perl code can be created by
8732 "sub FOO () { 123 }". Other kinds of constant subroutine have
8733 other treatment.
8734 The subroutine will have an empty prototype and will ignore any
8736 arguments when called. Its constant behaviour is determined by
8737 "sv". If "sv" is null, the subroutine will yield an empty list.
8738 If "sv" points to a scalar, the subroutine will always yield that
8739 scalar. If "sv" points to an array, the subroutine will always
8740 yield a list of the elements of that array in list context, or the
8741 number of elements in the array in scalar context. This function
8742 takes ownership of one counted reference to the scalar or array,
8743 and will arrange for the object to live as long as the subroutine
8744 does. If "sv" points to a scalar then the inlining assumes that
8745 the value of the scalar will never change, so the caller must
8746 ensure that the scalar is not subsequently written to. If "sv"
8747 points to an array then no such assumption is made, so it is
8748 ostensibly safe to mutate the array or its elements, but whether
8749 this is really supported has not been determined.
8750 The subroutine will have "CvFILE" set according to "PL_curcop".
8752 Other aspects of the subroutine will be left in their default
8753 state. The caller is free to mutate the subroutine beyond its
8754 initial state after this function has returned.
8755 If "name" is null then the subroutine will be anonymous, with its
8757 "CvGV" referring to an "__ANON__" glob. If "name" is non-null then
8758 the subroutine will be named accordingly, referenced by the
8759 appropriate glob. "name" is a string of length "len" bytes giving
8760 a sigilless symbol name, in UTF-8 if "flags" has the "SVf_UTF8" bit
8761 set and in Latin-1 otherwise. The name may be either qualified or
8762 unqualified. If the name is unqualified then it defaults to being
8763 in the stash specified by "stash" if that is non-null, or to
8764 "PL_curstash" if "stash" is null. The symbol is always added to
8765 the stash if necessary, with "GV_ADDMULTI" semantics.
8766 "flags" should not have bits set other than "SVf_UTF8".
8768 If there is already a subroutine of the specified name, then the
8770 new sub will replace the existing one in the glob. A warning may
8771 be generated about the redefinition.
8772 If the subroutine has one of a few special names, such as "BEGIN"
8774 or "END", then it will be claimed by the appropriate queue for
8775 automatic running of phase-related subroutines. In this case the
8776 relevant glob will be left not containing any subroutine, even if
8777 it did contain one before. Execution of the subroutine will likely
8778 be a no-op, unless "sv" was a tied array or the caller modified the
8779 subroutine in some interesting way before it was executed. In the
8780 case of "BEGIN", the treatment is buggy: the sub will be executed
8781 when only half built, and may be deleted prematurely, possibly
8782 causing a crash.
8783 The function returns a pointer to the constructed subroutine. If
8785 the sub is anonymous then ownership of one counted reference to the
8786 subroutine is transferred to the caller. If the sub is named then
8787 the caller does not get ownership of a reference. In most such
8788 cases, where the sub has a non-phase name, the sub will be alive at
8789 the point it is returned by virtue of being contained in the glob
8790 that names it. A phase-named subroutine will usually be alive by
8791 virtue of the reference owned by the phase's automatic run queue.
8792 A "BEGIN" subroutine may have been destroyed already by the time
8793 this function returns, but currently bugs occur in that case before
8794 the caller gets control. It is the caller's responsibility to
8795 ensure that it knows which of these situations applies.
8796 CV* newCONSTSUB_flags(HV* stash, const char* name, STRLEN len,
8798 U32 flags, SV* sv)
8799 "newDEFEROP"
8801 NOTE: "newDEFEROP" is experimental and may change or be removed
8802 without notice.
8803 Constructs and returns a deferred-block statement that implements
8805 the "defer" semantics. The "block" optree is consumed by this
8806 function and becomes part of the returned optree.
8807 The "flags" argument carries additional flags to set on the
8809 returned op, including the "op_private" field.
8810 OP* newDEFEROP(I32 flags, OP *block)
8812 "newDEFSVOP"
8814 Constructs and returns an op to access $_.
8815 OP* newDEFSVOP()
8817 "newFOROP"
8819 Constructs, checks, and returns an op tree expressing a "foreach"
8820 loop (iteration through a list of values). This is a heavyweight
8821 loop, with structure that allows exiting the loop by "last" and
8822 suchlike.
8823 "sv" optionally supplies the variable(s) that will be aliased to
8825 each item in turn; if null, it defaults to $_. "expr" supplies the
8826 list of values to iterate over. "block" supplies the main body of
8827 the loop, and "cont" optionally supplies a "continue" block that
8828 operates as a second half of the body. All of these optree inputs
8829 are consumed by this function and become part of the constructed op
8830 tree.
8831 "flags" gives the eight bits of "op_flags" for the "leaveloop" op
8833 and, shifted up eight bits, the eight bits of "op_private" for the
8834 "leaveloop" op, except that (in both cases) some bits will be set
8835 automatically.
8836 OP* newFOROP(I32 flags, OP* sv, OP* expr, OP* block, OP* cont)
8838 "newGIVENOP"
8840 Constructs, checks, and returns an op tree expressing a "given"
8841 block. "cond" supplies the expression to whose value $_ will be
8842 locally aliased, and "block" supplies the body of the "given"
8843 construct; they are consumed by this function and become part of
8844 the constructed op tree. "defsv_off" must be zero (it used to
8845 identity the pad slot of lexical $_).
8846 OP* newGIVENOP(OP* cond, OP* block, PADOFFSET defsv_off)
8848 "newGVOP"
8850 Constructs, checks, and returns an op of any type that involves an
8851 embedded reference to a GV. "type" is the opcode. "flags" gives
8852 the eight bits of "op_flags". "gv" identifies the GV that the op
8853 should reference; calling this function does not transfer ownership
8854 of any reference to it.
8855 OP* newGVOP(I32 type, I32 flags, GV* gv)
8857 "newLISTOP"
8859 Constructs, checks, and returns an op of any list type. "type" is
8860 the opcode. "flags" gives the eight bits of "op_flags", except
8861 that "OPf_KIDS" will be set automatically if required. "first" and
8862 "last" supply up to two ops to be direct children of the list op;
8863 they are consumed by this function and become part of the
8864 constructed op tree.
8865 For most list operators, the check function expects all the kid ops
8867 to be present already, so calling "newLISTOP(OP_JOIN, ...)" (e.g.)
8868 is not appropriate. What you want to do in that case is create an
8869 op of type "OP_LIST", append more children to it, and then call
8870 "op_convert_list". See "op_convert_list" for more information.
8871 OP* newLISTOP(I32 type, I32 flags, OP* first, OP* last)
8873 "newLOGOP"
8875 Constructs, checks, and returns a logical (flow control) op.
8876 "type" is the opcode. "flags" gives the eight bits of "op_flags",
8877 except that "OPf_KIDS" will be set automatically, and, shifted up
8878 eight bits, the eight bits of "op_private", except that the bit
8879 with value 1 is automatically set. "first" supplies the expression
8880 controlling the flow, and "other" supplies the side (alternate)
8881 chain of ops; they are consumed by this function and become part of
8882 the constructed op tree.
8883 OP* newLOGOP(I32 optype, I32 flags, OP *first, OP *other)
8885 "newLOOPEX"
8887 Constructs, checks, and returns a loop-exiting op (such as "goto"
8888 or "last"). "type" is the opcode. "label" supplies the parameter
8889 determining the target of the op; it is consumed by this function
8890 and becomes part of the constructed op tree.
8891 OP* newLOOPEX(I32 type, OP* label)
8893 "newLOOPOP"
8895 Constructs, checks, and returns an op tree expressing a loop. This
8896 is only a loop in the control flow through the op tree; it does not
8897 have the heavyweight loop structure that allows exiting the loop by
8898 "last" and suchlike. "flags" gives the eight bits of "op_flags"
8899 for the top-level op, except that some bits will be set
8900 automatically as required. "expr" supplies the expression
8901 controlling loop iteration, and "block" supplies the body of the
8902 loop; they are consumed by this function and become part of the
8903 constructed op tree. "debuggable" is currently unused and should
8904 always be 1.
8905 OP* newLOOPOP(I32 flags, I32 debuggable, OP* expr, OP* block)
8907 "newMETHOP"
8909 Constructs, checks, and returns an op of method type with a method
8910 name evaluated at runtime. "type" is the opcode. "flags" gives
8911 the eight bits of "op_flags", except that "OPf_KIDS" will be set
8912 automatically, and, shifted up eight bits, the eight bits of
8913 "op_private", except that the bit with value 1 is automatically
8914 set. "dynamic_meth" supplies an op which evaluates method name; it
8915 is consumed by this function and become part of the constructed op
8916 tree. Supported optypes: "OP_METHOD".
8917 OP* newMETHOP(I32 type, I32 flags, OP* dynamic_meth)
8919 "newMETHOP_named"
8921 Constructs, checks, and returns an op of method type with a
8922 constant method name. "type" is the opcode. "flags" gives the
8923 eight bits of "op_flags", and, shifted up eight bits, the eight
8924 bits of "op_private". "const_meth" supplies a constant method
8925 name; it must be a shared COW string. Supported optypes:
8926 "OP_METHOD_NAMED".
8927 OP* newMETHOP_named(I32 type, I32 flags, SV* const_meth)
8929 "newNULLLIST"
8931 Constructs, checks, and returns a new "stub" op, which represents
8932 an empty list expression.
8933 OP* newNULLLIST()
8935 "newOP"
8937 Constructs, checks, and returns an op of any base type (any type
8938 that has no extra fields). "type" is the opcode. "flags" gives
8939 the eight bits of "op_flags", and, shifted up eight bits, the eight
8940 bits of "op_private".
8941 OP* newOP(I32 optype, I32 flags)
8943 "newPADOP"
8945 Constructs, checks, and returns an op of any type that involves a
8946 reference to a pad element. "type" is the opcode. "flags" gives
8947 the eight bits of "op_flags". A pad slot is automatically
8948 allocated, and is populated with "sv"; this function takes
8949 ownership of one reference to it.
8950 This function only exists if Perl has been compiled to use
8952 ithreads.
8953 OP* newPADOP(I32 type, I32 flags, SV* sv)
8955 "newPMOP"
8957 Constructs, checks, and returns an op of any pattern matching type.
8958 "type" is the opcode. "flags" gives the eight bits of "op_flags"
8959 and, shifted up eight bits, the eight bits of "op_private".
8960 OP* newPMOP(I32 type, I32 flags)
8962 "newPVOP"
8964 Constructs, checks, and returns an op of any type that involves an
8965 embedded C-level pointer (PV). "type" is the opcode. "flags"
8966 gives the eight bits of "op_flags". "pv" supplies the C-level
8967 pointer. Depending on the op type, the memory referenced by "pv"
8968 may be freed when the op is destroyed. If the op is of a freeing
8969 type, "pv" must have been allocated using "PerlMemShared_malloc".
8970 OP* newPVOP(I32 type, I32 flags, char* pv)
8972 "newRANGE"
8974 Constructs and returns a "range" op, with subordinate "flip" and
8975 "flop" ops. "flags" gives the eight bits of "op_flags" for the
8976 "flip" op and, shifted up eight bits, the eight bits of
8977 "op_private" for both the "flip" and "range" ops, except that the
8978 bit with value 1 is automatically set. "left" and "right" supply
8979 the expressions controlling the endpoints of the range; they are
8980 consumed by this function and become part of the constructed op
8981 tree.
8982 OP* newRANGE(I32 flags, OP* left, OP* right)
8984 "newSLICEOP"
8986 Constructs, checks, and returns an "lslice" (list slice) op.
8987 "flags" gives the eight bits of "op_flags", except that "OPf_KIDS"
8988 will be set automatically, and, shifted up eight bits, the eight
8989 bits of "op_private", except that the bit with value 1 or 2 is
8990 automatically set as required. "listval" and "subscript" supply
8991 the parameters of the slice; they are consumed by this function and
8992 become part of the constructed op tree.
8993 OP* newSLICEOP(I32 flags, OP* subscript, OP* listop)
8995 "newSTATEOP"
8997 Constructs a state op (COP). The state op is normally a
8998 "nextstate" op, but will be a "dbstate" op if debugging is enabled
8999 for currently-compiled code. The state op is populated from
9000 "PL_curcop" (or "PL_compiling"). If "label" is non-null, it
9001 supplies the name of a label to attach to the state op; this
9002 function takes ownership of the memory pointed at by "label", and
9003 will free it. "flags" gives the eight bits of "op_flags" for the
9004 state op.
9005 If "o" is null, the state op is returned. Otherwise the state op
9007 is combined with "o" into a "lineseq" list op, which is returned.
9008 "o" is consumed by this function and becomes part of the returned
9009 op tree.
9010 OP* newSTATEOP(I32 flags, char* label, OP* o)
9012 "newSUB"
9014 Like "newATTRSUB", but without attributes.
9015 CV* newSUB(I32 floor, OP* o, OP* proto, OP* block)
9017 "newSVOP"
9019 Constructs, checks, and returns an op of any type that involves an
9020 embedded SV. "type" is the opcode. "flags" gives the eight bits
9021 of "op_flags". "sv" gives the SV to embed in the op; this function
9022 takes ownership of one reference to it.
9023 OP* newSVOP(I32 type, I32 flags, SV* sv)
9025 "newTRYCATCHOP"
9027 NOTE: "newTRYCATCHOP" is experimental and may change or be removed
9028 without notice.
9029 Constructs and returns a conditional execution statement that
9031 implements the "try"/"catch" semantics. First the op tree in
9032 "tryblock" is executed, inside a context that traps exceptions. If
9033 an exception occurs then the optree in "catchblock" is executed,
9034 with the trapped exception set into the lexical variable given by
9035 "catchvar" (which must be an op of type "OP_PADSV"). All the
9036 optrees are consumed by this function and become part of the
9037 returned op tree.
9038 The "flags" argument is currently ignored.
9040 OP* newTRYCATCHOP(I32 flags, OP* tryblock, OP *catchvar,
9042 OP* catchblock)
9043 "newUNOP"
9045 Constructs, checks, and returns an op of any unary type. "type" is
9046 the opcode. "flags" gives the eight bits of "op_flags", except
9047 that "OPf_KIDS" will be set automatically if required, and, shifted
9048 up eight bits, the eight bits of "op_private", except that the bit
9049 with value 1 is automatically set. "first" supplies an optional op
9050 to be the direct child of the unary op; it is consumed by this
9051 function and become part of the constructed op tree.
9052 OP* newUNOP(I32 type, I32 flags, OP* first)
9054 "newUNOP_AUX"
9056 Similar to "newUNOP", but creates an "UNOP_AUX" struct instead,
9057 with "op_aux" initialised to "aux"
9058 OP* newUNOP_AUX(I32 type, I32 flags, OP* first,
9060 UNOP_AUX_item *aux)
9061 "newWHENOP"
9063 Constructs, checks, and returns an op tree expressing a "when"
9064 block. "cond" supplies the test expression, and "block" supplies
9065 the block that will be executed if the test evaluates to true; they
9066 are consumed by this function and become part of the constructed op
9067 tree. "cond" will be interpreted DWIMically, often as a comparison
9068 against $_, and may be null to generate a "default" block.
9069 OP* newWHENOP(OP* cond, OP* block)
9071 "newWHILEOP"
9073 Constructs, checks, and returns an op tree expressing a "while"
9074 loop. This is a heavyweight loop, with structure that allows
9075 exiting the loop by "last" and suchlike.
9076 "loop" is an optional preconstructed "enterloop" op to use in the
9078 loop; if it is null then a suitable op will be constructed
9079 automatically. "expr" supplies the loop's controlling expression.
9080 "block" supplies the main body of the loop, and "cont" optionally
9081 supplies a "continue" block that operates as a second half of the
9082 body. All of these optree inputs are consumed by this function and
9083 become part of the constructed op tree.
9084 "flags" gives the eight bits of "op_flags" for the "leaveloop" op
9086 and, shifted up eight bits, the eight bits of "op_private" for the
9087 "leaveloop" op, except that (in both cases) some bits will be set
9088 automatically. "debuggable" is currently unused and should always
9089 be 1. "has_my" can be supplied as true to force the loop body to
9090 be enclosed in its own scope.
9091 OP* newWHILEOP(I32 flags, I32 debuggable, LOOP* loop, OP* expr,
9093 OP* block, OP* cont, I32 has_my)
9094 "newXS"
9096 Used by "xsubpp" to hook up XSUBs as Perl subs. "filename" needs
9097 to be static storage, as it is used directly as CvFILE(), without a
9098 copy being made.
9099 "OA_BASEOP"
9101 "OA_BINOP"
9102 "OA_COP"
9103 "OA_LISTOP"
9104 "OA_LOGOP"
9105 "OA_PADOP"
9106 "OA_PMOP"
9107 "OA_PVOP_OR_SVOP"
9108 "OA_SVOP"
9109 "OA_UNOP"
9110 "OA_LOOP"
9111 Described in perlguts.
9112 "OP"
9114 Described in perlguts.
9115 "op_append_elem"
9117 Append an item to the list of ops contained directly within a list-
9118 type op, returning the lengthened list. "first" is the list-type
9119 op, and "last" is the op to append to the list. "optype" specifies
9120 the intended opcode for the list. If "first" is not already a list
9121 of the right type, it will be upgraded into one. If either "first"
9122 or "last" is null, the other is returned unchanged.
9123 OP* op_append_elem(I32 optype, OP* first, OP* last)
9125 "op_append_list"
9127 Concatenate the lists of ops contained directly within two list-
9128 type ops, returning the combined list. "first" and "last" are the
9129 list-type ops to concatenate. "optype" specifies the intended
9130 opcode for the list. If either "first" or "last" is not already a
9131 list of the right type, it will be upgraded into one. If either
9132 "first" or "last" is null, the other is returned unchanged.
9133 OP* op_append_list(I32 optype, OP* first, OP* last)
9135 "OP_CLASS"
9137 Return the class of the provided OP: that is, which of the *OP
9138 structures it uses. For core ops this currently gets the
9139 information out of "PL_opargs", which does not always accurately
9140 reflect the type used; in v5.26 onwards, see also the function
9141 "op_class" which can do a better job of determining the used type.
9142 For custom ops the type is returned from the registration, and it
9144 is up to the registree to ensure it is accurate. The value
9145 returned will be one of the "OA_"* constants from op.h.
9146 U32 OP_CLASS(OP *o)
9148 "op_contextualize"
9150 Applies a syntactic context to an op tree representing an
9151 expression. "o" is the op tree, and "context" must be "G_SCALAR",
9152 "G_LIST", or "G_VOID" to specify the context to apply. The
9153 modified op tree is returned.
9154 OP* op_contextualize(OP* o, I32 context)
9156 "op_convert_list"
9158 Converts "o" into a list op if it is not one already, and then
9159 converts it into the specified "type", calling its check function,
9160 allocating a target if it needs one, and folding constants.
9161 A list-type op is usually constructed one kid at a time via
9163 "newLISTOP", "op_prepend_elem" and "op_append_elem". Then finally
9164 it is passed to "op_convert_list" to make it the right type.
9165 OP* op_convert_list(I32 optype, I32 flags, OP* o)
9167 "OP_DESC"
9169 Return a short description of the provided OP.
9170 const char * OP_DESC(OP *o)
9172 "op_free"
9174 Free an op and its children. Only use this when an op is no longer
9175 linked to from any optree.
9176 void op_free(OP* arg)
9178 "OpHAS_SIBLING"
9180 Returns true if "o" has a sibling
9181 bool OpHAS_SIBLING(OP *o)
9183 "OpLASTSIB_set"
9185 Marks "o" as having no further siblings and marks o as having the
9186 specified parent. See also "OpMORESIB_set" and "OpMAYBESIB_set".
9187 For a higher-level interface, see "op_sibling_splice".
9188 void OpLASTSIB_set(OP *o, OP *parent)
9190 "op_linklist"
9192 This function is the implementation of the "LINKLIST" macro. It
9193 should not be called directly.
9194 OP* op_linklist(OP *o)
9196 "op_lvalue"
9198 NOTE: "op_lvalue" is experimental and may change or be removed
9199 without notice.
9200 Propagate lvalue ("modifiable") context to an op and its children.
9202 "type" represents the context type, roughly based on the type of op
9203 that would do the modifying, although "local()" is represented by
9204 "OP_NULL", because it has no op type of its own (it is signalled by
9205 a flag on the lvalue op).
9206 This function detects things that can't be modified, such as
9208 "$x+1", and generates errors for them. For example, "$x+1 = 2"
9209 would cause it to be called with an op of type "OP_ADD" and a
9210 "type" argument of "OP_SASSIGN".
9211 It also flags things that need to behave specially in an lvalue
9213 context, such as "$$x = 5" which might have to vivify a reference
9214 in $x.
9215 OP* op_lvalue(OP* o, I32 type)
9217 "OpMAYBESIB_set"
9219 Conditionally does "OpMORESIB_set" or "OpLASTSIB_set" depending on
9220 whether "sib" is non-null. For a higher-level interface, see
9221 "op_sibling_splice".
9222 void OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
9224 "OpMORESIB_set"
9226 Sets the sibling of "o" to the non-zero value "sib". See also
9227 "OpLASTSIB_set" and "OpMAYBESIB_set". For a higher-level interface,
9228 see "op_sibling_splice".
9229 void OpMORESIB_set(OP *o, OP *sib)
9231 "OP_NAME"
9233 Return the name of the provided OP. For core ops this looks up the
9234 name from the op_type; for custom ops from the op_ppaddr.
9235 const char * OP_NAME(OP *o)
9237 "op_null"
9239 Neutralizes an op when it is no longer needed, but is still linked
9240 to from other ops.
9241 void op_null(OP* o)
9243 "op_parent"
9245 Returns the parent OP of "o", if it has a parent. Returns "NULL"
9246 otherwise.
9247 OP* op_parent(OP *o)
9249 "op_prepend_elem"
9251 Prepend an item to the list of ops contained directly within a
9252 list-type op, returning the lengthened list. "first" is the op to
9253 prepend to the list, and "last" is the list-type op. "optype"
9254 specifies the intended opcode for the list. If "last" is not
9255 already a list of the right type, it will be upgraded into one. If
9256 either "first" or "last" is null, the other is returned unchanged.
9257 OP* op_prepend_elem(I32 optype, OP* first, OP* last)
9259 "op_scope"
9261 NOTE: "op_scope" is experimental and may change or be removed
9262 without notice.
9263 Wraps up an op tree with some additional ops so that at runtime a
9265 dynamic scope will be created. The original ops run in the new
9266 dynamic scope, and then, provided that they exit normally, the
9267 scope will be unwound. The additional ops used to create and
9268 unwind the dynamic scope will normally be an "enter"/"leave" pair,
9269 but a "scope" op may be used instead if the ops are simple enough
9270 to not need the full dynamic scope structure.
9271 OP* op_scope(OP* o)
9273 "OpSIBLING"
9275 Returns the sibling of "o", or "NULL" if there is no sibling
9276 OP* OpSIBLING(OP *o)
9278 "op_sibling_splice"
9280 A general function for editing the structure of an existing chain
9281 of op_sibling nodes. By analogy with the perl-level "splice()"
9282 function, allows you to delete zero or more sequential nodes,
9283 replacing them with zero or more different nodes. Performs the
9284 necessary op_first/op_last housekeeping on the parent node and
9285 op_sibling manipulation on the children. The last deleted node
9286 will be marked as the last node by updating the
9287 op_sibling/op_sibparent or op_moresib field as appropriate.
9288 Note that op_next is not manipulated, and nodes are not freed; that
9290 is the responsibility of the caller. It also won't create a new
9291 list op for an empty list etc; use higher-level functions like
9292 op_append_elem() for that.
9293 "parent" is the parent node of the sibling chain. It may passed as
9295 "NULL" if the splicing doesn't affect the first or last op in the
9296 chain.
9297 "start" is the node preceding the first node to be spliced.
9299 Node(s) following it will be deleted, and ops will be inserted
9300 after it. If it is "NULL", the first node onwards is deleted, and
9301 nodes are inserted at the beginning.
9302 "del_count" is the number of nodes to delete. If zero, no nodes
9304 are deleted. If -1 or greater than or equal to the number of
9305 remaining kids, all remaining kids are deleted.
9306 "insert" is the first of a chain of nodes to be inserted in place
9308 of the nodes. If "NULL", no nodes are inserted.
9309 The head of the chain of deleted ops is returned, or "NULL" if no
9311 ops were deleted.
9312 For example:
9314 action before after returns
9316 ------ ----- ----- -------
9317 P P
9319 splice(P, A, 2, X-Y-Z) | | B-C
9320 A-B-C-D A-X-Y-Z-D
9321 P P
9323 splice(P, NULL, 1, X-Y) | | A
9324 A-B-C-D X-Y-B-C-D
9325 P P
9327 splice(P, NULL, 3, NULL) | | A-B-C
9328 A-B-C-D D
9329 P P
9331 splice(P, B, 0, X-Y) | | NULL
9332 A-B-C-D A-B-X-Y-C-D
9333 For lower-level direct manipulation of "op_sibparent" and
9335 "op_moresib", see "OpMORESIB_set", "OpLASTSIB_set",
9336 "OpMAYBESIB_set".
9337 OP* op_sibling_splice(OP *parent, OP *start, int del_count,
9339 OP* insert)
9340 "OP_TYPE_IS"
9342 Returns true if the given OP is not a "NULL" pointer and if it is
9343 of the given type.
9344 The negation of this macro, "OP_TYPE_ISNT" is also available as
9346 well as "OP_TYPE_IS_NN" and "OP_TYPE_ISNT_NN" which elide the NULL
9347 pointer check.
9348 bool OP_TYPE_IS(OP *o, Optype type)
9350 "OP_TYPE_IS_OR_WAS"
9352 Returns true if the given OP is not a NULL pointer and if it is of
9353 the given type or used to be before being replaced by an OP of type
9354 OP_NULL.
9355 The negation of this macro, "OP_TYPE_ISNT_AND_WASNT" is also
9357 available as well as "OP_TYPE_IS_OR_WAS_NN" and
9358 "OP_TYPE_ISNT_AND_WASNT_NN" which elide the "NULL" pointer check.
9359 bool OP_TYPE_IS_OR_WAS(OP *o, Optype type)
9361 "op_wrap_finally"
9363 NOTE: "op_wrap_finally" is experimental and may change or be
9364 removed without notice.
9365 Wraps the given "block" optree fragment in its own scoped block,
9367 arranging for the "finally" optree fragment to be invoked when
9368 leaving that block for any reason. Both optree fragments are
9369 consumed and the combined result is returned.
9370 OP* op_wrap_finally(OP *block, OP *finally)
9372 "peep_t"
9374 Described in perlguts.
9375 "Perl_cpeep_t"
9377 Described in perlguts.
9378 "PL_opfreehook"
9380 When non-"NULL", the function pointed by this variable will be
9381 called each time an OP is freed with the corresponding OP as the
9382 argument. This allows extensions to free any extra attribute they
9383 have locally attached to an OP. It is also assured to first fire
9384 for the parent OP and then for its kids.
9385 When you replace this variable, it is considered a good practice to
9387 store the possibly previously installed hook and that you recall it
9388 inside your own.
9389 On threaded perls, each thread has an independent copy of this
9391 variable; each initialized at creation time with the current value
9392 of the creating thread's copy.
9393 Perl_ophook_t PL_opfreehook
9395 "PL_peepp"
9397 Pointer to the per-subroutine peephole optimiser. This is a
9398 function that gets called at the end of compilation of a Perl
9399 subroutine (or equivalently independent piece of Perl code) to
9400 perform fixups of some ops and to perform small-scale
9401 optimisations. The function is called once for each subroutine
9402 that is compiled, and is passed, as sole parameter, a pointer to
9403 the op that is the entry point to the subroutine. It modifies the
9404 op tree in place.
9405 The peephole optimiser should never be completely replaced.
9407 Rather, add code to it by wrapping the existing optimiser. The
9408 basic way to do this can be seen in "Compile pass 3: peephole
9409 optimization" in perlguts. If the new code wishes to operate on
9410 ops throughout the subroutine's structure, rather than just at the
9411 top level, it is likely to be more convenient to wrap the
9412 "PL_rpeepp" hook.
9413 On threaded perls, each thread has an independent copy of this
9415 variable; each initialized at creation time with the current value
9416 of the creating thread's copy.
9417 peep_t PL_peepp
9419 "PL_rpeepp"
9421 Pointer to the recursive peephole optimiser. This is a function
9422 that gets called at the end of compilation of a Perl subroutine (or
9423 equivalently independent piece of Perl code) to perform fixups of
9424 some ops and to perform small-scale optimisations. The function is
9425 called once for each chain of ops linked through their "op_next"
9426 fields; it is recursively called to handle each side chain. It is
9427 passed, as sole parameter, a pointer to the op that is at the head
9428 of the chain. It modifies the op tree in place.
9429 The peephole optimiser should never be completely replaced.
9431 Rather, add code to it by wrapping the existing optimiser. The
9432 basic way to do this can be seen in "Compile pass 3: peephole
9433 optimization" in perlguts. If the new code wishes to operate only
9434 on ops at a subroutine's top level, rather than throughout the
9435 structure, it is likely to be more convenient to wrap the
9436 "PL_peepp" hook.
9437 On threaded perls, each thread has an independent copy of this
9439 variable; each initialized at creation time with the current value
9440 of the creating thread's copy.
9441 peep_t PL_rpeepp
9443 "PMOP"
9445 Described in perlguts.
9446 "rv2cv_op_cv"
9448 Examines an op, which is expected to identify a subroutine at
9449 runtime, and attempts to determine at compile time which subroutine
9450 it identifies. This is normally used during Perl compilation to
9451 determine whether a prototype can be applied to a function call.
9452 "cvop" is the op being considered, normally an "rv2cv" op. A
9453 pointer to the identified subroutine is returned, if it could be
9454 determined statically, and a null pointer is returned if it was not
9455 possible to determine statically.
9456 Currently, the subroutine can be identified statically if the RV
9458 that the "rv2cv" is to operate on is provided by a suitable "gv" or
9459 "const" op. A "gv" op is suitable if the GV's CV slot is
9460 populated. A "const" op is suitable if the constant value must be
9461 an RV pointing to a CV. Details of this process may change in
9462 future versions of Perl. If the "rv2cv" op has the
9463 "OPpENTERSUB_AMPER" flag set then no attempt is made to identify
9464 the subroutine statically: this flag is used to suppress compile-
9465 time magic on a subroutine call, forcing it to use default runtime
9466 behaviour.
9467 If "flags" has the bit "RV2CVOPCV_MARK_EARLY" set, then the
9469 handling of a GV reference is modified. If a GV was examined and
9470 its CV slot was found to be empty, then the "gv" op has the
9471 "OPpEARLY_CV" flag set. If the op is not optimised away, and the
9472 CV slot is later populated with a subroutine having a prototype,
9473 that flag eventually triggers the warning "called too early to
9474 check prototype".
9475 If "flags" has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then instead
9477 of returning a pointer to the subroutine it returns a pointer to
9478 the GV giving the most appropriate name for the subroutine in this
9479 context. Normally this is just the "CvGV" of the subroutine, but
9480 for an anonymous ("CvANON") subroutine that is referenced through a
9481 GV it will be the referencing GV. The resulting "GV*" is cast to
9482 "CV*" to be returned. A null pointer is returned as usual if there
9483 is no statically-determinable subroutine.
9484 CV* rv2cv_op_cv(OP *cvop, U32 flags)
9486 "UNOP"
9488 Described in perlguts.
9489 "XOP"
9491 Described in perlguts.
9492
9494 "pack_cat"
9495 "DEPRECATED!" It is planned to remove "pack_cat" from a future
9496 release of Perl. Do not use it for new code; remove it from
9497 existing code.
9498 The engine implementing "pack()" Perl function. Note: parameters
9500 "next_in_list" and "flags" are not used. This call should not be
9501 used; use "packlist" instead.
9502 void pack_cat(SV *cat, const char *pat, const char *patend,
9504 SV **beglist, SV **endlist, SV ***next_in_list,
9505 U32 flags)
9506 "packlist"
9508 The engine implementing "pack()" Perl function.
9509 void packlist(SV *cat, const char *pat, const char *patend,
9511 SV **beglist, SV **endlist)
9512 "unpack_str"
9514 "DEPRECATED!" It is planned to remove "unpack_str" from a future
9515 release of Perl. Do not use it for new code; remove it from
9516 existing code.
9517 The engine implementing "unpack()" Perl function. Note: parameters
9519 "strbeg", "new_s" and "ocnt" are not used. This call should not be
9520 used, use "unpackstring" instead.
9521 SSize_t unpack_str(const char *pat, const char *patend,
9523 const char *s, const char *strbeg,
9524 const char *strend, char **new_s, I32 ocnt,
9525 U32 flags)
9526 "unpackstring"
9528 The engine implementing the "unpack()" Perl function.
9529 Using the template "pat..patend", this function unpacks the string
9531 "s..strend" into a number of mortal SVs, which it pushes onto the
9532 perl argument (@_) stack (so you will need to issue a "PUTBACK"
9533 before and "SPAGAIN" after the call to this function). It returns
9534 the number of pushed elements.
9535 The "strend" and "patend" pointers should point to the byte
9537 following the last character of each string.
9538 Although this function returns its values on the perl argument
9540 stack, it doesn't take any parameters from that stack (and thus in
9541 particular there's no need to do a "PUSHMARK" before calling it,
9542 unlike "call_pv" for example).
9543 SSize_t unpackstring(const char *pat, const char *patend,
9545 const char *s, const char *strend,
9546 U32 flags)
9547
9549 "CvPADLIST"
9550 NOTE: "CvPADLIST" is experimental and may change or be removed
9551 without notice.
9552 CV's can have CvPADLIST(cv) set to point to a PADLIST. This is the
9554 CV's scratchpad, which stores lexical variables and opcode
9555 temporary and per-thread values.
9556 For these purposes "formats" are a kind-of CV; eval""s are too
9558 (except they're not callable at will and are always thrown away
9559 after the eval"" is done executing). Require'd files are simply
9560 evals without any outer lexical scope.
9561 XSUBs do not have a "CvPADLIST". "dXSTARG" fetches values from
9563 "PL_curpad", but that is really the callers pad (a slot of which is
9564 allocated by every entersub). Do not get or set "CvPADLIST" if a CV
9565 is an XSUB (as determined by "CvISXSUB()"), "CvPADLIST" slot is
9566 reused for a different internal purpose in XSUBs.
9567 The PADLIST has a C array where pads are stored.
9569 The 0th entry of the PADLIST is a PADNAMELIST which represents the
9571 "names" or rather the "static type information" for lexicals. The
9572 individual elements of a PADNAMELIST are PADNAMEs. Future
9573 refactorings might stop the PADNAMELIST from being stored in the
9574 PADLIST's array, so don't rely on it. See "PadlistNAMES".
9575 The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the
9577 stack frame at that depth of recursion into the CV. The 0th slot
9578 of a frame AV is an AV which is @_. Other entries are storage for
9579 variables and op targets.
9580 Iterating over the PADNAMELIST iterates over all possible pad
9582 items. Pad slots for targets ("SVs_PADTMP") and GVs end up having
9583 &PL_padname_undef "names", while slots for constants have
9584 &PL_padname_const "names" (see "pad_alloc"). That
9585 &PL_padname_undef and &PL_padname_const are used is an
9586 implementation detail subject to change. To test for them, use
9587 "!PadnamePV(name)" and "PadnamePV(name) && !PadnameLEN(name)",
9588 respectively.
9589 Only "my"/"our" variable slots get valid names. The rest are op
9591 targets/GVs/constants which are statically allocated or resolved at
9592 compile time. These don't have names by which they can be looked
9593 up from Perl code at run time through eval"" the way "my"/"our"
9594 variables can be. Since they can't be looked up by "name" but only
9595 by their index allocated at compile time (which is usually in
9596 "PL_op->op_targ"), wasting a name SV for them doesn't make sense.
9597 The pad names in the PADNAMELIST have their PV holding the name of
9599 the variable. The "COP_SEQ_RANGE_LOW" and "_HIGH" fields form a
9600 range (low+1..high inclusive) of cop_seq numbers for which the name
9601 is valid. During compilation, these fields may hold the special
9602 value PERL_PADSEQ_INTRO to indicate various stages:
9603 COP_SEQ_RANGE_LOW _HIGH
9605 ----------------- -----
9606 PERL_PADSEQ_INTRO 0 variable not yet introduced:
9607 { my ($x
9608 valid-seq# PERL_PADSEQ_INTRO variable in scope:
9609 { my ($x);
9610 valid-seq# valid-seq# compilation of scope complete:
9611 { my ($x); .... }
9612 When a lexical var hasn't yet been introduced, it already exists
9614 from the perspective of duplicate declarations, but not for
9615 variable lookups, e.g.
9616 my ($x, $x); # '"my" variable $x masks earlier declaration'
9618 my $x = $x; # equal to my $x = $::x;
9619 For typed lexicals "PadnameTYPE" points at the type stash. For
9621 "our" lexicals, "PadnameOURSTASH" points at the stash of the
9622 associated global (so that duplicate "our" declarations in the same
9623 package can be detected). "PadnameGEN" is sometimes used to store
9624 the generation number during compilation.
9625 If "PadnameOUTER" is set on the pad name, then that slot in the
9627 frame AV is a REFCNT'ed reference to a lexical from "outside".
9628 Such entries are sometimes referred to as 'fake'. In this case,
9629 the name does not use 'low' and 'high' to store a cop_seq range,
9630 since it is in scope throughout. Instead 'high' stores some flags
9631 containing info about the real lexical (is it declared in an anon,
9632 and is it capable of being instantiated multiple times?), and for
9633 fake ANONs, 'low' contains the index within the parent's pad where
9634 the lexical's value is stored, to make cloning quicker.
9635 If the 'name' is "&" the corresponding entry in the PAD is a CV
9637 representing a possible closure.
9638 Note that formats are treated as anon subs, and are cloned each
9640 time write is called (if necessary).
9641 The flag "SVs_PADSTALE" is cleared on lexicals each time the "my()"
9643 is executed, and set on scope exit. This allows the "Variable $x
9644 is not available" warning to be generated in evals, such as
9645 { my $x = 1; sub f { eval '$x'} } f();
9647 For state vars, "SVs_PADSTALE" is overloaded to mean 'not yet
9649 initialised', but this internal state is stored in a separate pad
9650 entry.
9651 PADLIST * CvPADLIST(CV *cv)
9653 "pad_add_name_pvs"
9655 Exactly like "pad_add_name_pvn", but takes a literal string instead
9656 of a string/length pair.
9657 PADOFFSET pad_add_name_pvs("name", U32 flags, HV *typestash,
9659 HV *ourstash)
9660 "PadARRAY"
9662 NOTE: "PadARRAY" is experimental and may change or be removed
9663 without notice.
9664 The C array of pad entries.
9666 SV ** PadARRAY(PAD * pad)
9668 "pad_compname_type"
9670 "DEPRECATED!" It is planned to remove "pad_compname_type" from a
9671 future release of Perl. Do not use it for new code; remove it from
9672 existing code.
9673 Looks up the type of the lexical variable at position "po" in the
9675 currently-compiling pad. If the variable is typed, the stash of
9676 the class to which it is typed is returned. If not, "NULL" is
9677 returned.
9678 Use ""PAD_COMPNAME_TYPE"" in perlintern instead.
9680 HV* pad_compname_type(const PADOFFSET po)
9682 "pad_findmy_pvs"
9684 Exactly like "pad_findmy_pvn", but takes a literal string instead
9685 of a string/length pair.
9686 PADOFFSET pad_findmy_pvs("name", U32 flags)
9688 "PadlistARRAY"
9690 NOTE: "PadlistARRAY" is experimental and may change or be removed
9691 without notice.
9692 The C array of a padlist, containing the pads. Only subscript it
9694 with numbers >= 1, as the 0th entry is not guaranteed to remain
9695 usable.
9696 PAD ** PadlistARRAY(PADLIST * padlist)
9698 "PadlistMAX"
9700 NOTE: "PadlistMAX" is experimental and may change or be removed
9701 without notice.
9702 The index of the last allocated space in the padlist. Note that
9704 the last pad may be in an earlier slot. Any entries following it
9705 will be "NULL" in that case.
9706 SSize_t PadlistMAX(PADLIST * padlist)
9708 "PadlistNAMES"
9710 NOTE: "PadlistNAMES" is experimental and may change or be removed
9711 without notice.
9712 The names associated with pad entries.
9714 PADNAMELIST * PadlistNAMES(PADLIST * padlist)
9716 "PadlistNAMESARRAY"
9718 NOTE: "PadlistNAMESARRAY" is experimental and may change or be
9719 removed without notice.
9720 The C array of pad names.
9722 PADNAME ** PadlistNAMESARRAY(PADLIST * padlist)
9724 "PadlistNAMESMAX"
9726 NOTE: "PadlistNAMESMAX" is experimental and may change or be
9727 removed without notice.
9728 The index of the last pad name.
9730 SSize_t PadlistNAMESMAX(PADLIST * padlist)
9732 "PadlistREFCNT"
9734 NOTE: "PadlistREFCNT" is experimental and may change or be removed
9735 without notice.
9736 The reference count of the padlist. Currently this is always 1.
9738 U32 PadlistREFCNT(PADLIST * padlist)
9740 "PadMAX"
9742 NOTE: "PadMAX" is experimental and may change or be removed without
9743 notice.
9744 The index of the last pad entry.
9746 SSize_t PadMAX(PAD * pad)
9748 "PadnameLEN"
9750 NOTE: "PadnameLEN" is experimental and may change or be removed
9751 without notice.
9752 The length of the name.
9754 STRLEN PadnameLEN(PADNAME * pn)
9756 "PadnamelistARRAY"
9758 NOTE: "PadnamelistARRAY" is experimental and may change or be
9759 removed without notice.
9760 The C array of pad names.
9762 PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl)
9764 "PadnamelistMAX"
9766 NOTE: "PadnamelistMAX" is experimental and may change or be removed
9767 without notice.
9768 The index of the last pad name.
9770 SSize_t PadnamelistMAX(PADNAMELIST * pnl)
9772 "PadnamelistREFCNT"
9774 NOTE: "PadnamelistREFCNT" is experimental and may change or be
9775 removed without notice.
9776 The reference count of the pad name list.
9778 SSize_t PadnamelistREFCNT(PADNAMELIST * pnl)
9780 "PadnamelistREFCNT_dec"
9782 NOTE: "PadnamelistREFCNT_dec" is experimental and may change or be
9783 removed without notice.
9784 Lowers the reference count of the pad name list.
9786 void PadnamelistREFCNT_dec(PADNAMELIST * pnl)
9788 "PadnamePV"
9790 NOTE: "PadnamePV" is experimental and may change or be removed
9791 without notice.
9792 The name stored in the pad name struct. This returns "NULL" for a
9794 target slot.
9795 char * PadnamePV(PADNAME * pn)
9797 "PadnameREFCNT"
9799 NOTE: "PadnameREFCNT" is experimental and may change or be removed
9800 without notice.
9801 The reference count of the pad name.
9803 SSize_t PadnameREFCNT(PADNAME * pn)
9805 "PadnameREFCNT_dec"
9807 NOTE: "PadnameREFCNT_dec" is experimental and may change or be
9808 removed without notice.
9809 Lowers the reference count of the pad name.
9811 void PadnameREFCNT_dec(PADNAME * pn)
9813 "PadnameSV"
9815 NOTE: "PadnameSV" is experimental and may change or be removed
9816 without notice.
9817 Returns the pad name as a mortal SV.
9819 SV * PadnameSV(PADNAME * pn)
9821 "PadnameUTF8"
9823 NOTE: "PadnameUTF8" is experimental and may change or be removed
9824 without notice.
9825 Whether PadnamePV is in UTF-8. Currently, this is always true.
9827 bool PadnameUTF8(PADNAME * pn)
9829 "pad_new"
9831 Create a new padlist, updating the global variables for the
9832 currently-compiling padlist to point to the new padlist. The
9833 following flags can be OR'ed together:
9834 padnew_CLONE this pad is for a cloned CV
9836 padnew_SAVE save old globals on the save stack
9837 padnew_SAVESUB also save extra stuff for start of sub
9838 PADLIST* pad_new(int flags)
9840 "PL_comppad"
9842 NOTE: "PL_comppad" is experimental and may change or be removed
9843 without notice.
9844 During compilation, this points to the array containing the values
9846 part of the pad for the currently-compiling code. (At runtime a CV
9847 may have many such value arrays; at compile time just one is
9848 constructed.) At runtime, this points to the array containing the
9849 currently-relevant values for the pad for the currently-executing
9850 code.
9851 "PL_comppad_name"
9853 NOTE: "PL_comppad_name" is experimental and may change or be
9854 removed without notice.
9855 During compilation, this points to the array containing the names
9857 part of the pad for the currently-compiling code.
9858 "PL_curpad"
9860 NOTE: "PL_curpad" is experimental and may change or be removed
9861 without notice.
9862 Points directly to the body of the "PL_comppad" array. (I.e., this
9864 is "PadARRAY(PL_comppad)".)
9865 "SVs_PADMY"
9867 "DEPRECATED!" It is planned to remove "SVs_PADMY" from a future
9868 release of Perl. Do not use it for new code; remove it from
9869 existing code.
9870 Described in perlguts.
9872 "SVs_PADTMP"
9874 Described in perlguts.
9875
9877 "GRPASSWD"
9878 This symbol, if defined, indicates to the C program that "struct
9879 group" in grp.h contains "gr_passwd".
9880 "HAS_ENDGRENT"
9882 This symbol, if defined, indicates that the getgrent routine is
9883 available for finalizing sequential access of the group database.
9884 "HAS_ENDGRENT_R"
9886 This symbol, if defined, indicates that the "endgrent_r" routine is
9887 available to endgrent re-entrantly.
9888 "HAS_ENDPWENT"
9890 This symbol, if defined, indicates that the "endpwent" routine is
9891 available for finalizing sequential access of the passwd database.
9892 "HAS_ENDPWENT_R"
9894 This symbol, if defined, indicates that the "endpwent_r" routine is
9895 available to endpwent re-entrantly.
9896 "HAS_GETGRENT"
9898 This symbol, if defined, indicates that the "getgrent" routine is
9899 available for sequential access of the group database.
9900 "HAS_GETGRENT_R"
9902 This symbol, if defined, indicates that the "getgrent_r" routine is
9903 available to getgrent re-entrantly.
9904 "HAS_GETPWENT"
9906 This symbol, if defined, indicates that the "getpwent" routine is
9907 available for sequential access of the passwd database. If this is
9908 not available, the older "getpw()" function may be available.
9909 "HAS_GETPWENT_R"
9911 This symbol, if defined, indicates that the "getpwent_r" routine is
9912 available to getpwent re-entrantly.
9913 "HAS_SETGRENT"
9915 This symbol, if defined, indicates that the "setgrent" routine is
9916 available for initializing sequential access of the group database.
9917 "HAS_SETGRENT_R"
9919 This symbol, if defined, indicates that the "setgrent_r" routine is
9920 available to setgrent re-entrantly.
9921 "HAS_SETPWENT"
9923 This symbol, if defined, indicates that the "setpwent" routine is
9924 available for initializing sequential access of the passwd
9925 database.
9926 "HAS_SETPWENT_R"
9928 This symbol, if defined, indicates that the "setpwent_r" routine is
9929 available to setpwent re-entrantly.
9930 "PWAGE"
9932 This symbol, if defined, indicates to the C program that "struct
9933 passwd" contains "pw_age".
9934 "PWCHANGE"
9936 This symbol, if defined, indicates to the C program that "struct
9937 passwd" contains "pw_change".
9938 "PWCLASS"
9940 This symbol, if defined, indicates to the C program that "struct
9941 passwd" contains "pw_class".
9942 "PWCOMMENT"
9944 This symbol, if defined, indicates to the C program that "struct
9945 passwd" contains "pw_comment".
9946 "PWEXPIRE"
9948 This symbol, if defined, indicates to the C program that "struct
9949 passwd" contains "pw_expire".
9950 "PWGECOS"
9952 This symbol, if defined, indicates to the C program that "struct
9953 passwd" contains "pw_gecos".
9954 "PWPASSWD"
9956 This symbol, if defined, indicates to the C program that "struct
9957 passwd" contains "pw_passwd".
9958 "PWQUOTA"
9960 This symbol, if defined, indicates to the C program that "struct
9961 passwd" contains "pw_quota".
9962
9964 "CSH"
9965 This symbol, if defined, contains the full pathname of csh.
9966 "LOC_SED"
9968 This symbol holds the complete pathname to the sed program.
9969 "SH_PATH"
9971 This symbol contains the full pathname to the shell used on this on
9972 this system to execute Bourne shell scripts. Usually, this will be
9973 /bin/sh, though it's possible that some systems will have /bin/ksh,
9974 /bin/pdksh, /bin/ash, /bin/bash, or even something such as
9975 D:/bin/sh.exe.
9976
9978 "CRYPT_R_PROTO"
9979 This symbol encodes the prototype of "crypt_r". It is zero if
9980 "d_crypt_r" is undef, and one of the "REENTRANT_PROTO_T_ABC" macros
9981 of reentr.h if "d_crypt_r" is defined.
9982 "CTERMID_R_PROTO"
9984 This symbol encodes the prototype of "ctermid_r". It is zero if
9985 "d_ctermid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9986 macros of reentr.h if "d_ctermid_r" is defined.
9987 "DRAND48_R_PROTO"
9989 This symbol encodes the prototype of "drand48_r". It is zero if
9990 "d_drand48_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9991 macros of reentr.h if "d_drand48_r" is defined.
9992 "ENDGRENT_R_PROTO"
9994 This symbol encodes the prototype of "endgrent_r". It is zero if
9995 "d_endgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
9996 macros of reentr.h if "d_endgrent_r" is defined.
9997 "ENDHOSTENT_R_PROTO"
9999 This symbol encodes the prototype of "endhostent_r". It is zero if
10000 "d_endhostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10001 macros of reentr.h if "d_endhostent_r" is defined.
10002 "ENDNETENT_R_PROTO"
10004 This symbol encodes the prototype of "endnetent_r". It is zero if
10005 "d_endnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10006 macros of reentr.h if "d_endnetent_r" is defined.
10007 "ENDPROTOENT_R_PROTO"
10009 This symbol encodes the prototype of "endprotoent_r". It is zero
10010 if "d_endprotoent_r" is undef, and one of the
10011 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_endprotoent_r" is
10012 defined.
10013 "ENDPWENT_R_PROTO"
10015 This symbol encodes the prototype of "endpwent_r". It is zero if
10016 "d_endpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10017 macros of reentr.h if "d_endpwent_r" is defined.
10018 "ENDSERVENT_R_PROTO"
10020 This symbol encodes the prototype of "endservent_r". It is zero if
10021 "d_endservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10022 macros of reentr.h if "d_endservent_r" is defined.
10023 "GDBMNDBM_H_USES_PROTOTYPES"
10025 This symbol, if defined, indicates that gdbm/ndbm.h uses real
10026 "ANSI" C prototypes instead of K&R style function declarations
10027 without any parameter information. While "ANSI" C prototypes are
10028 supported in C++, K&R style function declarations will yield
10029 errors.
10030 "GDBM_NDBM_H_USES_PROTOTYPES"
10032 This symbol, if defined, indicates that <gdbm-ndbm.h> uses real
10033 "ANSI" C prototypes instead of K&R style function declarations
10034 without any parameter information. While "ANSI" C prototypes are
10035 supported in C++, K&R style function declarations will yield
10036 errors.
10037 "GETGRENT_R_PROTO"
10039 This symbol encodes the prototype of "getgrent_r". It is zero if
10040 "d_getgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10041 macros of reentr.h if "d_getgrent_r" is defined.
10042 "GETGRGID_R_PROTO"
10044 This symbol encodes the prototype of "getgrgid_r". It is zero if
10045 "d_getgrgid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10046 macros of reentr.h if "d_getgrgid_r" is defined.
10047 "GETGRNAM_R_PROTO"
10049 This symbol encodes the prototype of "getgrnam_r". It is zero if
10050 "d_getgrnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10051 macros of reentr.h if "d_getgrnam_r" is defined.
10052 "GETHOSTBYADDR_R_PROTO"
10054 This symbol encodes the prototype of "gethostbyaddr_r". It is zero
10055 if "d_gethostbyaddr_r" is undef, and one of the
10056 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_gethostbyaddr_r"
10057 is defined.
10058 "GETHOSTBYNAME_R_PROTO"
10060 This symbol encodes the prototype of "gethostbyname_r". It is zero
10061 if "d_gethostbyname_r" is undef, and one of the
10062 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_gethostbyname_r"
10063 is defined.
10064 "GETHOSTENT_R_PROTO"
10066 This symbol encodes the prototype of "gethostent_r". It is zero if
10067 "d_gethostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10068 macros of reentr.h if "d_gethostent_r" is defined.
10069 "GETLOGIN_R_PROTO"
10071 This symbol encodes the prototype of "getlogin_r". It is zero if
10072 "d_getlogin_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10073 macros of reentr.h if "d_getlogin_r" is defined.
10074 "GETNETBYADDR_R_PROTO"
10076 This symbol encodes the prototype of "getnetbyaddr_r". It is zero
10077 if "d_getnetbyaddr_r" is undef, and one of the
10078 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getnetbyaddr_r" is
10079 defined.
10080 "GETNETBYNAME_R_PROTO"
10082 This symbol encodes the prototype of "getnetbyname_r". It is zero
10083 if "d_getnetbyname_r" is undef, and one of the
10084 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getnetbyname_r" is
10085 defined.
10086 "GETNETENT_R_PROTO"
10088 This symbol encodes the prototype of "getnetent_r". It is zero if
10089 "d_getnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10090 macros of reentr.h if "d_getnetent_r" is defined.
10091 "GETPROTOBYNAME_R_PROTO"
10093 This symbol encodes the prototype of "getprotobyname_r". It is
10094 zero if "d_getprotobyname_r" is undef, and one of the
10095 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getprotobyname_r"
10096 is defined.
10097 "GETPROTOBYNUMBER_R_PROTO"
10099 This symbol encodes the prototype of "getprotobynumber_r". It is
10100 zero if "d_getprotobynumber_r" is undef, and one of the
10101 "REENTRANT_PROTO_T_ABC" macros of reentr.h if
10102 "d_getprotobynumber_r" is defined.
10103 "GETPROTOENT_R_PROTO"
10105 This symbol encodes the prototype of "getprotoent_r". It is zero
10106 if "d_getprotoent_r" is undef, and one of the
10107 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getprotoent_r" is
10108 defined.
10109 "GETPWENT_R_PROTO"
10111 This symbol encodes the prototype of "getpwent_r". It is zero if
10112 "d_getpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10113 macros of reentr.h if "d_getpwent_r" is defined.
10114 "GETPWNAM_R_PROTO"
10116 This symbol encodes the prototype of "getpwnam_r". It is zero if
10117 "d_getpwnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10118 macros of reentr.h if "d_getpwnam_r" is defined.
10119 "GETPWUID_R_PROTO"
10121 This symbol encodes the prototype of "getpwuid_r". It is zero if
10122 "d_getpwuid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10123 macros of reentr.h if "d_getpwuid_r" is defined.
10124 "GETSERVBYNAME_R_PROTO"
10126 This symbol encodes the prototype of "getservbyname_r". It is zero
10127 if "d_getservbyname_r" is undef, and one of the
10128 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getservbyname_r"
10129 is defined.
10130 "GETSERVBYPORT_R_PROTO"
10132 This symbol encodes the prototype of "getservbyport_r". It is zero
10133 if "d_getservbyport_r" is undef, and one of the
10134 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getservbyport_r"
10135 is defined.
10136 "GETSERVENT_R_PROTO"
10138 This symbol encodes the prototype of "getservent_r". It is zero if
10139 "d_getservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10140 macros of reentr.h if "d_getservent_r" is defined.
10141 "GETSPNAM_R_PROTO"
10143 This symbol encodes the prototype of "getspnam_r". It is zero if
10144 "d_getspnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10145 macros of reentr.h if "d_getspnam_r" is defined.
10146 "HAS_DBMINIT_PROTO"
10148 This symbol, if defined, indicates that the system provides a
10149 prototype for the "dbminit()" function. Otherwise, it is up to the
10150 program to supply one. A good guess is
10151 extern int dbminit(char *);
10153 "HAS_DRAND48_PROTO"
10155 This symbol, if defined, indicates that the system provides a
10156 prototype for the "drand48()" function. Otherwise, it is up to the
10157 program to supply one. A good guess is
10158 extern double drand48(void);
10160 "HAS_FLOCK_PROTO"
10162 This symbol, if defined, indicates that the system provides a
10163 prototype for the "flock()" function. Otherwise, it is up to the
10164 program to supply one. A good guess is
10165 extern int flock(int, int);
10167 "HAS_GETHOST_PROTOS"
10169 This symbol, if defined, indicates that netdb.h includes prototypes
10170 for "gethostent()", "gethostbyname()", and "gethostbyaddr()".
10171 Otherwise, it is up to the program to guess them. See netdbtype.U
10172 (part of metaconfig) for probing for various "Netdb_xxx_t" types.
10173 "HAS_GETNET_PROTOS"
10175 This symbol, if defined, indicates that netdb.h includes prototypes
10176 for "getnetent()", "getnetbyname()", and "getnetbyaddr()".
10177 Otherwise, it is up to the program to guess them. See netdbtype.U
10178 (part of metaconfig) for probing for various "Netdb_xxx_t" types.
10179 "HAS_GETPROTO_PROTOS"
10181 This symbol, if defined, indicates that netdb.h includes prototypes
10182 for "getprotoent()", "getprotobyname()", and "getprotobyaddr()".
10183 Otherwise, it is up to the program to guess them. See netdbtype.U
10184 (part of metaconfig) for probing for various "Netdb_xxx_t" types.
10185 "HAS_GETSERV_PROTOS"
10187 This symbol, if defined, indicates that netdb.h includes prototypes
10188 for "getservent()", "getservbyname()", and "getservbyaddr()".
10189 Otherwise, it is up to the program to guess them. See netdbtype.U
10190 (part of metaconfig) for probing for various "Netdb_xxx_t" types.
10191 "HAS_MODFL_PROTO"
10193 This symbol, if defined, indicates that the system provides a
10194 prototype for the "modfl()" function. Otherwise, it is up to the
10195 program to supply one.
10196 "HAS_SBRK_PROTO"
10198 This symbol, if defined, indicates that the system provides a
10199 prototype for the "sbrk()" function. Otherwise, it is up to the
10200 program to supply one. Good guesses are
10201 extern void* sbrk(int);
10203 extern void* sbrk(size_t);
10204 "HAS_SETRESGID_PROTO"
10206 This symbol, if defined, indicates that the system provides a
10207 prototype for the "setresgid()" function. Otherwise, it is up to
10208 the program to supply one. Good guesses are
10209 extern int setresgid(uid_t ruid, uid_t euid, uid_t suid);
10211 "HAS_SETRESUID_PROTO"
10213 This symbol, if defined, indicates that the system provides a
10214 prototype for the "setresuid()" function. Otherwise, it is up to
10215 the program to supply one. Good guesses are
10216 extern int setresuid(uid_t ruid, uid_t euid, uid_t suid);
10218 "HAS_SHMAT_PROTOTYPE"
10220 This symbol, if defined, indicates that the sys/shm.h includes a
10221 prototype for "shmat()". Otherwise, it is up to the program to
10222 guess one. "Shmat_t" "shmat(int, Shmat_t, int)" is a good guess,
10223 but not always right so it should be emitted by the program only
10224 when "HAS_SHMAT_PROTOTYPE" is not defined to avoid conflicting
10225 defs.
10226 "HAS_SOCKATMARK_PROTO"
10228 This symbol, if defined, indicates that the system provides a
10229 prototype for the "sockatmark()" function. Otherwise, it is up to
10230 the program to supply one. A good guess is
10231 extern int sockatmark(int);
10233 "HAS_SYSCALL_PROTO"
10235 This symbol, if defined, indicates that the system provides a
10236 prototype for the "syscall()" function. Otherwise, it is up to the
10237 program to supply one. Good guesses are
10238 extern int syscall(int, ...);
10240 extern int syscall(long, ...);
10241 "HAS_TELLDIR_PROTO"
10243 This symbol, if defined, indicates that the system provides a
10244 prototype for the "telldir()" function. Otherwise, it is up to the
10245 program to supply one. A good guess is
10246 extern long telldir(DIR*);
10248 "NDBM_H_USES_PROTOTYPES"
10250 This symbol, if defined, indicates that ndbm.h uses real "ANSI" C
10251 prototypes instead of K&R style function declarations without any
10252 parameter information. While "ANSI" C prototypes are supported in
10253 C++, K&R style function declarations will yield errors.
10254 "RANDOM_R_PROTO"
10256 This symbol encodes the prototype of "random_r". It is zero if
10257 "d_random_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10258 macros of reentr.h if "d_random_r" is defined.
10259 "READDIR_R_PROTO"
10261 This symbol encodes the prototype of "readdir_r". It is zero if
10262 "d_readdir_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10263 macros of reentr.h if "d_readdir_r" is defined.
10264 "SETGRENT_R_PROTO"
10266 This symbol encodes the prototype of "setgrent_r". It is zero if
10267 "d_setgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10268 macros of reentr.h if "d_setgrent_r" is defined.
10269 "SETHOSTENT_R_PROTO"
10271 This symbol encodes the prototype of "sethostent_r". It is zero if
10272 "d_sethostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10273 macros of reentr.h if "d_sethostent_r" is defined.
10274 "SETLOCALE_R_PROTO"
10276 This symbol encodes the prototype of "setlocale_r". It is zero if
10277 "d_setlocale_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10278 macros of reentr.h if "d_setlocale_r" is defined.
10279 "SETNETENT_R_PROTO"
10281 This symbol encodes the prototype of "setnetent_r". It is zero if
10282 "d_setnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10283 macros of reentr.h if "d_setnetent_r" is defined.
10284 "SETPROTOENT_R_PROTO"
10286 This symbol encodes the prototype of "setprotoent_r". It is zero
10287 if "d_setprotoent_r" is undef, and one of the
10288 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_setprotoent_r" is
10289 defined.
10290 "SETPWENT_R_PROTO"
10292 This symbol encodes the prototype of "setpwent_r". It is zero if
10293 "d_setpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10294 macros of reentr.h if "d_setpwent_r" is defined.
10295 "SETSERVENT_R_PROTO"
10297 This symbol encodes the prototype of "setservent_r". It is zero if
10298 "d_setservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10299 macros of reentr.h if "d_setservent_r" is defined.
10300 "SRAND48_R_PROTO"
10302 This symbol encodes the prototype of "srand48_r". It is zero if
10303 "d_srand48_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10304 macros of reentr.h if "d_srand48_r" is defined.
10305 "SRANDOM_R_PROTO"
10307 This symbol encodes the prototype of "srandom_r". It is zero if
10308 "d_srandom_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10309 macros of reentr.h if "d_srandom_r" is defined.
10310 "STRERROR_R_PROTO"
10312 This symbol encodes the prototype of "strerror_r". It is zero if
10313 "d_strerror_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10314 macros of reentr.h if "d_strerror_r" is defined.
10315 "TMPNAM_R_PROTO"
10317 This symbol encodes the prototype of "tmpnam_r". It is zero if
10318 "d_tmpnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10319 macros of reentr.h if "d_tmpnam_r" is defined.
10320 "TTYNAME_R_PROTO"
10322 This symbol encodes the prototype of "ttyname_r". It is zero if
10323 "d_ttyname_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10324 macros of reentr.h if "d_ttyname_r" is defined.
10325
10327 "pregcomp"
10328 Described in perlreguts.
10329 REGEXP* pregcomp(SV * const pattern, const U32 flags)
10331 "pregexec"
10333 Described in perlreguts.
10334 I32 pregexec(REGEXP * const prog, char* stringarg, char* strend,
10336 char* strbeg, SSize_t minend, SV* screamer,
10337 U32 nosave)
10338 "re_compile"
10340 Compile the regular expression pattern "pattern", returning a
10341 pointer to the compiled object for later matching with the internal
10342 regex engine.
10343 This function is typically used by a custom regexp engine ".comp()"
10345 function to hand off to the core regexp engine those patterns it
10346 doesn't want to handle itself (typically passing through the same
10347 flags it was called with). In almost all other cases, a regexp
10348 should be compiled by calling ""pregcomp"" to compile using the
10349 currently active regexp engine.
10350 If "pattern" is already a "REGEXP", this function does nothing but
10352 return a pointer to the input. Otherwise the PV is extracted and
10353 treated like a string representing a pattern. See perlre.
10354 The possible flags for "rx_flags" are documented in perlreapi.
10356 Their names all begin with "RXf_".
10357 REGEXP* re_compile(SV * const pattern, U32 orig_rx_flags)
10359 "re_dup_guts"
10361 Duplicate a regexp.
10362 This routine is expected to clone a given regexp structure. It is
10364 only compiled under USE_ITHREADS.
10365 After all of the core data stored in struct regexp is duplicated
10367 the "regexp_engine.dupe" method is used to copy any private data
10368 stored in the *pprivate pointer. This allows extensions to handle
10369 any duplication they need to do.
10370 void re_dup_guts(const REGEXP *sstr, REGEXP *dstr,
10372 CLONE_PARAMS* param)
10373 "REGEX_LOCALE_CHARSET"
10375 Described in perlreapi.
10376 "REGEXP"
10378 Described in perlreapi.
10379 "regexp_engine"
10381 When a regexp is compiled, its "engine" field is then set to point
10382 at the appropriate structure, so that when it needs to be used Perl
10383 can find the right routines to do so.
10384 In order to install a new regexp handler, $^H{regcomp} is set to an
10386 integer which (when casted appropriately) resolves to one of these
10387 structures. When compiling, the "comp" method is executed, and the
10388 resulting "regexp" structure's engine field is expected to point
10389 back at the same structure.
10390 The pTHX_ symbol in the definition is a macro used by Perl under
10392 threading to provide an extra argument to the routine holding a
10393 pointer back to the interpreter that is executing the regexp. So
10394 under threading all routines get an extra argument.
10395 "regexp_paren_pair"
10397 Described in perlreapi.
10398 "regmatch_info"
10400 Some basic information about the current match that is created by
10401 Perl_regexec_flags and then passed to regtry(), regmatch() etc. It
10402 is allocated as a local var on the stack, so nothing should be
10403 stored in it that needs preserving or clearing up on croak(). For
10404 that, see the aux_info and aux_info_eval members of the
10405 regmatch_state union.
10406 "REXEC_COPY_STR"
10408 "REXEC_COPY_SKIP_PRE"
10409 "REXEC_COPY_SKIP_POST"
10410 Described in perlreapi.
10411 "RXapif_CLEAR"
10413 "RXapif_DELETE"
10414 "RXapif_EXISTS"
10415 "RXapif_FETCH"
10416 "RXapif_FIRSTKEY"
10417 "RXapif_NEXTKEY"
10418 "RXapif_SCALAR"
10419 "RXapif_STORE"
10420 "RXapif_ALL"
10421 "RXapif_ONE"
10422 "RXapif_REGNAME"
10423 "RXapif_REGNAMES"
10424 "RXapif_REGNAMES_COUNT"
10425 Described in perlreapi.
10426 "RX_BUFF_IDX_CARET_FULLMATCH"
10428 "RX_BUFF_IDX_CARET_POSTMATCH"
10429 "RX_BUFF_IDX_CARET_PREMATCH"
10430 "RX_BUFF_IDX_FULLMATCH"
10431 "RX_BUFF_IDX_POSTMATCH"
10432 "RX_BUFF_IDX_PREMATCH"
10433 Described in perlreapi.
10434 "RXf_PMf_MULTILINE"
10436 "RXf_PMf_SINGLELINE"
10437 "RXf_PMf_FOLD"
10438 "RXf_PMf_EXTENDED"
10439 "RXf_PMf_KEEPCOPY"
10440 Described in perlreapi.
10441 "RXf_SPLIT"
10443 "RXf_SKIPWHITE"
10444 "RXf_START_ONLY"
10445 "RXf_WHITE"
10446 "RXf_NULL"
10447 "RXf_NO_INPLACE_SUBST"
10448 Described in perlreapi.
10449 "RX_MATCH_COPIED"
10451 Described in perlreapi.
10452 RX_MATCH_COPIED(const REGEXP * rx)
10454 "RX_OFFS"
10456 Described in perlreapi.
10457 RX_OFFS(const REGEXP * rx_sv)
10459 "SvRX"
10461 Convenience macro to get the REGEXP from a SV. This is
10462 approximately equivalent to the following snippet:
10463 if (SvMAGICAL(sv))
10465 mg_get(sv);
10466 if (SvROK(sv))
10467 sv = MUTABLE_SV(SvRV(sv));
10468 if (SvTYPE(sv) == SVt_REGEXP)
10469 return (REGEXP*) sv;
10470 "NULL" will be returned if a REGEXP* is not found.
10472 REGEXP * SvRX(SV *sv)
10474 "SvRXOK"
10476 Returns a boolean indicating whether the SV (or the one it
10477 references) is a REGEXP.
10478 If you want to do something with the REGEXP* later use SvRX instead
10480 and check for NULL.
10481 bool SvRXOK(SV* sv)
10483 "SV_SAVED_COPY"
10485 Described in perlreapi.
10486
10488 These are used in the simple report generation feature of Perl. See
10489 perlform.
10490 "IoBOTTOM_GV"
10492 Described in perlguts.
10493 GV * IoBOTTOM_GV(IO *io)
10495 "IoBOTTOM_NAME"
10497 Described in perlguts.
10498 char * IoBOTTOM_NAME(IO *io)
10500 "IoFMT_GV"
10502 Described in perlguts.
10503 GV * IoFMT_GV(IO *io)
10505 "IoFMT_NAME"
10507 Described in perlguts.
10508 char * IoFMT_NAME(IO *io)
10510 "IoLINES"
10512 Described in perlguts.
10513 IV IoLINES(IO *io)
10515 "IoLINES_LEFT"
10517 Described in perlguts.
10518 IV IoLINES_LEFT(IO *io)
10520 "IoPAGE"
10522 Described in perlguts.
10523 IV IoPAGE(IO *io)
10525 "IoPAGE_LEN"
10527 Described in perlguts.
10528 IV IoPAGE_LEN(IO *io)
10530 "IoTOP_GV"
10532 Described in perlguts.
10533 GV * IoTOP_GV(IO *io)
10535 "IoTOP_NAME"
10537 Described in perlguts.
10538 char * IoTOP_NAME(IO *io)
10540
10542 "HAS_SIGINFO_SI_ADDR"
10543 This symbol, if defined, indicates that "siginfo_t" has the
10544 "si_addr" member
10545 "HAS_SIGINFO_SI_BAND"
10547 This symbol, if defined, indicates that "siginfo_t" has the
10548 "si_band" member
10549 "HAS_SIGINFO_SI_ERRNO"
10551 This symbol, if defined, indicates that "siginfo_t" has the
10552 "si_errno" member
10553 "HAS_SIGINFO_SI_PID"
10555 This symbol, if defined, indicates that "siginfo_t" has the
10556 "si_pid" member
10557 "HAS_SIGINFO_SI_STATUS"
10559 This symbol, if defined, indicates that "siginfo_t" has the
10560 "si_status" member
10561 "HAS_SIGINFO_SI_UID"
10563 This symbol, if defined, indicates that "siginfo_t" has the
10564 "si_uid" member
10565 "HAS_SIGINFO_SI_VALUE"
10567 This symbol, if defined, indicates that "siginfo_t" has the
10568 "si_value" member
10569 "PERL_SIGNALS_UNSAFE_FLAG"
10571 If this bit in "PL_signals" is set, the system is uing the pre-Perl
10572 5.8 unsafe signals. See "PERL_SIGNALS" in perlrun and "Deferred
10573 Signals (Safe Signals)" in perlipc.
10574 U32 PERL_SIGNALS_UNSAFE_FLAG
10576 "rsignal"
10578 A wrapper for the C library functions sigaction(2) or signal(2).
10579 Use this instead of those libc functions, as the Perl version gives
10580 the safest available implementation, and knows things that interact
10581 with the rest of the perl interpreter.
10582 Sighandler_t rsignal(int i, Sighandler_t t)
10584 "rsignal_state"
10586 Returns a the current signal handler for signal "signo". See
10587 ""rsignal"".
10588 Sighandler_t rsignal_state(int i)
10590 "Sigjmp_buf"
10592 This is the buffer type to be used with Sigsetjmp and Siglongjmp.
10593 "Siglongjmp"
10595 This macro is used in the same way as "siglongjmp()", but will
10596 invoke traditional "longjmp()" if siglongjmp isn't available. See
10597 "HAS_SIGSETJMP".
10598 void Siglongjmp(jmp_buf env, int val)
10600 "SIG_NAME"
10602 This symbol contains a list of signal names in order of signal
10603 number. This is intended to be used as a static array
10604 initialization, like this:
10605 char *sig_name[] = { SIG_NAME };
10607 The signals in the list are separated with commas, and each signal
10609 is surrounded by double quotes. There is no leading "SIG" in the
10610 signal name, i.e. "SIGQUIT" is known as ""QUIT"". Gaps in the
10611 signal numbers (up to "NSIG") are filled in with "NUMnn", etc.,
10612 where nn is the actual signal number (e.g. "NUM37"). The signal
10613 number for "sig_name[i]" is stored in "sig_num[i]". The last
10614 element is 0 to terminate the list with a "NULL". This corresponds
10615 to the 0 at the end of the "sig_name_init" list. Note that this
10616 variable is initialized from the "sig_name_init", not from
10617 "sig_name" (which is unused).
10618 "SIG_NUM"
10620 This symbol contains a list of signal numbers, in the same order as
10621 the "SIG_NAME" list. It is suitable for static array
10622 initialization, as in:
10623 int sig_num[] = { SIG_NUM };
10625 The signals in the list are separated with commas, and the indices
10627 within that list and the "SIG_NAME" list match, so it's easy to
10628 compute the signal name from a number or vice versa at the price of
10629 a small dynamic linear lookup. Duplicates are allowed, but are
10630 moved to the end of the list. The signal number corresponding to
10631 "sig_name[i]" is "sig_number[i]". if (i < "NSIG") then
10632 "sig_number[i]" == i. The last element is 0, corresponding to the
10633 0 at the end of the "sig_name_init" list. Note that this variable
10634 is initialized from the "sig_num_init", not from "sig_num" (which
10635 is unused).
10636 "Sigsetjmp"
10638 This macro is used in the same way as "sigsetjmp()", but will
10639 invoke traditional "setjmp()" if sigsetjmp isn't available. See
10640 "HAS_SIGSETJMP".
10641 int Sigsetjmp(jmp_buf env, int savesigs)
10643 "SIG_SIZE"
10645 This variable contains the number of elements of the "SIG_NAME" and
10646 "SIG_NUM" arrays, excluding the final "NULL" entry.
10647 "whichsig"
10649 "whichsig_pv"
10650 "whichsig_pvn"
10651 "whichsig_sv"
10652 These all convert a signal name into its corresponding signal
10653 number; returning -1 if no corresponding number was found.
10654 They differ only in the source of the signal name:
10656 "whichsig_pv" takes the name from the "NUL"-terminated string
10658 starting at "sig".
10659 "whichsig" is merely a different spelling, a synonym, of
10661 "whichsig_pv".
10662 "whichsig_pvn" takes the name from the string starting at "sig",
10664 with length "len" bytes.
10665 "whichsig_sv" takes the name from the PV stored in the SV "sigsv".
10667 I32 whichsig (const char* sig)
10669 I32 whichsig_pv (const char* sig)
10670 I32 whichsig_pvn(const char* sig, STRLEN len)
10671 I32 whichsig_sv (SV* sigsv)
10672
10674 These variables give details as to where various libraries,
10675 installation destinations, etc., go, as well as what various
10676 installation options were selected
10677 "ARCHLIB"
10679 This variable, if defined, holds the name of the directory in which
10680 the user wants to put architecture-dependent public library files
10681 for perl5. It is most often a local directory such as
10682 /usr/local/lib. Programs using this variable must be prepared to
10683 deal with filename expansion. If "ARCHLIB" is the same as
10684 "PRIVLIB", it is not defined, since presumably the program already
10685 searches "PRIVLIB".
10686 "ARCHLIB_EXP"
10688 This symbol contains the ~name expanded version of "ARCHLIB", to be
10689 used in programs that are not prepared to deal with ~ expansion at
10690 run-time.
10691 "ARCHNAME"
10693 This symbol holds a string representing the architecture name. It
10694 may be used to construct an architecture-dependant pathname where
10695 library files may be held under a private library, for instance.
10696 "BIN"
10698 This symbol holds the path of the bin directory where the package
10699 will be installed. Program must be prepared to deal with ~name
10700 substitution.
10701 "BIN_EXP"
10703 This symbol is the filename expanded version of the "BIN" symbol,
10704 for programs that do not want to deal with that at run-time.
10705 "INSTALL_USR_BIN_PERL"
10707 This symbol, if defined, indicates that Perl is to be installed
10708 also as /usr/bin/perl.
10709 "MULTIARCH"
10711 This symbol, if defined, signifies that the build process will
10712 produce some binary files that are going to be used in a cross-
10713 platform environment. This is the case for example with the NeXT
10714 "fat" binaries that contain executables for several "CPUs".
10715 "PERL_INC_VERSION_LIST"
10717 This variable specifies the list of subdirectories in over which
10718 perl.c:"incpush()" and lib/lib.pm will automatically search when
10719 adding directories to @"INC", in a format suitable for a C
10720 initialization string. See the "inc_version_list" entry in
10721 Porting/Glossary for more details.
10722 "PERL_OTHERLIBDIRS"
10724 This variable contains a colon-separated set of paths for the perl
10725 binary to search for additional library files or modules. These
10726 directories will be tacked to the end of @"INC". Perl will
10727 automatically search below each path for version- and architecture-
10728 specific directories. See "PERL_INC_VERSION_LIST" for more
10729 details.
10730 "PERL_RELOCATABLE_INC"
10732 This symbol, if defined, indicates that we'd like to relocate
10733 entries in @"INC" at run time based on the location of the perl
10734 binary.
10735 "PERL_TARGETARCH"
10737 This symbol, if defined, indicates the target architecture Perl has
10738 been cross-compiled to. Undefined if not a cross-compile.
10739 "PERL_USE_DEVEL"
10741 This symbol, if defined, indicates that Perl was configured with
10742 "-Dusedevel", to enable development features. This should not be
10743 done for production builds.
10744 "PERL_VENDORARCH"
10746 If defined, this symbol contains the name of a private library.
10747 The library is private in the sense that it needn't be in anyone's
10748 execution path, but it should be accessible by the world. It may
10749 have a ~ on the front. The standard distribution will put nothing
10750 in this directory. Vendors who distribute perl may wish to place
10751 their own architecture-dependent modules and extensions in this
10752 directory with
10753 MakeMaker Makefile.PL INSTALLDIRS=vendor
10755 or equivalent. See "INSTALL" for details.
10757 "PERL_VENDORARCH_EXP"
10759 This symbol contains the ~name expanded version of
10760 "PERL_VENDORARCH", to be used in programs that are not prepared to
10761 deal with ~ expansion at run-time.
10762 "PERL_VENDORLIB_EXP"
10764 This symbol contains the ~name expanded version of "VENDORLIB", to
10765 be used in programs that are not prepared to deal with ~ expansion
10766 at run-time.
10767 "PERL_VENDORLIB_STEM"
10769 This define is "PERL_VENDORLIB_EXP" with any trailing version-
10770 specific component removed. The elements in "inc_version_list"
10771 ("inc_version_list".U (part of metaconfig)) can be tacked onto this
10772 variable to generate a list of directories to search.
10773 "PRIVLIB"
10775 This symbol contains the name of the private library for this
10776 package. The library is private in the sense that it needn't be in
10777 anyone's execution path, but it should be accessible by the world.
10778 The program should be prepared to do ~ expansion.
10779 "PRIVLIB_EXP"
10781 This symbol contains the ~name expanded version of "PRIVLIB", to be
10782 used in programs that are not prepared to deal with ~ expansion at
10783 run-time.
10784 "SITEARCH"
10786 This symbol contains the name of the private library for this
10787 package. The library is private in the sense that it needn't be in
10788 anyone's execution path, but it should be accessible by the world.
10789 The program should be prepared to do ~ expansion. The standard
10790 distribution will put nothing in this directory. After perl has
10791 been installed, users may install their own local architecture-
10792 dependent modules in this directory with
10793 MakeMaker Makefile.PL
10795 or equivalent. See "INSTALL" for details.
10797 "SITEARCH_EXP"
10799 This symbol contains the ~name expanded version of "SITEARCH", to
10800 be used in programs that are not prepared to deal with ~ expansion
10801 at run-time.
10802 "SITELIB"
10804 This symbol contains the name of the private library for this
10805 package. The library is private in the sense that it needn't be in
10806 anyone's execution path, but it should be accessible by the world.
10807 The program should be prepared to do ~ expansion. The standard
10808 distribution will put nothing in this directory. After perl has
10809 been installed, users may install their own local architecture-
10810 independent modules in this directory with
10811 MakeMaker Makefile.PL
10813 or equivalent. See "INSTALL" for details.
10815 "SITELIB_EXP"
10817 This symbol contains the ~name expanded version of "SITELIB", to be
10818 used in programs that are not prepared to deal with ~ expansion at
10819 run-time.
10820 "SITELIB_STEM"
10822 This define is "SITELIB_EXP" with any trailing version-specific
10823 component removed. The elements in "inc_version_list"
10824 ("inc_version_list".U (part of metaconfig)) can be tacked onto this
10825 variable to generate a list of directories to search.
10826 "STARTPERL"
10828 This variable contains the string to put in front of a perl script
10829 to make sure (one hopes) that it runs with perl and not some shell.
10830 "USE_64_BIT_ALL"
10832 This symbol, if defined, indicates that 64-bit integers should be
10833 used when available. If not defined, the native integers will be
10834 used (be they 32 or 64 bits). The maximal possible 64-bitness is
10835 employed: LP64 or "ILP64", meaning that you will be able to use
10836 more than 2 gigabytes of memory. This mode is even more binary
10837 incompatible than "USE_64_BIT_INT". You may not be able to run the
10838 resulting executable in a 32-bit "CPU" at all or you may need at
10839 least to reboot your OS to 64-bit mode.
10840 "USE_64_BIT_INT"
10842 This symbol, if defined, indicates that 64-bit integers should be
10843 used when available. If not defined, the native integers will be
10844 employed (be they 32 or 64 bits). The minimal possible 64-bitness
10845 is used, just enough to get 64-bit integers into Perl. This may
10846 mean using for example "long longs", while your memory may still be
10847 limited to 2 gigabytes.
10848 "USE_BSD_GETPGRP"
10850 This symbol, if defined, indicates that getpgrp needs one arguments
10851 whereas "USG" one needs none.
10852 "USE_BSD_SETPGRP"
10854 This symbol, if defined, indicates that setpgrp needs two arguments
10855 whereas "USG" one needs none. See also "HAS_SETPGID" for a "POSIX"
10856 interface.
10857 "USE_CPLUSPLUS"
10859 This symbol, if defined, indicates that a C++ compiler was used to
10860 compiled Perl and will be used to compile extensions.
10861 "USE_CROSS_COMPILE"
10863 This symbol, if defined, indicates that Perl is being cross-
10864 compiled.
10865 "USE_C_BACKTRACE"
10867 This symbol, if defined, indicates that Perl should be built with
10868 support for backtrace.
10869 "USE_DTRACE"
10871 This symbol, if defined, indicates that Perl should be built with
10872 support for DTrace.
10873 "USE_DYNAMIC_LOADING"
10875 This symbol, if defined, indicates that dynamic loading of some
10876 sort is available.
10877 "USE_FAST_STDIO"
10879 This symbol, if defined, indicates that Perl should be built to use
10880 'fast stdio'. Defaults to define in Perls 5.8 and earlier, to
10881 undef later.
10882 "USE_ITHREADS"
10884 This symbol, if defined, indicates that Perl should be built to use
10885 the interpreter-based threading implementation.
10886 "USE_KERN_PROC_PATHNAME"
10888 This symbol, if defined, indicates that we can use sysctl with
10889 "KERN_PROC_PATHNAME" to get a full path for the executable, and
10890 hence convert $^X to an absolute path.
10891 "USE_LARGE_FILES"
10893 This symbol, if defined, indicates that large file support should
10894 be used when available.
10895 "USE_LONG_DOUBLE"
10897 This symbol, if defined, indicates that long doubles should be used
10898 when available.
10899 "USE_MORE_BITS"
10901 This symbol, if defined, indicates that 64-bit interfaces and long
10902 doubles should be used when available.
10903 "USE_NSGETEXECUTABLEPATH"
10905 This symbol, if defined, indicates that we can use
10906 "_NSGetExecutablePath" and realpath to get a full path for the
10907 executable, and hence convert $^X to an absolute path.
10908 "USE_PERLIO"
10910 This symbol, if defined, indicates that the PerlIO abstraction
10911 should be used throughout. If not defined, stdio should be used in
10912 a fully backward compatible manner.
10913 "USE_QUADMATH"
10915 This symbol, if defined, indicates that the quadmath library should
10916 be used when available.
10917 "USE_REENTRANT_API"
10919 This symbol, if defined, indicates that Perl should try to use the
10920 various "_r" versions of library functions. This is extremely
10921 experimental.
10922 "USE_SEMCTL_SEMID_DS"
10924 This symbol, if defined, indicates that "struct semid_ds" * is used
10925 for semctl "IPC_STAT".
10926 "USE_SEMCTL_SEMUN"
10928 This symbol, if defined, indicates that "union semun" is used for
10929 semctl "IPC_STAT".
10930 "USE_SITECUSTOMIZE"
10932 This symbol, if defined, indicates that sitecustomize should be
10933 used.
10934 "USE_SOCKS"
10936 This symbol, if defined, indicates that Perl should be built to use
10937 socks.
10938 "USE_STAT_BLOCKS"
10940 This symbol is defined if this system has a stat structure
10941 declaring "st_blksize" and "st_blocks".
10942 "USE_STDIO_BASE"
10944 This symbol is defined if the "_base" field (or similar) of the
10945 stdio "FILE" structure can be used to access the stdio buffer for a
10946 file handle. If this is defined, then the "FILE_base(fp)" macro
10947 will also be defined and should be used to access this field.
10948 Also, the "FILE_bufsiz(fp)" macro will be defined and should be
10949 used to determine the number of bytes in the buffer.
10950 "USE_STDIO_BASE" will never be defined unless "USE_STDIO_PTR" is.
10951 "USE_STDIO_PTR"
10953 This symbol is defined if the "_ptr" and "_cnt" fields (or similar)
10954 of the stdio "FILE" structure can be used to access the stdio
10955 buffer for a file handle. If this is defined, then the
10956 "FILE_ptr(fp)" and "FILE_cnt(fp)" macros will also be defined and
10957 should be used to access these fields.
10958 "USE_STRICT_BY_DEFAULT"
10960 This symbol, if defined, enables additional defaults. At this time
10961 it only enables implicit strict by default.
10962 "USE_THREADS"
10964 This symbol, if defined, indicates that Perl should be built to use
10965 threads. At present, it is a synonym for and "USE_ITHREADS", but
10966 eventually the source ought to be changed to use this to mean
10967 "_any_" threading implementation.
10968
10970 "HAS_SOCKADDR_IN6"
10971 This symbol, if defined, indicates the availability of "struct
10972 sockaddr_in6";
10973 "HAS_SOCKADDR_SA_LEN"
10975 This symbol, if defined, indicates that the "struct sockaddr"
10976 structure has a member called "sa_len", indicating the length of
10977 the structure.
10978 "HAS_SOCKADDR_STORAGE"
10980 This symbol, if defined, indicates the availability of "struct
10981 sockaddr_storage";
10982 "HAS_SOCKATMARK"
10984 This symbol, if defined, indicates that the "sockatmark" routine is
10985 available to test whether a socket is at the out-of-band mark.
10986 "HAS_SOCKET"
10988 This symbol, if defined, indicates that the "BSD" "socket"
10989 interface is supported.
10990 "HAS_SOCKETPAIR"
10992 This symbol, if defined, indicates that the "BSD" "socketpair()"
10993 call is supported.
10994 "HAS_SOCKS5_INIT"
10996 This symbol, if defined, indicates that the "socks5_init" routine
10997 is available to initialize "SOCKS" 5.
10998 "I_SOCKS"
11000 This symbol, if defined, indicates that socks.h exists and should
11001 be included.
11002 #ifdef I_SOCKS
11004 #include <socks.h>
11005 #endif
11006 "I_SYS_SOCKIO"
11008 This symbol, if defined, indicates the sys/sockio.h should be
11009 included to get socket ioctl options, like "SIOCATMARK".
11010 #ifdef I_SYS_SOCKIO
11012 #include <sys_sockio.h>
11013 #endif
11014
11016 "filter_add"
11017 Described in perlfilter.
11018 SV* filter_add(filter_t funcp, SV* datasv)
11020 "filter_del"
11022 Delete most recently added instance of the filter function argument
11023 void filter_del(filter_t funcp)
11025 "filter_read"
11027 Described in perlfilter.
11028 I32 filter_read(int idx, SV *buf_sv, int maxlen)
11030 "scan_vstring"
11032 Returns a pointer to the next character after the parsed vstring,
11033 as well as updating the passed in sv.
11034 Function must be called like
11036 sv = sv_2mortal(newSV(5));
11038 s = scan_vstring(s,e,sv);
11039 where s and e are the start and end of the string. The sv should
11041 already be large enough to store the vstring passed in, for
11042 performance reasons.
11043 This function may croak if fatal warnings are enabled in the
11045 calling scope, hence the sv_2mortal in the example (to prevent a
11046 leak). Make sure to do SvREFCNT_inc afterwards if you use
11047 sv_2mortal.
11048 char* scan_vstring(const char *s, const char *const e, SV *sv)
11050
11052 "dMARK"
11053 Declare a stack marker variable, "mark", for the XSUB. See "MARK"
11054 and "dORIGMARK".
11055 dMARK;
11057 "dORIGMARK"
11059 Saves the original stack mark for the XSUB. See "ORIGMARK".
11060 dORIGMARK;
11062 "dSP"
11064 Declares a local copy of perl's stack pointer for the XSUB,
11065 available via the "SP" macro. See "SP".
11066 dSP;
11068 "dTARGET"
11070 Declare that this function uses "TARG"
11071 dTARGET;
11073 "EXTEND"
11075 Used to extend the argument stack for an XSUB's return values.
11076 Once used, guarantees that there is room for at least "nitems" to
11077 be pushed onto the stack.
11078 void EXTEND(SP, SSize_t nitems)
11080 "MARK"
11082 Stack marker variable for the XSUB. See "dMARK".
11083 "mPUSHi"
11085 Push an integer onto the stack. The stack must have room for this
11086 element. Does not use "TARG". See also "PUSHi", "mXPUSHi" and
11087 "XPUSHi".
11088 void mPUSHi(IV iv)
11090 "mPUSHn"
11092 Push a double onto the stack. The stack must have room for this
11093 element. Does not use "TARG". See also "PUSHn", "mXPUSHn" and
11094 "XPUSHn".
11095 void mPUSHn(NV nv)
11097 "mPUSHp"
11099 Push a string onto the stack. The stack must have room for this
11100 element. The "len" indicates the length of the string. Does not
11101 use "TARG". See also "PUSHp", "mXPUSHp" and "XPUSHp".
11102 void mPUSHp(char* str, STRLEN len)
11104 "mPUSHs"
11106 Push an SV onto the stack and mortalizes the SV. The stack must
11107 have room for this element. Does not use "TARG". See also "PUSHs"
11108 and "mXPUSHs".
11109 void mPUSHs(SV* sv)
11111 "mPUSHu"
11113 Push an unsigned integer onto the stack. The stack must have room
11114 for this element. Does not use "TARG". See also "PUSHu",
11115 "mXPUSHu" and "XPUSHu".
11116 void mPUSHu(UV uv)
11118 "mXPUSHi"
11120 Push an integer onto the stack, extending the stack if necessary.
11121 Does not use "TARG". See also "XPUSHi", "mPUSHi" and "PUSHi".
11122 void mXPUSHi(IV iv)
11124 "mXPUSHn"
11126 Push a double onto the stack, extending the stack if necessary.
11127 Does not use "TARG". See also "XPUSHn", "mPUSHn" and "PUSHn".
11128 void mXPUSHn(NV nv)
11130 "mXPUSHp"
11132 Push a string onto the stack, extending the stack if necessary.
11133 The "len" indicates the length of the string. Does not use "TARG".
11134 See also "XPUSHp", "mPUSHp" and "PUSHp".
11135 void mXPUSHp(char* str, STRLEN len)
11137 "mXPUSHs"
11139 Push an SV onto the stack, extending the stack if necessary and
11140 mortalizes the SV. Does not use "TARG". See also "XPUSHs" and
11141 "mPUSHs".
11142 void mXPUSHs(SV* sv)
11144 "mXPUSHu"
11146 Push an unsigned integer onto the stack, extending the stack if
11147 necessary. Does not use "TARG". See also "XPUSHu", "mPUSHu" and
11148 "PUSHu".
11149 void mXPUSHu(UV uv)
11151 "newXSproto"
11153 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl
11154 prototypes to the subs.
11155 "ORIGMARK"
11157 The original stack mark for the XSUB. See "dORIGMARK".
11158 "PL_markstack"
11160 Described in perlguts.
11161 "PL_markstack_ptr"
11163 Described in perlguts.
11164 "PL_savestack"
11166 Described in perlguts.
11167 "PL_savestack_ix"
11169 Described in perlguts.
11170 "PL_scopestack"
11172 Described in perlguts.
11173 "PL_scopestack_ix"
11175 Described in perlguts.
11176 "PL_scopestack_name"
11178 Described in perlguts.
11179 "PL_stack_base"
11181 Described in perlguts.
11182 "PL_stack_sp"
11184 Described in perlguts.
11185 "PL_tmps_floor"
11187 Described in perlguts.
11188 "PL_tmps_ix"
11190 Described in perlguts.
11191 "PL_tmps_stack"
11193 Described in perlguts.
11194 "POPi"
11196 Pops an integer off the stack.
11197 IV POPi
11199 "POPl"
11201 Pops a long off the stack.
11202 long POPl
11204 "POPn"
11206 Pops a double off the stack.
11207 NV POPn
11209 "POPp"
11211 Pops a string off the stack.
11212 char* POPp
11214 "POPpbytex"
11216 Pops a string off the stack which must consist of bytes i.e.
11217 characters < 256.
11218 char* POPpbytex
11220 "POPpx"
11222 Pops a string off the stack. Identical to POPp. There are two
11223 names for historical reasons.
11224 char* POPpx
11226 "POPs"
11228 Pops an SV off the stack.
11229 SV* POPs
11231 "POPu"
11233 Pops an unsigned integer off the stack.
11234 UV POPu
11236 "POPul"
11238 Pops an unsigned long off the stack.
11239 long POPul
11241 "PUSHi"
11243 Push an integer onto the stack. The stack must have room for this
11244 element. Handles 'set' magic. Uses "TARG", so "dTARGET" or
11245 "dXSTARG" should be called to declare it. Do not call multiple
11246 "TARG"-oriented macros to return lists from XSUB's - see "mPUSHi"
11247 instead. See also "XPUSHi" and "mXPUSHi".
11248 void PUSHi(IV iv)
11250 "PUSHMARK"
11252 Opening bracket for arguments on a callback. See "PUTBACK" and
11253 perlcall.
11254 void PUSHMARK(SP)
11256 "PUSHmortal"
11258 Push a new mortal SV onto the stack. The stack must have room for
11259 this element. Does not use "TARG". See also "PUSHs",
11260 "XPUSHmortal" and "XPUSHs".
11261 void PUSHmortal
11263 "PUSHn"
11265 Push a double onto the stack. The stack must have room for this
11266 element. Handles 'set' magic. Uses "TARG", so "dTARGET" or
11267 "dXSTARG" should be called to declare it. Do not call multiple
11268 "TARG"-oriented macros to return lists from XSUB's - see "mPUSHn"
11269 instead. See also "XPUSHn" and "mXPUSHn".
11270 void PUSHn(NV nv)
11272 "PUSHp"
11274 Push a string onto the stack. The stack must have room for this
11275 element. The "len" indicates the length of the string. Handles
11276 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG" should be
11277 called to declare it. Do not call multiple "TARG"-oriented macros
11278 to return lists from XSUB's - see "mPUSHp" instead. See also
11279 "XPUSHp" and "mXPUSHp".
11280 void PUSHp(char* str, STRLEN len)
11282 "PUSHs"
11284 Push an SV onto the stack. The stack must have room for this
11285 element. Does not handle 'set' magic. Does not use "TARG". See
11286 also "PUSHmortal", "XPUSHs", and "XPUSHmortal".
11287 void PUSHs(SV* sv)
11289 "PUSHu"
11291 Push an unsigned integer onto the stack. The stack must have room
11292 for this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
11293 or "dXSTARG" should be called to declare it. Do not call multiple
11294 "TARG"-oriented macros to return lists from XSUB's - see "mPUSHu"
11295 instead. See also "XPUSHu" and "mXPUSHu".
11296 void PUSHu(UV uv)
11298 "PUTBACK"
11300 Closing bracket for XSUB arguments. This is usually handled by
11301 "xsubpp". See "PUSHMARK" and perlcall for other uses.
11302 PUTBACK;
11304 "SAVEt_INT"
11306 Described in perlguts.
11307 "SP"
11309 Stack pointer. This is usually handled by "xsubpp". See "dSP" and
11310 "SPAGAIN".
11311 "SPAGAIN"
11313 Refetch the stack pointer. Used after a callback. See perlcall.
11314 SPAGAIN;
11316 "SSNEW"
11318 "SSNEWa"
11319 "SSNEWt"
11320 "SSNEWat"
11321 These temporarily allocates data on the savestack, returning an I32
11322 index into the savestack, because a pointer would get broken if the
11323 savestack is moved on reallocation. Use ""SSPTR"" to convert the
11324 returned index into a pointer.
11325 The forms differ in that plain "SSNEW" allocates "size" bytes;
11327 "SSNEWt" and "SSNEWat" allocate "size" objects, each of which is
11328 type "type"; and <SSNEWa> and "SSNEWat" make sure to align the new
11329 data to an "align" boundary. The most useful value for the
11330 alignment is likely to be ""MEM_ALIGNBYTES"". The alignment will
11331 be preserved through savestack reallocation only if realloc returns
11332 data aligned to a size divisible by "align"!
11333 I32 SSNEW (Size_t size)
11335 I32 SSNEWa (Size_t_size, Size_t align)
11336 I32 SSNEWt (Size_t size, type)
11337 I32 SSNEWat(Size_t_size, type, Size_t align)
11338 "SSPTR"
11340 "SSPTRt"
11341 These convert the "index" returned by L/<"SSNEW"> and kin into
11342 actual pointers.
11343 The difference is that "SSPTR" casts the result to "type", and
11345 "SSPTRt" casts it to a pointer of that "type".
11346 type SSPTR (I32 index, type)
11348 type * SSPTRt(I32 index, type)
11349 "TARG"
11351 "TARG" is short for "target". It is an entry in the pad that an
11352 OPs "op_targ" refers to. It is scratchpad space, often used as a
11353 return value for the OP, but some use it for other purposes.
11354 TARG;
11356 "TOPs"
11358 Described in perlguts.
11359 "XPUSHi"
11361 Push an integer onto the stack, extending the stack if necessary.
11362 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG" should
11363 be called to declare it. Do not call multiple "TARG"-oriented
11364 macros to return lists from XSUB's - see "mXPUSHi" instead. See
11365 also "PUSHi" and "mPUSHi".
11366 void XPUSHi(IV iv)
11368 "XPUSHmortal"
11370 Push a new mortal SV onto the stack, extending the stack if
11371 necessary. Does not use "TARG". See also "XPUSHs", "PUSHmortal"
11372 and "PUSHs".
11373 void XPUSHmortal
11375 "XPUSHn"
11377 Push a double onto the stack, extending the stack if necessary.
11378 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG" should
11379 be called to declare it. Do not call multiple "TARG"-oriented
11380 macros to return lists from XSUB's - see "mXPUSHn" instead. See
11381 also "PUSHn" and "mPUSHn".
11382 void XPUSHn(NV nv)
11384 "XPUSHp"
11386 Push a string onto the stack, extending the stack if necessary.
11387 The "len" indicates the length of the string. Handles 'set' magic.
11388 Uses "TARG", so "dTARGET" or "dXSTARG" should be called to declare
11389 it. Do not call multiple "TARG"-oriented macros to return lists
11390 from XSUB's - see "mXPUSHp" instead. See also "PUSHp" and
11391 "mPUSHp".
11392 void XPUSHp(char* str, STRLEN len)
11394 "XPUSHs"
11396 Push an SV onto the stack, extending the stack if necessary. Does
11397 not handle 'set' magic. Does not use "TARG". See also
11398 "XPUSHmortal", "PUSHs" and "PUSHmortal".
11399 void XPUSHs(SV* sv)
11401 "XPUSHu"
11403 Push an unsigned integer onto the stack, extending the stack if
11404 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
11405 "dXSTARG" should be called to declare it. Do not call multiple
11406 "TARG"-oriented macros to return lists from XSUB's - see "mXPUSHu"
11407 instead. See also "PUSHu" and "mPUSHu".
11408 void XPUSHu(UV uv)
11410 "XS_APIVERSION_BOOTCHECK"
11412 Macro to verify that the perl api version an XS module has been
11413 compiled against matches the api version of the perl interpreter
11414 it's being loaded into.
11415 XS_APIVERSION_BOOTCHECK;
11417 "XSRETURN"
11419 Return from XSUB, indicating number of items on the stack. This is
11420 usually handled by "xsubpp".
11421 void XSRETURN(int nitems)
11423 "XSRETURN_EMPTY"
11425 Return an empty list from an XSUB immediately.
11426 XSRETURN_EMPTY;
11428 "XSRETURN_IV"
11430 Return an integer from an XSUB immediately. Uses "XST_mIV".
11431 void XSRETURN_IV(IV iv)
11433 "XSRETURN_NO"
11435 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
11436 XSRETURN_NO;
11438 "XSRETURN_NV"
11440 Return a double from an XSUB immediately. Uses "XST_mNV".
11441 void XSRETURN_NV(NV nv)
11443 "XSRETURN_PV"
11445 Return a copy of a string from an XSUB immediately. Uses
11446 "XST_mPV".
11447 void XSRETURN_PV(char* str)
11449 "XSRETURN_UNDEF"
11451 Return &PL_sv_undef from an XSUB immediately. Uses "XST_mUNDEF".
11452 XSRETURN_UNDEF;
11454 "XSRETURN_UV"
11456 Return an integer from an XSUB immediately. Uses "XST_mUV".
11457 void XSRETURN_UV(IV uv)
11459 "XSRETURN_YES"
11461 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
11462 XSRETURN_YES;
11464 "XST_mIV"
11466 Place an integer into the specified position "pos" on the stack.
11467 The value is stored in a new mortal SV.
11468 void XST_mIV(int pos, IV iv)
11470 "XST_mNO"
11472 Place &PL_sv_no into the specified position "pos" on the stack.
11473 void XST_mNO(int pos)
11475 "XST_mNV"
11477 Place a double into the specified position "pos" on the stack. The
11478 value is stored in a new mortal SV.
11479 void XST_mNV(int pos, NV nv)
11481 "XST_mPV"
11483 Place a copy of a string into the specified position "pos" on the
11484 stack. The value is stored in a new mortal SV.
11485 void XST_mPV(int pos, char* str)
11487 "XST_mUNDEF"
11489 Place &PL_sv_undef into the specified position "pos" on the stack.
11490 void XST_mUNDEF(int pos)
11492 "XST_mUV"
11494 Place an unsigned integer into the specified position "pos" on the
11495 stack. The value is stored in a new mortal SV.
11496 void XST_mUV(int pos, UV uv)
11498 "XST_mYES"
11500 Place &PL_sv_yes into the specified position "pos" on the stack.
11501 void XST_mYES(int pos)
11503 "XS_VERSION"
11505 The version identifier for an XS module. This is usually handled
11506 automatically by "ExtUtils::MakeMaker". See
11507 "XS_VERSION_BOOTCHECK".
11508 "XS_VERSION_BOOTCHECK"
11510 Macro to verify that a PM module's $VERSION variable matches the XS
11511 module's "XS_VERSION" variable. This is usually handled
11512 automatically by "xsubpp". See "The VERSIONCHECK: Keyword" in
11513 perlxs.
11514 XS_VERSION_BOOTCHECK;
11516
11518 See also "Unicode Support".
11519 "CAT2"
11521 This macro concatenates 2 tokens together.
11522 token CAT2(token x, token y)
11524 "Copy"
11526 "CopyD"
11527 The XSUB-writer's interface to the C "memcpy" function. The "src"
11528 is the source, "dest" is the destination, "nitems" is the number of
11529 items, and "type" is the type. May fail on overlapping copies.
11530 See also "Move".
11531 "CopyD" is like "Copy" but returns "dest". Useful for encouraging
11533 compilers to tail-call optimise.
11534 void Copy (void* src, void* dest, int nitems, type)
11536 void * CopyD(void* src, void* dest, int nitems, type)
11537 "delimcpy"
11539 Copy a source buffer to a destination buffer, stopping at (but not
11540 including) the first occurrence in the source of an unescaped
11541 (defined below) delimiter byte, "delim". The source is the bytes
11542 between "from" and "from_end" - 1. Similarly, the dest is "to" up
11543 to "to_end".
11544 The number of bytes copied is written to *retlen.
11546 Returns the position of the first uncopied "delim" in the "from"
11548 buffer, but if there is no such occurrence before "from_end", then
11549 "from_end" is returned, and the entire buffer
11550 "from" .. "from_end" - 1 is copied.
11551 If there is room in the destination available after the copy, an
11553 extra terminating safety "NUL" byte is appended (not included in
11554 the returned length).
11555 The error case is if the destination buffer is not large enough to
11557 accommodate everything that should be copied. In this situation, a
11558 value larger than "to_end" - "to" is written to *retlen, and as
11559 much of the source as fits will be written to the destination. Not
11560 having room for the safety "NUL" is not considered an error.
11561 In the following examples, let "x" be the delimiter, and 0
11563 represent a "NUL" byte (NOT the digit 0). Then we would have
11564 Source Destination
11566 abcxdef abc0
11567 provided the destination buffer is at least 4 bytes long.
11569 An escaped delimiter is one which is immediately preceded by a
11571 single backslash. Escaped delimiters are copied, and the copy
11572 continues past the delimiter; the backslash is not copied:
11573 Source Destination
11575 abc\xdef abcxdef0
11576 (provided the destination buffer is at least 8 bytes long).
11578 It's actually somewhat more complicated than that. A sequence of
11580 any odd number of backslashes escapes the following delimiter, and
11581 the copy continues with exactly one of the backslashes stripped.
11582 Source Destination
11584 abc\xdef abcxdef0
11585 abc\\\xdef abc\\xdef0
11586 abc\\\\\xdef abc\\\\xdef0
11587 (as always, if the destination is large enough)
11589 An even number of preceding backslashes does not escape the
11591 delimiter, so that the copy stops just before it, and includes all
11592 the backslashes (no stripping; zero is considered even):
11593 Source Destination
11595 abcxdef abc0
11596 abc\\xdef abc\\0
11597 abc\\\\xdef abc\\\\0
11598 char* delimcpy(char* to, const char* to_end, const char* from,
11600 const char* from_end, const int delim,
11601 I32* retlen)
11602 "do_join"
11604 This performs a Perl "join", placing the joined output into "sv".
11605 The elements to join are in SVs, stored in a C array of pointers to
11607 SVs, from **mark to "**sp - 1". Hence *mark is a reference to the
11608 first SV. Each SV will be coerced into a PV if not one already.
11609 "delim" contains the string (or coerced into a string) that is to
11611 separate each of the joined elements.
11612 If any component is in UTF-8, the result will be as well, and all
11614 non-UTF-8 components will be converted to UTF-8 as necessary.
11615 Magic and tainting are handled.
11617 void do_join(SV *sv, SV *delim, SV **mark, SV **sp)
11619 "do_sprintf"
11621 This performs a Perl "sprintf" placing the string output into "sv".
11622 The elements to format are in SVs, stored in a C array of pointers
11624 to SVs of length "len"> and beginning at **sarg. The element
11625 referenced by *sarg is the format.
11626 Magic and tainting are handled.
11628 void do_sprintf(SV* sv, SSize_t len, SV** sarg)
11630 "fbm_compile"
11632 Analyzes the string in order to make fast searches on it using
11633 "fbm_instr()" -- the Boyer-Moore algorithm.
11634 void fbm_compile(SV* sv, U32 flags)
11636 "fbm_instr"
11638 Returns the location of the SV in the string delimited by "big" and
11639 "bigend" ("bigend") is the char following the last char). It
11640 returns "NULL" if the string can't be found. The "sv" does not
11641 have to be "fbm_compiled", but the search will not be as fast then.
11642 char* fbm_instr(unsigned char* big, unsigned char* bigend,
11644 SV* littlestr, U32 flags)
11645 "foldEQ"
11647 Returns true if the leading "len" bytes of the strings "s1" and
11648 "s2" are the same case-insensitively; false otherwise. Uppercase
11649 and lowercase ASCII range bytes match themselves and their opposite
11650 case counterparts. Non-cased and non-ASCII range bytes match only
11651 themselves.
11652 I32 foldEQ(const char* a, const char* b, I32 len)
11654 "ibcmp"
11656 This is a synonym for "(! foldEQ())"
11657 I32 ibcmp(const char* a, const char* b, I32 len)
11659 "ibcmp_locale"
11661 This is a synonym for "(! foldEQ_locale())"
11662 I32 ibcmp_locale(const char* a, const char* b, I32 len)
11664 "ibcmp_utf8"
11666 This is a synonym for "(! foldEQ_utf8())"
11667 I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1,
11669 const char *s2, char **pe2, UV l2, bool u2)
11670 "instr"
11672 Same as strstr(3), which finds and returns a pointer to the first
11673 occurrence of the NUL-terminated substring "little" in the NUL-
11674 terminated string "big", returning NULL if not found. The
11675 terminating NUL bytes are not compared.
11676 char* instr(const char* big, const char* little)
11678 "memCHRs"
11680 Returns the position of the first occurence of the byte "c" in the
11681 literal string "list", or NULL if "c" doesn't appear in "list".
11682 All bytes are treated as unsigned char. Thus this macro can be
11683 used to determine if "c" is in a set of particular characters.
11684 Unlike strchr(3), it works even if "c" is "NUL" (and the set
11685 doesn't include "NUL").
11686 bool memCHRs("list", char c)
11688 "memEQ"
11690 Test two buffers (which may contain embedded "NUL" characters, to
11691 see if they are equal. The "len" parameter indicates the number of
11692 bytes to compare. Returns true or false. It is undefined behavior
11693 if either of the buffers doesn't contain at least "len" bytes.
11694 bool memEQ(char* s1, char* s2, STRLEN len)
11696 "memEQs"
11698 Like "memEQ", but the second string is a literal enclosed in double
11699 quotes, "l1" gives the number of bytes in "s1". Returns true or
11700 false.
11701 bool memEQs(char* s1, STRLEN l1, "s2")
11703 "memNE"
11705 Test two buffers (which may contain embedded "NUL" characters, to
11706 see if they are not equal. The "len" parameter indicates the
11707 number of bytes to compare. Returns true or false. It is
11708 undefined behavior if either of the buffers doesn't contain at
11709 least "len" bytes.
11710 bool memNE(char* s1, char* s2, STRLEN len)
11712 "memNEs"
11714 Like "memNE", but the second string is a literal enclosed in double
11715 quotes, "l1" gives the number of bytes in "s1". Returns true or
11716 false.
11717 bool memNEs(char* s1, STRLEN l1, "s2")
11719 "Move"
11721 "MoveD"
11722 The XSUB-writer's interface to the C "memmove" function. The "src"
11723 is the source, "dest" is the destination, "nitems" is the number of
11724 items, and "type" is the type. Can do overlapping moves. See also
11725 "Copy".
11726 "MoveD" is like "Move" but returns "dest". Useful for encouraging
11728 compilers to tail-call optimise.
11729 void Move (void* src, void* dest, int nitems, type)
11731 void * MoveD(void* src, void* dest, int nitems, type)
11732 "my_snprintf"
11734 The C library "snprintf" functionality, if available and standards-
11735 compliant (uses "vsnprintf", actually). However, if the
11736 "vsnprintf" is not available, will unfortunately use the unsafe
11737 "vsprintf" which can overrun the buffer (there is an overrun check,
11738 but that may be too late). Consider using "sv_vcatpvf" instead, or
11739 getting "vsnprintf".
11740 int my_snprintf(char *buffer, const Size_t len,
11742 const char *format, ...)
11743 "my_sprintf"
11745 "DEPRECATED!" It is planned to remove "my_sprintf" from a future
11746 release of Perl. Do not use it for new code; remove it from
11747 existing code.
11748 Do NOT use this due to the possibility of overflowing "buffer".
11750 Instead use my_snprintf()
11751 int my_sprintf(NN char *buffer, NN const char *pat, ...)
11753 "my_strlcat"
11755 The C library "strlcat" if available, or a Perl implementation of
11756 it. This operates on C "NUL"-terminated strings.
11757 "my_strlcat()" appends string "src" to the end of "dst". It will
11759 append at most "size - strlen(dst) - 1" characters. It will then
11760 "NUL"-terminate, unless "size" is 0 or the original "dst" string
11761 was longer than "size" (in practice this should not happen as it
11762 means that either "size" is incorrect or that "dst" is not a proper
11763 "NUL"-terminated string).
11764 Note that "size" is the full size of the destination buffer and the
11766 result is guaranteed to be "NUL"-terminated if there is room. Note
11767 that room for the "NUL" should be included in "size".
11768 The return value is the total length that "dst" would have if
11770 "size" is sufficiently large. Thus it is the initial length of
11771 "dst" plus the length of "src". If "size" is smaller than the
11772 return, the excess was not appended.
11773 Size_t my_strlcat(char *dst, const char *src, Size_t size)
11775 "my_strlcpy"
11777 The C library "strlcpy" if available, or a Perl implementation of
11778 it. This operates on C "NUL"-terminated strings.
11779 "my_strlcpy()" copies up to "size - 1" characters from the string
11781 "src" to "dst", "NUL"-terminating the result if "size" is not 0.
11782 The return value is the total length "src" would be if the copy
11784 completely succeeded. If it is larger than "size", the excess was
11785 not copied.
11786 Size_t my_strlcpy(char *dst, const char *src, Size_t size)
11788 "my_strnlen"
11790 The C library "strnlen" if available, or a Perl implementation of
11791 it.
11792 "my_strnlen()" computes the length of the string, up to "maxlen"
11794 characters. It will never attempt to address more than "maxlen"
11795 characters, making it suitable for use with strings that are not
11796 guaranteed to be NUL-terminated.
11797 Size_t my_strnlen(const char *str, Size_t maxlen)
11799 "my_vsnprintf"
11801 The C library "vsnprintf" if available and standards-compliant.
11802 However, if the "vsnprintf" is not available, will unfortunately
11803 use the unsafe "vsprintf" which can overrun the buffer (there is an
11804 overrun check, but that may be too late). Consider using
11805 "sv_vcatpvf" instead, or getting "vsnprintf".
11806 int my_vsnprintf(char *buffer, const Size_t len,
11808 const char *format, va_list ap)
11809 "ninstr"
11811 Find the first (leftmost) occurrence of a sequence of bytes within
11812 another sequence. This is the Perl version of "strstr()", extended
11813 to handle arbitrary sequences, potentially containing embedded
11814 "NUL" characters ("NUL" is what the initial "n" in the function
11815 name stands for; some systems have an equivalent, "memmem()", but
11816 with a somewhat different API).
11817 Another way of thinking about this function is finding a needle in
11819 a haystack. "big" points to the first byte in the haystack.
11820 "big_end" points to one byte beyond the final byte in the haystack.
11821 "little" points to the first byte in the needle. "little_end"
11822 points to one byte beyond the final byte in the needle. All the
11823 parameters must be non-"NULL".
11824 The function returns "NULL" if there is no occurrence of "little"
11826 within "big". If "little" is the empty string, "big" is returned.
11827 Because this function operates at the byte level, and because of
11829 the inherent characteristics of UTF-8 (or UTF-EBCDIC), it will work
11830 properly if both the needle and the haystack are strings with the
11831 same UTF-8ness, but not if the UTF-8ness differs.
11832 char* ninstr(const char* big, const char* bigend,
11834 const char* little, const char* lend)
11835 "Nullch"
11837 Null character pointer. (No longer available when "PERL_CORE" is
11838 defined.)
11839 "PL_na"
11841 A scratch pad variable in which to store a "STRLEN" value. If
11842 would have been better named something like "PL_temp_strlen".
11843 It is is typically used with "SvPV" when one is actually planning
11845 to discard the returned length, (hence the length is "Not
11846 Applicable", which is how this variable got its name).
11847 It is usually more efficient to either declare a local variable and
11849 use that instead, or to use the "SvPV_nolen" macro.
11850 STRLEN PL_na
11852 "rninstr"
11854 Like "ninstr", but instead finds the final (rightmost) occurrence
11855 of a sequence of bytes within another sequence, returning "NULL" if
11856 there is no such occurrence.
11857 char* rninstr(const char* big, const char* bigend,
11859 const char* little, const char* lend)
11860 "savepv"
11862 Perl's version of "strdup()". Returns a pointer to a newly
11863 allocated string which is a duplicate of "pv". The size of the
11864 string is determined by "strlen()", which means it may not contain
11865 embedded "NUL" characters and must have a trailing "NUL". To
11866 prevent memory leaks, the memory allocated for the new string needs
11867 to be freed when no longer needed. This can be done with the
11868 "Safefree" function, or "SAVEFREEPV".
11869 On some platforms, Windows for example, all allocated memory owned
11871 by a thread is deallocated when that thread ends. So if you need
11872 that not to happen, you need to use the shared memory functions,
11873 such as "savesharedpv".
11874 char* savepv(const char* pv)
11876 "savepvn"
11878 Perl's version of what "strndup()" would be if it existed. Returns
11879 a pointer to a newly allocated string which is a duplicate of the
11880 first "len" bytes from "pv", plus a trailing "NUL" byte. The
11881 memory allocated for the new string can be freed with the
11882 "Safefree()" function.
11883 On some platforms, Windows for example, all allocated memory owned
11885 by a thread is deallocated when that thread ends. So if you need
11886 that not to happen, you need to use the shared memory functions,
11887 such as "savesharedpvn".
11888 char* savepvn(const char* pv, Size_t len)
11890 "savepvs"
11892 Like "savepvn", but takes a literal string instead of a
11893 string/length pair.
11894 char* savepvs("literal string")
11896 "savesharedpv"
11898 A version of "savepv()" which allocates the duplicate string in
11899 memory which is shared between threads.
11900 char* savesharedpv(const char* pv)
11902 "savesharedpvn"
11904 A version of "savepvn()" which allocates the duplicate string in
11905 memory which is shared between threads. (With the specific
11906 difference that a "NULL" pointer is not acceptable)
11907 char* savesharedpvn(const char *const pv, const STRLEN len)
11909 "savesharedpvs"
11911 A version of "savepvs()" which allocates the duplicate string in
11912 memory which is shared between threads.
11913 char* savesharedpvs("literal string")
11915 "savesharedsvpv"
11917 A version of "savesharedpv()" which allocates the duplicate string
11918 in memory which is shared between threads.
11919 char* savesharedsvpv(SV *sv)
11921 "savesvpv"
11923 A version of "savepv()"/"savepvn()" which gets the string to
11924 duplicate from the passed in SV using "SvPV()"
11925 On some platforms, Windows for example, all allocated memory owned
11927 by a thread is deallocated when that thread ends. So if you need
11928 that not to happen, you need to use the shared memory functions,
11929 such as "savesharedsvpv".
11930 char* savesvpv(SV* sv)
11932 "strEQ"
11934 Test two "NUL"-terminated strings to see if they are equal.
11935 Returns true or false.
11936 bool strEQ(char* s1, char* s2)
11938 "strGE"
11940 Test two "NUL"-terminated strings to see if the first, "s1", is
11941 greater than or equal to the second, "s2". Returns true or false.
11942 bool strGE(char* s1, char* s2)
11944 "strGT"
11946 Test two "NUL"-terminated strings to see if the first, "s1", is
11947 greater than the second, "s2". Returns true or false.
11948 bool strGT(char* s1, char* s2)
11950 "STRINGIFY"
11952 This macro surrounds its token with double quotes.
11953 string STRINGIFY(token x)
11955 "strLE"
11957 Test two "NUL"-terminated strings to see if the first, "s1", is
11958 less than or equal to the second, "s2". Returns true or false.
11959 bool strLE(char* s1, char* s2)
11961 "STRLEN"
11963 Described in perlguts.
11964 "strLT"
11966 Test two "NUL"-terminated strings to see if the first, "s1", is
11967 less than the second, "s2". Returns true or false.
11968 bool strLT(char* s1, char* s2)
11970 "strNE"
11972 Test two "NUL"-terminated strings to see if they are different.
11973 Returns true or false.
11974 bool strNE(char* s1, char* s2)
11976 "strnEQ"
11978 Test two "NUL"-terminated strings to see if they are equal. The
11979 "len" parameter indicates the number of bytes to compare. Returns
11980 true or false. (A wrapper for "strncmp").
11981 bool strnEQ(char* s1, char* s2, STRLEN len)
11983 "strnNE"
11985 Test two "NUL"-terminated strings to see if they are different.
11986 The "len" parameter indicates the number of bytes to compare.
11987 Returns true or false. (A wrapper for "strncmp").
11988 bool strnNE(char* s1, char* s2, STRLEN len)
11990 "STR_WITH_LEN"
11992 Returns two comma separated tokens of the input literal string, and
11993 its length. This is convenience macro which helps out in some API
11994 calls. Note that it can't be used as an argument to macros or
11995 functions that under some configurations might be macros, which
11996 means that it requires the full Perl_xxx(aTHX_ ...) form for any
11997 API calls where it's used.
11998 pair STR_WITH_LEN("literal string")
12000 "Zero"
12002 "ZeroD"
12003 The XSUB-writer's interface to the C "memzero" function. The
12004 "dest" is the destination, "nitems" is the number of items, and
12005 "type" is the type.
12006 "ZeroD" is like "Zero" but returns "dest". Useful for encouraging
12008 compilers to tail-call optimise.
12009 void Zero (void* dest, int nitems, type)
12011 void * ZeroD(void* dest, int nitems, type)
12012
12014 "SVt_IV"
12015 Type flag for scalars. See "svtype".
12016 "SVt_NULL"
12018 Type flag for scalars. See "svtype".
12019 "SVt_NV"
12021 Type flag for scalars. See "svtype".
12022 "SVt_PV"
12024 Type flag for scalars. See "svtype".
12025 "SVt_PVAV"
12027 Type flag for arrays. See "svtype".
12028 "SVt_PVCV"
12030 Type flag for subroutines. See "svtype".
12031 "SVt_PVFM"
12033 Type flag for formats. See "svtype".
12034 "SVt_PVGV"
12036 Type flag for typeglobs. See "svtype".
12037 "SVt_PVHV"
12039 Type flag for hashes. See "svtype".
12040 "SVt_PVIO"
12042 Type flag for I/O objects. See "svtype".
12043 "SVt_PVIV"
12045 Type flag for scalars. See "svtype".
12046 "SVt_PVLV"
12048 Type flag for scalars. See "svtype".
12049 "SVt_PVMG"
12051 Type flag for scalars. See "svtype".
12052 "SVt_PVNV"
12054 Type flag for scalars. See "svtype".
12055 "SVt_REGEXP"
12057 Type flag for regular expressions. See "svtype".
12058 "svtype"
12060 An enum of flags for Perl types. These are found in the file sv.h
12061 in the "svtype" enum. Test these flags with the "SvTYPE" macro.
12062 The types are:
12064 SVt_NULL
12066 SVt_IV
12067 SVt_NV
12068 SVt_RV
12069 SVt_PV
12070 SVt_PVIV
12071 SVt_PVNV
12072 SVt_PVMG
12073 SVt_INVLIST
12074 SVt_REGEXP
12075 SVt_PVGV
12076 SVt_PVLV
12077 SVt_PVAV
12078 SVt_PVHV
12079 SVt_PVCV
12080 SVt_PVFM
12081 SVt_PVIO
12082 These are most easily explained from the bottom up.
12084 "SVt_PVIO" is for I/O objects, "SVt_PVFM" for formats, "SVt_PVCV"
12086 for subroutines, "SVt_PVHV" for hashes and "SVt_PVAV" for arrays.
12087 All the others are scalar types, that is, things that can be bound
12089 to a "$" variable. For these, the internal types are mostly
12090 orthogonal to types in the Perl language.
12091 Hence, checking "SvTYPE(sv) < SVt_PVAV" is the best way to see
12093 whether something is a scalar.
12094 "SVt_PVGV" represents a typeglob. If "!SvFAKE(sv)", then it is a
12096 real, incoercible typeglob. If "SvFAKE(sv)", then it is a scalar
12097 to which a typeglob has been assigned. Assigning to it again will
12098 stop it from being a typeglob. "SVt_PVLV" represents a scalar that
12099 delegates to another scalar behind the scenes. It is used, e.g.,
12100 for the return value of "substr" and for tied hash and array
12101 elements. It can hold any scalar value, including a typeglob.
12102 "SVt_REGEXP" is for regular expressions. "SVt_INVLIST" is for Perl
12103 core internal use only.
12104 "SVt_PVMG" represents a "normal" scalar (not a typeglob, regular
12106 expression, or delegate). Since most scalars do not need all the
12107 internal fields of a PVMG, we save memory by allocating smaller
12108 structs when possible. All the other types are just simpler forms
12109 of "SVt_PVMG", with fewer internal fields. "SVt_NULL" can only
12110 hold undef. "SVt_IV" can hold undef, an integer, or a reference.
12111 ("SVt_RV" is an alias for "SVt_IV", which exists for backward
12112 compatibility.) "SVt_NV" can hold any of those or a double.
12113 "SVt_PV" can only hold "undef" or a string. "SVt_PVIV" is a
12114 superset of "SVt_PV" and "SVt_IV". "SVt_PVNV" is similar.
12115 "SVt_PVMG" can hold anything "SVt_PVNV" can hold, but it can, but
12116 does not have to, be blessed or magical.
12117
12119 "boolSV"
12120 Returns a true SV if "b" is a true value, or a false SV if "b" is
12121 0.
12122 See also "PL_sv_yes" and "PL_sv_no".
12124 SV * boolSV(bool b)
12126 "croak_xs_usage"
12128 A specialised variant of "croak()" for emitting the usage message
12129 for xsubs
12130 croak_xs_usage(cv, "eee_yow");
12132 works out the package name and subroutine name from "cv", and then
12134 calls "croak()". Hence if "cv" is &ouch::awk, it would call
12135 "croak" as:
12136 Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
12138 "eee_yow");
12139 void croak_xs_usage(const CV *const cv, const char *const params)
12141 "DEFSV"
12143 Returns the SV associated with $_
12144 SV * DEFSV
12146 "DEFSV_set"
12148 Associate "sv" with $_
12149 void DEFSV_set(SV * sv)
12151 "get_sv"
12153 Returns the SV of the specified Perl scalar. "flags" are passed to
12154 ""gv_fetchpv"". If "GV_ADD" is set and the Perl variable does not
12155 exist then it will be created. If "flags" is zero and the variable
12156 does not exist then NULL is returned.
12157 NOTE: the "perl_get_sv()" form is deprecated.
12159 SV* get_sv(const char *name, I32 flags)
12161 "isGV_with_GP"
12163 Returns a boolean as to whether or not "sv" is a GV with a pointer
12164 to a GP (glob pointer).
12165 bool isGV_with_GP(SV * sv)
12167 "looks_like_number"
12169 Test if the content of an SV looks like a number (or is a number).
12170 "Inf" and "Infinity" are treated as numbers (so will not issue a
12171 non-numeric warning), even if your "atof()" doesn't grok them.
12172 Get-magic is ignored.
12173 I32 looks_like_number(SV *const sv)
12175 "MUTABLE_PTR"
12177 "MUTABLE_AV"
12178 "MUTABLE_CV"
12179 "MUTABLE_GV"
12180 "MUTABLE_HV"
12181 "MUTABLE_IO"
12182 "MUTABLE_SV"
12183 The "MUTABLE_*"() macros cast pointers to the types shown, in such
12184 a way (compiler permitting) that casting away const-ness will give
12185 a warning; e.g.:
12186 const SV *sv = ...;
12188 AV *av1 = (AV*)sv; <== BAD: the const has been silently
12189 cast away
12190 AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
12191 "MUTABLE_PTR" is the base macro used to derive new casts. The
12193 other already-built-in ones return pointers to what their names
12194 indicate.
12195 void * MUTABLE_PTR(void * p)
12197 AV * MUTABLE_AV (AV * p)
12198 CV * MUTABLE_CV (CV * p)
12199 GV * MUTABLE_GV (GV * p)
12200 HV * MUTABLE_HV (HV * p)
12201 IO * MUTABLE_IO (IO * p)
12202 SV * MUTABLE_SV (SV * p)
12203 "newRV"
12205 "newRV_inc"
12206 These are identical. They create an RV wrapper for an SV. The
12207 reference count for the original SV is incremented.
12208 SV* newRV(SV *const sv)
12210 "newRV_noinc"
12212 Creates an RV wrapper for an SV. The reference count for the
12213 original SV is not incremented.
12214 SV* newRV_noinc(SV *const tmpRef)
12216 "newSV"
12218 Creates a new SV. A non-zero "len" parameter indicates the number
12219 of bytes of preallocated string space the SV should have. An extra
12220 byte for a trailing "NUL" is also reserved. ("SvPOK" is not set
12221 for the SV even if string space is allocated.) The reference count
12222 for the new SV is set to 1.
12223 In 5.9.3, "newSV()" replaces the older "NEWSV()" API, and drops the
12225 first parameter, x, a debug aid which allowed callers to identify
12226 themselves. This aid has been superseded by a new build option,
12227 "PERL_MEM_LOG" (see "PERL_MEM_LOG" in perlhacktips). The older API
12228 is still there for use in XS modules supporting older perls.
12229 SV* newSV(const STRLEN len)
12231 "newSVhek"
12233 Creates a new SV from the hash key structure. It will generate
12234 scalars that point to the shared string table where possible.
12235 Returns a new (undefined) SV if "hek" is NULL.
12236 SV* newSVhek(const HEK *const hek)
12238 "newSViv"
12240 Creates a new SV and copies an integer into it. The reference
12241 count for the SV is set to 1.
12242 SV* newSViv(const IV i)
12244 "newSVnv"
12246 Creates a new SV and copies a floating point value into it. The
12247 reference count for the SV is set to 1.
12248 SV* newSVnv(const NV n)
12250 "newSVpadname"
12252 NOTE: "newSVpadname" is experimental and may change or be removed
12253 without notice.
12254 Creates a new SV containing the pad name.
12256 SV* newSVpadname(PADNAME *pn)
12258 "newSVpv"
12260 Creates a new SV and copies a string (which may contain "NUL"
12261 ("\0") characters) into it. The reference count for the SV is set
12262 to 1. If "len" is zero, Perl will compute the length using
12263 "strlen()", (which means if you use this option, that "s" can't
12264 have embedded "NUL" characters and has to have a terminating "NUL"
12265 byte).
12266 This function can cause reliability issues if you are likely to
12268 pass in empty strings that are not null terminated, because it will
12269 run strlen on the string and potentially run past valid memory.
12270 Using "newSVpvn" is a safer alternative for non "NUL" terminated
12272 strings. For string literals use "newSVpvs" instead. This
12273 function will work fine for "NUL" terminated strings, but if you
12274 want to avoid the if statement on whether to call "strlen" use
12275 "newSVpvn" instead (calling "strlen" yourself).
12276 SV* newSVpv(const char *const s, const STRLEN len)
12278 "newSVpvf"
12280 Creates a new SV and initializes it with the string formatted like
12281 "sv_catpvf".
12282 NOTE: "newSVpvf" must be explicitly called as "Perl_newSVpvf" with
12284 an "aTHX_" parameter.
12285 SV* Perl_newSVpvf(pTHX_ const char *const pat, ...)
12287 "newSVpvf_nocontext"
12289 Like "newSVpvf" but does not take a thread context ("aTHX")
12290 parameter, so is used in situations where the caller doesn't
12291 already have the thread context.
12292 SV* newSVpvf_nocontext(const char *const pat, ...)
12294 "newSVpvn"
12296 Creates a new SV and copies a string into it, which may contain
12297 "NUL" characters ("\0") and other binary data. The reference count
12298 for the SV is set to 1. Note that if "len" is zero, Perl will
12299 create a zero length (Perl) string. You are responsible for
12300 ensuring that the source buffer is at least "len" bytes long. If
12301 the "buffer" argument is NULL the new SV will be undefined.
12302 SV* newSVpvn(const char *const buffer, const STRLEN len)
12304 "newSVpvn_flags"
12306 Creates a new SV and copies a string (which may contain "NUL"
12307 ("\0") characters) into it. The reference count for the SV is set
12308 to 1. Note that if "len" is zero, Perl will create a zero length
12309 string. You are responsible for ensuring that the source string is
12310 at least "len" bytes long. If the "s" argument is NULL the new SV
12311 will be undefined. Currently the only flag bits accepted are
12312 "SVf_UTF8" and "SVs_TEMP". If "SVs_TEMP" is set, then
12313 "sv_2mortal()" is called on the result before returning. If
12314 "SVf_UTF8" is set, "s" is considered to be in UTF-8 and the
12315 "SVf_UTF8" flag will be set on the new SV. "newSVpvn_utf8()" is a
12316 convenience wrapper for this function, defined as
12317 #define newSVpvn_utf8(s, len, u) \
12319 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
12320 SV* newSVpvn_flags(const char *const s, const STRLEN len,
12322 const U32 flags)
12323 "newSVpvn_share"
12325 Creates a new SV with its "SvPVX_const" pointing to a shared string
12326 in the string table. If the string does not already exist in the
12327 table, it is created first. Turns on the "SvIsCOW" flag (or
12328 "READONLY" and "FAKE" in 5.16 and earlier). If the "hash"
12329 parameter is non-zero, that value is used; otherwise the hash is
12330 computed. The string's hash can later be retrieved from the SV
12331 with the "SvSHARED_HASH" macro. The idea here is that as the
12332 string table is used for shared hash keys these strings will have
12333 "SvPVX_const == HeKEY" and hash lookup will avoid string compare.
12334 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
12336 "newSVpvn_utf8"
12338 Creates a new SV and copies a string (which may contain "NUL"
12339 ("\0") characters) into it. If "utf8" is true, calls "SvUTF8_on"
12340 on the new SV. Implemented as a wrapper around "newSVpvn_flags".
12341 SV* newSVpvn_utf8(const char* s, STRLEN len, U32 utf8)
12343 "newSVpvs"
12345 Like "newSVpvn", but takes a literal string instead of a
12346 string/length pair.
12347 SV* newSVpvs("literal string")
12349 "newSVpvs_flags"
12351 Like "newSVpvn_flags", but takes a literal string instead of a
12352 string/length pair.
12353 SV* newSVpvs_flags("literal string", U32 flags)
12355 "newSVpv_share"
12357 Like "newSVpvn_share", but takes a "NUL"-terminated string instead
12358 of a string/length pair.
12359 SV* newSVpv_share(const char* s, U32 hash)
12361 "newSVpvs_share"
12363 Like "newSVpvn_share", but takes a literal string instead of a
12364 string/length pair and omits the hash parameter.
12365 SV* newSVpvs_share("literal string")
12367 "newSVrv"
12369 Creates a new SV for the existing RV, "rv", to point to. If "rv"
12370 is not an RV then it will be upgraded to one. If "classname" is
12371 non-null then the new SV will be blessed in the specified package.
12372 The new SV is returned and its reference count is 1. The reference
12373 count 1 is owned by "rv". See also newRV_inc() and newRV_noinc()
12374 for creating a new RV properly.
12375 SV* newSVrv(SV *const rv, const char *const classname)
12377 "newSVsv"
12379 "newSVsv_nomg"
12380 "newSVsv_flags"
12381 These create a new SV which is an exact duplicate of the original
12382 SV (using "sv_setsv".)
12383 They differ only in that "newSVsv" performs 'get' magic;
12385 "newSVsv_nomg" skips any magic; and "newSVsv_flags" allows you to
12386 explicitly set a "flags" parameter.
12387 SV* newSVsv (SV *const old)
12389 SV* newSVsv_nomg (SV *const old)
12390 SV* newSVsv_flags(SV *const old, I32 flags)
12391 "newSV_type"
12393 Creates a new SV, of the type specified. The reference count for
12394 the new SV is set to 1.
12395 SV* newSV_type(const svtype type)
12397 "newSV_type_mortal"
12399 Creates a new mortal SV, of the type specified. The reference
12400 count for the new SV is set to 1.
12401 This is equivalent to
12403 SV* sv = sv_2mortal(newSV_type(<some type>)) and
12404 SV* sv = sv_newmortal();
12405 sv_upgrade(sv, <some_type>) but should be more efficient than
12406 both of them. (Unless sv_2mortal is inlined at some point in the
12407 future.)
12408 SV* newSV_type_mortal(const svtype type)
12410 "newSVuv"
12412 Creates a new SV and copies an unsigned integer into it. The
12413 reference count for the SV is set to 1.
12414 SV* newSVuv(const UV u)
12416 "Nullsv"
12418 Null SV pointer. (No longer available when "PERL_CORE" is
12419 defined.)
12420 "PL_sv_no"
12422 This is the "false" SV. It is readonly. See "PL_sv_yes". Always
12423 refer to this as &PL_sv_no.
12424 SV PL_sv_no
12426 "PL_sv_undef"
12428 This is the "undef" SV. It is readonly. Always refer to this as
12429 &PL_sv_undef.
12430 SV PL_sv_undef
12432 "PL_sv_yes"
12434 This is the "true" SV. It is readonly. See "PL_sv_no". Always
12435 refer to this as &PL_sv_yes.
12436 SV PL_sv_yes
12438 "PL_sv_zero"
12440 This readonly SV has a zero numeric value and a "0" string value.
12441 It's similar to "PL_sv_no" except for its string value. Can be used
12442 as a cheap alternative to mXPUSHi(0) for example. Always refer to
12443 this as &PL_sv_zero. Introduced in 5.28.
12444 SV PL_sv_zero
12446 "SAVE_DEFSV"
12448 Localize $_. See "Localizing changes" in perlguts.
12449 void SAVE_DEFSV
12451 "sortsv"
12453 In-place sort an array of SV pointers with the given comparison
12454 routine.
12455 Currently this always uses mergesort. See "sortsv_flags" for a
12457 more flexible routine.
12458 void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
12460 "sortsv_flags"
12462 In-place sort an array of SV pointers with the given comparison
12463 routine, with various SORTf_* flag options.
12464 void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp,
12466 U32 flags)
12467 "SV"
12469 Described in perlguts.
12470 "sv_2cv"
12472 Using various gambits, try to get a CV from an SV; in addition, try
12473 if possible to set *st and *gvp to the stash and GV associated with
12474 it. The flags in "lref" are passed to "gv_fetchsv".
12475 CV* sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)
12477 "sv_2io"
12479 Using various gambits, try to get an IO from an SV: the IO slot if
12480 its a GV; or the recursive result if we're an RV; or the IO slot of
12481 the symbol named after the PV if we're a string.
12482 'Get' magic is ignored on the "sv" passed in, but will be called on
12484 "SvRV(sv)" if "sv" is an RV.
12485 IO* sv_2io(SV *const sv)
12487 "sv_2iv_flags"
12489 Return the integer value of an SV, doing any necessary string
12490 conversion. If "flags" has the "SV_GMAGIC" bit set, does an
12491 "mg_get()" first. Normally used via the "SvIV(sv)" and "SvIVx(sv)"
12492 macros.
12493 IV sv_2iv_flags(SV *const sv, const I32 flags)
12495 "sv_2mortal"
12497 Marks an existing SV as mortal. The SV will be destroyed "soon",
12498 either by an explicit call to "FREETMPS", or by an implicit call at
12499 places such as statement boundaries. "SvTEMP()" is turned on which
12500 means that the SV's string buffer can be "stolen" if this SV is
12501 copied. See also "sv_newmortal" and "sv_mortalcopy".
12502 SV* sv_2mortal(SV *const sv)
12504 "sv_2nv_flags"
12506 Return the num value of an SV, doing any necessary string or
12507 integer conversion. If "flags" has the "SV_GMAGIC" bit set, does
12508 an "mg_get()" first. Normally used via the "SvNV(sv)" and
12509 "SvNVx(sv)" macros.
12510 NV sv_2nv_flags(SV *const sv, const I32 flags)
12512 "sv_2pv"
12514 "sv_2pv_flags"
12515 These implement the various forms of the ""SvPV"" in perlapi
12516 macros. The macros are the preferred interface.
12517 These return a pointer to the string value of an SV (coercing it to
12519 a string if necessary), and set *lp to its length in bytes.
12520 The forms differ in that plain "sv_2pvbyte" always processes 'get'
12522 magic; and "sv_2pvbyte_flags" processes 'get' magic if and only if
12523 "flags" contains "SV_GMAGIC".
12524 char* sv_2pv (SV *sv, STRLEN *lp)
12526 char* sv_2pv_flags(SV *const sv, STRLEN *const lp,
12527 const U32 flags)
12528 "sv_2pvbyte"
12530 "sv_2pvbyte_flags"
12531 These implement the various forms of the ""SvPVbyte"" in perlapi
12532 macros. The macros are the preferred interface.
12533 These return a pointer to the byte-encoded representation of the
12535 SV, and set *lp to its length. If the SV is marked as being
12536 encoded as UTF-8, it will be downgraded, if possible, to a byte
12537 string. If the SV cannot be downgraded, they croak.
12538 The forms differ in that plain "sv_2pvbyte" always processes 'get'
12540 magic; and "sv_2pvbyte_flags" processes 'get' magic if and only if
12541 "flags" contains "SV_GMAGIC".
12542 char* sv_2pvbyte (SV *sv, STRLEN *const lp)
12544 char* sv_2pvbyte_flags(SV *sv, STRLEN *const lp, const U32 flags)
12545 "sv_2pvutf8"
12547 "sv_2pvutf8_flags"
12548 These implement the various forms of the ""SvPVutf8"" in perlapi
12549 macros. The macros are the preferred interface.
12550 These return a pointer to the UTF-8-encoded representation of the
12552 SV, and set *lp to its length in bytes. They may cause the SV to
12553 be upgraded to UTF-8 as a side-effect.
12554 The forms differ in that plain "sv_2pvutf8" always processes 'get'
12556 magic; and "sv_2pvutf8_flags" processes 'get' magic if and only if
12557 "flags" contains "SV_GMAGIC".
12558 char* sv_2pvutf8 (SV *sv, STRLEN *const lp)
12560 char* sv_2pvutf8_flags(SV *sv, STRLEN *const lp, const U32 flags)
12561 "sv_2uv_flags"
12563 Return the unsigned integer value of an SV, doing any necessary
12564 string conversion. If "flags" has the "SV_GMAGIC" bit set, does an
12565 "mg_get()" first. Normally used via the "SvUV(sv)" and "SvUVx(sv)"
12566 macros.
12567 UV sv_2uv_flags(SV *const sv, const I32 flags)
12569 "SvAMAGIC"
12571 Returns a boolean as to whether "sv" has overloading (active magic)
12572 enabled or not.
12573 bool SvAMAGIC(SV * sv)
12575 "sv_backoff"
12577 Remove any string offset. You should normally use the "SvOOK_off"
12578 macro wrapper instead.
12579 void sv_backoff(SV *const sv)
12581 "sv_bless"
12583 Blesses an SV into a specified package. The SV must be an RV. The
12584 package must be designated by its stash (see "gv_stashpv"). The
12585 reference count of the SV is unaffected.
12586 SV* sv_bless(SV *const sv, HV *const stash)
12588 "sv_catpv"
12590 "sv_catpv_flags"
12591 "sv_catpv_mg"
12592 "sv_catpv_nomg"
12593 These concatenate the "NUL"-terminated string "sstr" onto the end
12594 of the string which is in the SV. If the SV has the UTF-8 status
12595 set, then the bytes appended should be valid UTF-8.
12596 They differ only in how they handle magic:
12598 "sv_catpv_mg" performs both 'get' and 'set' magic.
12600 "sv_catpv" performs only 'get' magic.
12602 "sv_catpv_nomg" skips all magic.
12604 "sv_catpv_flags" has an extra "flags" parameter which allows you to
12606 specify any combination of magic handling (using "SV_GMAGIC" and/or
12607 "SV_SMAGIC"), and to also override the UTF-8 handling. By
12608 supplying the "SV_CATUTF8" flag, the appended string is forced to
12609 be interpreted as UTF-8; by supplying instead the "SV_CATBYTES"
12610 flag, it will be interpreted as just bytes. Either the SV or the
12611 string appended will be upgraded to UTF-8 if necessary.
12612 void sv_catpv (SV *const dsv, const char* sstr)
12614 void sv_catpv_flags(SV *dsv, const char *sstr, const I32 flags)
12615 void sv_catpv_mg (SV *const dsv, const char *const sstr)
12616 void sv_catpv_nomg (SV *const dsv, const char* sstr)
12617 "sv_catpvf"
12619 "sv_catpvf_nocontext"
12620 "sv_catpvf_mg"
12621 "sv_catpvf_mg_nocontext"
12622 These process their arguments like "sprintf", and append the
12623 formatted output to an SV. As with "sv_vcatpvfn", argument
12624 reordering is not supporte when called with a non-null C-style
12625 variable argument list.
12626 If the appended data contains "wide" characters (including, but not
12628 limited to, SVs with a UTF-8 PV formatted with %s, and characters
12629 >255 formatted with %c), the original SV might get upgraded to
12630 UTF-8.
12631 If the original SV was UTF-8, the pattern should be valid UTF-8; if
12633 the original SV was bytes, the pattern should be too.
12634 All perform 'get' magic, but only "sv_catpvf_mg" and
12636 "sv_catpvf_mg_nocontext" perform 'set' magic.
12637 "sv_catpvf_nocontext" and "sv_catpvf_mg_nocontext" do not take a
12639 thread context ("aTHX") parameter, so are used in situations where
12640 the caller doesn't already have the thread context.
12641 NOTE: "sv_catpvf" must be explicitly called as "Perl_sv_catpvf"
12643 with an "aTHX_" parameter.
12644 NOTE: "sv_catpvf_mg" must be explicitly called as
12646 "Perl_sv_catpvf_mg" with an "aTHX_" parameter.
12647 void Perl_sv_catpvf (pTHX_ SV *const sv,
12649 const char *const pat, ...)
12650 void sv_catpvf_nocontext (SV *const sv, const char *const pat,
12651 ...)
12652 void Perl_sv_catpvf_mg (pTHX_ SV *const sv,
12653 const char *const pat, ...)
12654 void sv_catpvf_mg_nocontext(SV *const sv, const char *const pat,
12655 ...)
12656 "sv_catpvn"
12658 "sv_catpvn_flags"
12659 "sv_catpvn_mg"
12660 "sv_catpvn_nomg"
12661 These concatenate the "len" bytes of the string beginning at "ptr"
12662 onto the end of the string which is in "dsv". The caller must make
12663 sure "ptr" contains at least "len" bytes.
12664 For all but "sv_catpvn_flags", the string appended is assumed to be
12666 valid UTF-8 if the SV has the UTF-8 status set, and a string of
12667 bytes otherwise.
12668 They differ in that:
12670 "sv_catpvn_mg" performs both 'get' and 'set' magic on "dsv".
12672 "sv_catpvn" performs only 'get' magic.
12674 "sv_catpvn_nomg" skips all magic.
12676 "sv_catpvn_flags" has an extra "flags" parameter which allows you
12678 to specify any combination of magic handling (using "SV_GMAGIC"
12679 and/or "SV_SMAGIC") and to also override the UTF-8 handling. By
12680 supplying the "SV_CATBYTES" flag, the appended string is
12681 interpreted as plain bytes; by supplying instead the "SV_CATUTF8"
12682 flag, it will be interpreted as UTF-8, and the "dsv" will be
12683 upgraded to UTF-8 if necessary.
12684 "sv_catpvn", "sv_catpvn_mg", and "sv_catpvn_nomg" are implemented
12686 in terms of "sv_catpvn_flags".
12687 void sv_catpvn (SV *dsv, const char *sstr, STRLEN len)
12689 void sv_catpvn_flags(SV *const dsv, const char *sstr,
12690 const STRLEN len, const I32 flags)
12691 void sv_catpvn_mg (SV *dsv, const char *sstr, STRLEN len)
12692 void sv_catpvn_nomg (SV *dsv, const char *sstr, STRLEN len)
12693 "sv_catpvs"
12695 Like "sv_catpvn", but takes a literal string instead of a
12696 string/length pair.
12697 void sv_catpvs(SV* sv, "literal string")
12699 "sv_catpvs_flags"
12701 Like "sv_catpvn_flags", but takes a literal string instead of a
12702 string/length pair.
12703 void sv_catpvs_flags(SV* sv, "literal string", I32 flags)
12705 "sv_catpvs_mg"
12707 Like "sv_catpvn_mg", but takes a literal string instead of a
12708 string/length pair.
12709 void sv_catpvs_mg(SV* sv, "literal string")
12711 "sv_catpvs_nomg"
12713 Like "sv_catpvn_nomg", but takes a literal string instead of a
12714 string/length pair.
12715 void sv_catpvs_nomg(SV* sv, "literal string")
12717 "sv_catsv"
12719 "sv_catsv_flags"
12720 "sv_catsv_mg"
12721 "sv_catsv_nomg"
12722 These concatenate the string from SV "sstr" onto the end of the
12723 string in SV "dsv". If "sstr" is null, these are no-ops; otherwise
12724 only "dsv" is modified.
12725 They differ only in what magic they perform:
12727 "sv_catsv_mg" performs 'get' magic on both SVs before the copy, and
12729 'set' magic on "dsv" afterwards.
12730 "sv_catsv" performs just 'get' magic, on both SVs.
12732 "sv_catsv_nomg" skips all magic.
12734 "sv_catsv_flags" has an extra "flags" parameter which allows you to
12736 use "SV_GMAGIC" and/or "SV_SMAGIC" to specify any combination of
12737 magic handling (although either both or neither SV will have 'get'
12738 magic applied to it.)
12739 "sv_catsv", "sv_catsv_mg", and "sv_catsv_nomg" are implemented in
12741 terms of "sv_catsv_flags".
12742 void sv_catsv (SV *dsv, SV *sstr)
12744 void sv_catsv_flags(SV *const dsv, SV *const sstr,
12745 const I32 flags)
12746 void sv_catsv_mg (SV *dsv, SV *sstr)
12747 void sv_catsv_nomg (SV *dsv, SV *sstr)
12748 "sv_chop"
12750 Efficient removal of characters from the beginning of the string
12751 buffer. "SvPOK(sv)", or at least "SvPOKp(sv)", must be true and
12752 "ptr" must be a pointer to somewhere inside the string buffer.
12753 "ptr" becomes the first character of the adjusted string. Uses the
12754 "OOK" hack. On return, only "SvPOK(sv)" and "SvPOKp(sv)" among the
12755 "OK" flags will be true.
12756 Beware: after this function returns, "ptr" and SvPVX_const(sv) may
12758 no longer refer to the same chunk of data.
12759 The unfortunate similarity of this function's name to that of
12761 Perl's "chop" operator is strictly coincidental. This function
12762 works from the left; "chop" works from the right.
12763 void sv_chop(SV *const sv, const char *const ptr)
12765 "sv_clear"
12767 Clear an SV: call any destructors, free up any memory used by the
12768 body, and free the body itself. The SV's head is not freed,
12769 although its type is set to all 1's so that it won't inadvertently
12770 be assumed to be live during global destruction etc. This function
12771 should only be called when "REFCNT" is zero. Most of the time
12772 you'll want to call "sv_free()" (or its macro wrapper
12773 "SvREFCNT_dec") instead.
12774 void sv_clear(SV *const orig_sv)
12776 "sv_cmp"
12778 Compares the strings in two SVs. Returns -1, 0, or 1 indicating
12779 whether the string in "sv1" is less than, equal to, or greater than
12780 the string in "sv2". Is UTF-8 and 'use bytes' aware, handles get
12781 magic, and will coerce its args to strings if necessary. See also
12782 "sv_cmp_locale".
12783 I32 sv_cmp(SV *const sv1, SV *const sv2)
12785 "sv_cmp_flags"
12787 Compares the strings in two SVs. Returns -1, 0, or 1 indicating
12788 whether the string in "sv1" is less than, equal to, or greater than
12789 the string in "sv2". Is UTF-8 and 'use bytes' aware and will
12790 coerce its args to strings if necessary. If the flags has the
12791 "SV_GMAGIC" bit set, it handles get magic. See also
12792 "sv_cmp_locale_flags".
12793 I32 sv_cmp_flags(SV *const sv1, SV *const sv2, const U32 flags)
12795 "sv_cmp_locale"
12797 Compares the strings in two SVs in a locale-aware manner. Is UTF-8
12798 and 'use bytes' aware, handles get magic, and will coerce its args
12799 to strings if necessary. See also "sv_cmp".
12800 I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
12802 "sv_cmp_locale_flags"
12804 Compares the strings in two SVs in a locale-aware manner. Is UTF-8
12805 and 'use bytes' aware and will coerce its args to strings if
12806 necessary. If the flags contain "SV_GMAGIC", it handles get magic.
12807 See also "sv_cmp_flags".
12808 I32 sv_cmp_locale_flags(SV *const sv1, SV *const sv2,
12810 const U32 flags)
12811 "sv_collxfrm"
12813 This calls "sv_collxfrm_flags" with the SV_GMAGIC flag. See
12814 "sv_collxfrm_flags".
12815 char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
12817 "sv_collxfrm_flags"
12819 Add Collate Transform magic to an SV if it doesn't already have it.
12820 If the flags contain "SV_GMAGIC", it handles get-magic.
12821 Any scalar variable may carry "PERL_MAGIC_collxfrm" magic that
12823 contains the scalar data of the variable, but transformed to such a
12824 format that a normal memory comparison can be used to compare the
12825 data according to the locale settings.
12826 char* sv_collxfrm_flags(SV *const sv, STRLEN *const nxp,
12828 I32 const flags)
12829 "sv_copypv"
12831 "sv_copypv_nomg"
12832 "sv_copypv_flags"
12833 These copy a stringified representation of the source SV into the
12834 destination SV. They automatically perform coercion of numeric
12835 values into strings. Guaranteed to preserve the "UTF8" flag even
12836 from overloaded objects. Similar in nature to "sv_2pv[_flags]" but
12837 they operate directly on an SV instead of just the string. Mostly
12838 they use ""sv_2pv_flags"" to do the work, except when that would
12839 lose the UTF-8'ness of the PV.
12840 The three forms differ only in whether or not they perform 'get
12842 magic' on "sv". "sv_copypv_nomg" skips 'get magic'; "sv_copypv"
12843 performs it; and "sv_copypv_flags" either performs it (if the
12844 "SV_GMAGIC" bit is set in "flags") or doesn't (if that bit is
12845 cleared).
12846 void sv_copypv (SV *const dsv, SV *const ssv)
12848 void sv_copypv_nomg (SV *const dsv, SV *const ssv)
12849 void sv_copypv_flags(SV *const dsv, SV *const ssv,
12850 const I32 flags)
12851 "SvCUR"
12853 Returns the length, in bytes, of the PV inside the SV. Note that
12854 this may not match Perl's "length"; for that, use
12855 "sv_len_utf8(sv)". See "SvLEN" also.
12856 STRLEN SvCUR(SV* sv)
12858 "SvCUR_set"
12860 Sets the current length, in bytes, of the C string which is in the
12861 SV. See "SvCUR" and "SvIV_set">.
12862 void SvCUR_set(SV* sv, STRLEN len)
12864 "sv_dec"
12866 "sv_dec_nomg"
12867 These auto-decrement the value in the SV, doing string to numeric
12868 conversion if necessary. They both handle operator overloading.
12869 They differ only in that:
12871 "sv_dec" handles 'get' magic; "sv_dec_nomg" skips 'get' magic.
12873 void sv_dec(SV *const sv)
12875 "sv_derived_from"
12877 Exactly like "sv_derived_from_pv", but doesn't take a "flags"
12878 parameter.
12879 bool sv_derived_from(SV* sv, const char *const name)
12881 "sv_derived_from_pv"
12883 Exactly like "sv_derived_from_pvn", but takes a nul-terminated
12884 string instead of a string/length pair.
12885 bool sv_derived_from_pv(SV* sv, const char *const name,
12887 U32 flags)
12888 "sv_derived_from_pvn"
12890 Returns a boolean indicating whether the SV is derived from the
12891 specified class at the C level. To check derivation at the Perl
12892 level, call "isa()" as a normal Perl method.
12893 Currently, the only significant value for "flags" is SVf_UTF8.
12895 bool sv_derived_from_pvn(SV* sv, const char *const name,
12897 const STRLEN len, U32 flags)
12898 "sv_derived_from_sv"
12900 Exactly like "sv_derived_from_pvn", but takes the name string in
12901 the form of an SV instead of a string/length pair. This is the
12902 advised form.
12903 bool sv_derived_from_sv(SV* sv, SV *namesv, U32 flags)
12905 "sv_does"
12907 Like "sv_does_pv", but doesn't take a "flags" parameter.
12908 bool sv_does(SV* sv, const char *const name)
12910 "sv_does_pv"
12912 Like "sv_does_sv", but takes a nul-terminated string instead of an
12913 SV.
12914 bool sv_does_pv(SV* sv, const char *const name, U32 flags)
12916 "sv_does_pvn"
12918 Like "sv_does_sv", but takes a string/length pair instead of an SV.
12919 bool sv_does_pvn(SV* sv, const char *const name,
12921 const STRLEN len, U32 flags)
12922 "sv_does_sv"
12924 Returns a boolean indicating whether the SV performs a specific,
12925 named role. The SV can be a Perl object or the name of a Perl
12926 class.
12927 bool sv_does_sv(SV* sv, SV* namesv, U32 flags)
12929 "SvEND"
12931 Returns a pointer to the spot just after the last character in the
12932 string which is in the SV, where there is usually a trailing "NUL"
12933 character (even though Perl scalars do not strictly require it).
12934 See "SvCUR". Access the character as "*(SvEND(sv))".
12935 Warning: If "SvCUR" is equal to "SvLEN", then "SvEND" points to
12937 unallocated memory.
12938 char* SvEND(SV* sv)
12940 "sv_eq"
12942 Returns a boolean indicating whether the strings in the two SVs are
12943 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and
12944 will coerce its args to strings if necessary.
12945 This function does not handle operator overloading. For a version
12947 that does, see instead "sv_streq".
12948 I32 sv_eq(SV* sv1, SV* sv2)
12950 "sv_eq_flags"
12952 Returns a boolean indicating whether the strings in the two SVs are
12953 identical. Is UTF-8 and 'use bytes' aware and coerces its args to
12954 strings if necessary. If the flags has the "SV_GMAGIC" bit set, it
12955 handles get-magic, too.
12956 This function does not handle operator overloading. For a version
12958 that does, see instead "sv_streq_flags".
12959 I32 sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)
12961 "sv_force_normal"
12963 Undo various types of fakery on an SV: if the PV is a shared
12964 string, make a private copy; if we're a ref, stop refing; if we're
12965 a glob, downgrade to an "xpvmg". See also "sv_force_normal_flags".
12966 void sv_force_normal(SV *sv)
12968 "sv_force_normal_flags"
12970 Undo various types of fakery on an SV, where fakery means "more
12971 than" a string: if the PV is a shared string, make a private copy;
12972 if we're a ref, stop refing; if we're a glob, downgrade to an
12973 "xpvmg"; if we're a copy-on-write scalar, this is the on-write time
12974 when we do the copy, and is also used locally; if this is a
12975 vstring, drop the vstring magic. If "SV_COW_DROP_PV" is set then a
12976 copy-on-write scalar drops its PV buffer (if any) and becomes
12977 "SvPOK_off" rather than making a copy. (Used where this scalar is
12978 about to be set to some other value.) In addition, the "flags"
12979 parameter gets passed to "sv_unref_flags()" when unreffing.
12980 "sv_force_normal" calls this function with flags set to 0.
12981 This function is expected to be used to signal to perl that this SV
12983 is about to be written to, and any extra book-keeping needs to be
12984 taken care of. Hence, it croaks on read-only values.
12985 void sv_force_normal_flags(SV *const sv, const U32 flags)
12987 "sv_free"
12989 Decrement an SV's reference count, and if it drops to zero, call
12990 "sv_clear" to invoke destructors and free up any memory used by the
12991 body; finally, deallocating the SV's head itself. Normally called
12992 via a wrapper macro "SvREFCNT_dec".
12993 void sv_free(SV *const sv)
12995 "SvGAMAGIC"
12997 Returns true if the SV has get magic or overloading. If either is
12998 true then the scalar is active data, and has the potential to
12999 return a new value every time it is accessed. Hence you must be
13000 careful to only read it once per user logical operation and work
13001 with that returned value. If neither is true then the scalar's
13002 value cannot change unless written to.
13003 U32 SvGAMAGIC(SV* sv)
13005 "SvGETMAGIC"
13007 Invokes "mg_get" on an SV if it has 'get' magic. For example, this
13008 will call "FETCH" on a tied variable. This macro evaluates its
13009 argument more than once.
13010 void SvGETMAGIC(SV* sv)
13012 "sv_gets"
13014 Get a line from the filehandle and store it into the SV, optionally
13015 appending to the currently-stored string. If "append" is not 0,
13016 the line is appended to the SV instead of overwriting it. "append"
13017 should be set to the byte offset that the appended string should
13018 start at in the SV (typically, "SvCUR(sv)" is a suitable choice).
13019 char* sv_gets(SV *const sv, PerlIO *const fp, I32 append)
13021 "sv_get_backrefs"
13023 NOTE: "sv_get_backrefs" is experimental and may change or be
13024 removed without notice.
13025 If "sv" is the target of a weak reference then it returns the back
13027 references structure associated with the sv; otherwise return
13028 "NULL".
13029 When returning a non-null result the type of the return is
13031 relevant. If it is an AV then the elements of the AV are the weak
13032 reference RVs which point at this item. If it is any other type
13033 then the item itself is the weak reference.
13034 See also "Perl_sv_add_backref()", "Perl_sv_del_backref()",
13036 "Perl_sv_kill_backrefs()"
13037 SV* sv_get_backrefs(SV *const sv)
13039 "SvGROW"
13041 Expands the character buffer in the SV so that it has room for the
13042 indicated number of bytes (remember to reserve space for an extra
13043 trailing "NUL" character). Calls "sv_grow" to perform the
13044 expansion if necessary. Returns a pointer to the character buffer.
13045 SV must be of type >= "SVt_PV". One alternative is to call
13046 "sv_grow" if you are not sure of the type of SV.
13047 You might mistakenly think that "len" is the number of bytes to add
13049 to the existing size, but instead it is the total size "sv" should
13050 be.
13051 char * SvGROW(SV* sv, STRLEN len)
13053 "sv_inc"
13055 "sv_inc_nomg"
13056 These auto-increment the value in the SV, doing string to numeric
13057 conversion if necessary. They both handle operator overloading.
13058 They differ only in that "sv_inc" performs 'get' magic;
13060 "sv_inc_nomg" skips any magic.
13061 void sv_inc(SV *const sv)
13063 "sv_insert"
13065 Inserts and/or replaces a string at the specified offset/length
13066 within the SV. Similar to the Perl "substr()" function, with
13067 "littlelen" bytes starting at "little" replacing "len" bytes of the
13068 string in "bigstr" starting at "offset". Handles get magic.
13069 void sv_insert(SV *const bigstr, const STRLEN offset,
13071 const STRLEN len, const char *const little,
13072 const STRLEN littlelen)
13073 "sv_insert_flags"
13075 Same as "sv_insert", but the extra "flags" are passed to the
13076 "SvPV_force_flags" that applies to "bigstr".
13077 void sv_insert_flags(SV *const bigstr, const STRLEN offset,
13079 const STRLEN len, const char *little,
13080 const STRLEN littlelen, const U32 flags)
13081 "SvIOK"
13083 Returns a U32 value indicating whether the SV contains an integer.
13084 U32 SvIOK(SV* sv)
13086 "SvIOK_notUV"
13088 Returns a boolean indicating whether the SV contains a signed
13089 integer.
13090 bool SvIOK_notUV(SV* sv)
13092 "SvIOK_off"
13094 Unsets the IV status of an SV.
13095 void SvIOK_off(SV* sv)
13097 "SvIOK_on"
13099 Tells an SV that it is an integer.
13100 void SvIOK_on(SV* sv)
13102 "SvIOK_only"
13104 Tells an SV that it is an integer and disables all other "OK" bits.
13105 void SvIOK_only(SV* sv)
13107 "SvIOK_only_UV"
13109 Tells an SV that it is an unsigned integer and disables all other
13110 "OK" bits.
13111 void SvIOK_only_UV(SV* sv)
13113 "SvIOKp"
13115 Returns a U32 value indicating whether the SV contains an integer.
13116 Checks the private setting. Use "SvIOK" instead.
13117 U32 SvIOKp(SV* sv)
13119 "SvIOK_UV"
13121 Returns a boolean indicating whether the SV contains an integer
13122 that must be interpreted as unsigned. A non-negative integer whose
13123 value is within the range of both an IV and a UV may be flagged as
13124 either "SvUOK" or "SvIOK".
13125 bool SvIOK_UV(SV* sv)
13127 "sv_isa"
13129 Returns a boolean indicating whether the SV is blessed into the
13130 specified class.
13131 This does not check for subtypes or method overloading. Use
13133 "sv_isa_sv" to verify an inheritance relationship in the same way
13134 as the "isa" operator by respecting any "isa()" method overloading;
13135 or "sv_derived_from_sv" to test directly on the actual object type.
13136 int sv_isa(SV* sv, const char *const name)
13138 "sv_isa_sv"
13140 NOTE: "sv_isa_sv" is experimental and may change or be removed
13141 without notice.
13142 Returns a boolean indicating whether the SV is an object reference
13144 and is derived from the specified class, respecting any "isa()"
13145 method overloading it may have. Returns false if "sv" is not a
13146 reference to an object, or is not derived from the specified class.
13147 This is the function used to implement the behaviour of the "isa"
13149 operator.
13150 Does not invoke magic on "sv".
13152 Not to be confused with the older "sv_isa" function, which does not
13154 use an overloaded "isa()" method, nor will check subclassing.
13155 bool sv_isa_sv(SV* sv, SV* namesv)
13157 "SvIsBOOL"
13159 Returns true if the SV is one of the special boolean constants
13160 (PL_sv_yes or PL_sv_no), or is a regular SV whose last assignment
13161 stored a copy of one.
13162 bool SvIsBOOL(SV* sv)
13164 "SvIsCOW"
13166 Returns a U32 value indicating whether the SV is Copy-On-Write
13167 (either shared hash key scalars, or full Copy On Write scalars if
13168 5.9.0 is configured for COW).
13169 U32 SvIsCOW(SV* sv)
13171 "SvIsCOW_shared_hash"
13173 Returns a boolean indicating whether the SV is Copy-On-Write shared
13174 hash key scalar.
13175 bool SvIsCOW_shared_hash(SV* sv)
13177 "sv_isobject"
13179 Returns a boolean indicating whether the SV is an RV pointing to a
13180 blessed object. If the SV is not an RV, or if the object is not
13181 blessed, then this will return false.
13182 int sv_isobject(SV* sv)
13184 "SvIV"
13186 "SvIVx"
13187 "SvIV_nomg"
13188 These coerce the given SV to IV and return it. The returned value
13189 in many circumstances will get stored in "sv"'s IV slot, but not in
13190 all cases. (Use "sv_setiv" to make sure it does).
13191 "SvIVx" is different from the others in that it is guaranteed to
13193 evaluate "sv" exactly once; the others may evaluate it multiple
13194 times. Only use this form if "sv" is an expression with side
13195 effects, otherwise use the more efficient "SvIV".
13196 "SvIV_nomg" is the same as "SvIV", but does not perform 'get'
13198 magic.
13199 IV SvIV(SV* sv)
13201 "SvIV_set"
13203 Set the value of the IV pointer in sv to val. It is possible to
13204 perform the same function of this macro with an lvalue assignment
13205 to "SvIVX". With future Perls, however, it will be more efficient
13206 to use "SvIV_set" instead of the lvalue assignment to "SvIVX".
13207 void SvIV_set(SV* sv, IV val)
13209 "SvIVX"
13211 Returns the raw value in the SV's IV slot, without checks or
13212 conversions. Only use when you are sure "SvIOK" is true. See also
13213 "SvIV".
13214 IV SvIVX(SV* sv)
13216 "SvLEN"
13218 Returns the size of the string buffer in the SV, not including any
13219 part attributable to "SvOOK". See "SvCUR".
13220 STRLEN SvLEN(SV* sv)
13222 "sv_len"
13224 Returns the length of the string in the SV. Handles magic and type
13225 coercion and sets the UTF8 flag appropriately. See also "SvCUR",
13226 which gives raw access to the "xpv_cur" slot.
13227 STRLEN sv_len(SV *const sv)
13229 "SvLEN_set"
13231 Set the size of the string buffer for the SV. See "SvLEN".
13232 void SvLEN_set(SV* sv, STRLEN len)
13234 "sv_len_utf8"
13236 "sv_len_utf8_nomg"
13237 These return the number of characters in the string in an SV,
13238 counting wide UTF-8 bytes as a single character. Both handle type
13239 coercion. They differ only in that "sv_len_utf8" performs 'get'
13240 magic; "sv_len_utf8_nomg" skips any magic.
13241 STRLEN sv_len_utf8(SV *const sv)
13243 "SvLOCK"
13245 Arranges for a mutual exclusion lock to be obtained on "sv" if a
13246 suitable module has been loaded.
13247 void SvLOCK(SV* sv)
13249 "sv_magic"
13251 Adds magic to an SV. First upgrades "sv" to type "SVt_PVMG" if
13252 necessary, then adds a new magic item of type "how" to the head of
13253 the magic list.
13254 See "sv_magicext" (which "sv_magic" now calls) for a description of
13256 the handling of the "name" and "namlen" arguments.
13257 You need to use "sv_magicext" to add magic to "SvREADONLY" SVs and
13259 also to add more than one instance of the same "how".
13260 void sv_magic(SV *const sv, SV *const obj, const int how,
13262 const char *const name, const I32 namlen)
13263 "sv_magicext"
13265 Adds magic to an SV, upgrading it if necessary. Applies the
13266 supplied "vtable" and returns a pointer to the magic added.
13267 Note that "sv_magicext" will allow things that "sv_magic" will not.
13269 In particular, you can add magic to "SvREADONLY" SVs, and add more
13270 than one instance of the same "how".
13271 If "namlen" is greater than zero then a "savepvn" copy of "name" is
13273 stored, if "namlen" is zero then "name" is stored as-is and - as
13274 another special case - if "(name && namlen == HEf_SVKEY)" then
13275 "name" is assumed to contain an SV* and is stored as-is with its
13276 "REFCNT" incremented.
13277 (This is now used as a subroutine by "sv_magic".)
13279 MAGIC * sv_magicext(SV *const sv, SV *const obj, const int how,
13281 const MGVTBL *const vtbl,
13282 const char *const name, const I32 namlen)
13283 "SvMAGIC_set"
13285 Set the value of the MAGIC pointer in "sv" to val. See "SvIV_set".
13286 void SvMAGIC_set(SV* sv, MAGIC* val)
13288 "sv_mortalcopy"
13290 Creates a new SV which is a copy of the original SV (using
13291 "sv_setsv"). The new SV is marked as mortal. It will be destroyed
13292 "soon", either by an explicit call to "FREETMPS", or by an implicit
13293 call at places such as statement boundaries. See also
13294 "sv_newmortal" and "sv_2mortal".
13295 SV* sv_mortalcopy(SV *const oldsv)
13297 "sv_mortalcopy_flags"
13299 Like "sv_mortalcopy", but the extra "flags" are passed to the
13300 "sv_setsv_flags".
13301 SV* sv_mortalcopy_flags(SV *const oldsv, U32 flags)
13303 "sv_newmortal"
13305 Creates a new null SV which is mortal. The reference count of the
13306 SV is set to 1. It will be destroyed "soon", either by an explicit
13307 call to "FREETMPS", or by an implicit call at places such as
13308 statement boundaries. See also "sv_mortalcopy" and "sv_2mortal".
13309 SV* sv_newmortal()
13311 "SvNIOK"
13313 Returns a U32 value indicating whether the SV contains a number,
13314 integer or double.
13315 U32 SvNIOK(SV* sv)
13317 "SvNIOK_off"
13319 Unsets the NV/IV status of an SV.
13320 void SvNIOK_off(SV* sv)
13322 "SvNIOKp"
13324 Returns a U32 value indicating whether the SV contains a number,
13325 integer or double. Checks the private setting. Use "SvNIOK"
13326 instead.
13327 U32 SvNIOKp(SV* sv)
13329 "SvNOK"
13331 Returns a U32 value indicating whether the SV contains a double.
13332 U32 SvNOK(SV* sv)
13334 "SvNOK_off"
13336 Unsets the NV status of an SV.
13337 void SvNOK_off(SV* sv)
13339 "SvNOK_on"
13341 Tells an SV that it is a double.
13342 void SvNOK_on(SV* sv)
13344 "SvNOK_only"
13346 Tells an SV that it is a double and disables all other OK bits.
13347 void SvNOK_only(SV* sv)
13349 "SvNOKp"
13351 Returns a U32 value indicating whether the SV contains a double.
13352 Checks the private setting. Use "SvNOK" instead.
13353 U32 SvNOKp(SV* sv)
13355 "sv_nolocking"
13357 "DEPRECATED!" It is planned to remove "sv_nolocking" from a future
13358 release of Perl. Do not use it for new code; remove it from
13359 existing code.
13360 Dummy routine which "locks" an SV when there is no locking module
13362 present. Exists to avoid test for a "NULL" function pointer and
13363 because it could potentially warn under some level of strict-ness.
13364 "Superseded" by "sv_nosharing()".
13366 void sv_nolocking(SV *sv)
13368 "sv_nounlocking"
13370 "DEPRECATED!" It is planned to remove "sv_nounlocking" from a
13371 future release of Perl. Do not use it for new code; remove it from
13372 existing code.
13373 Dummy routine which "unlocks" an SV when there is no locking module
13375 present. Exists to avoid test for a "NULL" function pointer and
13376 because it could potentially warn under some level of strict-ness.
13377 "Superseded" by "sv_nosharing()".
13379 void sv_nounlocking(SV *sv)
13381 "sv_numeq"
13383 A convenient shortcut for calling "sv_numeq_flags" with the
13384 "SV_GMAGIC" flag. This function basically behaves like the Perl
13385 code "$sv1 == $sv2".
13386 bool sv_numeq(SV* sv1, SV* sv2)
13388 "sv_numeq_flags"
13390 Returns a boolean indicating whether the numbers in the two SVs are
13391 identical. If the flags argument has the "SV_GMAGIC" bit set, it
13392 handles get-magic too. Will coerce its args to numbers if
13393 necessary. Treats "NULL" as undef.
13394 If flags does not have the "SV_SKIP_OVERLOAD" bit set, an attempt
13396 to use "==" overloading will be made. If such overloading does not
13397 exist or the flag is set, then regular numerical comparison will be
13398 used instead.
13399 bool sv_numeq_flags(SV* sv1, SV* sv2, const U32 flags)
13401 "SvNV"
13403 "SvNVx"
13404 "SvNV_nomg"
13405 These coerce the given SV to NV and return it. The returned value
13406 in many circumstances will get stored in "sv"'s NV slot, but not in
13407 all cases. (Use "sv_setnv" to make sure it does).
13408 "SvNVx" is different from the others in that it is guaranteed to
13410 evaluate "sv" exactly once; the others may evaluate it multiple
13411 times. Only use this form if "sv" is an expression with side
13412 effects, otherwise use the more efficient "SvNV".
13413 "SvNV_nomg" is the same as "SvNV", but does not perform 'get'
13415 magic.
13416 NV SvNV(SV* sv)
13418 "SvNV_set"
13420 Set the value of the NV pointer in "sv" to val. See "SvIV_set".
13421 void SvNV_set(SV* sv, NV val)
13423 "SvNVX"
13425 Returns the raw value in the SV's NV slot, without checks or
13426 conversions. Only use when you are sure "SvNOK" is true. See also
13427 "SvNV".
13428 NV SvNVX(SV* sv)
13430 "SvOK"
13432 Returns a U32 value indicating whether the value is defined. This
13433 is only meaningful for scalars.
13434 U32 SvOK(SV* sv)
13436 "SvOOK"
13438 Returns a U32 indicating whether the pointer to the string buffer
13439 is offset. This hack is used internally to speed up removal of
13440 characters from the beginning of a "SvPV". When "SvOOK" is true,
13441 then the start of the allocated string buffer is actually
13442 "SvOOK_offset()" bytes before "SvPVX". This offset used to be
13443 stored in "SvIVX", but is now stored within the spare part of the
13444 buffer.
13445 U32 SvOOK(SV* sv)
13447 "SvOOK_off"
13449 Remove any string offset.
13450 void SvOOK_off(SV * sv)
13452 "SvOOK_offset"
13454 Reads into "len" the offset from "SvPVX" back to the true start of
13455 the allocated buffer, which will be non-zero if "sv_chop" has been
13456 used to efficiently remove characters from start of the buffer.
13457 Implemented as a macro, which takes the address of "len", which
13458 must be of type "STRLEN". Evaluates "sv" more than once. Sets
13459 "len" to 0 if "SvOOK(sv)" is false.
13460 void SvOOK_offset(SV*sv, STRLEN len)
13462 "SvPOK"
13464 Returns a U32 value indicating whether the SV contains a character
13465 string.
13466 U32 SvPOK(SV* sv)
13468 "SvPOK_off"
13470 Unsets the PV status of an SV.
13471 void SvPOK_off(SV* sv)
13473 "SvPOK_on"
13475 Tells an SV that it is a string.
13476 void SvPOK_on(SV* sv)
13478 "SvPOK_only"
13480 Tells an SV that it is a string and disables all other "OK" bits.
13481 Will also turn off the UTF-8 status.
13482 void SvPOK_only(SV* sv)
13484 "SvPOK_only_UTF8"
13486 Tells an SV that it is a string and disables all other "OK" bits,
13487 and leaves the UTF-8 status as it was.
13488 void SvPOK_only_UTF8(SV* sv)
13490 "SvPOKp"
13492 Returns a U32 value indicating whether the SV contains a character
13493 string. Checks the private setting. Use "SvPOK" instead.
13494 U32 SvPOKp(SV* sv)
13496 "sv_pos_b2u"
13498 Converts the value pointed to by "offsetp" from a count of bytes
13499 from the start of the string, to a count of the equivalent number
13500 of UTF-8 chars. Handles magic and type coercion.
13501 Use "sv_pos_b2u_flags" in preference, which correctly handles
13503 strings longer than 2Gb.
13504 void sv_pos_b2u(SV *const sv, I32 *const offsetp)
13506 "sv_pos_b2u_flags"
13508 Converts "offset" from a count of bytes from the start of the
13509 string, to a count of the equivalent number of UTF-8 chars.
13510 Handles type coercion. "flags" is passed to "SvPV_flags", and
13511 usually should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
13512 STRLEN sv_pos_b2u_flags(SV *const sv, STRLEN const offset,
13514 U32 flags)
13515 "sv_pos_u2b"
13517 Converts the value pointed to by "offsetp" from a count of UTF-8
13518 chars from the start of the string, to a count of the equivalent
13519 number of bytes; if "lenp" is non-zero, it does the same to "lenp",
13520 but this time starting from the offset, rather than from the start
13521 of the string. Handles magic and type coercion.
13522 Use "sv_pos_u2b_flags" in preference, which correctly handles
13524 strings longer than 2Gb.
13525 void sv_pos_u2b(SV *const sv, I32 *const offsetp,
13527 I32 *const lenp)
13528 "sv_pos_u2b_flags"
13530 Converts the offset from a count of UTF-8 chars from the start of
13531 the string, to a count of the equivalent number of bytes; if "lenp"
13532 is non-zero, it does the same to "lenp", but this time starting
13533 from "offset", rather than from the start of the string. Handles
13534 type coercion. "flags" is passed to "SvPV_flags", and usually
13535 should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
13536 STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
13538 STRLEN *const lenp, U32 flags)
13539 "SvPV"
13541 "SvPVx"
13542 "SvPV_nomg"
13543 "SvPV_nolen"
13544 "SvPVx_nolen"
13545 "SvPV_nomg_nolen"
13546 "SvPV_mutable"
13547 "SvPV_const"
13548 "SvPVx_const"
13549 "SvPV_nolen_const"
13550 "SvPVx_nolen_const"
13551 "SvPV_nomg_const"
13552 "SvPV_nomg_const_nolen"
13553 "SvPV_flags"
13554 "SvPV_flags_const"
13555 "SvPV_flags_mutable"
13556 "SvPVbyte"
13557 "SvPVbyte_nomg"
13558 "SvPVbyte_nolen"
13559 "SvPVbytex_nolen"
13560 "SvPVbytex"
13561 "SvPVbyte_or_null"
13562 "SvPVbyte_or_null_nomg"
13563 "SvPVutf8"
13564 "SvPVutf8x"
13565 "SvPVutf8_nomg"
13566 "SvPVutf8_nolen"
13567 "SvPVutf8_or_null"
13568 "SvPVutf8_or_null_nomg"
13569 All these return a pointer to the string in "sv", or a stringified
13570 form of "sv" if it does not contain a string. The SV may cache the
13571 stringified version becoming "SvPOK".
13572 This is a very basic and common operation, so there are lots of
13574 slightly different versions of it.
13575 Note that there is no guarantee that the return value of
13577 "SvPV(sv)", for example, is equal to "SvPVX(sv)", or that
13578 "SvPVX(sv)" contains valid data, or that successive calls to
13579 "SvPV(sv)" (or another of these forms) will return the same pointer
13580 value each time. This is due to the way that things like
13581 overloading and Copy-On-Write are handled. In these cases, the
13582 return value may point to a temporary buffer or similar. If you
13583 absolutely need the "SvPVX" field to be valid (for example, if you
13584 intend to write to it), then see "SvPV_force".
13585 The differences between the forms are:
13587 The forms with neither "byte" nor "utf8" in their names (e.g.,
13589 "SvPV" or "SvPV_nolen") can expose the SV's internal string buffer.
13590 If that buffer consists entirely of bytes 0-255 and includes any
13591 bytes above 127, then you MUST consult "SvUTF8" to determine the
13592 actual code points the string is meant to contain. Generally
13593 speaking, it is probably safer to prefer "SvPVbyte", "SvPVutf8",
13594 and the like. See "How do I pass a Perl string to a C library?" in
13595 perlguts for more details.
13596 The forms with "flags" in their names allow you to use the "flags"
13598 parameter to specify to process 'get' magic (by setting the
13599 "SV_GMAGIC" flag) or to skip 'get' magic (by clearing it). The
13600 other forms process 'get' magic, except for the ones with "nomg" in
13601 their names, which skip 'get' magic.
13602 The forms that take a "len" parameter will set that variable to the
13604 byte length of the resultant string (these are macros, so don't use
13605 &len).
13606 The forms with "nolen" in their names indicate they don't have a
13608 "len" parameter. They should be used only when it is known that
13609 the PV is a C string, terminated by a NUL byte, and without
13610 intermediate NUL characters; or when you don't care about its
13611 length.
13612 The forms with "const" in their names return "const char *" so that
13614 the compiler will hopefully complain if you were to try to modify
13615 the contents of the string (unless you cast away const yourself).
13616 The other forms return a mutable pointer so that the string is
13618 modifiable by the caller; this is emphasized for the ones with
13619 "mutable" in their names.
13620 The forms whose name ends in "x" are the same as the corresponding
13622 form without the "x", but the "x" form is guaranteed to evaluate
13623 "sv" exactly once, with a slight loss of efficiency. Use this if
13624 "sv" is an expression with side effects.
13625 "SvPVutf8" is like "SvPV", but converts "sv" to UTF-8 first if not
13627 already UTF-8. Similiarly, the other forms with "utf8" in their
13628 names correspond to their respective forms without.
13629 "SvPVutf8_or_null" and "SvPVutf8_or_null_nomg" don't have
13631 corresponding non-"utf8" forms. Instead they are like
13632 "SvPVutf8_nomg", but when "sv" is undef, they return "NULL".
13633 "SvPVbyte" is like "SvPV", but converts "sv" to byte representation
13635 first if currently encoded as UTF-8. If "sv" cannot be downgraded
13636 from UTF-8, it croaks. Similiarly, the other forms with "byte" in
13637 their names correspond to their respective forms without.
13638 "SvPVbyte_or_null" doesn't have a corresponding non-"byte" form.
13640 Instead it is like "SvPVbyte", but when "sv" is undef, it returns
13641 "NULL".
13642 char* SvPV (SV* sv, STRLEN len)
13644 char* SvPVx (SV* sv, STRLEN len)
13645 char* SvPV_nomg (SV* sv, STRLEN len)
13646 char* SvPV_nolen (SV* sv)
13647 char* SvPVx_nolen (SV* sv)
13648 char* SvPV_nomg_nolen (SV* sv)
13649 char* SvPV_mutable (SV* sv, STRLEN len)
13650 const char* SvPV_const (SV* sv, STRLEN len)
13651 const char* SvPVx_const (SV* sv, STRLEN len)
13652 const char* SvPV_nolen_const (SV* sv)
13653 const char* SvPVx_nolen_const (SV* sv)
13654 const char* SvPV_nomg_const (SV* sv, STRLEN len)
13655 const char* SvPV_nomg_const_nolen(SV* sv)
13656 char * SvPV_flags (SV * sv, STRLEN len,
13657 U32 flags)
13658 const char * SvPV_flags_const (SV * sv, STRLEN len,
13659 U32 flags)
13660 char * SvPV_flags_mutable (SV * sv, STRLEN len,
13661 U32 flags)
13662 char* SvPVbyte (SV* sv, STRLEN len)
13663 char* SvPVbyte_nomg (SV* sv, STRLEN len)
13664 char* SvPVbyte_nolen (SV* sv)
13665 char* SvPVbytex_nolen (SV* sv)
13666 char* SvPVbytex (SV* sv, STRLEN len)
13667 char* SvPVbyte_or_null (SV* sv, STRLEN len)
13668 char* SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
13669 char* SvPVutf8 (SV* sv, STRLEN len)
13670 char* SvPVutf8x (SV* sv, STRLEN len)
13671 char* SvPVutf8_nomg (SV* sv, STRLEN len)
13672 char* SvPVutf8_nolen (SV* sv)
13673 char* SvPVutf8_or_null (SV* sv, STRLEN len)
13674 char* SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
13675 "SvPVCLEAR"
13677 Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is
13678 properly null terminated. Equivalent to sv_setpvs(""), but more
13679 efficient.
13680 char * SvPVCLEAR(SV* sv)
13682 "SvPV_force"
13684 "SvPV_force_nolen"
13685 "SvPVx_force"
13686 "SvPV_force_nomg"
13687 "SvPV_force_nomg_nolen"
13688 "SvPV_force_mutable"
13689 "SvPV_force_flags"
13690 "SvPV_force_flags_nolen"
13691 "SvPV_force_flags_mutable"
13692 "SvPVbyte_force"
13693 "SvPVbytex_force"
13694 "SvPVutf8_force"
13695 "SvPVutf8x_force"
13696 These are like "SvPV", returning the string in the SV, but will
13697 force the SV into containing a string ("SvPOK"), and only a string
13698 ("SvPOK_only"), by hook or by crook. You need to use one of these
13699 "force" routines if you are going to update the "SvPVX" directly.
13700 Note that coercing an arbitrary scalar into a plain PV will
13702 potentially strip useful data from it. For example if the SV was
13703 "SvROK", then the referent will have its reference count
13704 decremented, and the SV itself may be converted to an "SvPOK"
13705 scalar with a string buffer containing a value such as
13706 "ARRAY(0x1234)".
13707 The differences between the forms are:
13709 The forms with "flags" in their names allow you to use the "flags"
13711 parameter to specify to perform 'get' magic (by setting the
13712 "SV_GMAGIC" flag) or to skip 'get' magic (by clearing it). The
13713 other forms do perform 'get' magic, except for the ones with "nomg"
13714 in their names, which skip 'get' magic.
13715 The forms that take a "len" parameter will set that variable to the
13717 byte length of the resultant string (these are macros, so don't use
13718 &len).
13719 The forms with "nolen" in their names indicate they don't have a
13721 "len" parameter. They should be used only when it is known that
13722 the PV is a C string, terminated by a NUL byte, and without
13723 intermediate NUL characters; or when you don't care about its
13724 length.
13725 The forms with "mutable" in their names are effectively the same as
13727 those without, but the name emphasizes that the string is
13728 modifiable by the caller, which it is in all the forms.
13729 "SvPVutf8_force" is like "SvPV_force", but converts "sv" to UTF-8
13731 first if not already UTF-8.
13732 "SvPVutf8x_force" is like "SvPVutf8_force", but guarantees to
13734 evaluate "sv" only once; use the more efficient "SvPVutf8_force"
13735 otherwise.
13736 "SvPVbyte_force" is like "SvPV_force", but converts "sv" to byte
13738 representation first if currently encoded as UTF-8. If the SV
13739 cannot be downgraded from UTF-8, this croaks.
13740 "SvPVbytex_force" is like "SvPVbyte_force", but guarantees to
13742 evaluate "sv" only once; use the more efficient "SvPVbyte_force"
13743 otherwise.
13744 char* SvPV_force (SV* sv, STRLEN len)
13746 char* SvPV_force_nolen (SV* sv)
13747 char* SvPVx_force (SV* sv, STRLEN len)
13748 char* SvPV_force_nomg (SV* sv, STRLEN len)
13749 char* SvPV_force_nomg_nolen (SV * sv)
13750 char* SvPV_force_mutable (SV * sv, STRLEN len)
13751 char* SvPV_force_flags (SV * sv, STRLEN len, U32 flags)
13752 char* SvPV_force_flags_nolen (SV * sv, U32 flags)
13753 char* SvPV_force_flags_mutable(SV * sv, STRLEN len, U32 flags)
13754 char* SvPVbyte_force (SV* sv, STRLEN len)
13755 char* SvPVbytex_force (SV* sv, STRLEN len)
13756 char* SvPVutf8_force (SV* sv, STRLEN len)
13757 char* SvPVutf8x_force (SV* sv, STRLEN len)
13758 "SvPV_free"
13760 Frees the PV buffer in "sv", leaving things in a precarious state,
13761 so should only be used as part of a larger operation
13762 void SvPV_free(SV * sv)
13764 "sv_pvn_force_flags"
13766 Get a sensible string out of the SV somehow. If "flags" has the
13767 "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate, else
13768 not. "sv_pvn_force" and "sv_pvn_force_nomg" are implemented in
13769 terms of this function. You normally want to use the various
13770 wrapper macros instead: see "SvPV_force" and "SvPV_force_nomg".
13771 char* sv_pvn_force_flags(SV *const sv, STRLEN *const lp,
13773 const U32 flags)
13774 "SvPV_renew"
13776 Low level micro optimization of "SvGROW". It is generally better
13777 to use "SvGROW" instead. This is because "SvPV_renew" ignores
13778 potential issues that "SvGROW" handles. "sv" needs to have a real
13779 "PV" that is unencombered by things like COW. Using
13780 "SV_CHECK_THINKFIRST" or "SV_CHECK_THINKFIRST_COW_DROP" before
13781 calling this should clean it up, but why not just use "SvGROW" if
13782 you're not sure about the provenance?
13783 void SvPV_renew(SV* sv, STRLEN len)
13785 "SvPV_set"
13787 This is probably not what you want to use, you probably wanted
13788 "sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
13789 Set the value of the PV pointer in "sv" to the Perl allocated
13791 "NUL"-terminated string "val". See also "SvIV_set".
13792 Remember to free the previous PV buffer. There are many things to
13794 check. Beware that the existing pointer may be involved in copy-
13795 on-write or other mischief, so do "SvOOK_off(sv)" and use
13796 "sv_force_normal" or "SvPV_force" (or check the "SvIsCOW" flag)
13797 first to make sure this modification is safe. Then finally, if it
13798 is not a COW, call "SvPV_free" to free the previous PV buffer.
13799 void SvPV_set(SV* sv, char* val)
13801 "SvPVX"
13803 "SvPVXx"
13804 "SvPVX_const"
13805 "SvPVX_mutable"
13806 These return a pointer to the physical string in the SV. The SV
13807 must contain a string. Prior to 5.9.3 it is not safe to execute
13808 these unless the SV's type >= "SVt_PV".
13809 These are also used to store the name of an autoloaded subroutine
13811 in an XS AUTOLOAD routine. See "Autoloading with XSUBs" in
13812 perlguts.
13813 "SvPVXx" is identical to "SvPVX".
13815 "SvPVX_mutable" is merely a synonym for "SvPVX", but its name
13817 emphasizes that the string is modifiable by the caller.
13818 "SvPVX_const" differs in that the return value has been cast so
13820 that the compiler will complain if you were to try to modify the
13821 contents of the string, (unless you cast away const yourself).
13822 char* SvPVX (SV* sv)
13824 char* SvPVXx (SV* sv)
13825 const char* SvPVX_const (SV* sv)
13826 char* SvPVX_mutable(SV* sv)
13827 "SvPVXtrue"
13829 Note: This macro may evaluate "sv" more than once.
13830 Returns a boolean as to whether or not "sv" contains a PV that is
13832 considered TRUE. FALSE is returned if "sv" doesn't contain a PV,
13833 or if the PV it does contain is zero length, or consists of just
13834 the single character '0'. Every other PV value is considered TRUE.
13835 bool SvPVXtrue(SV * sv)
13837 "SvREADONLY"
13839 Returns true if the argument is readonly, otherwise returns false.
13840 Exposed to perl code via Internals::SvREADONLY().
13841 U32 SvREADONLY(SV* sv)
13843 "SvREADONLY_off"
13845 Mark an object as not-readonly. Exactly what this mean depends on
13846 the object type. Exposed to perl code via Internals::SvREADONLY().
13847 U32 SvREADONLY_off(SV* sv)
13849 "SvREADONLY_on"
13851 Mark an object as readonly. Exactly what this means depends on the
13852 object type. Exposed to perl code via Internals::SvREADONLY().
13853 U32 SvREADONLY_on(SV* sv)
13855 "sv_ref"
13857 Returns a SV describing what the SV passed in is a reference to.
13858 dst can be a SV to be set to the description or NULL, in which case
13860 a mortal SV is returned.
13861 If ob is true and the SV is blessed, the description is the class
13863 name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
13864 SV* sv_ref(SV *dst, const SV *const sv, const int ob)
13866 "SvREFCNT"
13868 Returns the value of the object's reference count. Exposed to perl
13869 code via Internals::SvREFCNT().
13870 U32 SvREFCNT(SV* sv)
13872 "SvREFCNT_dec"
13874 "SvREFCNT_dec_NN"
13875 These decrement the reference count of the given SV.
13876 "SvREFCNT_dec_NN" may only be used when "sv" is known to not be
13878 "NULL".
13879 void SvREFCNT_dec(SV *sv)
13881 "SvREFCNT_inc"
13883 "SvREFCNT_inc_NN"
13884 "SvREFCNT_inc_void"
13885 "SvREFCNT_inc_void_NN"
13886 "SvREFCNT_inc_simple"
13887 "SvREFCNT_inc_simple_NN"
13888 "SvREFCNT_inc_simple_void"
13889 "SvREFCNT_inc_simple_void_NN"
13890 These all increment the reference count of the given SV. The ones
13891 without "void" in their names return the SV.
13892 "SvREFCNT_inc" is the base operation; the rest are optimizations if
13894 various input constraints are known to be true; hence, all can be
13895 replaced with "SvREFCNT_inc".
13896 "SvREFCNT_inc_NN" can only be used if you know "sv" is not "NULL".
13898 Since we don't have to check the NULLness, it's faster and smaller.
13899 "SvREFCNT_inc_void" can only be used if you don't need the return
13901 value. The macro doesn't need to return a meaningful value.
13902 "SvREFCNT_inc_void_NN" can only be used if you both don't need the
13904 return value, and you know that "sv" is not "NULL". The macro
13905 doesn't need to return a meaningful value, or check for NULLness,
13906 so it's smaller and faster.
13907 "SvREFCNT_inc_simple" can only be used with expressions without
13909 side effects. Since we don't have to store a temporary value, it's
13910 faster.
13911 "SvREFCNT_inc_simple_NN" can only be used with expressions without
13913 side effects and you know "sv" is not "NULL". Since we don't have
13914 to store a temporary value, nor check for NULLness, it's faster and
13915 smaller.
13916 "SvREFCNT_inc_simple_void" can only be used with expressions
13918 without side effects and you don't need the return value.
13919 "SvREFCNT_inc_simple_void_NN" can only be used with expressions
13921 without side effects, you don't need the return value, and you know
13922 "sv" is not "NULL".
13923 SV * SvREFCNT_inc (SV *sv)
13925 SV * SvREFCNT_inc_NN (SV *sv)
13926 void SvREFCNT_inc_void (SV *sv)
13927 void SvREFCNT_inc_void_NN (SV* sv)
13928 SV* SvREFCNT_inc_simple (SV* sv)
13929 SV* SvREFCNT_inc_simple_NN (SV* sv)
13930 void SvREFCNT_inc_simple_void (SV* sv)
13931 void SvREFCNT_inc_simple_void_NN(SV* sv)
13932 "sv_reftype"
13934 Returns a string describing what the SV is a reference to.
13935 If ob is true and the SV is blessed, the string is the class name,
13937 otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
13938 const char* sv_reftype(const SV *const sv, const int ob)
13940 "sv_replace"
13942 Make the first argument a copy of the second, then delete the
13943 original. The target SV physically takes over ownership of the
13944 body of the source SV and inherits its flags; however, the target
13945 keeps any magic it owns, and any magic in the source is discarded.
13946 Note that this is a rather specialist SV copying operation; most of
13947 the time you'll want to use "sv_setsv" or one of its many macro
13948 front-ends.
13949 void sv_replace(SV *const sv, SV *const nsv)
13951 "sv_report_used"
13953 Dump the contents of all SVs not yet freed (debugging aid).
13954 void sv_report_used()
13956 "sv_reset"
13958 Underlying implementation for the "reset" Perl function. Note that
13959 the perl-level function is vaguely deprecated.
13960 void sv_reset(const char* s, HV *const stash)
13962 "SvROK"
13964 Tests if the SV is an RV.
13965 U32 SvROK(SV* sv)
13967 "SvROK_off"
13969 Unsets the RV status of an SV.
13970 void SvROK_off(SV* sv)
13972 "SvROK_on"
13974 Tells an SV that it is an RV.
13975 void SvROK_on(SV* sv)
13977 "SvRV"
13979 Dereferences an RV to return the SV.
13980 SV* SvRV(SV* sv)
13982 "SvRV_set"
13984 Set the value of the RV pointer in "sv" to val. See "SvIV_set".
13985 void SvRV_set(SV* sv, SV* val)
13987 "sv_rvunweaken"
13989 Unweaken a reference: Clear the "SvWEAKREF" flag on this RV; remove
13990 the backreference to this RV from the array of backreferences
13991 associated with the target SV, increment the refcount of the
13992 target. Silently ignores "undef" and warns on non-weak references.
13993 SV* sv_rvunweaken(SV *const sv)
13995 "sv_rvweaken"
13997 Weaken a reference: set the "SvWEAKREF" flag on this RV; give the
13998 referred-to SV "PERL_MAGIC_backref" magic if it hasn't already; and
13999 push a back-reference to this RV onto the array of backreferences
14000 associated with that magic. If the RV is magical, set magic will
14001 be called after the RV is cleared. Silently ignores "undef" and
14002 warns on already-weak references.
14003 SV* sv_rvweaken(SV *const sv)
14005 "sv_setbool"
14007 "sv_setbool_mg"
14008 These set an SV to a true or false boolean value, upgrading first
14009 if necessary.
14010 They differ only in that "sv_setbool_mg" handles 'set' magic;
14012 "sv_setbool" does not.
14013 void sv_setbool(SV *sv, bool b)
14015 "sv_setiv"
14017 "sv_setiv_mg"
14018 These copy an integer into the given SV, upgrading first if
14019 necessary.
14020 They differ only in that "sv_setiv_mg" handles 'set' magic;
14022 "sv_setiv" does not.
14023 void sv_setiv (SV *const sv, const IV num)
14025 void sv_setiv_mg(SV *const sv, const IV i)
14026 "SvSETMAGIC"
14028 Invokes "mg_set" on an SV if it has 'set' magic. This is necessary
14029 after modifying a scalar, in case it is a magical variable like $|
14030 or a tied variable (it calls "STORE"). This macro evaluates its
14031 argument more than once.
14032 void SvSETMAGIC(SV* sv)
14034 "sv_setnv"
14036 "sv_setnv_mg"
14037 These copy a double into the given SV, upgrading first if
14038 necessary.
14039 They differ only in that "sv_setnv_mg" handles 'set' magic;
14041 "sv_setnv" does not.
14042 void sv_setnv(SV *const sv, const NV num)
14044 "sv_setpv"
14046 "sv_setpv_mg"
14047 "sv_setpvn"
14048 "sv_setpvn_fresh"
14049 "sv_setpvn_mg"
14050 "sv_setpvs"
14051 "sv_setpvs_mg"
14052 These copy a string into the SV "sv", making sure it is
14053 "SvPOK_only".
14054 In the "pvs" forms, the string must be a C literal string, enclosed
14056 in double quotes.
14057 In the "pvn" forms, the first byte of the string is pointed to by
14059 "ptr", and "len" indicates the number of bytes to be copied,
14060 potentially including embedded "NUL" characters.
14061 In the plain "pv" forms, "ptr" points to a NUL-terminated C string.
14063 That is, it points to the first byte of the string, and the copy
14064 proceeds up through the first enountered "NUL" byte.
14065 In the forms that take a "ptr" argument, if it is NULL, the SV will
14067 become undefined.
14068 The UTF-8 flag is not changed by these functions. A terminating
14070 NUL byte is guaranteed in the result.
14071 The "_mg" forms handle 'set' magic; the other forms skip all magic.
14073 "sv_setpvn_fresh" is a cut-down alternative to "sv_setpvn",
14075 intended ONLY to be used with a fresh sv that has been upgraded to
14076 a SVt_PV, SVt_PVIV, SVt_PVNV, or SVt_PVMG.
14077 void sv_setpv (SV *const sv, const char *const ptr)
14079 void sv_setpv_mg (SV *const sv, const char *const ptr)
14080 void sv_setpvn (SV *const sv, const char *const ptr,
14081 const STRLEN len)
14082 void sv_setpvn_fresh(SV *const sv, const char *const ptr,
14083 const STRLEN len)
14084 void sv_setpvn_mg (SV *const sv, const char *const ptr,
14085 const STRLEN len)
14086 void sv_setpvs (SV* sv, "literal string")
14087 void sv_setpvs_mg (SV* sv, "literal string")
14088 "sv_setpvf"
14090 "sv_setpvf_nocontext"
14091 "sv_setpvf_mg"
14092 "sv_setpvf_mg_nocontext"
14093 These work like "sv_catpvf" but copy the text into the SV instead
14094 of appending it.
14095 The differences between these are:
14097 "sv_setpvf_mg" and "sv_setpvf_mg_nocontext" perform 'set' magic;
14099 "sv_setpvf" and "sv_setpvf_nocontext" skip all magic.
14100 "sv_setpvf_nocontext" and "sv_setpvf_mg_nocontext" do not take a
14102 thread context ("aTHX") parameter, so are used in situations where
14103 the caller doesn't already have the thread context.
14104 NOTE: "sv_setpvf" must be explicitly called as "Perl_sv_setpvf"
14106 with an "aTHX_" parameter.
14107 NOTE: "sv_setpvf_mg" must be explicitly called as
14109 "Perl_sv_setpvf_mg" with an "aTHX_" parameter.
14110 void Perl_sv_setpvf (pTHX_ SV *const sv,
14112 const char *const pat, ...)
14113 void sv_setpvf_nocontext (SV *const sv, const char *const pat,
14114 ...)
14115 void Perl_sv_setpvf_mg (pTHX_ SV *const sv,
14116 const char *const pat, ...)
14117 void sv_setpvf_mg_nocontext(SV *const sv, const char *const pat,
14118 ...)
14119 "sv_setpviv"
14121 "sv_setpviv_mg"
14122 "DEPRECATED!" It is planned to remove both forms from a future
14123 release of Perl. Do not use them for new code; remove them from
14124 existing code.
14125 These copy an integer into the given SV, also updating its string
14127 value.
14128 They differ only in that "sv_setpviv_mg" performs 'set' magic;
14130 "sv_setpviv" skips any magic.
14131 void sv_setpviv (SV *const sv, const IV num)
14133 void sv_setpviv_mg(SV *const sv, const IV iv)
14134 "sv_setpv_bufsize"
14136 Sets the SV to be a string of cur bytes length, with at least len
14137 bytes available. Ensures that there is a null byte at SvEND.
14138 Returns a char * pointer to the SvPV buffer.
14139 char * sv_setpv_bufsize(SV *const sv, const STRLEN cur,
14141 const STRLEN len)
14142 "sv_setref_iv"
14144 Copies an integer into a new SV, optionally blessing the SV. The
14145 "rv" argument will be upgraded to an RV. That RV will be modified
14146 to point to the new SV. The "classname" argument indicates the
14147 package for the blessing. Set "classname" to "NULL" to avoid the
14148 blessing. The new SV will have a reference count of 1, and the RV
14149 will be returned.
14150 SV* sv_setref_iv(SV *const rv, const char *const classname,
14152 const IV iv)
14153 "sv_setref_nv"
14155 Copies a double into a new SV, optionally blessing the SV. The
14156 "rv" argument will be upgraded to an RV. That RV will be modified
14157 to point to the new SV. The "classname" argument indicates the
14158 package for the blessing. Set "classname" to "NULL" to avoid the
14159 blessing. The new SV will have a reference count of 1, and the RV
14160 will be returned.
14161 SV* sv_setref_nv(SV *const rv, const char *const classname,
14163 const NV nv)
14164 "sv_setref_pv"
14166 Copies a pointer into a new SV, optionally blessing the SV. The
14167 "rv" argument will be upgraded to an RV. That RV will be modified
14168 to point to the new SV. If the "pv" argument is "NULL", then
14169 "PL_sv_undef" will be placed into the SV. The "classname" argument
14170 indicates the package for the blessing. Set "classname" to "NULL"
14171 to avoid the blessing. The new SV will have a reference count of
14172 1, and the RV will be returned.
14173 Do not use with other Perl types such as HV, AV, SV, CV, because
14175 those objects will become corrupted by the pointer copy process.
14176 Note that "sv_setref_pvn" copies the string while this copies the
14178 pointer.
14179 SV* sv_setref_pv(SV *const rv, const char *const classname,
14181 void *const pv)
14182 "sv_setref_pvn"
14184 Copies a string into a new SV, optionally blessing the SV. The
14185 length of the string must be specified with "n". The "rv" argument
14186 will be upgraded to an RV. That RV will be modified to point to
14187 the new SV. The "classname" argument indicates the package for the
14188 blessing. Set "classname" to "NULL" to avoid the blessing. The
14189 new SV will have a reference count of 1, and the RV will be
14190 returned.
14191 Note that "sv_setref_pv" copies the pointer while this copies the
14193 string.
14194 SV* sv_setref_pvn(SV *const rv, const char *const classname,
14196 const char *const pv, const STRLEN n)
14197 "sv_setref_pvs"
14199 Like "sv_setref_pvn", but takes a literal string instead of a
14200 string/length pair.
14201 SV * sv_setref_pvs(SV *const rv, const char *const classname,
14203 "literal string")
14204 "sv_setref_uv"
14206 Copies an unsigned integer into a new SV, optionally blessing the
14207 SV. The "rv" argument will be upgraded to an RV. That RV will be
14208 modified to point to the new SV. The "classname" argument
14209 indicates the package for the blessing. Set "classname" to "NULL"
14210 to avoid the blessing. The new SV will have a reference count of
14211 1, and the RV will be returned.
14212 SV* sv_setref_uv(SV *const rv, const char *const classname,
14214 const UV uv)
14215 "sv_setrv_inc"
14217 "sv_setrv_inc_mg"
14218 As "sv_setrv_noinc" but increments the reference count of ref.
14219 "sv_setrv_inc_mg" will invoke 'set' magic on the SV; "sv_setrv_inc"
14221 will not.
14222 void sv_setrv_inc(SV *const sv, SV *const ref)
14224 "sv_setrv_noinc"
14226 "sv_setrv_noinc_mg"
14227 Copies an SV pointer into the given SV as an SV reference,
14228 upgrading it if necessary. After this, "SvRV(sv)" is equal to ref.
14229 This does not adjust the reference count of ref. The reference ref
14230 must not be NULL.
14231 "sv_setrv_noinc_mg" will invoke 'set' magic on the SV;
14233 "sv_setrv_noinc" will not.
14234 void sv_setrv_noinc(SV *const sv, SV *const ref)
14236 "SvSetSV"
14238 "SvSetMagicSV"
14239 "SvSetSV_nosteal"
14240 "SvSetMagicSV_nosteal"
14241 if "dsv" is the same as "ssv", these do nothing. Otherwise they
14242 all call some form of "sv_setsv". They may evaluate their
14243 arguments more than once.
14244 The only differences are:
14246 "SvSetMagicSV" and "SvSetMagicSV_nosteal" perform any required
14248 'set' magic afterwards on the destination SV; "SvSetSV" and
14249 "SvSetSV_nosteal" do not.
14250 "SvSetSV_nosteal" "SvSetMagicSV_nosteal" call a non-destructive
14252 version of "sv_setsv".
14253 void SvSetSV(SV* dsv, SV* ssv)
14255 "sv_setsv"
14257 "sv_setsv_flags"
14258 "sv_setsv_mg"
14259 "sv_setsv_nomg"
14260 These copy the contents of the source SV "ssv" into the destination
14261 SV "dsv". "ssv" may be destroyed if it is mortal, so don't use
14262 these functions if the source SV needs to be reused. Loosely
14263 speaking, they perform a copy-by-value, obliterating any previous
14264 content of the destination.
14265 They differ only in that:
14267 "sv_setsv" calls 'get' magic on "ssv", but skips 'set' magic on
14269 "dsv".
14270 "sv_setsv_mg" calls both 'get' magic on "ssv" and 'set' magic on
14272 "dsv".
14273 "sv_setsv_nomg" skips all magic.
14275 "sv_setsv_flags" has a "flags" parameter which you can use to
14277 specify any combination of magic handling, and also you can specify
14278 "SV_NOSTEAL" so that the buffers of temps will not be stolen.
14279 You probably want to instead use one of the assortment of wrappers,
14281 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
14282 "SvSetMagicSV_nosteal".
14283 "sv_setsv_flags" is the primary function for copying scalars, and
14285 most other copy-ish functions and macros use it underneath.
14286 void sv_setsv (SV *dsv, SV *ssv)
14288 void sv_setsv_flags(SV *dsv, SV *ssv, const I32 flags)
14289 void sv_setsv_mg (SV *const dsv, SV *const ssv)
14290 void sv_setsv_nomg (SV *dsv, SV *ssv)
14291 "sv_setuv"
14293 "sv_setuv_mg"
14294 These copy an unsigned integer into the given SV, upgrading first
14295 if necessary.
14296 They differ only in that "sv_setuv_mg" handles 'set' magic;
14298 "sv_setuv" does not.
14299 void sv_setuv (SV *const sv, const UV num)
14301 void sv_setuv_mg(SV *const sv, const UV u)
14302 "sv_set_undef"
14304 Equivalent to "sv_setsv(sv, &PL_sv_undef)", but more efficient.
14305 Doesn't handle set magic.
14306 The perl equivalent is "$sv = undef;". Note that it doesn't free
14308 any string buffer, unlike "undef $sv".
14309 Introduced in perl 5.25.12.
14311 void sv_set_undef(SV *sv)
14313 "SvSHARE"
14315 Arranges for "sv" to be shared between threads if a suitable module
14316 has been loaded.
14317 void SvSHARE(SV* sv)
14319 "SvSHARED_HASH"
14321 Returns the hash for "sv" created by "newSVpvn_share".
14322 struct hek* SvSHARED_HASH(SV * sv)
14324 "SvSTASH"
14326 Returns the stash of the SV.
14327 HV* SvSTASH(SV* sv)
14329 "SvSTASH_set"
14331 Set the value of the STASH pointer in "sv" to val. See "SvIV_set".
14332 void SvSTASH_set(SV* sv, HV* val)
14334 "sv_streq"
14336 A convenient shortcut for calling "sv_streq_flags" with the
14337 "SV_GMAGIC" flag. This function basically behaves like the Perl
14338 code "$sv1 eq $sv2".
14339 bool sv_streq(SV* sv1, SV* sv2)
14341 "sv_streq_flags"
14343 Returns a boolean indicating whether the strings in the two SVs are
14344 identical. If the flags argument has the "SV_GMAGIC" bit set, it
14345 handles get-magic too. Will coerce its args to strings if
14346 necessary. Treats "NULL" as undef. Correctly handles the UTF8 flag.
14347 If flags does not have the "SV_SKIP_OVERLOAD" bit set, an attempt
14349 to use "eq" overloading will be made. If such overloading does not
14350 exist or the flag is set, then regular string comparison will be
14351 used instead.
14352 bool sv_streq_flags(SV* sv1, SV* sv2, const U32 flags)
14354 "SvTRUE"
14356 "SvTRUEx"
14357 "SvTRUE_nomg"
14358 "SvTRUE_NN"
14359 "SvTRUE_nomg_NN"
14360 These return a boolean indicating whether Perl would evaluate the
14361 SV as true or false. See "SvOK" for a defined/undefined test.
14362 As of Perl 5.32, all are guaranteed to evaluate "sv" only once.
14364 Prior to that release, only "SvTRUEx" guaranteed single evaluation;
14365 now "SvTRUEx" is identical to "SvTRUE".
14366 "SvTRUE_nomg" and "TRUE_nomg_NN" do not perform 'get' magic; the
14368 others do unless the scalar is already "SvPOK", "SvIOK", or "SvNOK"
14369 (the public, not the private flags).
14370 "SvTRUE_NN" is like "SvTRUE", but "sv" is assumed to be non-null
14372 (NN). If there is a possibility that it is NULL, use plain
14373 "SvTRUE".
14374 "SvTRUE_nomg_NN" is like "SvTRUE_nomg", but "sv" is assumed to be
14376 non-null (NN). If there is a possibility that it is NULL, use
14377 plain "SvTRUE_nomg".
14378 bool SvTRUE(SV *sv)
14380 "SvTYPE"
14382 Returns the type of the SV. See "svtype".
14383 svtype SvTYPE(SV* sv)
14385 "SvUNLOCK"
14387 Releases a mutual exclusion lock on "sv" if a suitable module has
14388 been loaded.
14389 void SvUNLOCK(SV* sv)
14391 "sv_unmagic"
14393 Removes all magic of type "type" from an SV.
14394 int sv_unmagic(SV *const sv, const int type)
14396 "sv_unmagicext"
14398 Removes all magic of type "type" with the specified "vtbl" from an
14399 SV.
14400 int sv_unmagicext(SV *const sv, const int type, MGVTBL *vtbl)
14402 "sv_unref"
14404 Unsets the RV status of the SV, and decrements the reference count
14405 of whatever was being referenced by the RV. This can almost be
14406 thought of as a reversal of "newSVrv". This is "sv_unref_flags"
14407 with the "flag" being zero. See "SvROK_off".
14408 void sv_unref(SV* sv)
14410 "sv_unref_flags"
14412 Unsets the RV status of the SV, and decrements the reference count
14413 of whatever was being referenced by the RV. This can almost be
14414 thought of as a reversal of "newSVrv". The "cflags" argument can
14415 contain "SV_IMMEDIATE_UNREF" to force the reference count to be
14416 decremented (otherwise the decrementing is conditional on the
14417 reference count being different from one or the reference being a
14418 readonly SV). See "SvROK_off".
14419 void sv_unref_flags(SV *const ref, const U32 flags)
14421 "SvUOK"
14423 Returns a boolean indicating whether the SV contains an integer
14424 that must be interpreted as unsigned. A non-negative integer whose
14425 value is within the range of both an IV and a UV may be flagged as
14426 either "SvUOK" or "SvIOK".
14427 bool SvUOK(SV* sv)
14429 "SvUPGRADE"
14431 Used to upgrade an SV to a more complex form. Uses "sv_upgrade" to
14432 perform the upgrade if necessary. See "svtype".
14433 void SvUPGRADE(SV* sv, svtype type)
14435 "sv_upgrade"
14437 Upgrade an SV to a more complex form. Generally adds a new body
14438 type to the SV, then copies across as much information as possible
14439 from the old body. It croaks if the SV is already in a more
14440 complex form than requested. You generally want to use the
14441 "SvUPGRADE" macro wrapper, which checks the type before calling
14442 "sv_upgrade", and hence does not croak. See also "svtype".
14443 void sv_upgrade(SV *const sv, svtype new_type)
14445 "sv_usepvn"
14447 "sv_usepvn_mg"
14448 "sv_usepvn_flags"
14449 These tell an SV to use "ptr" for its string value. Normally SVs
14450 have their string stored inside the SV, but these tell the SV to
14451 use an external string instead.
14452 "ptr" should point to memory that was allocated by ""Newx"". It
14454 must be the start of a "Newx"-ed block of memory, and not a pointer
14455 to the middle of it (beware of "OOK" and copy-on-write), and not be
14456 from a non-"Newx" memory allocator like "malloc". The string
14457 length, "len", must be supplied. By default this function will
14458 ""Renew"" (i.e. realloc, move) the memory pointed to by "ptr", so
14459 that the pointer should not be freed or used by the programmer
14460 after giving it to "sv_usepvn", and neither should any pointers
14461 from "behind" that pointer (e.g., "ptr" + 1) be used.
14462 In the "sv_usepvn_flags" form, if "flags & SV_SMAGIC" is true,
14464 "SvSETMAGIC" is called before returning. And if
14465 "flags & SV_HAS_TRAILING_NUL" is true, then "ptr[len]" must be
14466 "NUL", and the realloc will be skipped (i.e., the buffer is
14467 actually at least 1 byte longer than "len", and already meets the
14468 requirements for storing in "SvPVX").
14469 "sv_usepvn" is merely "sv_usepvn_flags" with "flags" set to 0, so
14471 'set' magic is skipped.
14472 "sv_usepvn_mg" is merely "sv_usepvn_flags" with "flags" set to
14474 "SV_SMAGIC", so 'set' magic is performed.
14475 void sv_usepvn (SV* sv, char* ptr, STRLEN len)
14477 void sv_usepvn_mg (SV *sv, char *ptr, STRLEN len)
14478 void sv_usepvn_flags(SV *const sv, char* ptr, const STRLEN len,
14479 const U32 flags)
14480 "SvUTF8"
14482 Returns a U32 value indicating the UTF-8 status of an SV. If
14483 things are set-up properly, this indicates whether or not the SV
14484 contains UTF-8 encoded data. You should use this after a call to
14485 "SvPV" or one of its variants, in case any call to string
14486 overloading updates the internal flag.
14487 If you want to take into account the bytes pragma, use "DO_UTF8"
14489 instead.
14490 U32 SvUTF8(SV* sv)
14492 "sv_utf8_decode"
14494 If the PV of the SV is an octet sequence in Perl's extended UTF-8
14495 and contains a multiple-byte character, the "SvUTF8" flag is turned
14496 on so that it looks like a character. If the PV contains only
14497 single-byte characters, the "SvUTF8" flag stays off. Scans PV for
14498 validity and returns FALSE if the PV is invalid UTF-8.
14499 bool sv_utf8_decode(SV *const sv)
14501 "sv_utf8_downgrade"
14503 "sv_utf8_downgrade_flags"
14504 "sv_utf8_downgrade_nomg"
14505 These attempt to convert the PV of an SV from characters to bytes.
14506 If the PV contains a character that cannot fit in a byte, this
14507 conversion will fail; in this case, "FALSE" is returned if
14508 "fail_ok" is true; otherwise they croak.
14509 They are not a general purpose Unicode to byte encoding interface:
14511 use the "Encode" extension for that.
14512 They differ only in that:
14514 "sv_utf8_downgrade" processes 'get' magic on "sv".
14516 "sv_utf8_downgrade_nomg" does not.
14518 "sv_utf8_downgrade_flags" has an additional "flags" parameter in
14520 which you can specify "SV_GMAGIC" to process 'get' magic, or leave
14521 it cleared to not process 'get' magic.
14522 bool sv_utf8_downgrade (SV *const sv, const bool fail_ok)
14524 bool sv_utf8_downgrade_flags(SV *const sv, const bool fail_ok,
14525 const U32 flags)
14526 bool sv_utf8_downgrade_nomg (SV *const sv, const bool fail_ok)
14527 "sv_utf8_encode"
14529 Converts the PV of an SV to UTF-8, but then turns the "SvUTF8" flag
14530 off so that it looks like octets again.
14531 void sv_utf8_encode(SV *const sv)
14533 "sv_utf8_upgrade"
14535 "sv_utf8_upgrade_nomg"
14536 "sv_utf8_upgrade_flags"
14537 "sv_utf8_upgrade_flags_grow"
14538 These convert the PV of an SV to its UTF-8-encoded form. The SV is
14539 forced to string form if it is not already. They always set the
14540 "SvUTF8" flag to avoid future validity checks even if the whole
14541 string is the same in UTF-8 as not. They return the number of
14542 bytes in the converted string
14543 The forms differ in just two ways. The main difference is whether
14545 or not they perform 'get magic' on "sv". "sv_utf8_upgrade_nomg"
14546 skips 'get magic'; "sv_utf8_upgrade" performs it; and
14547 "sv_utf8_upgrade_flags" and "sv_utf8_upgrade_flags_grow" either
14548 perform it (if the "SV_GMAGIC" bit is set in "flags") or don't (if
14549 that bit is cleared).
14550 The other difference is that "sv_utf8_upgrade_flags_grow" has an
14552 additional parameter, "extra", which allows the caller to specify
14553 an amount of space to be reserved as spare beyond what is needed
14554 for the actual conversion. This is used when the caller knows it
14555 will soon be needing yet more space, and it is more efficient to
14556 request space from the system in a single call. This form is
14557 otherwise identical to "sv_utf8_upgrade_flags".
14558 These are not a general purpose byte encoding to Unicode interface:
14560 use the Encode extension for that.
14561 The "SV_FORCE_UTF8_UPGRADE" flag is now ignored.
14563 STRLEN sv_utf8_upgrade (SV *sv)
14565 STRLEN sv_utf8_upgrade_nomg (SV *sv)
14566 STRLEN sv_utf8_upgrade_flags (SV *const sv, const I32 flags)
14567 STRLEN sv_utf8_upgrade_flags_grow(SV *const sv, const I32 flags,
14568 STRLEN extra)
14569 "SvUTF8_off"
14571 Unsets the UTF-8 status of an SV (the data is not changed, just the
14572 flag). Do not use frivolously.
14573 void SvUTF8_off(SV *sv)
14575 "SvUTF8_on"
14577 Turn on the UTF-8 status of an SV (the data is not changed, just
14578 the flag). Do not use frivolously.
14579 void SvUTF8_on(SV *sv)
14581 "SvUV"
14583 "SvUVx"
14584 "SvUV_nomg"
14585 These coerce the given SV to UV and return it. The returned value
14586 in many circumstances will get stored in "sv"'s UV slot, but not in
14587 all cases. (Use "sv_setuv" to make sure it does).
14588 "SvUVx" is different from the others in that it is guaranteed to
14590 evaluate "sv" exactly once; the others may evaluate it multiple
14591 times. Only use this form if "sv" is an expression with side
14592 effects, otherwise use the more efficient "SvUV".
14593 "SvUV_nomg" is the same as "SvUV", but does not perform 'get'
14595 magic.
14596 UV SvUV(SV* sv)
14598 "SvUV_set"
14600 Set the value of the UV pointer in "sv" to val. See "SvIV_set".
14601 void SvUV_set(SV* sv, UV val)
14603 "SvUVX"
14605 Returns the raw value in the SV's UV slot, without checks or
14606 conversions. Only use when you are sure "SvIOK" is true. See also
14607 "SvUV".
14608 UV SvUVX(SV* sv)
14610 "SvUVXx"
14612 "DEPRECATED!" It is planned to remove "SvUVXx" from a future
14613 release of Perl. Do not use it for new code; remove it from
14614 existing code.
14615 This is an unnecessary synonym for "SvUVX"
14617 UV SvUVXx(SV* sv)
14619 "sv_vcatpvf"
14621 "sv_vcatpvf_mg"
14622 These process their arguments like "sv_vcatpvfn" called with a non-
14623 null C-style variable argument list, and append the formatted
14624 output to "sv".
14625 They differ only in that "sv_vcatpvf_mg" performs 'set' magic;
14627 "sv_vcatpvf" skips 'set' magic.
14628 Both perform 'get' magic.
14630 They are usually accessed via their frontends "sv_catpvf" and
14632 "sv_catpvf_mg".
14633 void sv_vcatpvf(SV *const sv, const char *const pat,
14635 va_list *const args)
14636 "sv_vcatpvfn"
14638 "sv_vcatpvfn_flags"
14639 These process their arguments like vsprintf(3) and append the
14640 formatted output to an SV. They use an array of SVs if the C-style
14641 variable argument list is missing ("NULL"). Argument reordering
14642 (using format specifiers like "%2$d" or "%*2$d") is supported only
14643 when using an array of SVs; using a C-style "va_list" argument list
14644 with a format string that uses argument reordering will yield an
14645 exception.
14646 When running with taint checks enabled, they indicate via
14648 "maybe_tainted" if results are untrustworthy (often due to the use
14649 of locales).
14650 They assume that "pat" has the same utf8-ness as "sv". It's the
14652 caller's responsibility to ensure that this is so.
14653 They differ in that "sv_vcatpvfn_flags" has a "flags" parameter in
14655 which you can set or clear the "SV_GMAGIC" and/or SV_SMAGIC flags,
14656 to specify which magic to handle or not handle; whereas plain
14657 "sv_vcatpvfn" always specifies both 'get' and 'set' magic.
14658 They are usually used via one of the frontends ""sv_vcatpvf"" and
14660 ""sv_vcatpvf_mg"".
14661 void sv_vcatpvfn (SV *const sv, const char *const pat,
14663 const STRLEN patlen, va_list *const args,
14664 SV **const svargs, const Size_t sv_count,
14665 bool *const maybe_tainted)
14666 void sv_vcatpvfn_flags(SV *const sv, const char *const pat,
14667 const STRLEN patlen, va_list *const args,
14668 SV **const svargs, const Size_t sv_count,
14669 bool *const maybe_tainted,
14670 const U32 flags)
14671 "SvVOK"
14673 Returns a boolean indicating whether the SV contains a v-string.
14674 bool SvVOK(SV* sv)
14676 "sv_vsetpvf"
14678 "sv_vsetpvf_mg"
14679 These work like "sv_vcatpvf" but copy the text into the SV instead
14680 of appending it.
14681 They differ only in that "sv_vsetpvf_mg" performs 'set' magic;
14683 "sv_vsetpvf" skips all magic.
14684 They are usually used via their frontends, "sv_setpvf" and
14686 "sv_setpvf_mg".
14687 void sv_vsetpvf(SV *const sv, const char *const pat,
14689 va_list *const args)
14690 "sv_vsetpvfn"
14692 Works like "sv_vcatpvfn" but copies the text into the SV instead of
14693 appending it.
14694 Usually used via one of its frontends ""sv_vsetpvf"" and
14696 ""sv_vsetpvf_mg"".
14697 void sv_vsetpvfn(SV *const sv, const char *const pat,
14699 const STRLEN patlen, va_list *const args,
14700 SV **const svargs, const Size_t sv_count,
14701 bool *const maybe_tainted)
14702 "SvVSTRING_mg"
14704 Returns the vstring magic, or NULL if none
14705 MAGIC* SvVSTRING_mg(SV * sv)
14707 "vnewSVpvf"
14709 Like "newSVpvf" but the arguments are an encapsulated argument
14710 list.
14711 SV* vnewSVpvf(const char *const pat, va_list *const args)
14713
14715 "SvTAINT"
14716 Taints an SV if tainting is enabled, and if some input to the
14717 current expression is tainted--usually a variable, but possibly
14718 also implicit inputs such as locale settings. "SvTAINT" propagates
14719 that taintedness to the outputs of an expression in a pessimistic
14720 fashion; i.e., without paying attention to precisely which outputs
14721 are influenced by which inputs.
14722 void SvTAINT(SV* sv)
14724 "SvTAINTED"
14726 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
14727 not.
14728 bool SvTAINTED(SV* sv)
14730 "SvTAINTED_off"
14732 Untaints an SV. Be very careful with this routine, as it short-
14733 circuits some of Perl's fundamental security features. XS module
14734 authors should not use this function unless they fully understand
14735 all the implications of unconditionally untainting the value.
14736 Untainting should be done in the standard perl fashion, via a
14737 carefully crafted regexp, rather than directly untainting
14738 variables.
14739 void SvTAINTED_off(SV* sv)
14741 "SvTAINTED_on"
14743 Marks an SV as tainted if tainting is enabled.
14744 void SvTAINTED_on(SV* sv)
14746
14748 "ASCTIME_R_PROTO"
14749 This symbol encodes the prototype of "asctime_r". It is zero if
14750 "d_asctime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
14751 macros of reentr.h if "d_asctime_r" is defined.
14752 "CTIME_R_PROTO"
14754 This symbol encodes the prototype of "ctime_r". It is zero if
14755 "d_ctime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC" macros
14756 of reentr.h if "d_ctime_r" is defined.
14757 "GMTIME_MAX"
14759 This symbol contains the maximum value for the "time_t" offset that
14760 the system function gmtime () accepts, and defaults to 0
14761 "GMTIME_MIN"
14763 This symbol contains the minimum value for the "time_t" offset that
14764 the system function gmtime () accepts, and defaults to 0
14765 "GMTIME_R_PROTO"
14767 This symbol encodes the prototype of "gmtime_r". It is zero if
14768 "d_gmtime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
14769 macros of reentr.h if "d_gmtime_r" is defined.
14770 "HAS_ASCTIME64"
14772 This symbol, if defined, indicates that the "asctime64" () routine
14773 is available to do the 64bit variant of asctime ()
14774 "HAS_ASCTIME_R"
14776 This symbol, if defined, indicates that the "asctime_r" routine is
14777 available to asctime re-entrantly.
14778 "HAS_CTIME64"
14780 This symbol, if defined, indicates that the "ctime64" () routine is
14781 available to do the 64bit variant of ctime ()
14782 "HAS_CTIME_R"
14784 This symbol, if defined, indicates that the "ctime_r" routine is
14785 available to ctime re-entrantly.
14786 "HAS_DIFFTIME"
14788 This symbol, if defined, indicates that the "difftime" routine is
14789 available.
14790 "HAS_DIFFTIME64"
14792 This symbol, if defined, indicates that the "difftime64" () routine
14793 is available to do the 64bit variant of difftime ()
14794 "HAS_FUTIMES"
14796 This symbol, if defined, indicates that the "futimes" routine is
14797 available to change file descriptor time stamps with "struct
14798 timevals".
14799 "HAS_GETITIMER"
14801 This symbol, if defined, indicates that the "getitimer" routine is
14802 available to return interval timers.
14803 "HAS_GETTIMEOFDAY"
14805 This symbol, if defined, indicates that the "gettimeofday()" system
14806 call is available for a sub-second accuracy clock. Usually, the
14807 file sys/resource.h needs to be included (see "I_SYS_RESOURCE").
14808 The type "Timeval" should be used to refer to ""struct timeval"".
14809 "HAS_GMTIME64"
14811 This symbol, if defined, indicates that the "gmtime64" () routine
14812 is available to do the 64bit variant of gmtime ()
14813 "HAS_GMTIME_R"
14815 This symbol, if defined, indicates that the "gmtime_r" routine is
14816 available to gmtime re-entrantly.
14817 "HAS_LOCALTIME64"
14819 This symbol, if defined, indicates that the "localtime64" ()
14820 routine is available to do the 64bit variant of localtime ()
14821 "HAS_LOCALTIME_R"
14823 This symbol, if defined, indicates that the "localtime_r" routine
14824 is available to localtime re-entrantly.
14825 "HAS_MKTIME"
14827 This symbol, if defined, indicates that the "mktime" routine is
14828 available.
14829 "HAS_MKTIME64"
14831 This symbol, if defined, indicates that the "mktime64" () routine
14832 is available to do the 64bit variant of mktime ()
14833 "HAS_NANOSLEEP"
14835 This symbol, if defined, indicates that the "nanosleep" system call
14836 is available to sleep with 1E-9 sec accuracy.
14837 "HAS_SETITIMER"
14839 This symbol, if defined, indicates that the "setitimer" routine is
14840 available to set interval timers.
14841 "HAS_STRFTIME"
14843 This symbol, if defined, indicates that the "strftime" routine is
14844 available to do time formatting.
14845 "HAS_TIME"
14847 This symbol, if defined, indicates that the "time()" routine
14848 exists.
14849 "HAS_TIMEGM"
14851 This symbol, if defined, indicates that the "timegm" routine is
14852 available to do the opposite of gmtime ()
14853 "HAS_TIMES"
14855 This symbol, if defined, indicates that the "times()" routine
14856 exists. Note that this became obsolete on some systems ("SUNOS"),
14857 which now use "getrusage()". It may be necessary to include
14858 sys/times.h.
14859 "HAS_TM_TM_GMTOFF"
14861 This symbol, if defined, indicates to the C program that the
14862 "struct tm" has a "tm_gmtoff" field.
14863 "HAS_TM_TM_ZONE"
14865 This symbol, if defined, indicates to the C program that the
14866 "struct tm" has a "tm_zone" field.
14867 "HAS_TZNAME"
14869 This symbol, if defined, indicates that the "tzname[]" array is
14870 available to access timezone names.
14871 "HAS_USLEEP"
14873 This symbol, if defined, indicates that the "usleep" routine is
14874 available to let the process sleep on a sub-second accuracy.
14875 "HAS_USLEEP_PROTO"
14877 This symbol, if defined, indicates that the system provides a
14878 prototype for the "usleep()" function. Otherwise, it is up to the
14879 program to supply one. A good guess is
14880 extern int usleep(useconds_t);
14882 "I_TIME"
14884 This symbol is always defined, and indicates to the C program that
14885 it should include time.h.
14886 #ifdef I_TIME
14888 #include <time.h>
14889 #endif
14890 "I_UTIME"
14892 This symbol, if defined, indicates to the C program that it should
14893 include utime.h.
14894 #ifdef I_UTIME
14896 #include <utime.h>
14897 #endif
14898 "LOCALTIME_MAX"
14900 This symbol contains the maximum value for the "time_t" offset that
14901 the system function localtime () accepts, and defaults to 0
14902 "LOCALTIME_MIN"
14904 This symbol contains the minimum value for the "time_t" offset that
14905 the system function localtime () accepts, and defaults to 0
14906 "LOCALTIME_R_NEEDS_TZSET"
14908 Many libc's "localtime_r" implementations do not call tzset, making
14909 them differ from "localtime()", and making timezone changes using
14910 $"ENV"{TZ} without explicitly calling tzset impossible. This symbol
14911 makes us call tzset before "localtime_r"
14912 "LOCALTIME_R_PROTO"
14914 This symbol encodes the prototype of "localtime_r". It is zero if
14915 "d_localtime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
14916 macros of reentr.h if "d_localtime_r" is defined.
14917 "L_R_TZSET"
14919 If "localtime_r()" needs tzset, it is defined in this define
14920 "mini_mktime"
14922 normalise "struct tm" values without the localtime() semantics (and
14923 overhead) of mktime().
14924 void mini_mktime(struct tm *ptm)
14926 "my_strftime"
14928 strftime(), but with a different API so that the return value is a
14929 pointer to the formatted result (which MUST be arranged to be FREED
14930 BY THE CALLER). This allows this function to increase the buffer
14931 size as needed, so that the caller doesn't have to worry about
14932 that.
14933 Note that yday and wday effectively are ignored by this function,
14935 as mini_mktime() overwrites them
14936 Also note that this is always executed in the underlying locale of
14938 the program, giving localized results.
14939 NOTE: "my_strftime" must be explicitly called as "Perl_my_strftime"
14941 with an "aTHX_" parameter.
14942 char * Perl_my_strftime(pTHX_ const char *fmt, int sec, int min,
14944 int hour, int mday, int mon, int year,
14945 int wday, int yday, int isdst)
14946
14948 "DB_Hash_t"
14949 This symbol contains the type of the prefix structure element in
14950 the db.h header file. In older versions of DB, it was int, while
14951 in newer ones it is "size_t".
14952 "DB_Prefix_t"
14954 This symbol contains the type of the prefix structure element in
14955 the db.h header file. In older versions of DB, it was int, while
14956 in newer ones it is "u_int32_t".
14957 "Direntry_t"
14959 This symbol is set to '"struct direct"' or '"struct dirent"'
14960 depending on whether dirent is available or not. You should use
14961 this pseudo type to portably declare your directory entries.
14962 "Fpos_t"
14964 This symbol holds the type used to declare file positions in libc.
14965 It can be "fpos_t", long, uint, etc... It may be necessary to
14966 include sys/types.h to get any typedef'ed information.
14967 "Free_t"
14969 This variable contains the return type of "free()". It is usually
14970 void, but occasionally int.
14971 "Gid_t"
14973 This symbol holds the return type of "getgid()" and the type of
14974 argument to "setrgid()" and related functions. Typically, it is
14975 the type of group ids in the kernel. It can be int, ushort,
14976 "gid_t", etc... It may be necessary to include sys/types.h to get
14977 any typedef'ed information.
14978 "Gid_t_f"
14980 This symbol defines the format string used for printing a "Gid_t".
14981 "Gid_t_sign"
14983 This symbol holds the signedness of a "Gid_t". 1 for unsigned, -1
14984 for signed.
14985 "Gid_t_size"
14987 This symbol holds the size of a "Gid_t" in bytes.
14988 "Groups_t"
14990 This symbol holds the type used for the second argument to
14991 "getgroups()" and "setgroups()". Usually, this is the same as
14992 gidtype ("gid_t") , but sometimes it isn't. It can be int, ushort,
14993 "gid_t", etc... It may be necessary to include sys/types.h to get
14994 any typedef'ed information. This is only required if you have
14995 "getgroups()" or "setgroups()"..
14996 "Malloc_t"
14998 This symbol is the type of pointer returned by malloc and realloc.
14999 "Mmap_t"
15001 This symbol holds the return type of the "mmap()" system call (and
15002 simultaneously the type of the first argument). Usually set to
15003 'void *' or '"caddr_t"'.
15004 "Mode_t"
15006 This symbol holds the type used to declare file modes for systems
15007 calls. It is usually "mode_t", but may be int or unsigned short.
15008 It may be necessary to include sys/types.h to get any typedef'ed
15009 information.
15010 "Netdb_hlen_t"
15012 This symbol holds the type used for the 2nd argument to
15013 "gethostbyaddr()".
15014 "Netdb_host_t"
15016 This symbol holds the type used for the 1st argument to
15017 "gethostbyaddr()".
15018 "Netdb_name_t"
15020 This symbol holds the type used for the argument to
15021 "gethostbyname()".
15022 "Netdb_net_t"
15024 This symbol holds the type used for the 1st argument to
15025 "getnetbyaddr()".
15026 "Off_t"
15028 This symbol holds the type used to declare offsets in the kernel.
15029 It can be int, long, "off_t", etc... It may be necessary to include
15030 sys/types.h to get any typedef'ed information.
15031 "Off_t_size"
15033 This symbol holds the number of bytes used by the "Off_t".
15034 "Pid_t"
15036 This symbol holds the type used to declare process ids in the
15037 kernel. It can be int, uint, "pid_t", etc... It may be necessary
15038 to include sys/types.h to get any typedef'ed information.
15039 "Rand_seed_t"
15041 This symbol defines the type of the argument of the random seed
15042 function.
15043 "Select_fd_set_t"
15045 This symbol holds the type used for the 2nd, 3rd, and 4th arguments
15046 to select. Usually, this is '"fd_set" *', if "HAS_FD_SET" is
15047 defined, and 'int *' otherwise. This is only useful if you have
15048 "select()", of course.
15049 "Shmat_t"
15051 This symbol holds the return type of the "shmat()" system call.
15052 Usually set to 'void *' or 'char *'.
15053 "Signal_t"
15055 This symbol's value is either "void" or "int", corresponding to the
15056 appropriate return type of a signal handler. Thus, you can declare
15057 a signal handler using ""Signal_t" (*handler)()", and define the
15058 handler using ""Signal_t" "handler(sig)"".
15059 "Size_t"
15061 This symbol holds the type used to declare length parameters for
15062 string functions. It is usually "size_t", but may be unsigned
15063 long, int, etc. It may be necessary to include sys/types.h to get
15064 any typedef'ed information.
15065 "Size_t_size"
15067 This symbol holds the size of a "Size_t" in bytes.
15068 "Sock_size_t"
15070 This symbol holds the type used for the size argument of various
15071 socket calls (just the base type, not the pointer-to).
15072 "SSize_t"
15074 This symbol holds the type used by functions that return a count of
15075 bytes or an error condition. It must be a signed type. It is
15076 usually "ssize_t", but may be long or int, etc. It may be
15077 necessary to include sys/types.h or unistd.h to get any typedef'ed
15078 information. We will pick a type such that "sizeof(SSize_t)" ==
15079 "sizeof(Size_t)".
15080 "Time_t"
15082 This symbol holds the type returned by "time()". It can be long, or
15083 "time_t" on "BSD" sites (in which case sys/types.h should be
15084 included).
15085 "Uid_t"
15087 This symbol holds the type used to declare user ids in the kernel.
15088 It can be int, ushort, "uid_t", etc... It may be necessary to
15089 include sys/types.h to get any typedef'ed information.
15090 "Uid_t_f"
15092 This symbol defines the format string used for printing a "Uid_t".
15093 "Uid_t_sign"
15095 This symbol holds the signedness of a "Uid_t". 1 for unsigned, -1
15096 for signed.
15097 "Uid_t_size"
15099 This symbol holds the size of a "Uid_t" in bytes.
15100
15102 "Unicode Support" in perlguts has an introduction to this API.
15103 See also "Character classification", "Character case changing", and
15105 "String Handling". Various functions outside this section also work
15106 specially with Unicode. Search for the string "utf8" in this document.
15107 "BOM_UTF8"
15109 This is a macro that evaluates to a string constant of the UTF-8
15110 bytes that define the Unicode BYTE ORDER MARK (U+FEFF) for the
15111 platform that perl is compiled on. This allows code to use a
15112 mnemonic for this character that works on both ASCII and EBCDIC
15113 platforms. "sizeof(BOM_UTF8) - 1" can be used to get its length in
15114 bytes.
15115 "bytes_cmp_utf8"
15117 Compares the sequence of characters (stored as octets) in "b",
15118 "blen" with the sequence of characters (stored as UTF-8) in "u",
15119 "ulen". Returns 0 if they are equal, -1 or -2 if the first string
15120 is less than the second string, +1 or +2 if the first string is
15121 greater than the second string.
15122 -1 or +1 is returned if the shorter string was identical to the
15124 start of the longer string. -2 or +2 is returned if there was a
15125 difference between characters within the strings.
15126 int bytes_cmp_utf8(const U8 *b, STRLEN blen, const U8 *u,
15128 STRLEN ulen)
15129 "bytes_from_utf8"
15131 NOTE: "bytes_from_utf8" is experimental and may change or be
15132 removed without notice.
15133 Converts a potentially UTF-8 encoded string "s" of length *lenp
15135 into native byte encoding. On input, the boolean *is_utf8p gives
15136 whether or not "s" is actually encoded in UTF-8.
15137 Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-
15139 destructive of the input string.
15140 Do nothing if *is_utf8p is 0, or if there are code points in the
15142 string not expressible in native byte encoding. In these cases,
15143 *is_utf8p and *lenp are unchanged, and the return value is the
15144 original "s".
15145 Otherwise, *is_utf8p is set to 0, and the return value is a pointer
15147 to a newly created string containing a downgraded copy of "s", and
15148 whose length is returned in *lenp, updated. The new string is
15149 "NUL"-terminated. The caller is responsible for arranging for the
15150 memory used by this string to get freed.
15151 Upon successful return, the number of variants in the string can be
15153 computed by having saved the value of *lenp before the call, and
15154 subtracting the after-call value of *lenp from it.
15155 U8* bytes_from_utf8(const U8 *s, STRLEN *lenp, bool *is_utf8p)
15157 "bytes_to_utf8"
15159 NOTE: "bytes_to_utf8" is experimental and may change or be removed
15160 without notice.
15161 Converts a string "s" of length *lenp bytes from the native
15163 encoding into UTF-8. Returns a pointer to the newly-created
15164 string, and sets *lenp to reflect the new length in bytes. The
15165 caller is responsible for arranging for the memory used by this
15166 string to get freed.
15167 Upon successful return, the number of variants in the string can be
15169 computed by having saved the value of *lenp before the call, and
15170 subtracting it from the after-call value of *lenp.
15171 A "NUL" character will be written after the end of the string.
15173 If you want to convert to UTF-8 from encodings other than the
15175 native (Latin1 or EBCDIC), see "sv_recode_to_utf8"().
15176 U8* bytes_to_utf8(const U8 *s, STRLEN *lenp)
15178 "DO_UTF8"
15180 Returns a bool giving whether or not the PV in "sv" is to be
15181 treated as being encoded in UTF-8.
15182 You should use this after a call to "SvPV()" or one of its
15184 variants, in case any call to string overloading updates the
15185 internal UTF-8 encoding flag.
15186 bool DO_UTF8(SV* sv)
15188 "foldEQ_utf8"
15190 Returns true if the leading portions of the strings "s1" and "s2"
15191 (either or both of which may be in UTF-8) are the same case-
15192 insensitively; false otherwise. How far into the strings to
15193 compare is determined by other input parameters.
15194 If "u1" is true, the string "s1" is assumed to be in UTF-8-encoded
15196 Unicode; otherwise it is assumed to be in native 8-bit encoding.
15197 Correspondingly for "u2" with respect to "s2".
15198 If the byte length "l1" is non-zero, it says how far into "s1" to
15200 check for fold equality. In other words, "s1"+"l1" will be used as
15201 a goal to reach. The scan will not be considered to be a match
15202 unless the goal is reached, and scanning won't continue past that
15203 goal. Correspondingly for "l2" with respect to "s2".
15204 If "pe1" is non-"NULL" and the pointer it points to is not "NULL",
15206 that pointer is considered an end pointer to the position 1 byte
15207 past the maximum point in "s1" beyond which scanning will not
15208 continue under any circumstances. (This routine assumes that UTF-8
15209 encoded input strings are not malformed; malformed input can cause
15210 it to read past "pe1"). This means that if both "l1" and "pe1" are
15211 specified, and "pe1" is less than "s1"+"l1", the match will never
15212 be successful because it can never get as far as its goal (and in
15213 fact is asserted against). Correspondingly for "pe2" with respect
15214 to "s2".
15215 At least one of "s1" and "s2" must have a goal (at least one of
15217 "l1" and "l2" must be non-zero), and if both do, both have to be
15218 reached for a successful match. Also, if the fold of a character
15219 is multiple characters, all of them must be matched (see tr21
15220 reference below for 'folding').
15221 Upon a successful match, if "pe1" is non-"NULL", it will be set to
15223 point to the beginning of the next character of "s1" beyond what
15224 was matched. Correspondingly for "pe2" and "s2".
15225 For case-insensitiveness, the "casefolding" of Unicode is used
15227 instead of upper/lowercasing both the characters, see
15228 <https://www.unicode.org/reports/tr21/> (Case Mappings).
15229 I32 foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1,
15231 const char *s2, char **pe2, UV l2, bool u2)
15232 "is_ascii_string"
15234 This is a misleadingly-named synonym for
15235 "is_utf8_invariant_string". On ASCII-ish platforms, the name isn't
15236 misleading: the ASCII-range characters are exactly the UTF-8
15237 invariants. But EBCDIC machines have more invariants than just the
15238 ASCII characters, so "is_utf8_invariant_string" is preferred.
15239 bool is_ascii_string(const U8* const s, STRLEN len)
15241 "is_c9strict_utf8_string"
15243 Returns TRUE if the first "len" bytes of string "s" form a valid
15244 UTF-8-encoded string that conforms to Unicode Corrigendum #9
15245 <http://www.unicode.org/versions/corrigendum9.html>; otherwise it
15246 returns FALSE. If "len" is 0, it will be calculated using
15247 strlen(s) (which means if you use this option, that "s" can't have
15248 embedded "NUL" characters and has to have a terminating "NUL"
15249 byte). Note that all characters being ASCII constitute 'a valid
15250 UTF-8 string'.
15251 This function returns FALSE for strings containing any code points
15253 above the Unicode max of 0x10FFFF or surrogate code points, but
15254 accepts non-character code points per Corrigendum #9
15255 <http://www.unicode.org/versions/corrigendum9.html>.
15256 See also "is_utf8_invariant_string",
15258 "is_utf8_invariant_string_loc", "is_utf8_string",
15259 "is_utf8_string_flags", "is_utf8_string_loc",
15260 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
15261 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
15262 "is_utf8_fixed_width_buf_loc_flags",
15263 "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
15264 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
15265 "is_c9strict_utf8_string_loc", and
15266 "is_c9strict_utf8_string_loclen".
15267 bool is_c9strict_utf8_string(const U8 *s, STRLEN len)
15269 "is_c9strict_utf8_string_loc"
15271 Like "is_c9strict_utf8_string" but stores the location of the
15272 failure (in the case of "utf8ness failure") or the location
15273 "s"+"len" (in the case of "utf8ness success") in the "ep" pointer.
15274 See also "is_c9strict_utf8_string_loclen".
15276 bool is_c9strict_utf8_string_loc(const U8 *s, STRLEN len,
15278 const U8 **ep)
15279 "is_c9strict_utf8_string_loclen"
15281 Like "is_c9strict_utf8_string" but stores the location of the
15282 failure (in the case of "utf8ness failure") or the location
15283 "s"+"len" (in the case of "utf8ness success") in the "ep" pointer,
15284 and the number of UTF-8 encoded characters in the "el" pointer.
15285 See also "is_c9strict_utf8_string_loc".
15287 bool is_c9strict_utf8_string_loclen(const U8 *s, STRLEN len,
15289 const U8 **ep, STRLEN *el)
15290 "isC9_STRICT_UTF8_CHAR"
15292 Evaluates to non-zero if the first few bytes of the string starting
15293 at "s" and looking no further than "e - 1" are well-formed UTF-8
15294 that represents some Unicode non-surrogate code point; otherwise it
15295 evaluates to 0. If non-zero, the value gives how many bytes
15296 starting at "s" comprise the code point's representation. Any
15297 bytes remaining before "e", but beyond the ones needed to form the
15298 first code point in "s", are not examined.
15299 The largest acceptable code point is the Unicode maximum 0x10FFFF.
15301 This differs from "isSTRICT_UTF8_CHAR" only in that it accepts non-
15302 character code points. This corresponds to Unicode Corrigendum #9
15303 <http://www.unicode.org/versions/corrigendum9.html>. which said
15304 that non-character code points are merely discouraged rather than
15305 completely forbidden in open interchange. See "Noncharacter code
15306 points" in perlunicode.
15307 Use "isUTF8_CHAR" to check for Perl's extended UTF-8; and
15309 "isUTF8_CHAR_flags" for a more customized definition.
15310 Use "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
15312 "is_c9strict_utf8_string_loclen" to check entire strings.
15313 Size_t isC9_STRICT_UTF8_CHAR(const U8 * const s0,
15315 const U8 * const e)
15316 "is_invariant_string"
15318 This is a somewhat misleadingly-named synonym for
15319 "is_utf8_invariant_string". "is_utf8_invariant_string" is
15320 preferred, as it indicates under what conditions the string is
15321 invariant.
15322 bool is_invariant_string(const U8* const s, STRLEN len)
15324 "isSTRICT_UTF8_CHAR"
15326 Evaluates to non-zero if the first few bytes of the string starting
15327 at "s" and looking no further than "e - 1" are well-formed UTF-8
15328 that represents some Unicode code point completely acceptable for
15329 open interchange between all applications; otherwise it evaluates
15330 to 0. If non-zero, the value gives how many bytes starting at "s"
15331 comprise the code point's representation. Any bytes remaining
15332 before "e", but beyond the ones needed to form the first code point
15333 in "s", are not examined.
15334 The largest acceptable code point is the Unicode maximum 0x10FFFF,
15336 and must not be a surrogate nor a non-character code point. Thus
15337 this excludes any code point from Perl's extended UTF-8.
15338 This is used to efficiently decide if the next few bytes in "s" is
15340 legal Unicode-acceptable UTF-8 for a single character.
15341 Use "isC9_STRICT_UTF8_CHAR" to use the Unicode Corrigendum #9
15343 <http://www.unicode.org/versions/corrigendum9.html> definition of
15344 allowable code points; "isUTF8_CHAR" to check for Perl's extended
15345 UTF-8; and "isUTF8_CHAR_flags" for a more customized definition.
15346 Use "is_strict_utf8_string", "is_strict_utf8_string_loc", and
15348 "is_strict_utf8_string_loclen" to check entire strings.
15349 Size_t isSTRICT_UTF8_CHAR(const U8 * const s0,
15351 const U8 * const e)
15352 "is_strict_utf8_string"
15354 Returns TRUE if the first "len" bytes of string "s" form a valid
15355 UTF-8-encoded string that is fully interchangeable by any
15356 application using Unicode rules; otherwise it returns FALSE. If
15357 "len" is 0, it will be calculated using strlen(s) (which means if
15358 you use this option, that "s" can't have embedded "NUL" characters
15359 and has to have a terminating "NUL" byte). Note that all
15360 characters being ASCII constitute 'a valid UTF-8 string'.
15361 This function returns FALSE for strings containing any code points
15363 above the Unicode max of 0x10FFFF, surrogate code points, or non-
15364 character code points.
15365 See also "is_utf8_invariant_string",
15367 "is_utf8_invariant_string_loc", "is_utf8_string",
15368 "is_utf8_string_flags", "is_utf8_string_loc",
15369 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
15370 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
15371 "is_utf8_fixed_width_buf_loc_flags",
15372 "is_utf8_fixed_width_buf_loclen_flags",
15373 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
15374 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
15375 "is_c9strict_utf8_string_loclen".
15376 bool is_strict_utf8_string(const U8 *s, STRLEN len)
15378 "is_strict_utf8_string_loc"
15380 Like "is_strict_utf8_string" but stores the location of the failure
15381 (in the case of "utf8ness failure") or the location "s"+"len" (in
15382 the case of "utf8ness success") in the "ep" pointer.
15383 See also "is_strict_utf8_string_loclen".
15385 bool is_strict_utf8_string_loc(const U8 *s, STRLEN len,
15387 const U8 **ep)
15388 "is_strict_utf8_string_loclen"
15390 Like "is_strict_utf8_string" but stores the location of the failure
15391 (in the case of "utf8ness failure") or the location "s"+"len" (in
15392 the case of "utf8ness success") in the "ep" pointer, and the number
15393 of UTF-8 encoded characters in the "el" pointer.
15394 See also "is_strict_utf8_string_loc".
15396 bool is_strict_utf8_string_loclen(const U8 *s, STRLEN len,
15398 const U8 **ep, STRLEN *el)
15399 "is_utf8_char"
15401 "DEPRECATED!" It is planned to remove "is_utf8_char" from a future
15402 release of Perl. Do not use it for new code; remove it from
15403 existing code.
15404 Tests if some arbitrary number of bytes begins in a valid UTF-8
15406 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC
15407 machines) character is a valid UTF-8 character. The actual number
15408 of bytes in the UTF-8 character will be returned if it is valid,
15409 otherwise 0.
15410 This function is deprecated due to the possibility that malformed
15412 input could cause reading beyond the end of the input buffer. Use
15413 "isUTF8_CHAR" instead.
15414 STRLEN is_utf8_char(const U8 *s)
15416 "is_utf8_char_buf"
15418 This is identical to the macro "isUTF8_CHAR" in perlapi.
15419 STRLEN is_utf8_char_buf(const U8 *buf, const U8 *buf_end)
15421 "is_utf8_fixed_width_buf_flags"
15423 Returns TRUE if the fixed-width buffer starting at "s" with length
15424 "len" is entirely valid UTF-8, subject to the restrictions given by
15425 "flags"; otherwise it returns FALSE.
15426 If "flags" is 0, any well-formed UTF-8, as extended by Perl, is
15428 accepted without restriction. If the final few bytes of the buffer
15429 do not form a complete code point, this will return TRUE anyway,
15430 provided that "is_utf8_valid_partial_char_flags" returns TRUE for
15431 them.
15432 If "flags" in non-zero, it can be any combination of the
15434 "UTF8_DISALLOW_foo" flags accepted by "utf8n_to_uvchr", and with
15435 the same meanings.
15436 This function differs from "is_utf8_string_flags" only in that the
15438 latter returns FALSE if the final few bytes of the string don't
15439 form a complete code point.
15440 bool is_utf8_fixed_width_buf_flags(const U8 * const s,
15442 STRLEN len, const U32 flags)
15443 "is_utf8_fixed_width_buf_loclen_flags"
15445 Like "is_utf8_fixed_width_buf_loc_flags" but stores the number of
15446 complete, valid characters found in the "el" pointer.
15447 bool is_utf8_fixed_width_buf_loclen_flags(const U8 * const s,
15449 STRLEN len,
15450 const U8 **ep,
15451 STRLEN *el,
15452 const U32 flags)
15453 "is_utf8_fixed_width_buf_loc_flags"
15455 Like "is_utf8_fixed_width_buf_flags" but stores the location of the
15456 failure in the "ep" pointer. If the function returns TRUE, *ep
15457 will point to the beginning of any partial character at the end of
15458 the buffer; if there is no partial character *ep will contain
15459 "s"+"len".
15460 See also "is_utf8_fixed_width_buf_loclen_flags".
15462 bool is_utf8_fixed_width_buf_loc_flags(const U8 * const s,
15464 STRLEN len, const U8 **ep,
15465 const U32 flags)
15466 "is_utf8_invariant_string"
15468 Returns TRUE if the first "len" bytes of the string "s" are the
15469 same regardless of the UTF-8 encoding of the string (or UTF-EBCDIC
15470 encoding on EBCDIC machines); otherwise it returns FALSE. That is,
15471 it returns TRUE if they are UTF-8 invariant. On ASCII-ish
15472 machines, all the ASCII characters and only the ASCII characters
15473 fit this definition. On EBCDIC machines, the ASCII-range
15474 characters are invariant, but so also are the C1 controls.
15475 If "len" is 0, it will be calculated using strlen(s), (which means
15477 if you use this option, that "s" can't have embedded "NUL"
15478 characters and has to have a terminating "NUL" byte).
15479 See also "is_utf8_string", "is_utf8_string_flags",
15481 "is_utf8_string_loc", "is_utf8_string_loc_flags",
15482 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
15483 "is_utf8_fixed_width_buf_flags",
15484 "is_utf8_fixed_width_buf_loc_flags",
15485 "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
15486 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
15487 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
15488 "is_c9strict_utf8_string_loclen".
15489 bool is_utf8_invariant_string(const U8* const s, STRLEN len)
15491 "is_utf8_invariant_string_loc"
15493 Like "is_utf8_invariant_string" but upon failure, stores the
15494 location of the first UTF-8 variant character in the "ep" pointer;
15495 if all characters are UTF-8 invariant, this function does not
15496 change the contents of *ep.
15497 bool is_utf8_invariant_string_loc(const U8* const s, STRLEN len,
15499 const U8 ** ep)
15500 "is_utf8_string"
15502 Returns TRUE if the first "len" bytes of string "s" form a valid
15503 Perl-extended-UTF-8 string; returns FALSE otherwise. If "len" is
15504 0, it will be calculated using strlen(s) (which means if you use
15505 this option, that "s" can't have embedded "NUL" characters and has
15506 to have a terminating "NUL" byte). Note that all characters being
15507 ASCII constitute 'a valid UTF-8 string'.
15508 This function considers Perl's extended UTF-8 to be valid. That
15510 means that code points above Unicode, surrogates, and non-character
15511 code points are considered valid by this function. Use
15512 "is_strict_utf8_string", "is_c9strict_utf8_string", or
15513 "is_utf8_string_flags" to restrict what code points are considered
15514 valid.
15515 See also "is_utf8_invariant_string",
15517 "is_utf8_invariant_string_loc", "is_utf8_string_loc",
15518 "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags",
15519 "is_utf8_fixed_width_buf_loc_flags",
15520 "is_utf8_fixed_width_buf_loclen_flags",
15521 bool is_utf8_string(const U8 *s, STRLEN len)
15523 "is_utf8_string_flags"
15525 Returns TRUE if the first "len" bytes of string "s" form a valid
15526 UTF-8 string, subject to the restrictions imposed by "flags";
15527 returns FALSE otherwise. If "len" is 0, it will be calculated
15528 using strlen(s) (which means if you use this option, that "s" can't
15529 have embedded "NUL" characters and has to have a terminating "NUL"
15530 byte). Note that all characters being ASCII constitute 'a valid
15531 UTF-8 string'.
15532 If "flags" is 0, this gives the same results as "is_utf8_string";
15534 if "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the
15535 same results as "is_strict_utf8_string"; and if "flags" is
15536 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same results
15537 as "is_c9strict_utf8_string". Otherwise "flags" may be any
15538 combination of the "UTF8_DISALLOW_foo" flags understood by
15539 "utf8n_to_uvchr", with the same meanings.
15540 See also "is_utf8_invariant_string",
15542 "is_utf8_invariant_string_loc", "is_utf8_string",
15543 "is_utf8_string_loc", "is_utf8_string_loc_flags",
15544 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
15545 "is_utf8_fixed_width_buf_flags",
15546 "is_utf8_fixed_width_buf_loc_flags",
15547 "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
15548 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
15549 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
15550 "is_c9strict_utf8_string_loclen".
15551 bool is_utf8_string_flags(const U8 *s, STRLEN len,
15553 const U32 flags)
15554 "is_utf8_string_loc"
15556 Like "is_utf8_string" but stores the location of the failure (in
15557 the case of "utf8ness failure") or the location "s"+"len" (in the
15558 case of "utf8ness success") in the "ep" pointer.
15559 See also "is_utf8_string_loclen".
15561 bool is_utf8_string_loc(const U8 *s, const STRLEN len,
15563 const U8 **ep)
15564 "is_utf8_string_loclen"
15566 Like "is_utf8_string" but stores the location of the failure (in
15567 the case of "utf8ness failure") or the location "s"+"len" (in the
15568 case of "utf8ness success") in the "ep" pointer, and the number of
15569 UTF-8 encoded characters in the "el" pointer.
15570 See also "is_utf8_string_loc".
15572 bool is_utf8_string_loclen(const U8 *s, STRLEN len,
15574 const U8 **ep, STRLEN *el)
15575 "is_utf8_string_loclen_flags"
15577 Like "is_utf8_string_flags" but stores the location of the failure
15578 (in the case of "utf8ness failure") or the location "s"+"len" (in
15579 the case of "utf8ness success") in the "ep" pointer, and the number
15580 of UTF-8 encoded characters in the "el" pointer.
15581 See also "is_utf8_string_loc_flags".
15583 bool is_utf8_string_loclen_flags(const U8 *s, STRLEN len,
15585 const U8 **ep, STRLEN *el,
15586 const U32 flags)
15587 "is_utf8_string_loc_flags"
15589 Like "is_utf8_string_flags" but stores the location of the failure
15590 (in the case of "utf8ness failure") or the location "s"+"len" (in
15591 the case of "utf8ness success") in the "ep" pointer.
15592 See also "is_utf8_string_loclen_flags".
15594 bool is_utf8_string_loc_flags(const U8 *s, STRLEN len,
15596 const U8 **ep, const U32 flags)
15597 "is_utf8_valid_partial_char"
15599 Returns 0 if the sequence of bytes starting at "s" and looking no
15600 further than "e - 1" is the UTF-8 encoding, as extended by Perl,
15601 for one or more code points. Otherwise, it returns 1 if there
15602 exists at least one non-empty sequence of bytes that when appended
15603 to sequence "s", starting at position "e" causes the entire
15604 sequence to be the well-formed UTF-8 of some code point; otherwise
15605 returns 0.
15606 In other words this returns TRUE if "s" points to a partial
15608 UTF-8-encoded code point.
15609 This is useful when a fixed-length buffer is being tested for being
15611 well-formed UTF-8, but the final few bytes in it don't comprise a
15612 full character; that is, it is split somewhere in the middle of the
15613 final code point's UTF-8 representation. (Presumably when the
15614 buffer is refreshed with the next chunk of data, the new first
15615 bytes will complete the partial code point.) This function is
15616 used to verify that the final bytes in the current buffer are in
15617 fact the legal beginning of some code point, so that if they
15618 aren't, the failure can be signalled without having to wait for the
15619 next read.
15620 bool is_utf8_valid_partial_char(const U8 * const s0,
15622 const U8 * const e)
15623 "is_utf8_valid_partial_char_flags"
15625 Like "is_utf8_valid_partial_char", it returns a boolean giving
15626 whether or not the input is a valid UTF-8 encoded partial
15627 character, but it takes an extra parameter, "flags", which can
15628 further restrict which code points are considered valid.
15629 If "flags" is 0, this behaves identically to
15631 "is_utf8_valid_partial_char". Otherwise "flags" can be any
15632 combination of the "UTF8_DISALLOW_foo" flags accepted by
15633 "utf8n_to_uvchr". If there is any sequence of bytes that can
15634 complete the input partial character in such a way that a non-
15635 prohibited character is formed, the function returns TRUE;
15636 otherwise FALSE. Non character code points cannot be determined
15637 based on partial character input. But many of the other possible
15638 excluded types can be determined from just the first one or two
15639 bytes.
15640 bool is_utf8_valid_partial_char_flags(const U8 * const s0,
15642 const U8 * const e,
15643 const U32 flags)
15644 "isUTF8_CHAR"
15646 Evaluates to non-zero if the first few bytes of the string starting
15647 at "s" and looking no further than "e - 1" are well-formed UTF-8,
15648 as extended by Perl, that represents some code point; otherwise it
15649 evaluates to 0. If non-zero, the value gives how many bytes
15650 starting at "s" comprise the code point's representation. Any
15651 bytes remaining before "e", but beyond the ones needed to form the
15652 first code point in "s", are not examined.
15653 The code point can be any that will fit in an IV on this machine,
15655 using Perl's extension to official UTF-8 to represent those higher
15656 than the Unicode maximum of 0x10FFFF. That means that this macro
15657 is used to efficiently decide if the next few bytes in "s" is legal
15658 UTF-8 for a single character.
15659 Use "isSTRICT_UTF8_CHAR" to restrict the acceptable code points to
15661 those defined by Unicode to be fully interchangeable across
15662 applications; "isC9_STRICT_UTF8_CHAR" to use the Unicode
15663 Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>
15664 definition of allowable code points; and "isUTF8_CHAR_flags" for a
15665 more customized definition.
15666 Use "is_utf8_string", "is_utf8_string_loc", and
15668 "is_utf8_string_loclen" to check entire strings.
15669 Note also that a UTF-8 "invariant" character (i.e. ASCII on non-
15671 EBCDIC machines) is a valid UTF-8 character.
15672 Size_t isUTF8_CHAR(const U8 * const s0, const U8 * const e)
15674 "isUTF8_CHAR_flags"
15676 Evaluates to non-zero if the first few bytes of the string starting
15677 at "s" and looking no further than "e - 1" are well-formed UTF-8,
15678 as extended by Perl, that represents some code point, subject to
15679 the restrictions given by "flags"; otherwise it evaluates to 0. If
15680 non-zero, the value gives how many bytes starting at "s" comprise
15681 the code point's representation. Any bytes remaining before "e",
15682 but beyond the ones needed to form the first code point in "s", are
15683 not examined.
15684 If "flags" is 0, this gives the same results as "isUTF8_CHAR"; if
15686 "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the same
15687 results as "isSTRICT_UTF8_CHAR"; and if "flags" is
15688 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same results
15689 as "isC9_STRICT_UTF8_CHAR". Otherwise "flags" may be any
15690 combination of the "UTF8_DISALLOW_foo" flags understood by
15691 "utf8n_to_uvchr", with the same meanings.
15692 The three alternative macros are for the most commonly needed
15694 validations; they are likely to run somewhat faster than this more
15695 general one, as they can be inlined into your code.
15696 Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
15698 "is_utf8_string_loclen_flags" to check entire strings.
15699 Size_t isUTF8_CHAR_flags(const U8 * const s0, const U8 * const e,
15701 const U32 flags)
15702 "LATIN1_TO_NATIVE"
15704 Returns the native equivalent of the input Latin-1 code point
15705 (including ASCII and control characters) given by "ch". Thus,
15706 "LATIN1_TO_NATIVE(66)" on EBCDIC platforms returns 194. These each
15707 represent the character "B" on their respective platforms. On
15708 ASCII platforms no conversion is needed, so this macro expands to
15709 just its input, adding no time nor space requirements to the
15710 implementation.
15711 For conversion of code points potentially larger than will fit in a
15713 character, use "UNI_TO_NATIVE".
15714 U8 LATIN1_TO_NATIVE(U8 ch)
15716 "NATIVE_TO_LATIN1"
15718 Returns the Latin-1 (including ASCII and control characters)
15719 equivalent of the input native code point given by "ch". Thus,
15720 "NATIVE_TO_LATIN1(193)" on EBCDIC platforms returns 65. These each
15721 represent the character "A" on their respective platforms. On
15722 ASCII platforms no conversion is needed, so this macro expands to
15723 just its input, adding no time nor space requirements to the
15724 implementation.
15725 For conversion of code points potentially larger than will fit in a
15727 character, use "NATIVE_TO_UNI".
15728 U8 NATIVE_TO_LATIN1(U8 ch)
15730 "NATIVE_TO_UNI"
15732 Returns the Unicode equivalent of the input native code point
15733 given by "ch". Thus, "NATIVE_TO_UNI(195)" on EBCDIC platforms
15734 returns 67. These each represent the character "C" on their
15735 respective platforms. On ASCII platforms no conversion is needed,
15736 so this macro expands to just its input, adding no time nor space
15737 requirements to the implementation.
15738 UV NATIVE_TO_UNI(UV ch)
15740 "pv_uni_display"
15742 Build to the scalar "dsv" a displayable version of the UTF-8
15743 encoded string "spv", length "len", the displayable version being
15744 at most "pvlim" bytes long (if longer, the rest is truncated and
15745 "..." will be appended).
15746 The "flags" argument can have "UNI_DISPLAY_ISPRINT" set to display
15748 "isPRINT()"able characters as themselves, "UNI_DISPLAY_BACKSLASH"
15749 to display the "\\[nrfta\\]" as the backslashed versions (like
15750 "\n") ("UNI_DISPLAY_BACKSLASH" is preferred over
15751 "UNI_DISPLAY_ISPRINT" for "\\"). "UNI_DISPLAY_QQ" (and its alias
15752 "UNI_DISPLAY_REGEX") have both "UNI_DISPLAY_BACKSLASH" and
15753 "UNI_DISPLAY_ISPRINT" turned on.
15754 Additionally, there is now "UNI_DISPLAY_BACKSPACE" which allows
15756 "\b" for a backspace, but only when "UNI_DISPLAY_BACKSLASH" also is
15757 set.
15758 The pointer to the PV of the "dsv" is returned.
15760 See also "sv_uni_display".
15762 char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len,
15764 STRLEN pvlim, UV flags)
15765 "REPLACEMENT_CHARACTER_UTF8"
15767 This is a macro that evaluates to a string constant of the UTF-8
15768 bytes that define the Unicode REPLACEMENT CHARACTER (U+FFFD) for
15769 the platform that perl is compiled on. This allows code to use a
15770 mnemonic for this character that works on both ASCII and EBCDIC
15771 platforms. "sizeof(REPLACEMENT_CHARACTER_UTF8) - 1" can be used to
15772 get its length in bytes.
15773 "sv_cat_decode"
15775 "encoding" is assumed to be an "Encode" object, the PV of "ssv" is
15776 assumed to be octets in that encoding and decoding the input starts
15777 from the position which "(PV + *offset)" pointed to. "dsv" will be
15778 concatenated with the decoded UTF-8 string from "ssv". Decoding
15779 will terminate when the string "tstr" appears in decoding output or
15780 the input ends on the PV of "ssv". The value which "offset" points
15781 will be modified to the last input position on "ssv".
15782 Returns TRUE if the terminator was found, else returns FALSE.
15784 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset,
15786 char* tstr, int tlen)
15787 "sv_recode_to_utf8"
15789 "encoding" is assumed to be an "Encode" object, on entry the PV of
15790 "sv" is assumed to be octets in that encoding, and "sv" will be
15791 converted into Unicode (and UTF-8).
15792 If "sv" already is UTF-8 (or if it is not "POK"), or if "encoding"
15794 is not a reference, nothing is done to "sv". If "encoding" is not
15795 an "Encode::XS" Encoding object, bad things will happen. (See
15796 encoding and Encode.)
15797 The PV of "sv" is returned.
15799 char* sv_recode_to_utf8(SV* sv, SV *encoding)
15801 "sv_uni_display"
15803 Build to the scalar "dsv" a displayable version of the scalar "sv",
15804 the displayable version being at most "pvlim" bytes long (if
15805 longer, the rest is truncated and "..." will be appended).
15806 The "flags" argument is as in "pv_uni_display"().
15808 The pointer to the PV of the "dsv" is returned.
15810 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
15812 "UNICODE_IS_NONCHAR"
15814 Returns a boolean as to whether or not "uv" is one of the Unicode
15815 non-character code points
15816 bool UNICODE_IS_NONCHAR(const UV uv)
15818 "UNICODE_IS_REPLACEMENT"
15820 Returns a boolean as to whether or not "uv" is the Unicode
15821 REPLACEMENT CHARACTER
15822 bool UNICODE_IS_REPLACEMENT(const UV uv)
15824 "UNICODE_IS_SUPER"
15826 Returns a boolean as to whether or not "uv" is above the maximum
15827 legal Unicode code point of U+10FFFF.
15828 bool UNICODE_IS_SUPER(const UV uv)
15830 "UNICODE_IS_SURROGATE"
15832 Returns a boolean as to whether or not "uv" is one of the Unicode
15833 surrogate code points
15834 bool UNICODE_IS_SURROGATE(const UV uv)
15836 "UNICODE_REPLACEMENT"
15838 Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT
15839 CHARACTER
15840 "UNI_TO_NATIVE"
15842 Returns the native equivalent of the input Unicode code point
15843 given by "ch". Thus, "UNI_TO_NATIVE(68)" on EBCDIC platforms
15844 returns 196. These each represent the character "D" on their
15845 respective platforms. On ASCII platforms no conversion is needed,
15846 so this macro expands to just its input, adding no time nor space
15847 requirements to the implementation.
15848 UV UNI_TO_NATIVE(UV ch)
15850 "utf8n_to_uvchr"
15852 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15853 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"() rather
15854 than call this directly.
15855 Bottom level UTF-8 decode routine. Returns the native code point
15857 value of the first character in the string "s", which is assumed to
15858 be in UTF-8 (or UTF-EBCDIC) encoding, and no longer than "curlen"
15859 bytes; *retlen (if "retlen" isn't NULL) will be set to the length,
15860 in bytes, of that character.
15861 The value of "flags" determines the behavior when "s" does not
15863 point to a well-formed UTF-8 character. If "flags" is 0,
15864 encountering a malformation causes zero to be returned and *retlen
15865 is set so that ("s" + *retlen) is the next possible position in "s"
15866 that could begin a non-malformed character. Also, if UTF-8
15867 warnings haven't been lexically disabled, a warning is raised.
15868 Some UTF-8 input sequences may contain multiple malformations.
15869 This function tries to find every possible one in each call, so
15870 multiple warnings can be raised for the same sequence.
15871 Various ALLOW flags can be set in "flags" to allow (and not warn
15873 on) individual types of malformations, such as the sequence being
15874 overlong (that is, when there is a shorter sequence that can
15875 express the same code point; overlong sequences are expressly
15876 forbidden in the UTF-8 standard due to potential security issues).
15877 Another malformation example is the first byte of a character not
15878 being a legal first byte. See utf8.h for the list of such flags.
15879 Even if allowed, this function generally returns the Unicode
15880 REPLACEMENT CHARACTER when it encounters a malformation. There are
15881 flags in utf8.h to override this behavior for the overlong
15882 malformations, but don't do that except for very specialized
15883 purposes.
15884 The "UTF8_CHECK_ONLY" flag overrides the behavior when a non-
15886 allowed (by other flags) malformation is found. If this flag is
15887 set, the routine assumes that the caller will raise a warning, and
15888 this function will silently just set "retlen" to "-1" (cast to
15889 "STRLEN") and return zero.
15890 Note that this API requires disambiguation between successful
15892 decoding a "NUL" character, and an error return (unless the
15893 "UTF8_CHECK_ONLY" flag is set), as in both cases, 0 is returned,
15894 and, depending on the malformation, "retlen" may be set to 1. To
15895 disambiguate, upon a zero return, see if the first byte of "s" is 0
15896 as well. If so, the input was a "NUL"; if not, the input had an
15897 error. Or you can use "utf8n_to_uvchr_error".
15898 Certain code points are considered problematic. These are Unicode
15900 surrogates, Unicode non-characters, and code points above the
15901 Unicode maximum of 0x10FFFF. By default these are considered
15902 regular code points, but certain situations warrant special
15903 handling for them, which can be specified using the "flags"
15904 parameter. If "flags" contains
15905 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", all three classes are treated
15906 as malformations and handled as such. The flags
15907 "UTF8_DISALLOW_SURROGATE", "UTF8_DISALLOW_NONCHAR", and
15908 "UTF8_DISALLOW_SUPER" (meaning above the legal Unicode maximum) can
15909 be set to disallow these categories individually.
15910 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed inputs to
15911 the strict UTF-8 traditionally defined by Unicode. Use
15912 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE" to use the strictness
15913 definition given by Unicode Corrigendum #9
15914 <https://www.unicode.org/versions/corrigendum9.html>. The
15915 difference between traditional strictness and C9 strictness is that
15916 the latter does not forbid non-character code points. (They are
15917 still discouraged, however.) For more discussion see "Noncharacter
15918 code points" in perlunicode.
15919 The flags "UTF8_WARN_ILLEGAL_INTERCHANGE",
15921 "UTF8_WARN_ILLEGAL_C9_INTERCHANGE", "UTF8_WARN_SURROGATE",
15922 "UTF8_WARN_NONCHAR", and "UTF8_WARN_SUPER" will cause warning
15923 messages to be raised for their respective categories, but
15924 otherwise the code points are considered valid (not malformations).
15925 To get a category to both be treated as a malformation and raise a
15926 warning, specify both the WARN and DISALLOW flags. (But note that
15927 warnings are not raised if lexically disabled nor if
15928 "UTF8_CHECK_ONLY" is also specified.)
15929 Extremely high code points were never specified in any standard,
15931 and require an extension to UTF-8 to express, which Perl does. It
15932 is likely that programs written in something other than Perl would
15933 not be able to read files that contain these; nor would Perl
15934 understand files written by something that uses a different
15935 extension. For these reasons, there is a separate set of flags
15936 that can warn and/or disallow these extremely high code points,
15937 even if other above-Unicode ones are accepted. They are the
15938 "UTF8_WARN_PERL_EXTENDED" and "UTF8_DISALLOW_PERL_EXTENDED" flags.
15939 For more information see "UTF8_GOT_PERL_EXTENDED". Of course
15940 "UTF8_DISALLOW_SUPER" will treat all above-Unicode code points,
15941 including these, as malformations. (Note that the Unicode standard
15942 considers anything above 0x10FFFF to be illegal, but there are
15943 standards predating it that allow up to 0x7FFF_FFFF (2**31 -1))
15944 A somewhat misleadingly named synonym for "UTF8_WARN_PERL_EXTENDED"
15946 is retained for backward compatibility: "UTF8_WARN_ABOVE_31_BIT".
15947 Similarly, "UTF8_DISALLOW_ABOVE_31_BIT" is usable instead of the
15948 more accurately named "UTF8_DISALLOW_PERL_EXTENDED". The names are
15949 misleading because these flags can apply to code points that
15950 actually do fit in 31 bits. This happens on EBCDIC platforms, and
15951 sometimes when the overlong malformation is also present. The new
15952 names accurately describe the situation in all cases.
15953 All other code points corresponding to Unicode characters,
15955 including private use and those yet to be assigned, are never
15956 considered malformed and never warn.
15957 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen,
15959 const U32 flags)
15960 "utf8n_to_uvchr_error"
15962 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
15963 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"() rather
15964 than call this directly.
15965 This function is for code that needs to know what the precise
15967 malformation(s) are when an error is found. If you also need to
15968 know the generated warning messages, use "utf8n_to_uvchr_msgs"()
15969 instead.
15970 It is like "utf8n_to_uvchr" but it takes an extra parameter placed
15972 after all the others, "errors". If this parameter is 0, this
15973 function behaves identically to "utf8n_to_uvchr". Otherwise,
15974 "errors" should be a pointer to a "U32" variable, which this
15975 function sets to indicate any errors found. Upon return, if
15976 *errors is 0, there were no errors found. Otherwise, *errors is
15977 the bit-wise "OR" of the bits described in the list below. Some of
15978 these bits will be set if a malformation is found, even if the
15979 input "flags" parameter indicates that the given malformation is
15980 allowed; those exceptions are noted:
15981 "UTF8_GOT_PERL_EXTENDED"
15983 The input sequence is not standard UTF-8, but a Perl extension.
15984 This bit is set only if the input "flags" parameter contains
15985 either the "UTF8_DISALLOW_PERL_EXTENDED" or the
15986 "UTF8_WARN_PERL_EXTENDED" flags.
15987 Code points above 0x7FFF_FFFF (2**31 - 1) were never specified
15989 in any standard, and so some extension must be used to express
15990 them. Perl uses a natural extension to UTF-8 to represent the
15991 ones up to 2**36-1, and invented a further extension to
15992 represent even higher ones, so that any code point that fits in
15993 a 64-bit word can be represented. Text using these extensions
15994 is not likely to be portable to non-Perl code. We lump both of
15995 these extensions together and refer to them as Perl extended
15996 UTF-8. There exist other extensions that people have invented,
15997 incompatible with Perl's.
15998 On EBCDIC platforms starting in Perl v5.24, the Perl extension
16000 for representing extremely high code points kicks in at
16001 0x3FFF_FFFF (2**30 -1), which is lower than on ASCII. Prior to
16002 that, code points 2**31 and higher were simply unrepresentable,
16003 and a different, incompatible method was used to represent code
16004 points between 2**30 and 2**31 - 1.
16005 On both platforms, ASCII and EBCDIC, "UTF8_GOT_PERL_EXTENDED"
16007 is set if Perl extended UTF-8 is used.
16008 In earlier Perls, this bit was named "UTF8_GOT_ABOVE_31_BIT",
16010 which you still may use for backward compatibility. That name
16011 is misleading, as this flag may be set when the code point
16012 actually does fit in 31 bits. This happens on EBCDIC
16013 platforms, and sometimes when the overlong malformation is also
16014 present. The new name accurately describes the situation in
16015 all cases.
16016 "UTF8_GOT_CONTINUATION"
16018 The input sequence was malformed in that the first byte was a
16019 UTF-8 continuation byte.
16020 "UTF8_GOT_EMPTY"
16022 The input "curlen" parameter was 0.
16023 "UTF8_GOT_LONG"
16025 The input sequence was malformed in that there is some other
16026 sequence that evaluates to the same code point, but that
16027 sequence is shorter than this one.
16028 Until Unicode 3.1, it was legal for programs to accept this
16030 malformation, but it was discovered that this created security
16031 issues.
16032 "UTF8_GOT_NONCHAR"
16034 The code point represented by the input UTF-8 sequence is for a
16035 Unicode non-character code point. This bit is set only if the
16036 input "flags" parameter contains either the
16037 "UTF8_DISALLOW_NONCHAR" or the "UTF8_WARN_NONCHAR" flags.
16038 "UTF8_GOT_NON_CONTINUATION"
16040 The input sequence was malformed in that a non-continuation
16041 type byte was found in a position where only a continuation
16042 type one should be. See also "UTF8_GOT_SHORT".
16043 "UTF8_GOT_OVERFLOW"
16045 The input sequence was malformed in that it is for a code point
16046 that is not representable in the number of bits available in an
16047 IV on the current platform.
16048 "UTF8_GOT_SHORT"
16050 The input sequence was malformed in that "curlen" is smaller
16051 than required for a complete sequence. In other words, the
16052 input is for a partial character sequence.
16053 "UTF8_GOT_SHORT" and "UTF8_GOT_NON_CONTINUATION" both indicate
16055 a too short sequence. The difference is that
16056 "UTF8_GOT_NON_CONTINUATION" indicates always that there is an
16057 error, while "UTF8_GOT_SHORT" means that an incomplete sequence
16058 was looked at. If no other flags are present, it means that
16059 the sequence was valid as far as it went. Depending on the
16060 application, this could mean one of three things:
16061 • The "curlen" length parameter passed in was too small, and
16063 the function was prevented from examining all the necessary
16064 bytes.
16065 • The buffer being looked at is based on reading data, and
16067 the data received so far stopped in the middle of a
16068 character, so that the next read will read the remainder of
16069 this character. (It is up to the caller to deal with the
16070 split bytes somehow.)
16071 • This is a real error, and the partial sequence is all we're
16073 going to get.
16074 "UTF8_GOT_SUPER"
16076 The input sequence was malformed in that it is for a non-
16077 Unicode code point; that is, one above the legal Unicode
16078 maximum. This bit is set only if the input "flags" parameter
16079 contains either the "UTF8_DISALLOW_SUPER" or the
16080 "UTF8_WARN_SUPER" flags.
16081 "UTF8_GOT_SURROGATE"
16083 The input sequence was malformed in that it is for a -Unicode
16084 UTF-16 surrogate code point. This bit is set only if the input
16085 "flags" parameter contains either the "UTF8_DISALLOW_SURROGATE"
16086 or the "UTF8_WARN_SURROGATE" flags.
16087 To do your own error handling, call this function with the
16089 "UTF8_CHECK_ONLY" flag to suppress any warnings, and then examine
16090 the *errors return.
16091 UV utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
16093 STRLEN *retlen, const U32 flags,
16094 U32 * errors)
16095 "utf8n_to_uvchr_msgs"
16097 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
16098 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"() rather
16099 than call this directly.
16100 This function is for code that needs to know what the precise
16102 malformation(s) are when an error is found, and wants the
16103 corresponding warning and/or error messages to be returned to the
16104 caller rather than be displayed. All messages that would have been
16105 displayed if all lexical warnings are enabled will be returned.
16106 It is just like "utf8n_to_uvchr_error" but it takes an extra
16108 parameter placed after all the others, "msgs". If this parameter
16109 is 0, this function behaves identically to "utf8n_to_uvchr_error".
16110 Otherwise, "msgs" should be a pointer to an "AV *" variable, in
16111 which this function creates a new AV to contain any appropriate
16112 messages. The elements of the array are ordered so that the first
16113 message that would have been displayed is in the 0th element, and
16114 so on. Each element is a hash with three key-value pairs, as
16115 follows:
16116 "text"
16118 The text of the message as a "SVpv".
16119 "warn_categories"
16121 The warning category (or categories) packed into a "SVuv".
16122 "flag"
16124 A single flag bit associated with this message, in a "SVuv".
16125 The bit corresponds to some bit in the *errors return value,
16126 such as "UTF8_GOT_LONG".
16127 It's important to note that specifying this parameter as non-null
16129 will cause any warnings this function would otherwise generate to
16130 be suppressed, and instead be placed in *msgs. The caller can
16131 check the lexical warnings state (or not) when choosing what to do
16132 with the returned messages.
16133 If the flag "UTF8_CHECK_ONLY" is passed, no warnings are generated,
16135 and hence no AV is created.
16136 The caller, of course, is responsible for freeing any returned AV.
16138 UV utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
16140 STRLEN *retlen, const U32 flags,
16141 U32 * errors, AV ** msgs)
16142 "UTF8SKIP"
16144 returns the number of bytes a non-malformed UTF-8 encoded character
16145 whose first (perhaps only) byte is pointed to by "s".
16146 If there is a possibility of malformed input, use instead:
16148 "UTF8_SAFE_SKIP" if you know the maximum ending pointer in the
16150 buffer pointed to by "s"; or
16151 "UTF8_CHK_SKIP" if you don't know it.
16152 It is better to restructure your code so the end pointer is passed
16154 down so that you know what it actually is at the point of this
16155 call, but if that isn't possible, "UTF8_CHK_SKIP" can minimize the
16156 chance of accessing beyond the end of the input buffer.
16157 STRLEN UTF8SKIP(char* s)
16159 "UTF8_CHK_SKIP"
16161 This is a safer version of "UTF8SKIP", but still not as safe as
16162 "UTF8_SAFE_SKIP". This version doesn't blindly assume that the
16163 input string pointed to by "s" is well-formed, but verifies that
16164 there isn't a NUL terminating character before the expected end of
16165 the next character in "s". The length "UTF8_CHK_SKIP" returns
16166 stops just before any such NUL.
16167 Perl tends to add NULs, as an insurance policy, after the end of
16169 strings in SV's, so it is likely that using this macro will prevent
16170 inadvertent reading beyond the end of the input buffer, even if it
16171 is malformed UTF-8.
16172 This macro is intended to be used by XS modules where the inputs
16174 could be malformed, and it isn't feasible to restructure to use the
16175 safer "UTF8_SAFE_SKIP", for example when interfacing with a C
16176 library.
16177 STRLEN UTF8_CHK_SKIP(char* s)
16179 "utf8_distance"
16181 Returns the number of UTF-8 characters between the UTF-8 pointers
16182 "a" and "b".
16183 WARNING: use only if you *know* that the pointers point inside the
16185 same UTF-8 buffer.
16186 IV utf8_distance(const U8 *a, const U8 *b)
16188 "utf8_hop"
16190 Return the UTF-8 pointer "s" displaced by "off" characters, either
16191 forward or backward.
16192 WARNING: do not use the following unless you *know* "off" is within
16194 the UTF-8 data pointed to by "s" *and* that on entry "s" is aligned
16195 on the first byte of character or just after the last byte of a
16196 character.
16197 U8* utf8_hop(const U8 *s, SSize_t off)
16199 "utf8_hop_back"
16201 Return the UTF-8 pointer "s" displaced by up to "off" characters,
16202 backward.
16203 "off" must be non-positive.
16205 "s" must be after or equal to "start".
16207 When moving backward it will not move before "start".
16209 Will not exceed this limit even if the string is not valid "UTF-8".
16211 U8* utf8_hop_back(const U8 *s, SSize_t off, const U8 *start)
16213 "utf8_hop_forward"
16215 Return the UTF-8 pointer "s" displaced by up to "off" characters,
16216 forward.
16217 "off" must be non-negative.
16219 "s" must be before or equal to "end".
16221 When moving forward it will not move beyond "end".
16223 Will not exceed this limit even if the string is not valid "UTF-8".
16225 U8* utf8_hop_forward(const U8 *s, SSize_t off, const U8 *end)
16227 "utf8_hop_safe"
16229 Return the UTF-8 pointer "s" displaced by up to "off" characters,
16230 either forward or backward.
16231 When moving backward it will not move before "start".
16233 When moving forward it will not move beyond "end".
16235 Will not exceed those limits even if the string is not valid
16237 "UTF-8".
16238 U8* utf8_hop_safe(const U8 *s, SSize_t off, const U8 *start,
16240 const U8 *end)
16241 "UTF8_IS_INVARIANT"
16243 Evaluates to 1 if the byte "c" represents the same character when
16244 encoded in UTF-8 as when not; otherwise evaluates to 0. UTF-8
16245 invariant characters can be copied as-is when converting to/from
16246 UTF-8, saving time.
16247 In spite of the name, this macro gives the correct result if the
16249 input string from which "c" comes is not encoded in UTF-8.
16250 See "UVCHR_IS_INVARIANT" for checking if a UV is invariant.
16252 bool UTF8_IS_INVARIANT(char c)
16254 "UTF8_IS_NONCHAR"
16256 Evaluates to non-zero if the first few bytes of the string starting
16257 at "s" and looking no further than "e - 1" are well-formed UTF-8
16258 that represents one of the Unicode non-character code points;
16259 otherwise it evaluates to 0. If non-zero, the value gives how many
16260 bytes starting at "s" comprise the code point's representation.
16261 bool UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
16263 "UTF8_IS_REPLACEMENT"
16265 Evaluates to non-zero if the first few bytes of the string starting
16266 at "s" and looking no further than "e - 1" are well-formed UTF-8
16267 that represents the Unicode REPLACEMENT CHARACTER; otherwise it
16268 evaluates to 0. If non-zero, the value gives how many bytes
16269 starting at "s" comprise the code point's representation.
16270 bool UTF8_IS_REPLACEMENT(const U8 *s, const U8 *e)
16272 "UTF8_IS_SUPER"
16274 Recall that Perl recognizes an extension to UTF-8 that can encode
16275 code points larger than the ones defined by Unicode, which are
16276 0..0x10FFFF.
16277 This macro evaluates to non-zero if the first few bytes of the
16279 string starting at "s" and looking no further than "e - 1" are from
16280 this UTF-8 extension; otherwise it evaluates to 0. If non-zero,
16281 the return is how many bytes starting at "s" comprise the code
16282 point's representation.
16283 0 is returned if the bytes are not well-formed extended UTF-8, or
16285 if they represent a code point that cannot fit in a UV on the
16286 current platform. Hence this macro can give different results when
16287 run on a 64-bit word machine than on one with a 32-bit word size.
16288 Note that it is illegal in Perl to have code points that are larger
16290 than what can fit in an IV on the current machine; and illegal in
16291 Unicode to have any that this macro matches
16292 bool UTF8_IS_SUPER(const U8 *s, const U8 *e)
16294 "UTF8_IS_SURROGATE"
16296 Evaluates to non-zero if the first few bytes of the string starting
16297 at "s" and looking no further than "e - 1" are well-formed UTF-8
16298 that represents one of the Unicode surrogate code points; otherwise
16299 it evaluates to 0. If non-zero, the value gives how many bytes
16300 starting at "s" comprise the code point's representation.
16301 bool UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
16303 "utf8_length"
16305 Returns the number of characters in the sequence of UTF-8-encoded
16306 bytes starting at "s" and ending at the byte just before "e". If
16307 <s> and <e> point to the same place, it returns 0 with no warning
16308 raised.
16309 If "e < s" or if the scan would end up past "e", it raises a UTF8
16311 warning and returns the number of valid characters.
16312 STRLEN utf8_length(const U8* s, const U8 *e)
16314 "UTF8_MAXBYTES"
16316 The maximum width of a single UTF-8 encoded character, in bytes.
16317 NOTE: Strictly speaking Perl's UTF-8 should not be called UTF-8
16319 since UTF-8 is an encoding of Unicode, and Unicode's upper limit,
16320 0x10FFFF, can be expressed with 4 bytes. However, Perl thinks of
16321 UTF-8 as a way to encode non-negative integers in a binary format,
16322 even those above Unicode.
16323 "UTF8_MAXBYTES_CASE"
16325 The maximum number of UTF-8 bytes a single Unicode character can
16326 uppercase/lowercase/titlecase/fold into.
16327 "UTF8_SAFE_SKIP"
16329 returns 0 if "s >= e"; otherwise returns the number of bytes in the
16330 UTF-8 encoded character whose first byte is pointed to by "s".
16331 But it never returns beyond "e". On DEBUGGING builds, it asserts
16332 that "s <= e".
16333 STRLEN UTF8_SAFE_SKIP(char* s, char* e)
16335 "UTF8_SKIP"
16337 This is a synonym for "UTF8SKIP"
16338 STRLEN UTF8_SKIP(char* s)
16340 "utf8_to_bytes"
16342 NOTE: "utf8_to_bytes" is experimental and may change or be removed
16343 without notice.
16344 Converts a string "s" of length *lenp from UTF-8 into native byte
16346 encoding. Unlike "bytes_to_utf8", this over-writes the original
16347 string, and updates *lenp to contain the new length. Returns zero
16348 on failure (leaving "s" unchanged) setting *lenp to -1.
16349 Upon successful return, the number of variants in the string can be
16351 computed by having saved the value of *lenp before the call, and
16352 subtracting the after-call value of *lenp from it.
16353 If you need a copy of the string, see "bytes_from_utf8".
16355 U8* utf8_to_bytes(U8 *s, STRLEN *lenp)
16357 "utf8_to_uvchr"
16359 "DEPRECATED!" It is planned to remove "utf8_to_uvchr" from a
16360 future release of Perl. Do not use it for new code; remove it from
16361 existing code.
16362 Returns the native code point of the first character in the string
16364 "s" which is assumed to be in UTF-8 encoding; "retlen" will be set
16365 to the length, in bytes, of that character.
16366 Some, but not all, UTF-8 malformations are detected, and in fact,
16368 some malformed input could cause reading beyond the end of the
16369 input buffer, which is why this function is deprecated. Use
16370 "utf8_to_uvchr_buf" instead.
16371 If "s" points to one of the detected malformations, and UTF8
16373 warnings are enabled, zero is returned and *retlen is set (if
16374 "retlen" isn't "NULL") to -1. If those warnings are off, the
16375 computed value if well-defined (or the Unicode REPLACEMENT
16376 CHARACTER, if not) is silently returned, and *retlen is set (if
16377 "retlen" isn't NULL) so that ("s" + *retlen) is the next possible
16378 position in "s" that could begin a non-malformed character. See
16379 "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is
16380 returned.
16381 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
16383 "utf8_to_uvchr_buf"
16385 Returns the native code point of the first character in the string
16386 "s" which is assumed to be in UTF-8 encoding; "send" points to 1
16387 beyond the end of "s". *retlen will be set to the length, in
16388 bytes, of that character.
16389 If "s" does not point to a well-formed UTF-8 character and UTF8
16391 warnings are enabled, zero is returned and *retlen is set (if
16392 "retlen" isn't "NULL") to -1. If those warnings are off, the
16393 computed value, if well-defined (or the Unicode REPLACEMENT
16394 CHARACTER if not), is silently returned, and *retlen is set (if
16395 "retlen" isn't "NULL") so that ("s" + *retlen) is the next possible
16396 position in "s" that could begin a non-malformed character. See
16397 "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is
16398 returned.
16399 UV utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen)
16401 "UVCHR_IS_INVARIANT"
16403 Evaluates to 1 if the representation of code point "cp" is the same
16404 whether or not it is encoded in UTF-8; otherwise evaluates to 0.
16405 UTF-8 invariant characters can be copied as-is when converting
16406 to/from UTF-8, saving time. "cp" is Unicode if above 255;
16407 otherwise is platform-native.
16408 bool UVCHR_IS_INVARIANT(UV cp)
16410 "UVCHR_SKIP"
16412 returns the number of bytes required to represent the code point
16413 "cp" when encoded as UTF-8. "cp" is a native (ASCII or EBCDIC)
16414 code point if less than 255; a Unicode code point otherwise.
16415 STRLEN UVCHR_SKIP(UV cp)
16417 "uvchr_to_utf8"
16419 Adds the UTF-8 representation of the native code point "uv" to the
16420 end of the string "d"; "d" should have at least "UVCHR_SKIP(uv)+1"
16421 (up to "UTF8_MAXBYTES+1") free bytes available. The return value
16422 is the pointer to the byte after the end of the new character. In
16423 other words,
16424 d = uvchr_to_utf8(d, uv);
16426 is the recommended wide native character-aware way of saying
16428 *(d++) = uv;
16430 This function accepts any code point from 0.."IV_MAX" as input.
16432 "IV_MAX" is typically 0x7FFF_FFFF in a 32-bit word.
16433 It is possible to forbid or warn on non-Unicode code points, or
16435 those that may be problematic by using "uvchr_to_utf8_flags".
16436 U8* uvchr_to_utf8(U8 *d, UV uv)
16438 "uvchr_to_utf8_flags"
16440 Adds the UTF-8 representation of the native code point "uv" to the
16441 end of the string "d"; "d" should have at least "UVCHR_SKIP(uv)+1"
16442 (up to "UTF8_MAXBYTES+1") free bytes available. The return value
16443 is the pointer to the byte after the end of the new character. In
16444 other words,
16445 d = uvchr_to_utf8_flags(d, uv, flags);
16447 or, in most cases,
16449 d = uvchr_to_utf8_flags(d, uv, 0);
16451 This is the Unicode-aware way of saying
16453 *(d++) = uv;
16455 If "flags" is 0, this function accepts any code point from
16457 0.."IV_MAX" as input. "IV_MAX" is typically 0x7FFF_FFFF in a
16458 32-bit word.
16459 Specifying "flags" can further restrict what is allowed and not
16461 warned on, as follows:
16462 If "uv" is a Unicode surrogate code point and
16464 "UNICODE_WARN_SURROGATE" is set, the function will raise a warning,
16465 provided UTF8 warnings are enabled. If instead
16466 "UNICODE_DISALLOW_SURROGATE" is set, the function will fail and
16467 return NULL. If both flags are set, the function will both warn
16468 and return NULL.
16469 Similarly, the "UNICODE_WARN_NONCHAR" and
16471 "UNICODE_DISALLOW_NONCHAR" flags affect how the function handles a
16472 Unicode non-character.
16473 And likewise, the "UNICODE_WARN_SUPER" and "UNICODE_DISALLOW_SUPER"
16475 flags affect the handling of code points that are above the Unicode
16476 maximum of 0x10FFFF. Languages other than Perl may not be able to
16477 accept files that contain these.
16478 The flag "UNICODE_WARN_ILLEGAL_INTERCHANGE" selects all three of
16480 the above WARN flags; and "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE"
16481 selects all three DISALLOW flags.
16482 "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed inputs
16483 to the strict UTF-8 traditionally defined by Unicode. Similarly,
16484 "UNICODE_WARN_ILLEGAL_C9_INTERCHANGE" and
16485 "UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE" are shortcuts to select
16486 the above-Unicode and surrogate flags, but not the non-character
16487 ones, as defined in Unicode Corrigendum #9
16488 <https://www.unicode.org/versions/corrigendum9.html>. See
16489 "Noncharacter code points" in perlunicode.
16490 Extremely high code points were never specified in any standard,
16492 and require an extension to UTF-8 to express, which Perl does. It
16493 is likely that programs written in something other than Perl would
16494 not be able to read files that contain these; nor would Perl
16495 understand files written by something that uses a different
16496 extension. For these reasons, there is a separate set of flags
16497 that can warn and/or disallow these extremely high code points,
16498 even if other above-Unicode ones are accepted. They are the
16499 "UNICODE_WARN_PERL_EXTENDED" and "UNICODE_DISALLOW_PERL_EXTENDED"
16500 flags. For more information see "UTF8_GOT_PERL_EXTENDED". Of
16501 course "UNICODE_DISALLOW_SUPER" will treat all above-Unicode code
16502 points, including these, as malformations. (Note that the Unicode
16503 standard considers anything above 0x10FFFF to be illegal, but there
16504 are standards predating it that allow up to 0x7FFF_FFFF (2**31 -1))
16505 A somewhat misleadingly named synonym for
16507 "UNICODE_WARN_PERL_EXTENDED" is retained for backward
16508 compatibility: "UNICODE_WARN_ABOVE_31_BIT". Similarly,
16509 "UNICODE_DISALLOW_ABOVE_31_BIT" is usable instead of the more
16510 accurately named "UNICODE_DISALLOW_PERL_EXTENDED". The names are
16511 misleading because on EBCDIC platforms,these flags can apply to
16512 code points that actually do fit in 31 bits. The new names
16513 accurately describe the situation in all cases.
16514 U8* uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
16516 "uvchr_to_utf8_flags_msgs"
16518 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
16519 CIRCUMSTANCES.
16520 Most code should use ""uvchr_to_utf8_flags"()" rather than call
16522 this directly.
16523 This function is for code that wants any warning and/or error
16525 messages to be returned to the caller rather than be displayed.
16526 All messages that would have been displayed if all lexical warnings
16527 are enabled will be returned.
16528 It is just like "uvchr_to_utf8_flags" but it takes an extra
16530 parameter placed after all the others, "msgs". If this parameter
16531 is 0, this function behaves identically to "uvchr_to_utf8_flags".
16532 Otherwise, "msgs" should be a pointer to an "HV *" variable, in
16533 which this function creates a new HV to contain any appropriate
16534 messages. The hash has three key-value pairs, as follows:
16535 "text"
16537 The text of the message as a "SVpv".
16538 "warn_categories"
16540 The warning category (or categories) packed into a "SVuv".
16541 "flag"
16543 A single flag bit associated with this message, in a "SVuv".
16544 The bit corresponds to some bit in the *errors return value,
16545 such as "UNICODE_GOT_SURROGATE".
16546 It's important to note that specifying this parameter as non-null
16548 will cause any warnings this function would otherwise generate to
16549 be suppressed, and instead be placed in *msgs. The caller can
16550 check the lexical warnings state (or not) when choosing what to do
16551 with the returned messages.
16552 The caller, of course, is responsible for freeing any returned HV.
16554 U8* uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags, HV ** msgs)
16556
16558 "C_ARRAY_END"
16559 Returns a pointer to one element past the final element of the
16560 input C array.
16561 void * C_ARRAY_END(void *a)
16563 "C_ARRAY_LENGTH"
16565 Returns the number of elements in the input C array (so you want
16566 your zero-based indices to be less than but not equal to).
16567 STRLEN C_ARRAY_LENGTH(void *a)
16569 "getcwd_sv"
16571 Fill "sv" with current working directory
16572 int getcwd_sv(SV* sv)
16574 "IN_PERL_COMPILETIME"
16576 Returns 1 if this macro is being called during the compilation
16577 phase of the program; otherwise 0;
16578 bool IN_PERL_COMPILETIME
16580 "IN_PERL_RUNTIME"
16582 Returns 1 if this macro is being called during the execution phase
16583 of the program; otherwise 0;
16584 bool IN_PERL_RUNTIME
16586 "IS_SAFE_SYSCALL"
16588 Same as "is_safe_syscall".
16589 bool IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
16591 NN const char *what, NN const char *op_name)
16592 "is_safe_syscall"
16594 Test that the given "pv" (with length "len") doesn't contain any
16595 internal "NUL" characters. If it does, set "errno" to "ENOENT",
16596 optionally warn using the "syscalls" category, and return FALSE.
16597 Return TRUE if the name is safe.
16599 "what" and "op_name" are used in any warning.
16601 Used by the "IS_SAFE_SYSCALL()" macro.
16603 bool is_safe_syscall(const char *pv, STRLEN len,
16605 const char *what, const char *op_name)
16606 "my_setenv"
16608 A wrapper for the C library setenv(3). Don't use the latter, as
16609 the perl version has desirable safeguards
16610 void my_setenv(const char* nam, const char* val)
16612 "phase_name"
16614 Returns the given phase's name as a NUL-terminated string.
16615 For example, to print a stack trace that includes the current
16617 interpreter phase you might do:
16618 const char* phase_name = phase_name(PL_phase);
16620 mess("This is weird. (Perl phase: %s)", phase_name);
16621 const char *const phase_name(enum perl_phase)
16623 "Poison"
16625 PoisonWith(0xEF) for catching access to freed memory.
16626 void Poison(void* dest, int nitems, type)
16628 "PoisonFree"
16630 PoisonWith(0xEF) for catching access to freed memory.
16631 void PoisonFree(void* dest, int nitems, type)
16633 "PoisonNew"
16635 PoisonWith(0xAB) for catching access to allocated but uninitialized
16636 memory.
16637 void PoisonNew(void* dest, int nitems, type)
16639 "PoisonWith"
16641 Fill up memory with a byte pattern (a byte repeated over and over
16642 again) that hopefully catches attempts to access uninitialized
16643 memory.
16644 void PoisonWith(void* dest, int nitems, type, U8 byte)
16646 "StructCopy"
16648 This is an architecture-independent macro to copy one structure to
16649 another.
16650 void StructCopy(type *src, type *dest, type)
16652 "sv_destroyable"
16654 Dummy routine which reports that object can be destroyed when there
16655 is no sharing module present. It ignores its single SV argument,
16656 and returns 'true'. Exists to avoid test for a "NULL" function
16657 pointer and because it could potentially warn under some level of
16658 strict-ness.
16659 bool sv_destroyable(SV *sv)
16661 "sv_nosharing"
16663 Dummy routine which "shares" an SV when there is no sharing module
16664 present. Or "locks" it. Or "unlocks" it. In other words, ignores
16665 its single SV argument. Exists to avoid test for a "NULL" function
16666 pointer and because it could potentially warn under some level of
16667 strict-ness.
16668 void sv_nosharing(SV *sv)
16670
16672 "new_version"
16673 Returns a new version object based on the passed in SV:
16674 SV *sv = new_version(SV *ver);
16676 Does not alter the passed in ver SV. See "upg_version" if you want
16678 to upgrade the SV.
16679 SV* new_version(SV *ver)
16681 "PERL_REVISION"
16683 "DEPRECATED!" It is planned to remove "PERL_REVISION" from a
16684 future release of Perl. Do not use it for new code; remove it from
16685 existing code.
16686 The major number component of the perl interpreter currently being
16688 compiled or executing. This has been 5 from 1993 into 2020.
16689 Instead use one of the version comparison macros. See
16691 "PERL_VERSION_EQ".
16692 "PERL_SUBVERSION"
16694 "DEPRECATED!" It is planned to remove "PERL_SUBVERSION" from a
16695 future release of Perl. Do not use it for new code; remove it from
16696 existing code.
16697 The micro number component of the perl interpreter currently being
16699 compiled or executing. In stable releases this gives the dot
16700 release number for maintenance updates. In development releases
16701 this gives a tag for a snapshot of the status at various points in
16702 the development cycle.
16703 Instead use one of the version comparison macros. See
16705 "PERL_VERSION_EQ".
16706 "PERL_VERSION"
16708 "DEPRECATED!" It is planned to remove "PERL_VERSION" from a future
16709 release of Perl. Do not use it for new code; remove it from
16710 existing code.
16711 The minor number component of the perl interpreter currently being
16713 compiled or executing. Between 1993 into 2020, this has ranged
16714 from 0 to 33.
16715 Instead use one of the version comparison macros. See
16717 "PERL_VERSION_EQ".
16718 "PERL_VERSION_EQ"
16720 "PERL_VERSION_NE"
16721 "PERL_VERSION_LT"
16722 "PERL_VERSION_LE"
16723 "PERL_VERSION_GT"
16724 "PERL_VERSION_GE"
16725 Returns whether or not the perl currently being compiled has the
16726 specified relationship to the perl given by the parameters. For
16727 example,
16728 #if PERL_VERSION_GT(5,24,2)
16730 code that will only be compiled on perls after v5.24.2
16731 #else
16732 fallback code
16733 #endif
16734 Note that this is usable in making compile-time decisions
16736 You may use the special value '*' for the final number to mean ALL
16738 possible values for it. Thus,
16739 #if PERL_VERSION_EQ(5,31,'*')
16741 means all perls in the 5.31 series. And
16743 #if PERL_VERSION_NE(5,24,'*')
16745 means all perls EXCEPT 5.24 ones. And
16747 #if PERL_VERSION_LE(5,9,'*')
16749 is effectively
16751 #if PERL_VERSION_LT(5,10,0)
16753 This means you don't have to think so much when converting from the
16755 existing deprecated "PERL_VERSION" to using this macro:
16756 #if PERL_VERSION <= 9
16758 becomes
16760 #if PERL_VERSION_LE(5,9,'*')
16762 bool PERL_VERSION_EQ(const U8 major, const U8 minor,
16764 const U8 patch)
16765 "prescan_version"
16767 Validate that a given string can be parsed as a version object, but
16768 doesn't actually perform the parsing. Can use either strict or lax
16769 validation rules. Can optionally set a number of hint variables to
16770 save the parsing code some time when tokenizing.
16771 const char* prescan_version(const char *s, bool strict,
16773 const char** errstr, bool *sqv,
16774 int *ssaw_decimal, int *swidth,
16775 bool *salpha)
16776 "scan_version"
16778 Returns a pointer to the next character after the parsed version
16779 string, as well as upgrading the passed in SV to an RV.
16780 Function must be called with an already existing SV like
16782 sv = newSV(0);
16784 s = scan_version(s, SV *sv, bool qv);
16785 Performs some preprocessing to the string to ensure that it has the
16787 correct characteristics of a version. Flags the object if it
16788 contains an underscore (which denotes this is an alpha version).
16789 The boolean qv denotes that the version should be interpreted as if
16790 it had multiple decimals, even if it doesn't.
16791 const char* scan_version(const char *s, SV *rv, bool qv)
16793 "upg_version"
16795 In-place upgrade of the supplied SV to a version object.
16796 SV *sv = upg_version(SV *sv, bool qv);
16798 Returns a pointer to the upgraded SV. Set the boolean qv if you
16800 want to force this SV to be interpreted as an "extended" version.
16801 SV* upg_version(SV *ver, bool qv)
16803 "vcmp"
16805 Version object aware cmp. Both operands must already have been
16806 converted into version objects.
16807 int vcmp(SV *lhv, SV *rhv)
16809 "vnormal"
16811 Accepts a version object and returns the normalized string
16812 representation. Call like:
16813 sv = vnormal(rv);
16815 NOTE: you can pass either the object directly or the SV contained
16817 within the RV.
16818 The SV returned has a refcount of 1.
16820 SV* vnormal(SV *vs)
16822 "vnumify"
16824 Accepts a version object and returns the normalized floating point
16825 representation. Call like:
16826 sv = vnumify(rv);
16828 NOTE: you can pass either the object directly or the SV contained
16830 within the RV.
16831 The SV returned has a refcount of 1.
16833 SV* vnumify(SV *vs)
16835 "vstringify"
16837 In order to maintain maximum compatibility with earlier versions of
16838 Perl, this function will return either the floating point notation
16839 or the multiple dotted notation, depending on whether the original
16840 version contained 1 or more dots, respectively.
16841 The SV returned has a refcount of 1.
16843 SV* vstringify(SV *vs)
16845 "vverify"
16847 Validates that the SV contains valid internal structure for a
16848 version object. It may be passed either the version object (RV) or
16849 the hash itself (HV). If the structure is valid, it returns the
16850 HV. If the structure is invalid, it returns NULL.
16851 SV *hv = vverify(sv);
16853 Note that it only confirms the bare minimum structure (so as not to
16855 get confused by derived classes which may contain additional hash
16856 entries):
16857 • The SV is an HV or a reference to an HV
16859 • The hash contains a "version" key
16861 • The "version" key has a reference to an AV as its value
16863 SV* vverify(SV *vs)
16865
16867 In all these calls, the "U32 wn" parameters are warning category
16868 constants. You can see the ones currently available in "Category
16869 Hierarchy" in warnings, just capitalize all letters in the names and
16870 prefix them by "WARN_". So, for example, the category "void" used in a
16871 perl program becomes "WARN_VOID" when used in XS code and passed to one
16872 of the calls below.
16873 "ckWARN"
16875 "ckWARN2"
16876 "ckWARN3"
16877 "ckWARN4"
16878 These return a boolean as to whether or not warnings are enabled
16879 for any of the warning category(ies) parameters: "w", "w1", ....
16880 Should any of the categories by default be enabled even if not
16882 within the scope of "use warnings", instead use the "ckWARN_d"
16883 macros.
16884 The categories must be completely independent, one may not be
16886 subclassed from the other.
16887 bool ckWARN (U32 w)
16889 bool ckWARN2(U32 w1, U32 w2)
16890 bool ckWARN3(U32 w1, U32 w2, U32 w3)
16891 bool ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
16892 "ckWARN_d"
16894 "ckWARN2_d"
16895 "ckWARN3_d"
16896 "ckWARN4_d"
16897 Like "ckWARN", but for use if and only if the warning category(ies)
16898 is by default enabled even if not within the scope of
16899 "use warnings".
16900 bool ckWARN_d (U32 w)
16902 bool ckWARN2_d(U32 w1, U32 w2)
16903 bool ckWARN3_d(U32 w1, U32 w2, U32 w3)
16904 bool ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
16905 "ck_warner"
16907 "ck_warner_d"
16908 If none of the warning categories given by "err" are enabled, do
16909 nothing; otherwise call "warner" or "warner_nocontext" with the
16910 passed-in parameters;.
16911 "err" must be one of the "packWARN", "packWARN2", "packWARN3",
16913 "packWARN4" macros populated with the appropriate number of warning
16914 categories.
16915 The two forms differ only in that "ck_warner_d" should be used if
16917 warnings for any of the categories are by default enabled.
16918 NOTE: "ck_warner" must be explicitly called as "Perl_ck_warner"
16920 with an "aTHX_" parameter.
16921 NOTE: "ck_warner_d" must be explicitly called as "Perl_ck_warner_d"
16923 with an "aTHX_" parameter.
16924 void Perl_ck_warner(pTHX_ U32 err, const char* pat, ...)
16926 "CLEAR_ERRSV"
16928 Clear the contents of $@, setting it to the empty string.
16929 This replaces any read-only SV with a fresh SV and removes any
16931 magic.
16932 void CLEAR_ERRSV()
16934 "croak"
16936 "croak_nocontext"
16937 These are XS interfaces to Perl's "die" function.
16938 They take a sprintf-style format pattern and argument list, which
16940 are used to generate a string message. If the message does not end
16941 with a newline, then it will be extended with some indication of
16942 the current location in the code, as described for "mess_sv".
16943 The error message will be used as an exception, by default
16945 returning control to the nearest enclosing "eval", but subject to
16946 modification by a $SIG{__DIE__} handler. In any case, these croak
16947 functions never return normally.
16948 For historical reasons, if "pat" is null then the contents of
16950 "ERRSV" ($@) will be used as an error message or object instead of
16951 building an error message from arguments. If you want to throw a
16952 non-string object, or build an error message in an SV yourself, it
16953 is preferable to use the "croak_sv" function, which does not
16954 involve clobbering "ERRSV".
16955 The two forms differ only in that "croak_nocontext" does not take a
16957 thread context ("aTHX") parameter. It is usually preferred as it
16958 takes up fewer bytes of code than plain "Perl_croak", and time is
16959 rarely a critical resource when you are about to throw an
16960 exception.
16961 NOTE: "croak" must be explicitly called as "Perl_croak" with an
16963 "aTHX_" parameter.
16964 void Perl_croak (pTHX_ const char* pat, ...)
16966 void croak_nocontext(const char* pat, ...)
16967 "croak_no_modify"
16969 This encapsulates a common reason for dying, generating terser
16970 object code than using the generic "Perl_croak". It is exactly
16971 equivalent to "Perl_croak(aTHX_ "%s", PL_no_modify)" (which expands
16972 to something like "Modification of a read-only value attempted").
16973 Less code used on exception code paths reduces CPU cache pressure.
16975 void croak_no_modify()
16977 "croak_sv"
16979 This is an XS interface to Perl's "die" function.
16980 "baseex" is the error message or object. If it is a reference, it
16982 will be used as-is. Otherwise it is used as a string, and if it
16983 does not end with a newline then it will be extended with some
16984 indication of the current location in the code, as described for
16985 "mess_sv".
16986 The error message or object will be used as an exception, by
16988 default returning control to the nearest enclosing "eval", but
16989 subject to modification by a $SIG{__DIE__} handler. In any case,
16990 the "croak_sv" function never returns normally.
16991 To die with a simple string message, the "croak" function may be
16993 more convenient.
16994 void croak_sv(SV *baseex)
16996 "die"
16998 "die_nocontext"
16999 These behave the same as "croak", except for the return type. They
17000 should be used only where the "OP *" return type is required. They
17001 never actually return.
17002 The two forms differ only in that "die_nocontext" does not take a
17004 thread context ("aTHX") parameter, so is used in situations where
17005 the caller doesn't already have the thread context.
17006 NOTE: "die" must be explicitly called as "Perl_die" with an "aTHX_"
17008 parameter.
17009 OP* Perl_die (pTHX_ const char* pat, ...)
17011 OP* die_nocontext(const char* pat, ...)
17012 "die_sv"
17014 This behaves the same as "croak_sv", except for the return type.
17015 It should be used only where the "OP *" return type is required.
17016 The function never actually returns.
17017 OP* die_sv(SV *baseex)
17019 "ERRSV"
17021 Returns the SV for $@, creating it if needed.
17022 SV * ERRSV
17024 "packWARN"
17026 "packWARN2"
17027 "packWARN3"
17028 "packWARN4"
17029 These macros are used to pack warning categories into a single U32
17030 to pass to macros and functions that take a warning category
17031 parameter. The number of categories to pack is given by the name,
17032 with a corresponding number of category parameters passed.
17033 U32 packWARN (U32 w1)
17035 U32 packWARN2(U32 w1, U32 w2)
17036 U32 packWARN3(U32 w1, U32 w2, U32 w3)
17037 U32 packWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
17038 "SANE_ERRSV"
17040 Clean up ERRSV so we can safely set it.
17041 This replaces any read-only SV with a fresh writable copy and
17043 removes any magic.
17044 void SANE_ERRSV()
17046 "vcroak"
17048 This is an XS interface to Perl's "die" function.
17049 "pat" and "args" are a sprintf-style format pattern and
17051 encapsulated argument list. These are used to generate a string
17052 message. If the message does not end with a newline, then it will
17053 be extended with some indication of the current location in the
17054 code, as described for "mess_sv".
17055 The error message will be used as an exception, by default
17057 returning control to the nearest enclosing "eval", but subject to
17058 modification by a $SIG{__DIE__} handler. In any case, the "croak"
17059 function never returns normally.
17060 For historical reasons, if "pat" is null then the contents of
17062 "ERRSV" ($@) will be used as an error message or object instead of
17063 building an error message from arguments. If you want to throw a
17064 non-string object, or build an error message in an SV yourself, it
17065 is preferable to use the "croak_sv" function, which does not
17066 involve clobbering "ERRSV".
17067 void vcroak(const char* pat, va_list* args)
17069 "vwarn"
17071 This is an XS interface to Perl's "warn" function.
17072 This is like "warn", but "args" are an encapsulated argument list.
17074 Unlike with "vcroak", "pat" is not permitted to be null.
17076 void vwarn(const char* pat, va_list* args)
17078 "vwarner"
17080 This is like "warner", but "args" are an encapsulated argument
17081 list.
17082 void vwarner(U32 err, const char* pat, va_list* args)
17084 "warn"
17086 "warn_nocontext"
17087 These are XS interfaces to Perl's "warn" function.
17088 They take a sprintf-style format pattern and argument list, which
17090 are used to generate a string message. If the message does not end
17091 with a newline, then it will be extended with some indication of
17092 the current location in the code, as described for "mess_sv".
17093 The error message or object will by default be written to standard
17095 error, but this is subject to modification by a $SIG{__WARN__}
17096 handler.
17097 Unlike with "croak", "pat" is not permitted to be null.
17099 The two forms differ only in that "warn_nocontext" does not take a
17101 thread context ("aTHX") parameter, so is used in situations where
17102 the caller doesn't already have the thread context.
17103 NOTE: "warn" must be explicitly called as "Perl_warn" with an
17105 "aTHX_" parameter.
17106 void Perl_warn (pTHX_ const char* pat, ...)
17108 void warn_nocontext(const char* pat, ...)
17109 "warner"
17111 "warner_nocontext"
17112 These output a warning of the specified category (or categories)
17113 given by "err", using the sprintf-style format pattern "pat", and
17114 argument list.
17115 "err" must be one of the "packWARN", "packWARN2", "packWARN3",
17117 "packWARN4" macros populated with the appropriate number of warning
17118 categories. If any of the warning categories they specify is
17119 fatal, a fatal exception is thrown.
17120 In any event a message is generated by the pattern and arguments.
17122 If the message does not end with a newline, then it will be
17123 extended with some indication of the current location in the code,
17124 as described for "mess_sv".
17125 The error message or object will by default be written to standard
17127 error, but this is subject to modification by a $SIG{__WARN__}
17128 handler.
17129 "pat" is not permitted to be null.
17131 The two forms differ only in that "warner_nocontext" does not take
17133 a thread context ("aTHX") parameter, so is used in situations where
17134 the caller doesn't already have the thread context.
17135 These functions differ from the similarly named "warn" functions,
17137 in that the latter are for XS code to unconditionally display a
17138 warning, whereas these are for code that may be compiling a perl
17139 program, and does extra checking to see if the warning should be
17140 fatal.
17141 NOTE: "warner" must be explicitly called as "Perl_warner" with an
17143 "aTHX_" parameter.
17144 void Perl_warner (pTHX_ U32 err, const char* pat, ...)
17146 void warner_nocontext(U32 err, const char* pat, ...)
17147 "warn_sv"
17149 This is an XS interface to Perl's "warn" function.
17150 "baseex" is the error message or object. If it is a reference, it
17152 will be used as-is. Otherwise it is used as a string, and if it
17153 does not end with a newline then it will be extended with some
17154 indication of the current location in the code, as described for
17155 "mess_sv".
17156 The error message or object will by default be written to standard
17158 error, but this is subject to modification by a $SIG{__WARN__}
17159 handler.
17160 To warn with a simple string message, the "warn" function may be
17162 more convenient.
17163 void warn_sv(SV *baseex)
17165
17167 xsubpp compiles XS code into C. See "xsubpp" in perlutil.
17168 "aMY_CXT"
17170 Described in perlxs.
17171 "aMY_CXT_"
17173 Described in perlxs.
17174 "_aMY_CXT"
17176 Described in perlxs.
17177 "ax"
17179 Variable which is setup by "xsubpp" to indicate the stack base
17180 offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros. The
17181 "dMARK" macro must be called prior to setup the "MARK" variable.
17182 I32 ax
17184 "CLASS"
17186 Variable which is setup by "xsubpp" to indicate the class name for
17187 a C++ XS constructor. This is always a "char*". See "THIS".
17188 char* CLASS
17190 "dAX"
17192 Sets up the "ax" variable. This is usually handled automatically
17193 by "xsubpp" by calling "dXSARGS".
17194 dAX;
17196 "dAXMARK"
17198 Sets up the "ax" variable and stack marker variable "mark". This
17199 is usually handled automatically by "xsubpp" by calling "dXSARGS".
17200 dAXMARK;
17202 "dITEMS"
17204 Sets up the "items" variable. This is usually handled
17205 automatically by "xsubpp" by calling "dXSARGS".
17206 dITEMS;
17208 "dMY_CXT"
17210 Described in perlxs.
17211 "dMY_CXT_SV"
17213 Now a placeholder that declares nothing
17214 dMY_CXT_SV;
17216 "dUNDERBAR"
17218 Sets up any variable needed by the "UNDERBAR" macro. It used to
17219 define "padoff_du", but it is currently a noop. However, it is
17220 strongly advised to still use it for ensuring past and future
17221 compatibility.
17222 dUNDERBAR;
17224 "dXSARGS"
17226 Sets up stack and mark pointers for an XSUB, calling "dSP" and
17227 "dMARK". Sets up the "ax" and "items" variables by calling "dAX"
17228 and "dITEMS". This is usually handled automatically by "xsubpp".
17229 dXSARGS;
17231 "dXSI32"
17233 Sets up the "ix" variable for an XSUB which has aliases. This is
17234 usually handled automatically by "xsubpp".
17235 dXSI32;
17237 "items"
17239 Variable which is setup by "xsubpp" to indicate the number of items
17240 on the stack. See "Variable-length Parameter Lists" in perlxs.
17241 I32 items
17243 "ix"
17245 Variable which is setup by "xsubpp" to indicate which of an XSUB's
17246 aliases was used to invoke it. See "The ALIAS: Keyword" in perlxs.
17247 I32 ix
17249 "MY_CXT"
17251 Described in perlxs.
17252 "MY_CXT_CLONE"
17254 Described in perlxs.
17255 "MY_CXT_INIT"
17257 Described in perlxs.
17258 "pMY_CXT"
17260 Described in perlxs.
17261 "pMY_CXT_"
17263 Described in perlxs.
17264 "_pMY_CXT"
17266 Described in perlxs.
17267 "RETVAL"
17269 Variable which is setup by "xsubpp" to hold the return value for an
17270 XSUB. This is always the proper type for the XSUB. See "The
17271 RETVAL Variable" in perlxs.
17272 type RETVAL
17274 "ST"
17276 Used to access elements on the XSUB's stack.
17277 SV* ST(int ix)
17279 "START_MY_CXT"
17281 Described in perlxs.
17282 "THIS"
17284 Variable which is setup by "xsubpp" to designate the object in a
17285 C++ XSUB. This is always the proper type for the C++ object. See
17286 "CLASS" and "Using XS With C++" in perlxs.
17287 type THIS
17289 "UNDERBAR"
17291 The SV* corresponding to the $_ variable. Works even if there is a
17292 lexical $_ in scope.
17293 "XS"
17295 Macro to declare an XSUB and its C parameter list. This is handled
17296 by "xsubpp". It is the same as using the more explicit
17297 "XS_EXTERNAL" macro; the latter is preferred.
17298 "XS_EXTERNAL"
17300 Macro to declare an XSUB and its C parameter list explicitly
17301 exporting the symbols.
17302 "XS_INTERNAL"
17304 Macro to declare an XSUB and its C parameter list without exporting
17305 the symbols. This is handled by "xsubpp" and generally preferable
17306 over exporting the XSUB symbols unnecessarily.
17307 "XSPROTO"
17309 Macro used by "XS_INTERNAL" and "XS_EXTERNAL" to declare a function
17310 prototype. You probably shouldn't be using this directly yourself.
17311
17313 The following functions have been flagged as part of the public API,
17314 but are currently undocumented. Use them at your own risk, as the
17315 interfaces are subject to change. Functions that are not listed in
17316 this document are not intended for public use, and should NOT be used
17317 under any circumstances.
17318 If you feel you need to use one of these functions, first send email to
17320 perl5-porters@perl.org <mailto:perl5-porters@perl.org>. It may be that
17321 there is a good reason for the function not being documented, and it
17322 should be removed from this list; or it may just be that no one has
17323 gotten around to documenting it. In the latter case, you will be asked
17324 to submit a patch to document the function. Once your patch is
17325 accepted, it will indicate that the interface is stable (unless it is
17326 explicitly marked otherwise) and usable by you.
17327 clone_params_del gv_name_set newANONSUB save_helem
17329 clone_params_new hv_free_ent newAVREF save_helem_flags
17330 do_close hv_ksplit newCVREF save_pushi32ptr
17331 do_open hv_name_set newGVREF save_pushptr
17332 do_openn my_failure_exit newHVREF save_pushptrptr
17333 gv_autoload_pv newANONATTRSUB newSVREF start_subparse
17334 gv_autoload_pvn newANONHASH save_aelem sv_dup
17335 gv_autoload_sv newANONLIST save_aelem_flags sv_dup_inc
17336
17338 Until May 1997, this document was maintained by Jeff Okamoto
17339 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
17340 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
17342 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
17343 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
17344 Stephen McCamant, and Gurusamy Sarathy.
17345 API Listing originally by Dean Roehrich <roehrich@cray.com>.
17347 Updated to be autogenerated from comments in the source by Benjamin
17349 Stuhl.
17350
17352 config.h, perlapio, perlcall, perlclib, perlembed, perlfilter,
17353 perlguts, perlhacktips, perlintern, perlinterp, perliol, perlmroapi,
17354 perlreapi, perlreguts, perlxs
17355perl v5.36.0 2022-08-30 PERLAPI(1)