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 may 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_push_simple"
301 This is a cut-down version of av_push that assumes that the array
302 is very straightforward - no magic, not readonly, and AvREAL - and
303 that "key" is not less than -1. This function MUST NOT be used in
304 situations where any of those assumptions may not hold.
305 Pushes an SV (transferring control of one reference count) onto the
307 end of the array. The array will grow automatically to accommodate
308 the addition.
309 Perl equivalent: "push @myarray, $val;".
311 void av_push_simple(AV *av, SV *val)
313 "av_shift"
315 Removes one SV from the start of the array, reducing its size by
316 one and returning the SV (transferring control of one reference
317 count) to the caller. Returns &PL_sv_undef if the array is empty.
318 Perl equivalent: "shift(@myarray);"
320 SV * av_shift(AV *av)
322 "av_store"
324 Stores an SV in an array. The array index is specified as "key".
325 The return value will be "NULL" if the operation failed or if the
326 value did not need to be actually stored within the array (as in
327 the case of tied arrays). Otherwise, it can be dereferenced to get
328 the "SV*" that was stored there (= "val")).
329 Note that the caller is responsible for suitably incrementing the
331 reference count of "val" before the call, and decrementing it if
332 the function returned "NULL".
333 Approximate Perl equivalent: "splice(@myarray, $key, 1, $val)".
335 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
337 for more information on how to use this function on tied arrays.
338 SV ** av_store(AV *av, SSize_t key, SV *val)
340 "av_tindex"
342 "av_top_index"
343 These behave identically. If the array "av" is empty, these return
344 -1; otherwise they return the maximum value of the indices of all
345 the array elements which are currently defined in "av".
346 They process 'get' magic.
348 The Perl equivalent for these is $#av.
350 Use "av_count" to get the number of elements in an array.
352 SSize_t av_tindex(AV *av)
354 "av_undef"
356 Undefines the array. The XS equivalent of undef(@array).
357 As well as freeing all the elements of the array (like av_clear()),
359 this also frees the memory used by the av to store its list of
360 scalars.
361 See "av_clear" for a note about the array possibly being invalid on
363 return.
364 void av_undef(AV *av)
366 "av_unshift"
368 Unshift the given number of "undef" values onto the beginning of
369 the array. The array will grow automatically to accommodate the
370 addition.
371 Perl equivalent: "unshift @myarray, ((undef) x $num);"
373 void av_unshift(AV *av, SSize_t num)
375 "get_av"
377 Returns the AV of the specified Perl global or package array with
378 the given name (so it won't work on lexical variables). "flags"
379 are passed to "gv_fetchpv". If "GV_ADD" is set and the Perl
380 variable does not exist then it will be created. If "flags" is
381 zero (ignoring "SVf_UTF8") and the variable does not exist then
382 "NULL" is returned.
383 Perl equivalent: "@{"$name"}".
385 NOTE: the perl_get_av() form is deprecated.
387 AV * get_av(const char *name, I32 flags)
389 "newAV"
391 "newAV_alloc_x"
392 "newAV_alloc_xz"
393 These all create a new AV, setting the reference count to 1. If
394 you also know the initial elements of the array with, see
395 ""av_make"".
396 As background, an array consists of three things:
398 1. A data structure containing information about the array as a
400 whole, such as its size and reference count.
401 2. A C language array of pointers to the individual elements.
403 These are treated as pointers to SVs, so all must be castable
404 to SV*.
405 3. The individual elements themselves. These could be, for
407 instance, SVs and/or AVs and/or HVs, etc.
408 An empty array need only have the first data structure, and all
410 these functions create that. They differ in what else they do, as
411 follows:
412 "newAV" form
414 This does nothing beyond creating the whole-array data
415 structure. The Perl equivalent is approximately "my @array;"
416 This is useful when the minimum size of the array could be zero
418 (perhaps there are likely code paths that will entirely skip
419 using it).
420 If the array does get used, the pointers data structure will
422 need to be allocated at that time. This will end up being done
423 by "av_extend">, either explicitly:
424 av_extend(av, len);
426 or implicitly when the first element is stored:
428 (void)av_store(av, 0, sv);
430 Unused array elements are typically initialized by "av_extend".
432 "newAV_alloc_x" form
434 This effectively does a "newAV" followed by also allocating
435 (uninitialized) space for the pointers array. This is used
436 when you know ahead of time the likely minimum size of the
437 array. It is more efficient to do this than doing a plain
438 "newAV" followed by an "av_extend".
439 Of course the array can be extended later should it become
441 necessary.
442 "size" must be at least 1.
444 "newAV_alloc_xz" form
446 This is "newAV_alloc_x", but initializes each pointer in it to
447 NULL. This gives added safety to guard against them being read
448 before being set.
449 "size" must be at least 1.
451 The following examples all result in an array that can fit four
453 elements (indexes 0 .. 3):
454 AV *av = newAV();
456 av_extend(av, 3);
457 AV *av = newAV_alloc_x(4);
459 AV *av = newAV_alloc_xz(4);
461 In contrast, the following examples allocate an array that is only
463 guaranteed to fit one element without extending:
464 AV *av = newAV_alloc_x(1);
466 AV *av = newAV_alloc_xz(1);
467 AV * newAV ()
469 AV * newAV_alloc_x (SSize_t size)
470 AV * newAV_alloc_xz(SSize_t size)
471 "newAVav"
473 Creates a new AV and populates it with values copied from an
474 existing AV. The new AV will have a reference count of 1, and will
475 contain newly created SVs copied from the original SV. The
476 original source will remain unchanged.
477 Perl equivalent: "my @new_array = @existing_array;"
479 AV * newAVav(AV *oav)
481 "newAVhv"
483 Creates a new AV and populates it with keys and values copied from
484 an existing HV. The new AV will have a reference count of 1, and
485 will contain newly created SVs copied from the original HV. The
486 original source will remain unchanged.
487 Perl equivalent: "my @new_array = %existing_hash;"
489 AV * newAVhv(HV *ohv)
491 "Nullav"
493 "DEPRECATED!" It is planned to remove "Nullav" from a future
494 release of Perl. Do not use it for new code; remove it from
495 existing code.
496 Null AV pointer.
498 (deprecated - use "(AV *)NULL" instead)
500
502 "call_argv"
503 Performs a callback to the specified named and package-scoped Perl
504 subroutine with "argv" (a "NULL"-terminated array of strings) as
505 arguments. See perlcall.
506 Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
508 NOTE: the perl_call_argv() form is deprecated.
510 I32 call_argv(const char *sub_name, I32 flags, char **argv)
512 "call_method"
514 Performs a callback to the specified Perl method. The blessed
515 object must be on the stack. See perlcall.
516 NOTE: the perl_call_method() form is deprecated.
518 I32 call_method(const char *methname, I32 flags)
520 "call_pv"
522 Performs a callback to the specified Perl sub. See perlcall.
523 NOTE: the perl_call_pv() form is deprecated.
525 I32 call_pv(const char *sub_name, I32 flags)
527 "call_sv"
529 Performs a callback to the Perl sub specified by the SV.
530 If neither the "G_METHOD" nor "G_METHOD_NAMED" flag is supplied,
532 the SV may be any of a CV, a GV, a reference to a CV, a reference
533 to a GV or SvPV(sv) will be used as the name of the sub to call.
534 If the "G_METHOD" flag is supplied, the SV may be a reference to a
536 CV or SvPV(sv) will be used as the name of the method to call.
537 If the "G_METHOD_NAMED" flag is supplied, SvPV(sv) will be used as
539 the name of the method to call.
540 Some other values are treated specially for internal use and should
542 not be depended on.
543 See perlcall.
545 NOTE: the perl_call_sv() form is deprecated.
547 I32 call_sv(SV *sv, volatile I32 flags)
549 "DESTRUCTORFUNC_NOCONTEXT_t"
551 Described in perlguts.
552 "DESTRUCTORFUNC_t"
554 Described in perlguts.
555 "ENTER"
557 Opening bracket on a callback. See "LEAVE" and perlcall.
558 ENTER;
560 "ENTER_with_name"
562 Same as "ENTER", but when debugging is enabled it also associates
563 the given literal string with the new scope.
564 ENTER_with_name("name");
566 "eval_pv"
568 Tells Perl to "eval" the given string in scalar context and return
569 an SV* result.
570 NOTE: the perl_eval_pv() form is deprecated.
572 SV * eval_pv(const char *p, I32 croak_on_error)
574 "eval_sv"
576 Tells Perl to "eval" the string in the SV. It supports the same
577 flags as "call_sv", with the obvious exception of "G_EVAL". See
578 perlcall.
579 The "G_RETHROW" flag can be used if you only need eval_sv() to
581 execute code specified by a string, but not catch any errors.
582 NOTE: the perl_eval_sv() form is deprecated.
584 I32 eval_sv(SV *sv, I32 flags)
586 "FREETMPS"
588 Closing bracket for temporaries on a callback. See "SAVETMPS" and
589 perlcall.
590 FREETMPS;
592 "G_DISCARD"
594 Described in perlcall.
595 "G_EVAL"
597 Described in perlcall.
598 "GIMME"
600 "DEPRECATED!" It is planned to remove "GIMME" from a future
601 release of Perl. Do not use it for new code; remove it from
602 existing code.
603 A backward-compatible version of "GIMME_V" which can only return
605 "G_SCALAR" or "G_LIST"; in a void context, it returns "G_SCALAR".
606 Deprecated. Use "GIMME_V" instead.
607 U32 GIMME
609 "GIMME_V"
611 The XSUB-writer's equivalent to Perl's "wantarray". Returns
612 "G_VOID", "G_SCALAR" or "G_LIST" for void, scalar or list context,
613 respectively. See perlcall for a usage example.
614 U32 GIMME_V
616 "G_KEEPERR"
618 Described in perlcall.
619 "G_LIST"
621 Described in perlcall.
622 "G_NOARGS"
624 Described in perlcall.
625 "G_SCALAR"
627 Described in perlcall.
628 "G_VOID"
630 Described in perlcall.
631 "is_lvalue_sub"
633 Returns non-zero if the sub calling this function is being called
634 in an lvalue context. Returns 0 otherwise.
635 I32 is_lvalue_sub()
637 "LEAVE"
639 Closing bracket on a callback. See "ENTER" and perlcall.
640 LEAVE;
642 "LEAVE_with_name"
644 Same as "LEAVE", but when debugging is enabled it first checks that
645 the scope has the given name. "name" must be a literal string.
646 LEAVE_with_name("name");
648 "MORTALDESTRUCTOR_SV"
650 Described in perlguts.
651 MORTALDESTRUCTOR_SV(SV *coderef, SV *args)
653 "mortal_destructor_sv"
655 This function arranges for either a Perl code reference, or a C
656 function reference to be called at the end of the current
657 statement.
658 The "coderef" argument determines the type of function that will be
660 called. If it is SvROK() it is assumed to be a reference to a CV
661 and will arrange for the coderef to be called. If it is not SvROK()
662 then it is assumed to be a SvIV() which is SvIOK() whose value is a
663 pointer to a C function of type "DESTRUCTORFUNC_t" created using
664 PTR2INT(). Either way the "args" parameter will be provided to the
665 callback as a parameter, although the rules for doing so differ
666 between the Perl and C mode. Normally this function is only used
667 directly for the Perl case and the wrapper mortal_destructor_x() is
668 used for the C function case.
669 When operating in Perl callback mode the "args" parameter may be
671 NULL in which case the code reference is called with no arguments,
672 otherwise if it is an AV (SvTYPE(args) == SVt_PVAV) then the
673 contents of the AV will be used as the arguments to the code
674 reference, and if it is any other type then the "args" SV will be
675 provided as a single argument to the code reference.
676 When operating in a C callback mode the "args" parameter will be
678 passed directly to the C function as a "void *" pointer. No
679 additional processing of the argument will be peformed, and it is
680 the callers responsibility to free the "args" parameter if
681 necessary.
682 Be aware that there is a signficant difference in timing between
684 the end of the current statement and the end of the current pseudo
685 block. If you are looking for a mechanism to trigger a function at
686 the end of the current pseudo block you should look at
687 SAVEDESTRUCTORX() instead of this function.
688 void mortal_destructor_sv(SV *coderef, SV *args)
690 "MORTALDESTRUCTOR_X"
692 Described in perlguts.
693 MORTALDESTRUCTOR_X(DESTRUCTORFUNC_t f, SV *sv)
695 "PL_errgv"
697 Described in perlcall.
698 "save_aelem"
700 "save_aelem_flags"
701 These each arrange for the value of the array element "av[idx]" to
702 be restored at the end of the enclosing pseudo-block.
703 In "save_aelem", the SV at C**sptr> will be replaced by a new
705 "undef" scalar. That scalar will inherit any magic from the
706 original **sptr, and any 'set' magic will be processed.
707 In "save_aelem_flags", "SAVEf_KEEPOLDELEM" being set in "flags"
709 causes the function to forgo all that: the scalar at **sptr is
710 untouched. If "SAVEf_KEEPOLDELEM" is not set, the SV at C**sptr>
711 will be replaced by a new "undef" scalar. That scalar will inherit
712 any magic from the original **sptr. Any 'set' magic will be
713 processed if and only if "SAVEf_SETMAGIC" is set in in "flags".
714 void save_aelem (AV *av, SSize_t idx, SV **sptr)
716 void save_aelem_flags(AV *av, SSize_t idx, SV **sptr,
717 const U32 flags)
718 "save_aptr"
720 Described in perlguts.
721 void save_aptr(AV **aptr)
723 "save_ary"
725 Described in perlguts.
726 AV * save_ary(GV *gv)
728 "SAVEBOOL"
730 Described in perlguts.
731 SAVEBOOL(bool i)
733 "SAVEDELETE"
735 Described in perlguts.
736 SAVEDELETE(HV * hv, char * key, I32 length)
738 "SAVEDESTRUCTOR"
740 Described in perlguts.
741 SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)
743 "SAVEDESTRUCTOR_X"
745 Described in perlguts.
746 SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)
748 "SAVEFREEOP"
750 Described in perlguts.
751 SAVEFREEOP(OP *op)
753 "SAVEFREEPV"
755 Described in perlguts.
756 SAVEFREEPV(char *pv)
758 "SAVEFREERCPV"
760 Described in perlguts.
761 SAVEFREERCPV(char *pv)
763 "SAVEFREESV"
765 Described in perlguts.
766 SAVEFREESV(SV* sv)
768 "SAVEGENERICSV"
770 Described in perlguts.
771 SAVEGENERICSV(char **psv)
773 "save_hash"
775 Described in perlguts.
776 HV * save_hash(GV *gv)
778 "save_helem"
780 "save_helem_flags"
781 These each arrange for the value of the hash element (in Perlish
782 terms) "$hv{key}]" to be restored at the end of the enclosing
783 pseudo-block.
784 In "save_helem", the SV at C**sptr> will be replaced by a new
786 "undef" scalar. That scalar will inherit any magic from the
787 original **sptr, and any 'set' magic will be processed.
788 In "save_helem_flags", "SAVEf_KEEPOLDELEM" being set in "flags"
790 causes the function to forgo all that: the scalar at **sptr is
791 untouched. If "SAVEf_KEEPOLDELEM" is not set, the SV at C**sptr>
792 will be replaced by a new "undef" scalar. That scalar will inherit
793 any magic from the original **sptr. Any 'set' magic will be
794 processed if and only if "SAVEf_SETMAGIC" is set in in "flags".
795 void save_helem (HV *hv, SV *key, SV **sptr)
797 void save_helem_flags(HV *hv, SV *key, SV **sptr,
798 const U32 flags)
799 "save_hptr"
801 Described in perlguts.
802 void save_hptr(HV **hptr)
804 "SAVEINT"
806 Described in perlguts.
807 SAVEINT(int i)
809 "save_item"
811 Described in perlguts.
812 void save_item(SV *item)
814 "SAVEIV"
816 Described in perlguts.
817 SAVEIV(IV i)
819 "SAVEI8"
821 Described in perlguts.
822 SAVEI8(I8 i)
824 "SAVEI16"
826 Described in perlguts.
827 SAVEI16(I16 i)
829 "SAVEI32"
831 Described in perlguts.
832 SAVEI32(I32 i)
834 "SAVELONG"
836 Described in perlguts.
837 SAVELONG(long i)
839 "SAVEMORTALIZESV"
841 Described in perlguts.
842 SAVEMORTALIZESV(SV* sv)
844 "SAVEPPTR"
846 Described in perlguts.
847 SAVEPPTR(char * p)
849 "SAVERCPV"
851 Described in perlguts.
852 SAVERCPV(char *pv)
854 "save_scalar"
856 Described in perlguts.
857 SV * save_scalar(GV *gv)
859 "SAVESPTR"
861 Described in perlguts.
862 SAVESPTR(SV * s)
864 "SAVESTACK_POS"
866 Described in perlguts.
867 SAVESTACK_POS()
869 "SAVESTRLEN"
871 Described in perlguts.
872 SAVESTRLEN(STRLEN i)
874 "save_svref"
876 Described in perlguts.
877 SV * save_svref(SV **sptr)
879 "SAVETMPS"
881 Opening bracket for temporaries on a callback. See "FREETMPS" and
882 perlcall.
883 SAVETMPS;
885
887 "Atof"
888 This is a synonym for ""my_atof"".
889 NV Atof(NN const char * const s)
891 "cBOOL"
893 Cast-to-bool. When Perl was able to be compiled on pre-C99
894 compilers, a "(bool)" cast didn't necessarily do the right thing,
895 so this macro was created (and made somewhat complicated to work
896 around bugs in old compilers). Now, many years later, and C99 is
897 used, this is no longer required, but is kept for backwards
898 compatibility.
899 bool cBOOL(bool expr)
901 "INT2PTR"
903 Described in perlguts.
904 type INT2PTR(type, int value)
906 "I_V"
908 Cast an NV to IV while avoiding undefined C behavior
909 IV I_V(NV what)
911 "I_32"
913 Cast an NV to I32 while avoiding undefined C behavior
914 I32 I_32(NV what)
916 "PTR2IV"
918 Described in perlguts.
919 IV PTR2IV(void * ptr)
921 "PTR2nat"
923 Described in perlguts.
924 IV PTR2nat(void *)
926 "PTR2NV"
928 Described in perlguts.
929 NV PTR2NV(void * ptr)
931 "PTR2ul"
933 Described in perlguts.
934 unsigned long PTR2ul(void *)
936 "PTR2UV"
938 Described in perlguts.
939 UV PTR2UV(void * ptr)
941 "PTRV"
943 Described in perlguts.
944 "U_V"
946 Cast an NV to UV while avoiding undefined C behavior
947 UV U_V(NV what)
949 "U_32"
951 Cast an NV to U32 while avoiding undefined C behavior
952 U32 U_32(NV what)
954
956 Perl uses "full" Unicode case mappings. This means that converting a
957 single character to another case may result in a sequence of more than
958 one character. For example, the uppercase of "ß" (LATIN SMALL LETTER
959 SHARP S) is the two character sequence "SS". This presents some
960 complications The lowercase of all characters in the range 0..255 is
961 a single character, and thus "toLOWER_L1" is furnished. But,
962 "toUPPER_L1" can't exist, as it couldn't return a valid result for all
963 legal inputs. Instead "toUPPER_uvchr" has an API that does allow every
964 possible legal result to be returned.) Likewise no other function that
965 is crippled by not being able to give the correct results for the full
966 range of possible inputs has been implemented here.
967 "toFOLD"
969 "toFOLD_A"
970 "toFOLD_utf8"
971 "toFOLD_utf8_safe"
972 "toFOLD_uvchr"
973 These all return the foldcase of a character. "foldcase" is an
974 internal case for "/i" pattern matching. If the foldcase of
975 character A and the foldcase of character B are the same, they
976 match caselessly; otherwise they don't.
977 The differences in the forms are what domain they operate on, and
979 whether the input is specified as a code point (those forms with a
980 "cp" parameter) or as a UTF-8 string (the others). In the latter
981 case, the code point to use is the first one in the buffer of UTF-8
982 encoded code points, delineated by the arguments "p .. e - 1".
983 "toFOLD" and "toFOLD_A" are synonyms of each other. They return
985 the foldcase of any ASCII-range code point. In this range, the
986 foldcase is identical to the lowercase. All other inputs are
987 returned unchanged. Since these are macros, the input type may be
988 any integral one, and the output will occupy the same number of
989 bits as the input.
990 There is no "toFOLD_L1" nor "toFOLD_LATIN1" as the foldcase of some
992 code points in the 0..255 range is above that range or consists of
993 multiple characters. Instead use "toFOLD_uvchr".
994 "toFOLD_uvchr" returns the foldcase of any Unicode code point. The
996 return value is identical to that of "toFOLD_A" for input code
997 points in the ASCII range. The foldcase of the vast majority of
998 Unicode code points is the same as the code point itself. For
999 these, and for code points above the legal Unicode maximum, this
1000 returns the input code point unchanged. It additionally stores the
1001 UTF-8 of the result into the buffer beginning at "s", and its
1002 length in bytes into *lenp. The caller must have made "s" large
1003 enough to contain at least "UTF8_MAXBYTES_CASE+1" bytes to avoid
1004 possible overflow.
1005 NOTE: the foldcase of a code point may be more than one code point.
1007 The return value of this function is only the first of these. The
1008 entire foldcase is returned in "s". To determine if the result is
1009 more than a single code point, you can do something like this:
1010 uc = toFOLD_uvchr(cp, s, &len);
1012 if (len > UTF8SKIP(s)) { is multiple code points }
1013 else { is a single code point }
1014 "toFOLD_utf8" and "toFOLD_utf8_safe" are synonyms of each other.
1016 The only difference between these and "toFOLD_uvchr" is that the
1017 source for these is encoded in UTF-8, instead of being a code
1018 point. It is passed as a buffer starting at "p", with "e" pointing
1019 to one byte beyond its end. The "p" buffer may certainly contain
1020 more than one code point; but only the first one (up through
1021 "e - 1") is examined. If the UTF-8 for the input character is
1022 malformed in some way, the program may croak, or the function may
1023 return the REPLACEMENT CHARACTER, at the discretion of the
1024 implementation, and subject to change in future releases.
1025 UV toFOLD (UV cp)
1027 UV toFOLD_A (UV cp)
1028 UV toFOLD_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1029 UV toFOLD_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1030 UV toFOLD_uvchr (UV cp, U8* s, STRLEN* lenp)
1031 "toLOWER"
1033 "toLOWER_A"
1034 "toLOWER_LATIN1"
1035 "toLOWER_LC"
1036 "toLOWER_L1"
1037 "toLOWER_utf8"
1038 "toLOWER_utf8_safe"
1039 "toLOWER_uvchr"
1040 These all return the lowercase of a character. The differences are
1041 what domain they operate on, and whether the input is specified as
1042 a code point (those forms with a "cp" parameter) or as a UTF-8
1043 string (the others). In the latter case, the code point to use is
1044 the first one in the buffer of UTF-8 encoded code points,
1045 delineated by the arguments "p .. e - 1".
1046 "toLOWER" and "toLOWER_A" are synonyms of each other. They return
1048 the lowercase of any uppercase ASCII-range code point. All other
1049 inputs are returned unchanged. Since these are macros, the input
1050 type may be any integral one, and the output will occupy the same
1051 number of bits as the input.
1052 "toLOWER_L1" and "toLOWER_LATIN1" are synonyms of each other. They
1054 behave identically as "toLOWER" for ASCII-range input. But
1055 additionally will return the lowercase of any uppercase code point
1056 in the entire 0..255 range, assuming a Latin-1 encoding (or the
1057 EBCDIC equivalent on such platforms).
1058 "toLOWER_LC" returns the lowercase of the input code point
1060 according to the rules of the current POSIX locale. Input code
1061 points outside the range 0..255 are returned unchanged.
1062 "toLOWER_uvchr" returns the lowercase of any Unicode code point.
1064 The return value is identical to that of "toLOWER_L1" for input
1065 code points in the 0..255 range. The lowercase of the vast
1066 majority of Unicode code points is the same as the code point
1067 itself. For these, and for code points above the legal Unicode
1068 maximum, this returns the input code point unchanged. It
1069 additionally stores the UTF-8 of the result into the buffer
1070 beginning at "s", and its length in bytes into *lenp. The caller
1071 must have made "s" large enough to contain at least
1072 "UTF8_MAXBYTES_CASE+1" bytes to avoid possible overflow.
1073 NOTE: the lowercase of a code point may be more than one code
1075 point. The return value of this function is only the first of
1076 these. The entire lowercase is returned in "s". To determine if
1077 the result is more than a single code point, you can do something
1078 like this:
1079 uc = toLOWER_uvchr(cp, s, &len);
1081 if (len > UTF8SKIP(s)) { is multiple code points }
1082 else { is a single code point }
1083 "toLOWER_utf8" and "toLOWER_utf8_safe" are synonyms of each other.
1085 The only difference between these and "toLOWER_uvchr" is that the
1086 source for these is encoded in UTF-8, instead of being a code
1087 point. It is passed as a buffer starting at "p", with "e" pointing
1088 to one byte beyond its end. The "p" buffer may certainly contain
1089 more than one code point; but only the first one (up through
1090 "e - 1") is examined. If the UTF-8 for the input character is
1091 malformed in some way, the program may croak, or the function may
1092 return the REPLACEMENT CHARACTER, at the discretion of the
1093 implementation, and subject to change in future releases.
1094 UV toLOWER (UV cp)
1096 UV toLOWER_A (UV cp)
1097 UV toLOWER_LATIN1 (UV cp)
1098 UV toLOWER_LC (UV cp)
1099 UV toLOWER_L1 (UV cp)
1100 UV toLOWER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1101 UV toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1102 UV toLOWER_uvchr (UV cp, U8* s, STRLEN* lenp)
1103 "toTITLE"
1105 "toTITLE_A"
1106 "toTITLE_utf8"
1107 "toTITLE_utf8_safe"
1108 "toTITLE_uvchr"
1109 These all return the titlecase of a character. The differences are
1110 what domain they operate on, and whether the input is specified as
1111 a code point (those forms with a "cp" parameter) or as a UTF-8
1112 string (the others). In the latter case, the code point to use is
1113 the first one in the buffer of UTF-8 encoded code points,
1114 delineated by the arguments "p .. e - 1".
1115 "toTITLE" and "toTITLE_A" are synonyms of each other. They return
1117 the titlecase of any lowercase ASCII-range code point. In this
1118 range, the titlecase is identical to the uppercase. All other
1119 inputs are returned unchanged. Since these are macros, the input
1120 type may be any integral one, and the output will occupy the same
1121 number of bits as the input.
1122 There is no "toTITLE_L1" nor "toTITLE_LATIN1" as the titlecase of
1124 some code points in the 0..255 range is above that range or
1125 consists of multiple characters. Instead use "toTITLE_uvchr".
1126 "toTITLE_uvchr" returns the titlecase of any Unicode code point.
1128 The return value is identical to that of "toTITLE_A" for input code
1129 points in the ASCII range. The titlecase of the vast majority of
1130 Unicode code points is the same as the code point itself. For
1131 these, and for code points above the legal Unicode maximum, this
1132 returns the input code point unchanged. It additionally stores the
1133 UTF-8 of the result into the buffer beginning at "s", and its
1134 length in bytes into *lenp. The caller must have made "s" large
1135 enough to contain at least "UTF8_MAXBYTES_CASE+1" bytes to avoid
1136 possible overflow.
1137 NOTE: the titlecase of a code point may be more than one code
1139 point. The return value of this function is only the first of
1140 these. The entire titlecase is returned in "s". To determine if
1141 the result is more than a single code point, you can do something
1142 like this:
1143 uc = toTITLE_uvchr(cp, s, &len);
1145 if (len > UTF8SKIP(s)) { is multiple code points }
1146 else { is a single code point }
1147 "toTITLE_utf8" and "toTITLE_utf8_safe" are synonyms of each other.
1149 The only difference between these and "toTITLE_uvchr" is that the
1150 source for these is encoded in UTF-8, instead of being a code
1151 point. It is passed as a buffer starting at "p", with "e" pointing
1152 to one byte beyond its end. The "p" buffer may certainly contain
1153 more than one code point; but only the first one (up through
1154 "e - 1") is examined. If the UTF-8 for the input character is
1155 malformed in some way, the program may croak, or the function may
1156 return the REPLACEMENT CHARACTER, at the discretion of the
1157 implementation, and subject to change in future releases.
1158 UV toTITLE (UV cp)
1160 UV toTITLE_A (UV cp)
1161 UV toTITLE_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1162 UV toTITLE_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1163 UV toTITLE_uvchr (UV cp, U8* s, STRLEN* lenp)
1164 "toUPPER"
1166 "toUPPER_A"
1167 "toUPPER_utf8"
1168 "toUPPER_utf8_safe"
1169 "toUPPER_uvchr"
1170 These all return the uppercase of a character. The differences are
1171 what domain they operate on, and whether the input is specified as
1172 a code point (those forms with a "cp" parameter) or as a UTF-8
1173 string (the others). In the latter case, the code point to use is
1174 the first one in the buffer of UTF-8 encoded code points,
1175 delineated by the arguments "p .. e - 1".
1176 "toUPPER" and "toUPPER_A" are synonyms of each other. They return
1178 the uppercase of any lowercase ASCII-range code point. All other
1179 inputs are returned unchanged. Since these are macros, the input
1180 type may be any integral one, and the output will occupy the same
1181 number of bits as the input.
1182 There is no "toUPPER_L1" nor "toUPPER_LATIN1" as the uppercase of
1184 some code points in the 0..255 range is above that range or
1185 consists of multiple characters. Instead use "toUPPER_uvchr".
1186 "toUPPER_uvchr" returns the uppercase of any Unicode code point.
1188 The return value is identical to that of "toUPPER_A" for input code
1189 points in the ASCII range. The uppercase of the vast majority of
1190 Unicode code points is the same as the code point itself. For
1191 these, and for code points above the legal Unicode maximum, this
1192 returns the input code point unchanged. It additionally stores the
1193 UTF-8 of the result into the buffer beginning at "s", and its
1194 length in bytes into *lenp. The caller must have made "s" large
1195 enough to contain at least "UTF8_MAXBYTES_CASE+1" bytes to avoid
1196 possible overflow.
1197 NOTE: the uppercase of a code point may be more than one code
1199 point. The return value of this function is only the first of
1200 these. The entire uppercase is returned in "s". To determine if
1201 the result is more than a single code point, you can do something
1202 like this:
1203 uc = toUPPER_uvchr(cp, s, &len);
1205 if (len > UTF8SKIP(s)) { is multiple code points }
1206 else { is a single code point }
1207 "toUPPER_utf8" and "toUPPER_utf8_safe" are synonyms of each other.
1209 The only difference between these and "toUPPER_uvchr" is that the
1210 source for these is encoded in UTF-8, instead of being a code
1211 point. It is passed as a buffer starting at "p", with "e" pointing
1212 to one byte beyond its end. The "p" buffer may certainly contain
1213 more than one code point; but only the first one (up through
1214 "e - 1") is examined. If the UTF-8 for the input character is
1215 malformed in some way, the program may croak, or the function may
1216 return the REPLACEMENT CHARACTER, at the discretion of the
1217 implementation, and subject to change in future releases.
1218 UV toUPPER (UV cp)
1220 UV toUPPER_A (UV cp)
1221 UV toUPPER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1222 UV toUPPER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1223 UV toUPPER_uvchr (UV cp, U8* s, STRLEN* lenp)
1224
1226 This section is about functions (really macros) that classify
1227 characters into types, such as punctuation versus alphabetic, etc.
1228 Most of these are analogous to regular expression character classes.
1229 (See "POSIX Character Classes" in perlrecharclass.) There are several
1230 variants for each class. (Not all macros have all variants; each item
1231 below lists the ones valid for it.) None are affected by "use bytes",
1232 and only the ones with "LC" in the name are affected by the current
1233 locale.
1234 The base function, e.g., isALPHA(), takes any signed or unsigned value,
1236 treating it as a code point, and returns a boolean as to whether or not
1237 the character represented by it is (or on non-ASCII platforms,
1238 corresponds to) an ASCII character in the named class based on
1239 platform, Unicode, and Perl rules. If the input is a number that
1240 doesn't fit in an octet, FALSE is returned.
1241 Variant "isFOO_A" (e.g., isALPHA_A()) is identical to the base function
1243 with no suffix "_A". This variant is used to emphasize by its name
1244 that only ASCII-range characters can return TRUE.
1245 Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivalent) character
1247 set onto the platform. That is, the code points that are ASCII are
1248 unaffected, since ASCII is a subset of Latin-1. But the non-ASCII code
1249 points are treated as if they are Latin-1 characters. For example,
1250 isWORDCHAR_L1() will return true when called with the code point 0xDF,
1251 which is a word character in both ASCII and EBCDIC (though it
1252 represents different characters in each). If the input is a number
1253 that doesn't fit in an octet, FALSE is returned. (Perl's documentation
1254 uses a colloquial definition of Latin-1, to include all code points
1255 below 256.)
1256 Variant "isFOO_uvchr" is exactly like the "isFOO_L1" variant, for
1258 inputs below 256, but if the code point is larger than 255, Unicode
1259 rules are used to determine if it is in the character class. For
1260 example, isWORDCHAR_uvchr(0x100) returns TRUE, since 0x100 is LATIN
1261 CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.
1262 Variants "isFOO_utf8" and "isFOO_utf8_safe" are like "isFOO_uvchr", but
1264 are used for UTF-8 encoded strings. The two forms are different names
1265 for the same thing. Each call to one of these classifies the first
1266 character of the string starting at "p". The second parameter, "e",
1267 points to anywhere in the string beyond the first character, up to one
1268 byte past the end of the entire string. Although both variants are
1269 identical, the suffix "_safe" in one name emphasizes that it will not
1270 attempt to read beyond "e - 1", provided that the constraint "s < e" is
1271 true (this is asserted for in "-DDEBUGGING" builds). If the UTF-8 for
1272 the input character is malformed in some way, the program may croak, or
1273 the function may return FALSE, at the discretion of the implementation,
1274 and subject to change in future releases.
1275 Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but
1277 the result is based on the current locale, which is what "LC" in the
1278 name stands for. If Perl can determine that the current locale is a
1279 UTF-8 locale, it uses the published Unicode rules; otherwise, it uses
1280 the C library function that gives the named classification. For
1281 example, isDIGIT_LC() when not in a UTF-8 locale returns the result of
1282 calling isdigit(). FALSE is always returned if the input won't fit
1283 into an octet. On some platforms where the C library function is known
1284 to be defective, Perl changes its result to follow the POSIX standard's
1285 rules.
1286 Variant "isFOO_LC_uvchr" acts exactly like "isFOO_LC" for inputs less
1288 than 256, but for larger ones it returns the Unicode classification of
1289 the code point.
1290 Variants "isFOO_LC_utf8" and "isFOO_LC_utf8_safe" are like
1292 "isFOO_LC_uvchr", but are used for UTF-8 encoded strings. The two
1293 forms are different names for the same thing. Each call to one of
1294 these classifies the first character of the string starting at "p".
1295 The second parameter, "e", points to anywhere in the string beyond the
1296 first character, up to one byte past the end of the entire string.
1297 Although both variants are identical, the suffix "_safe" in one name
1298 emphasizes that it will not attempt to read beyond "e - 1", provided
1299 that the constraint "s < e" is true (this is asserted for in
1300 "-DDEBUGGING" builds). If the UTF-8 for the input character is
1301 malformed in some way, the program may croak, or the function may
1302 return FALSE, at the discretion of the implementation, and subject to
1303 change in future releases.
1304 "isALNUM"
1306 "isALNUM_A"
1307 "isALNUM_LC"
1308 "isALNUM_LC_uvchr"
1309 These are each a synonym for their respectively named
1310 ""isWORDCHAR"" variant.
1311 They are provided for backward compatibility, even though a word
1313 character includes more than the standard C language meaning of
1314 alphanumeric. To get the C language definition, use the
1315 corresponding ""isALPHANUMERIC"" variant.
1316 bool isALNUM(UV ch)
1318 "isALNUMC"
1320 "isALNUMC_A"
1321 "isALNUMC_LC"
1322 "isALNUMC_LC_uvchr"
1323 "isALNUMC_L1"
1324 These are discouraged, backward compatibility macros for
1325 ""isALPHANUMERIC"". That is, each returns a boolean indicating
1326 whether the specified character is one of "[A-Za-z0-9]", analogous
1327 to "m/[[:alnum:]]/".
1328 The "C" suffix in the names was meant to indicate that they
1330 correspond to the C language isalnum(3).
1331 bool isALNUMC(UV ch)
1333 "isALPHA"
1335 "isALPHA_A"
1336 "isALPHA_LC"
1337 "isALPHA_LC_utf8_safe"
1338 "isALPHA_LC_uvchr"
1339 "isALPHA_L1"
1340 "isALPHA_utf8"
1341 "isALPHA_utf8_safe"
1342 "isALPHA_uvchr"
1343 Returns a boolean indicating whether the specified input is one of
1344 "[A-Za-z]", analogous to "m/[[:alpha:]]/". See the top of this
1345 section for an explanation of the variants.
1346 bool isALPHA (UV ch)
1348 bool isALPHA_A (UV ch)
1349 bool isALPHA_LC (UV ch)
1350 bool isALPHA_LC_utf8_safe(U8 * s, U8 *end)
1351 bool isALPHA_LC_uvchr (UV ch)
1352 bool isALPHA_L1 (UV ch)
1353 bool isALPHA_utf8 (U8 * s, U8 * end)
1354 bool isALPHA_utf8_safe (U8 * s, U8 * end)
1355 bool isALPHA_uvchr (UV ch)
1356 "isALPHANUMERIC"
1358 "isALPHANUMERIC_A"
1359 "isALPHANUMERIC_LC"
1360 "isALPHANUMERIC_LC_utf8_safe"
1361 "isALPHANUMERIC_LC_uvchr"
1362 "isALPHANUMERIC_L1"
1363 "isALPHANUMERIC_utf8"
1364 "isALPHANUMERIC_utf8_safe"
1365 "isALPHANUMERIC_uvchr"
1366 Returns a boolean indicating whether the specified character is one
1367 of "[A-Za-z0-9]", analogous to "m/[[:alnum:]]/". See the top of
1368 this section for an explanation of the variants.
1369 bool isALPHANUMERIC (UV ch)
1371 bool isALPHANUMERIC_A (UV ch)
1372 bool isALPHANUMERIC_LC (UV ch)
1373 bool isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end)
1374 bool isALPHANUMERIC_LC_uvchr (UV ch)
1375 bool isALPHANUMERIC_L1 (UV ch)
1376 bool isALPHANUMERIC_utf8 (U8 * s, U8 * end)
1377 bool isALPHANUMERIC_utf8_safe (U8 * s, U8 * end)
1378 bool isALPHANUMERIC_uvchr (UV ch)
1379 "isASCII"
1381 "isASCII_A"
1382 "isASCII_LC"
1383 "isASCII_LC_utf8_safe"
1384 "isASCII_LC_uvchr"
1385 "isASCII_L1"
1386 "isASCII_utf8"
1387 "isASCII_utf8_safe"
1388 "isASCII_uvchr"
1389 Returns a boolean indicating whether the specified character is one
1390 of the 128 characters in the ASCII character set, analogous to
1391 "m/[[:ascii:]]/". On non-ASCII platforms, it returns TRUE iff this
1392 character corresponds to an ASCII character. Variants isASCII_A()
1393 and isASCII_L1() are identical to isASCII(). See the top of this
1394 section for an explanation of the variants. Note, however, that
1395 some platforms do not have the C library routine isascii(). In
1396 these cases, the variants whose names contain "LC" are the same as
1397 the corresponding ones without.
1398 Also note, that because all ASCII characters are UTF-8 invariant
1400 (meaning they have the exact same representation (always a single
1401 byte) whether encoded in UTF-8 or not), "isASCII" will give the
1402 correct results when called with any byte in any string encoded or
1403 not in UTF-8. And similarly "isASCII_utf8" and "isASCII_utf8_safe"
1404 will work properly on any string encoded or not in UTF-8.
1405 bool isASCII (UV ch)
1407 bool isASCII_A (UV ch)
1408 bool isASCII_LC (UV ch)
1409 bool isASCII_LC_utf8_safe(U8 * s, U8 *end)
1410 bool isASCII_LC_uvchr (UV ch)
1411 bool isASCII_L1 (UV ch)
1412 bool isASCII_utf8 (U8 * s, U8 * end)
1413 bool isASCII_utf8_safe (U8 * s, U8 * end)
1414 bool isASCII_uvchr (UV ch)
1415 "isBLANK"
1417 "isBLANK_A"
1418 "isBLANK_LC"
1419 "isBLANK_LC_utf8_safe"
1420 "isBLANK_LC_uvchr"
1421 "isBLANK_L1"
1422 "isBLANK_utf8"
1423 "isBLANK_utf8_safe"
1424 "isBLANK_uvchr"
1425 Returns a boolean indicating whether the specified character is a
1426 character considered to be a blank, analogous to "m/[[:blank:]]/".
1427 See the top of this section for an explanation of the variants.
1428 Note, however, that some platforms do not have the C library
1429 routine isblank(). In these cases, the variants whose names
1430 contain "LC" are the same as the corresponding ones without.
1431 bool isBLANK (UV ch)
1433 bool isBLANK_A (UV ch)
1434 bool isBLANK_LC (UV ch)
1435 bool isBLANK_LC_utf8_safe(U8 * s, U8 *end)
1436 bool isBLANK_LC_uvchr (UV ch)
1437 bool isBLANK_L1 (UV ch)
1438 bool isBLANK_utf8 (U8 * s, U8 * end)
1439 bool isBLANK_utf8_safe (U8 * s, U8 * end)
1440 bool isBLANK_uvchr (UV ch)
1441 "isCNTRL"
1443 "isCNTRL_A"
1444 "isCNTRL_LC"
1445 "isCNTRL_LC_utf8_safe"
1446 "isCNTRL_LC_uvchr"
1447 "isCNTRL_L1"
1448 "isCNTRL_utf8"
1449 "isCNTRL_utf8_safe"
1450 "isCNTRL_uvchr"
1451 Returns a boolean indicating whether the specified character is a
1452 control character, analogous to "m/[[:cntrl:]]/". See the top of
1453 this section for an explanation of the variants. On EBCDIC
1454 platforms, you almost always want to use the "isCNTRL_L1" variant.
1455 bool isCNTRL (UV ch)
1457 bool isCNTRL_A (UV ch)
1458 bool isCNTRL_LC (UV ch)
1459 bool isCNTRL_LC_utf8_safe(U8 * s, U8 *end)
1460 bool isCNTRL_LC_uvchr (UV ch)
1461 bool isCNTRL_L1 (UV ch)
1462 bool isCNTRL_utf8 (U8 * s, U8 * end)
1463 bool isCNTRL_utf8_safe (U8 * s, U8 * end)
1464 bool isCNTRL_uvchr (UV ch)
1465 "isDIGIT"
1467 "isDIGIT_A"
1468 "isDIGIT_LC"
1469 "isDIGIT_LC_utf8_safe"
1470 "isDIGIT_LC_uvchr"
1471 "isDIGIT_L1"
1472 "isDIGIT_utf8"
1473 "isDIGIT_utf8_safe"
1474 "isDIGIT_uvchr"
1475 Returns a boolean indicating whether the specified character is a
1476 digit, analogous to "m/[[:digit:]]/". Variants "isDIGIT_A" and
1477 "isDIGIT_L1" are identical to "isDIGIT". See the top of this
1478 section for an explanation of the variants.
1479 bool isDIGIT (UV ch)
1481 bool isDIGIT_A (UV ch)
1482 bool isDIGIT_LC (UV ch)
1483 bool isDIGIT_LC_utf8_safe(U8 * s, U8 *end)
1484 bool isDIGIT_LC_uvchr (UV ch)
1485 bool isDIGIT_L1 (UV ch)
1486 bool isDIGIT_utf8 (U8 * s, U8 * end)
1487 bool isDIGIT_utf8_safe (U8 * s, U8 * end)
1488 bool isDIGIT_uvchr (UV ch)
1489 "isGRAPH"
1491 "isGRAPH_A"
1492 "isGRAPH_LC"
1493 "isGRAPH_LC_utf8_safe"
1494 "isGRAPH_LC_uvchr"
1495 "isGRAPH_L1"
1496 "isGRAPH_utf8"
1497 "isGRAPH_utf8_safe"
1498 "isGRAPH_uvchr"
1499 Returns a boolean indicating whether the specified character is a
1500 graphic character, analogous to "m/[[:graph:]]/". See the top of
1501 this section for an explanation of the variants.
1502 bool isGRAPH (UV ch)
1504 bool isGRAPH_A (UV ch)
1505 bool isGRAPH_LC (UV ch)
1506 bool isGRAPH_LC_utf8_safe(U8 * s, U8 *end)
1507 bool isGRAPH_LC_uvchr (UV ch)
1508 bool isGRAPH_L1 (UV ch)
1509 bool isGRAPH_utf8 (U8 * s, U8 * end)
1510 bool isGRAPH_utf8_safe (U8 * s, U8 * end)
1511 bool isGRAPH_uvchr (UV ch)
1512 "isIDCONT"
1514 "isIDCONT_A"
1515 "isIDCONT_LC"
1516 "isIDCONT_LC_utf8_safe"
1517 "isIDCONT_LC_uvchr"
1518 "isIDCONT_L1"
1519 "isIDCONT_utf8"
1520 "isIDCONT_utf8_safe"
1521 "isIDCONT_uvchr"
1522 Returns a boolean indicating whether the specified character can be
1523 the second or succeeding character of an identifier. This is very
1524 close to, but not quite the same as the official Unicode property
1525 "XID_Continue". The difference is that this returns true only if
1526 the input character also matches "isWORDCHAR". See the top of this
1527 section for an explanation of the variants.
1528 bool isIDCONT (UV ch)
1530 bool isIDCONT_A (UV ch)
1531 bool isIDCONT_LC (UV ch)
1532 bool isIDCONT_LC_utf8_safe(U8 * s, U8 *end)
1533 bool isIDCONT_LC_uvchr (UV ch)
1534 bool isIDCONT_L1 (UV ch)
1535 bool isIDCONT_utf8 (U8 * s, U8 * end)
1536 bool isIDCONT_utf8_safe (U8 * s, U8 * end)
1537 bool isIDCONT_uvchr (UV ch)
1538 "isIDFIRST"
1540 "isIDFIRST_A"
1541 "isIDFIRST_LC"
1542 "isIDFIRST_LC_utf8_safe"
1543 "isIDFIRST_LC_uvchr"
1544 "isIDFIRST_L1"
1545 "isIDFIRST_utf8"
1546 "isIDFIRST_utf8_safe"
1547 "isIDFIRST_uvchr"
1548 Returns a boolean indicating whether the specified character can be
1549 the first character of an identifier. This is very close to, but
1550 not quite the same as the official Unicode property "XID_Start".
1551 The difference is that this returns true only if the input
1552 character also matches "isWORDCHAR". See the top of this section
1553 for an explanation of the variants.
1554 bool isIDFIRST (UV ch)
1556 bool isIDFIRST_A (UV ch)
1557 bool isIDFIRST_LC (UV ch)
1558 bool isIDFIRST_LC_utf8_safe(U8 * s, U8 *end)
1559 bool isIDFIRST_LC_uvchr (UV ch)
1560 bool isIDFIRST_L1 (UV ch)
1561 bool isIDFIRST_utf8 (U8 * s, U8 * end)
1562 bool isIDFIRST_utf8_safe (U8 * s, U8 * end)
1563 bool isIDFIRST_uvchr (UV ch)
1564 "isLOWER"
1566 "isLOWER_A"
1567 "isLOWER_LC"
1568 "isLOWER_LC_utf8_safe"
1569 "isLOWER_LC_uvchr"
1570 "isLOWER_L1"
1571 "isLOWER_utf8"
1572 "isLOWER_utf8_safe"
1573 "isLOWER_uvchr"
1574 Returns a boolean indicating whether the specified character is a
1575 lowercase character, analogous to "m/[[:lower:]]/". See the top of
1576 this section for an explanation of the variants
1577 bool isLOWER (UV ch)
1579 bool isLOWER_A (UV ch)
1580 bool isLOWER_LC (UV ch)
1581 bool isLOWER_LC_utf8_safe(U8 * s, U8 *end)
1582 bool isLOWER_LC_uvchr (UV ch)
1583 bool isLOWER_L1 (UV ch)
1584 bool isLOWER_utf8 (U8 * s, U8 * end)
1585 bool isLOWER_utf8_safe (U8 * s, U8 * end)
1586 bool isLOWER_uvchr (UV ch)
1587 "isOCTAL"
1589 "isOCTAL_A"
1590 "isOCTAL_L1"
1591 Returns a boolean indicating whether the specified character is an
1592 octal digit, [0-7]. The only two variants are "isOCTAL_A" and
1593 "isOCTAL_L1"; each is identical to "isOCTAL".
1594 bool isOCTAL(UV ch)
1596 "isPRINT"
1598 "isPRINT_A"
1599 "isPRINT_LC"
1600 "isPRINT_LC_utf8_safe"
1601 "isPRINT_LC_uvchr"
1602 "isPRINT_L1"
1603 "isPRINT_utf8"
1604 "isPRINT_utf8_safe"
1605 "isPRINT_uvchr"
1606 Returns a boolean indicating whether the specified character is a
1607 printable character, analogous to "m/[[:print:]]/". See the top of
1608 this section for an explanation of the variants.
1609 bool isPRINT (UV ch)
1611 bool isPRINT_A (UV ch)
1612 bool isPRINT_LC (UV ch)
1613 bool isPRINT_LC_utf8_safe(U8 * s, U8 *end)
1614 bool isPRINT_LC_uvchr (UV ch)
1615 bool isPRINT_L1 (UV ch)
1616 bool isPRINT_utf8 (U8 * s, U8 * end)
1617 bool isPRINT_utf8_safe (U8 * s, U8 * end)
1618 bool isPRINT_uvchr (UV ch)
1619 "isPSXSPC"
1621 "isPSXSPC_A"
1622 "isPSXSPC_LC"
1623 "isPSXSPC_LC_utf8_safe"
1624 "isPSXSPC_LC_uvchr"
1625 "isPSXSPC_L1"
1626 "isPSXSPC_utf8"
1627 "isPSXSPC_utf8_safe"
1628 "isPSXSPC_uvchr"
1629 (short for Posix Space) Starting in 5.18, this is identical in all
1630 its forms to the corresponding isSPACE() macros. The locale forms
1631 of this macro are identical to their corresponding isSPACE() forms
1632 in all Perl releases. In releases prior to 5.18, the non-locale
1633 forms differ from their isSPACE() forms only in that the isSPACE()
1634 forms don't match a Vertical Tab, and the isPSXSPC() forms do.
1635 Otherwise they are identical. Thus this macro is analogous to what
1636 "m/[[:space:]]/" matches in a regular expression. See the top of
1637 this section for an explanation of the variants.
1638 bool isPSXSPC (UV ch)
1640 bool isPSXSPC_A (UV ch)
1641 bool isPSXSPC_LC (UV ch)
1642 bool isPSXSPC_LC_utf8_safe(U8 * s, U8 *end)
1643 bool isPSXSPC_LC_uvchr (UV ch)
1644 bool isPSXSPC_L1 (UV ch)
1645 bool isPSXSPC_utf8 (U8 * s, U8 * end)
1646 bool isPSXSPC_utf8_safe (U8 * s, U8 * end)
1647 bool isPSXSPC_uvchr (UV ch)
1648 "isPUNCT"
1650 "isPUNCT_A"
1651 "isPUNCT_LC"
1652 "isPUNCT_LC_utf8_safe"
1653 "isPUNCT_LC_uvchr"
1654 "isPUNCT_L1"
1655 "isPUNCT_utf8"
1656 "isPUNCT_utf8_safe"
1657 "isPUNCT_uvchr"
1658 Returns a boolean indicating whether the specified character is a
1659 punctuation character, analogous to "m/[[:punct:]]/". Note that
1660 the definition of what is punctuation isn't as straightforward as
1661 one might desire. See "POSIX Character Classes" in perlrecharclass
1662 for details. See the top of this section for an explanation of the
1663 variants.
1664 bool isPUNCT (UV ch)
1666 bool isPUNCT_A (UV ch)
1667 bool isPUNCT_LC (UV ch)
1668 bool isPUNCT_LC_utf8_safe(U8 * s, U8 *end)
1669 bool isPUNCT_LC_uvchr (UV ch)
1670 bool isPUNCT_L1 (UV ch)
1671 bool isPUNCT_utf8 (U8 * s, U8 * end)
1672 bool isPUNCT_utf8_safe (U8 * s, U8 * end)
1673 bool isPUNCT_uvchr (UV ch)
1674 "isSPACE"
1676 "isSPACE_A"
1677 "isSPACE_LC"
1678 "isSPACE_LC_utf8_safe"
1679 "isSPACE_LC_uvchr"
1680 "isSPACE_L1"
1681 "isSPACE_utf8"
1682 "isSPACE_utf8_safe"
1683 "isSPACE_uvchr"
1684 Returns a boolean indicating whether the specified character is a
1685 whitespace character. This is analogous to what "m/\s/" matches in
1686 a regular expression. Starting in Perl 5.18 this also matches what
1687 "m/[[:space:]]/" does. Prior to 5.18, only the locale forms of
1688 this macro (the ones with "LC" in their names) matched precisely
1689 what "m/[[:space:]]/" does. In those releases, the only
1690 difference, in the non-locale variants, was that isSPACE() did not
1691 match a vertical tab. (See "isPSXSPC" for a macro that matches a
1692 vertical tab in all releases.) See the top of this section for an
1693 explanation of the variants.
1694 bool isSPACE (UV ch)
1696 bool isSPACE_A (UV ch)
1697 bool isSPACE_LC (UV ch)
1698 bool isSPACE_LC_utf8_safe(U8 * s, U8 *end)
1699 bool isSPACE_LC_uvchr (UV ch)
1700 bool isSPACE_L1 (UV ch)
1701 bool isSPACE_utf8 (U8 * s, U8 * end)
1702 bool isSPACE_utf8_safe (U8 * s, U8 * end)
1703 bool isSPACE_uvchr (UV ch)
1704 "isUPPER"
1706 "isUPPER_A"
1707 "isUPPER_LC"
1708 "isUPPER_LC_utf8_safe"
1709 "isUPPER_LC_uvchr"
1710 "isUPPER_L1"
1711 "isUPPER_utf8"
1712 "isUPPER_utf8_safe"
1713 "isUPPER_uvchr"
1714 Returns a boolean indicating whether the specified character is an
1715 uppercase character, analogous to "m/[[:upper:]]/". See the top of
1716 this section for an explanation of the variants.
1717 bool isUPPER (UV ch)
1719 bool isUPPER_A (UV ch)
1720 bool isUPPER_LC (UV ch)
1721 bool isUPPER_LC_utf8_safe(U8 * s, U8 *end)
1722 bool isUPPER_LC_uvchr (UV ch)
1723 bool isUPPER_L1 (UV ch)
1724 bool isUPPER_utf8 (U8 * s, U8 * end)
1725 bool isUPPER_utf8_safe (U8 * s, U8 * end)
1726 bool isUPPER_uvchr (UV ch)
1727 "isWORDCHAR"
1729 "isWORDCHAR_A"
1730 "isWORDCHAR_LC"
1731 "isWORDCHAR_LC_utf8_safe"
1732 "isWORDCHAR_LC_uvchr"
1733 "isWORDCHAR_L1"
1734 "isWORDCHAR_utf8"
1735 "isWORDCHAR_utf8_safe"
1736 "isWORDCHAR_uvchr"
1737 Returns a boolean indicating whether the specified character is a
1738 character that is a word character, analogous to what "m/\w/" and
1739 "m/[[:word:]]/" match in a regular expression. A word character is
1740 an alphabetic character, a decimal digit, a connecting punctuation
1741 character (such as an underscore), or a "mark" character that
1742 attaches to one of those (like some sort of accent).
1743 See the top of this section for an explanation of the variants.
1745 "isWORDCHAR_A", "isWORDCHAR_L1", "isWORDCHAR_uvchr",
1747 "isWORDCHAR_LC", "isWORDCHAR_LC_uvchr", "isWORDCHAR_LC_utf8", and
1748 "isWORDCHAR_LC_utf8_safe" are also as described there, but
1749 additionally include the platform's native underscore.
1750 bool isWORDCHAR (UV ch)
1752 bool isWORDCHAR_A (UV ch)
1753 bool isWORDCHAR_LC (UV ch)
1754 bool isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end)
1755 bool isWORDCHAR_LC_uvchr (UV ch)
1756 bool isWORDCHAR_L1 (UV ch)
1757 bool isWORDCHAR_utf8 (U8 * s, U8 * end)
1758 bool isWORDCHAR_utf8_safe (U8 * s, U8 * end)
1759 bool isWORDCHAR_uvchr (UV ch)
1760 "isXDIGIT"
1762 "isXDIGIT_A"
1763 "isXDIGIT_LC"
1764 "isXDIGIT_LC_utf8_safe"
1765 "isXDIGIT_LC_uvchr"
1766 "isXDIGIT_L1"
1767 "isXDIGIT_utf8"
1768 "isXDIGIT_utf8_safe"
1769 "isXDIGIT_uvchr"
1770 Returns a boolean indicating whether the specified character is a
1771 hexadecimal digit. In the ASCII range these are "[0-9A-Fa-f]".
1772 Variants isXDIGIT_A() and isXDIGIT_L1() are identical to
1773 isXDIGIT(). See the top of this section for an explanation of the
1774 variants.
1775 bool isXDIGIT (UV ch)
1777 bool isXDIGIT_A (UV ch)
1778 bool isXDIGIT_LC (UV ch)
1779 bool isXDIGIT_LC_utf8_safe(U8 * s, U8 *end)
1780 bool isXDIGIT_LC_uvchr (UV ch)
1781 bool isXDIGIT_L1 (UV ch)
1782 bool isXDIGIT_utf8 (U8 * s, U8 * end)
1783 bool isXDIGIT_utf8_safe (U8 * s, U8 * end)
1784 bool isXDIGIT_uvchr (UV ch)
1785
1787 "CPPLAST"
1788 This symbol is intended to be used along with "CPPRUN" in the same
1789 manner symbol "CPPMINUS" is used with "CPPSTDIN". It contains
1790 either "-" or "".
1791 "CPPMINUS"
1793 This symbol contains the second part of the string which will
1794 invoke the C preprocessor on the standard input and produce to
1795 standard output. This symbol will have the value "-" if "CPPSTDIN"
1796 needs a minus to specify standard input, otherwise the value is "".
1797 "CPPRUN"
1799 This symbol contains the string which will invoke a C preprocessor
1800 on the standard input and produce to standard output. It needs to
1801 end with "CPPLAST", after all other preprocessor flags have been
1802 specified. The main difference with "CPPSTDIN" is that this
1803 program will never be a pointer to a shell wrapper, i.e. it will be
1804 empty if no preprocessor is available directly to the user. Note
1805 that it may well be different from the preprocessor used to compile
1806 the C program.
1807 "CPPSTDIN"
1809 This symbol contains the first part of the string which will invoke
1810 the C preprocessor on the standard input and produce to standard
1811 output. Typical value of "cc -E" or "/lib/cpp", but it can also
1812 call a wrapper. See "CPPRUN".
1813 "HASATTRIBUTE_ALWAYS_INLINE"
1815 Can we handle "GCC" attribute for functions that should always be
1816 inlined.
1817 "HASATTRIBUTE_DEPRECATED"
1819 Can we handle "GCC" attribute for marking deprecated "APIs"
1820 "HASATTRIBUTE_FORMAT"
1822 Can we handle "GCC" attribute for checking printf-style formats
1823 "HASATTRIBUTE_NONNULL"
1825 Can we handle "GCC" attribute for nonnull function parms.
1826 "HASATTRIBUTE_NORETURN"
1828 Can we handle "GCC" attribute for functions that do not return
1829 "HASATTRIBUTE_PURE"
1831 Can we handle "GCC" attribute for pure functions
1832 "HASATTRIBUTE_UNUSED"
1834 Can we handle "GCC" attribute for unused variables and arguments
1835 "HASATTRIBUTE_VISIBILITY"
1837 Can we handle "GCC" attribute for functions that should have a
1838 different visibility.
1839 "HASATTRIBUTE_WARN_UNUSED_RESULT"
1841 Can we handle "GCC" attribute for warning on unused results
1842 "HAS_BUILTIN_ADD_OVERFLOW"
1844 This symbol, if defined, indicates that the compiler supports
1845 "__builtin_add_overflow" for adding integers with overflow checks.
1846 "HAS_BUILTIN_CHOOSE_EXPR"
1848 Can we handle "GCC" builtin for compile-time ternary-like
1849 expressions
1850 "HAS_BUILTIN_EXPECT"
1852 Can we handle "GCC" builtin for telling that certain values are
1853 more likely
1854 "HAS_BUILTIN_MUL_OVERFLOW"
1856 This symbol, if defined, indicates that the compiler supports
1857 "__builtin_mul_overflow" for multiplying integers with overflow
1858 checks.
1859 "HAS_BUILTIN_SUB_OVERFLOW"
1861 This symbol, if defined, indicates that the compiler supports
1862 "__builtin_sub_overflow" for subtracting integers with overflow
1863 checks.
1864 "HAS_C99_VARIADIC_MACROS"
1866 If defined, the compiler supports C99 variadic macros.
1867 "HAS_STATIC_INLINE"
1869 This symbol, if defined, indicates that the C compiler supports
1870 C99-style static inline. That is, the function can't be called
1871 from another translation unit.
1872 "MEM_ALIGNBYTES"
1874 This symbol contains the number of bytes required to align a
1875 double, or a long double when applicable. Usual values are 2, 4 and
1876 8. The default is eight, for safety. For cross-compiling or
1877 multiarch support, Configure will set a minimum of 8.
1878 "PERL_STATIC_INLINE"
1880 This symbol gives the best-guess incantation to use for static
1881 inline functions. If "HAS_STATIC_INLINE" is defined, this will
1882 give C99-style inline. If "HAS_STATIC_INLINE" is not defined, this
1883 will give a plain 'static'. It will always be defined to something
1884 that gives static linkage. Possibilities include
1885 static inline (c99)
1887 static __inline__ (gcc -ansi)
1888 static __inline (MSVC)
1889 static _inline (older MSVC)
1890 static (c89 compilers)
1891 "PERL_THREAD_LOCAL"
1893 This symbol, if defined, gives a linkage specification for thread-
1894 local storage. For example, for a C11 compiler this will be
1895 "_Thread_local". Beware, some compilers are sensitive to the C
1896 language standard they are told to parse. For example, suncc
1897 defaults to C11, so our probe will report that "_Thread_local" can
1898 be used. However, if the -std=c99 is later added to the compiler
1899 flags, then "_Thread_local" will become a syntax error. Hence it is
1900 important for these flags to be consistent between probing and use.
1901 "U32_ALIGNMENT_REQUIRED"
1903 This symbol, if defined, indicates that you must access character
1904 data through U32-aligned pointers.
1905
1907 "__ASSERT_"
1908 This is a helper macro to avoid preprocessor issues, replaced by
1909 nothing unless under DEBUGGING, where it expands to an assert of
1910 its argument, followed by a comma (hence the comma operator). If
1911 we just used a straight assert(), we would get a comma with nothing
1912 before it when not DEBUGGING.
1913 __ASSERT_(bool expr)
1915 "ASSUME"
1917 "ASSUME" is like assert(), but it has a benefit in a release build.
1918 It is a hint to a compiler about a statement of fact in a function
1919 call free expression, which allows the compiler to generate better
1920 machine code. In a debug build, ASSUME(x) is a synonym for
1921 assert(x). ASSUME(0) means the control path is unreachable. In a
1922 for loop, "ASSUME" can be used to hint that a loop will run at
1923 least X times. "ASSUME" is based off MSVC's "__assume" intrinsic
1924 function, see its documents for more details.
1925 ASSUME(bool expr)
1927 "dNOOP"
1929 Declare nothing; typically used as a placeholder to replace
1930 something that used to declare something. Works on compilers that
1931 require declarations before any code.
1932 dNOOP;
1934 "END_EXTERN_C"
1936 When not compiling using C++, expands to nothing. Otherwise ends a
1937 section of code already begun by a "START_EXTERN_C".
1938 END_EXTERN_C
1940 "EXTERN_C"
1942 When not compiling using C++, expands to nothing. Otherwise is
1943 used in a declaration of a function to indicate the function should
1944 have external C linkage. This is required for things to work for
1945 just about all functions with external linkage compiled into perl.
1946 Often, you can use "START_EXTERN_C" ... "END_EXTERN_C" blocks
1947 surrounding all your code that you need to have this linkage.
1948 Example usage:
1950 EXTERN_C int flock(int fd, int op);
1952 "LIKELY"
1954 Returns the input unchanged, but at the same time it gives a branch
1955 prediction hint to the compiler that this condition is likely to be
1956 true.
1957 LIKELY(bool expr)
1959 "NOOP"
1961 Do nothing; typically used as a placeholder to replace something
1962 that used to do something.
1963 NOOP;
1965 "PERL_UNUSED_ARG"
1967 This is used to suppress compiler warnings that a parameter to a
1968 function is not used. This situation can arise, for example, when
1969 a parameter is needed under some configuration conditions, but not
1970 others, so that C preprocessor conditional compilation causes it be
1971 used just sometimes.
1972 PERL_UNUSED_ARG(void x);
1974 "PERL_UNUSED_CONTEXT"
1976 This is used to suppress compiler warnings that the thread context
1977 parameter to a function is not used. This situation can arise, for
1978 example, when a C preprocessor conditional compilation causes it be
1979 used just some times.
1980 PERL_UNUSED_CONTEXT;
1982 "PERL_UNUSED_DECL"
1984 Tells the compiler that the parameter in the function prototype
1985 just before it is not necessarily expected to be used in the
1986 function. Not that many compilers understand this, so this should
1987 only be used in cases where "PERL_UNUSED_ARG" can't conveniently be
1988 used.
1989 Example usage:
1991 Signal_t
1993 Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
1994 void *uap PERL_UNUSED_DECL, bool safe)
1995 "PERL_UNUSED_RESULT"
1997 This macro indicates to discard the return value of the function
1998 call inside it, e.g.,
1999 PERL_UNUSED_RESULT(foo(a, b))
2001 The main reason for this is that the combination of "gcc
2003 -Wunused-result" (part of "-Wall") and the
2004 "__attribute__((warn_unused_result))" cannot be silenced with
2005 casting to "void". This causes trouble when the system header
2006 files use the attribute.
2007 Use "PERL_UNUSED_RESULT" sparingly, though, since usually the
2009 warning is there for a good reason: you might lose success/failure
2010 information, or leak resources, or changes in resources.
2011 But sometimes you just want to ignore the return value, e.g., on
2013 codepaths soon ending up in abort, or in "best effort" attempts, or
2014 in situations where there is no good way to handle failures.
2015 Sometimes "PERL_UNUSED_RESULT" might not be the most natural way:
2017 another possibility is that you can capture the return value and
2018 use "PERL_UNUSED_VAR" on that.
2019 PERL_UNUSED_RESULT(void x)
2021 "PERL_UNUSED_VAR"
2023 This is used to suppress compiler warnings that the variable x is
2024 not used. This situation can arise, for example, when a C
2025 preprocessor conditional compilation causes it be used just some
2026 times.
2027 PERL_UNUSED_VAR(void x);
2029 "START_EXTERN_C"
2031 When not compiling using C++, expands to nothing. Otherwise begins
2032 a section of code in which every function will effectively have
2033 "EXTERN_C" applied to it, that is to have external C linkage. The
2034 section is ended by a "END_EXTERN_C".
2035 START_EXTERN_C
2037 "STATIC"
2039 Described in perlguts.
2040 "STMT_END"
2042 "STMT_START"
2043 These allow a series of statements in a macro to be used as a
2044 single statement, as in
2045 if (x) STMT_START { ... } STMT_END else ...
2047 Note that you can't return a value out of this construct and cannot
2049 use it as an operand to the comma operator. These limit its
2050 utility.
2051 But, a value could be returned by constructing the API so that a
2053 pointer is passed and the macro dereferences this to set the
2054 return. If the value can be any of various types, depending on
2055 context, you can handle that situation in some situations by adding
2056 the type of the return as an extra accompanying parameter:
2057 #define foo(param, type) STMT_START {
2059 type * param; *param = do_calc; ...
2060 } STMT_END
2061 This could be awkward, so consider instead using a C language
2063 "static inline" function.
2064 If you do use this construct, it is easy to forget that it is a
2066 macro and not a function, and hence fall into traps that might not
2067 show up until someone someday writes code which contains names that
2068 clash with the ones you chose here, or calls it with a parameter
2069 which is an expression with side effects, the consequences of which
2070 you didn't think about. See "Writing safer macros" in perlhacktips
2071 for how to avoid these.
2072 "UNLIKELY"
2074 Returns the input unchanged, but at the same time it gives a branch
2075 prediction hint to the compiler that this condition is likely to be
2076 false.
2077 UNLIKELY(bool expr)
2079
2081 "BhkDISABLE"
2082 NOTE: "BhkDISABLE" is experimental and may change or be removed
2083 without notice.
2084 Temporarily disable an entry in this BHK structure, by clearing the
2086 appropriate flag. "which" is a preprocessor token indicating which
2087 entry to disable.
2088 void BhkDISABLE(BHK *hk, token which)
2090 "BhkENABLE"
2092 NOTE: "BhkENABLE" is experimental and may change or be removed
2093 without notice.
2094 Re-enable an entry in this BHK structure, by setting the
2096 appropriate flag. "which" is a preprocessor token indicating which
2097 entry to enable. This will assert (under -DDEBUGGING) if the entry
2098 doesn't contain a valid pointer.
2099 void BhkENABLE(BHK *hk, token which)
2101 "BhkENTRY_set"
2103 NOTE: "BhkENTRY_set" is experimental and may change or be removed
2104 without notice.
2105 Set an entry in the BHK structure, and set the flags to indicate it
2107 is valid. "which" is a preprocessing token indicating which entry
2108 to set. The type of "ptr" depends on the entry.
2109 void BhkENTRY_set(BHK *hk, token which, void *ptr)
2111 "blockhook_register"
2113 NOTE: "blockhook_register" is experimental and may change or be
2114 removed without notice.
2115 Register a set of hooks to be called when the Perl lexical scope
2117 changes at compile time. See "Compile-time scope hooks" in
2118 perlguts.
2119 NOTE: "blockhook_register" must be explicitly called as
2121 "Perl_blockhook_register" with an "aTHX_" parameter.
2122 void Perl_blockhook_register(pTHX_ BHK *hk)
2124
2126 "aTHX"
2127 Described in perlguts.
2128 "aTHX_"
2130 Described in perlguts.
2131 "CPERLscope"
2133 "DEPRECATED!" It is planned to remove "CPERLscope" from a future
2134 release of Perl. Do not use it for new code; remove it from
2135 existing code.
2136 Now a no-op.
2138 void CPERLscope(void x)
2140 "dTHR"
2142 Described in perlguts.
2143 "dTHX"
2145 Described in perlguts.
2146 "dTHXa"
2148 On threaded perls, set "pTHX" to "a"; on unthreaded perls, do
2149 nothing
2150 "dTHXoa"
2152 Now a synonym for "dTHXa".
2153 "dVAR"
2155 This is now a synonym for dNOOP: declare nothing
2156 "GETENV_PRESERVES_OTHER_THREAD"
2158 This symbol, if defined, indicates that the getenv system call
2159 doesn't zap the static buffer of getenv() in a different thread.
2160 The typical getenv() implementation will return a pointer to the
2161 proper position in **environ. But some may instead copy them to a
2162 static buffer in getenv(). If there is a per-thread instance of
2163 that buffer, or the return points to **environ, then a
2164 many-reader/1-writer mutex will work; otherwise an exclusive
2165 locking mutex is required to prevent races.
2166 "HAS_PTHREAD_ATFORK"
2168 This symbol, if defined, indicates that the "pthread_atfork"
2169 routine is available to setup fork handlers.
2170 "HAS_PTHREAD_ATTR_SETSCOPE"
2172 This symbol, if defined, indicates that the "pthread_attr_setscope"
2173 system call is available to set the contention scope attribute of a
2174 thread attribute object.
2175 "HAS_PTHREAD_YIELD"
2177 This symbol, if defined, indicates that the "pthread_yield" routine
2178 is available to yield the execution of the current thread.
2179 "sched_yield" is preferable to "pthread_yield".
2180 "HAS_SCHED_YIELD"
2182 This symbol, if defined, indicates that the "sched_yield" routine
2183 is available to yield the execution of the current thread.
2184 "sched_yield" is preferable to "pthread_yield".
2185 "I_MACH_CTHREADS"
2187 This symbol, if defined, indicates to the C program that it should
2188 include mach/cthreads.h.
2189 #ifdef I_MACH_CTHREADS
2191 #include <mach_cthreads.h>
2192 #endif
2193 "I_PTHREAD"
2195 This symbol, if defined, indicates to the C program that it should
2196 include pthread.h.
2197 #ifdef I_PTHREAD
2199 #include <pthread.h>
2200 #endif
2201 "MULTIPLICITY"
2203 This symbol, if defined, indicates that Perl should be built to use
2204 multiplicity.
2205 "OLD_PTHREAD_CREATE_JOINABLE"
2207 This symbol, if defined, indicates how to create pthread in
2208 joinable (aka undetached) state. "NOTE": not defined if pthread.h
2209 already has defined "PTHREAD_CREATE_JOINABLE" (the new version of
2210 the constant). If defined, known values are
2211 "PTHREAD_CREATE_UNDETACHED" and "__UNDETACHED".
2212 "OLD_PTHREADS_API"
2214 This symbol, if defined, indicates that Perl should be built to use
2215 the old draft "POSIX" threads "API".
2216 "PERL_IMPLICIT_CONTEXT"
2218 Described in perlguts.
2219 "PERL_NO_GET_CONTEXT"
2221 Described in perlguts.
2222 "pTHX"
2224 Described in perlguts.
2225 "pTHX_"
2227 Described in perlguts.
2228 "SCHED_YIELD"
2230 This symbol defines the way to yield the execution of the current
2231 thread. Known ways are "sched_yield", "pthread_yield", and
2232 "pthread_yield" with "NULL".
2233
2235 "cop_fetch_label"
2236 NOTE: "cop_fetch_label" is experimental and may change or be
2237 removed without notice.
2238 Returns the label attached to a cop, and stores its length in bytes
2240 into *len. Upon return, *flags will be set to either "SVf_UTF8" or
2241 0.
2242 Alternatively, use the macro "CopLABEL_len_flags"; or if you don't
2244 need to know if the label is UTF-8 or not, the macro
2245 "CopLABEL_len"; or if you additionally don't need to know the
2246 length, "CopLABEL".
2247 const char * cop_fetch_label(COP * const cop, STRLEN *len,
2249 U32 *flags)
2250 "CopFILE"
2252 Returns the name of the file associated with the "COP" "c"
2253 const char * CopFILE(const COP * c)
2255 "CopFILEAV"
2257 Returns the AV associated with the "COP" "c", creating it if
2258 necessary.
2259 AV * CopFILEAV(const COP * c)
2261 "CopFILEAVn"
2263 Returns the AV associated with the "COP" "c", returning NULL if it
2264 doesn't already exist.
2265 AV * CopFILEAVn(const COP * c)
2267 "CopFILE_copy"
2269 Efficiently copies the cop file name from one COP to another. Wraps
2270 the required logic to do a refcounted copy under threads or not.
2271 void CopFILE_copy(COP * dst, COP * src)
2273 "CopFILE_free"
2275 Frees the file data in a cop. Under the hood this is a refcounting
2276 operation.
2277 void CopFILE_free(COP * c)
2279 "CopFILEGV"
2281 Returns the GV associated with the "COP" "c"
2282 GV * CopFILEGV(const COP * c)
2284 "CopFILEGV_set"
2286 Available only on unthreaded perls. Makes "pv" the name of the
2287 file associated with the "COP" "c"
2288 void CopFILEGV_set(COP *c, GV *gv)
2290 "CopFILE_LEN"
2292 Returns the length of the file associated with the "COP" "c"
2293 const char * CopFILE_LEN(const COP * c)
2295 "CopFILE_set"
2297 Makes "pv" the name of the file associated with the "COP" "c"
2298 void CopFILE_set(COP * c, const char * pv)
2300 "CopFILE_setn"
2302 Makes "pv" the name of the file associated with the "COP" "c"
2303 void CopFILE_setn(COP * c, const char * pv, STRLEN len)
2305 "CopFILESV"
2307 Returns the SV associated with the "COP" "c"
2308 SV * CopFILESV(const COP * c)
2310 "cophh_copy"
2312 NOTE: "cophh_copy" is experimental and may change or be removed
2313 without notice.
2314 Make and return a complete copy of the cop hints hash "cophh".
2316 COPHH * cophh_copy(COPHH *cophh)
2318 "cophh_delete_pv"
2320 "cophh_delete_pvn"
2321 "cophh_delete_pvs"
2322 "cophh_delete_sv"
2323 NOTE: all these forms are experimental and may change or be removed
2324 without notice.
2325 These delete a key and its associated value from the cop hints hash
2327 "cophh", and return the modified hash. The returned hash pointer
2328 is in general not the same as the hash pointer that was passed in.
2329 The input hash is consumed by the function, and the pointer to it
2330 must not be subsequently used. Use "cophh_copy" if you need both
2331 hashes.
2332 The forms differ in how the key is specified. In all forms, the
2334 key is pointed to by "key". In the plain "pv" form, the key is a C
2335 language NUL-terminated string. In the "pvs" form, the key is a C
2336 language string literal. In the "pvn" form, an additional
2337 parameter, "keylen", specifies the length of the string, which
2338 hence, may contain embedded-NUL characters. In the "sv" form, *key
2339 is an SV, and the key is the PV extracted from that. using
2340 "SvPV_const".
2341 "hash" is a precomputed hash of the key string, or zero if it has
2343 not been precomputed. This parameter is omitted from the "pvs"
2344 form, as it is computed automatically at compile time.
2345 The only flag currently used from the "flags" parameter is
2347 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2348 the "pv*" forms, it specifies whether the key octets are
2349 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2350 form uses the underlying SV to determine the UTF-8ness of the
2351 octets.
2352 COPHH * cophh_delete_pv (COPHH *cophh, const char *key, U32 hash,
2354 U32 flags)
2355 COPHH * cophh_delete_pvn(COPHH *cophh, const char *key,
2356 STRLEN keylen, U32 hash, U32 flags)
2357 COPHH * cophh_delete_pvs(COPHH *cophh, "key", U32 flags)
2358 COPHH * cophh_delete_sv (COPHH *cophh, SV *key, U32 hash,
2359 U32 flags)
2360 "cophh_exists_pvn"
2362 NOTE: "cophh_exists_pvn" is experimental and may change or be
2363 removed without notice.
2364 These look up the hint entry in the cop "cop" with the key
2366 specified by "key" (and "keylen" in the "pvn" form), returning true
2367 if a value exists, and false otherwise.
2368 The forms differ in how the key is specified. In the plain "pv"
2370 form, the key is a C language NUL-terminated string. In the "pvs"
2371 form, the key is a C language string literal. In the "pvn" form,
2372 an additional parameter, "keylen", specifies the length of the
2373 string, which hence, may contain embedded-NUL characters. In the
2374 "sv" form, *key is an SV, and the key is the PV extracted from
2375 that. using "SvPV_const".
2376 "hash" is a precomputed hash of the key string, or zero if it has
2378 not been precomputed. This parameter is omitted from the "pvs"
2379 form, as it is computed automatically at compile time.
2380 The only flag currently used from the "flags" parameter is
2382 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2383 the "pv*" forms, it specifies whether the key octets are
2384 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2385 form uses the underlying SV to determine the UTF-8ness of the
2386 octets.
2387 bool cophh_exists_pvn(const COPHH *cophh, const char *key,
2389 STRLEN keylen, U32 hash, U32 flags)
2390 "cophh_fetch_pv"
2392 "cophh_fetch_pvn"
2393 "cophh_fetch_pvs"
2394 "cophh_fetch_sv"
2395 NOTE: all these forms are experimental and may change or be removed
2396 without notice.
2397 These look up the entry in the cop hints hash "cophh" with the key
2399 specified by "key" (and "keylen" in the "pvn" form), returning that
2400 value as a mortal scalar copy, or &PL_sv_placeholder if there is no
2401 value associated with the key.
2402 The forms differ in how the key is specified. In the plain "pv"
2404 form, the key is a C language NUL-terminated string. In the "pvs"
2405 form, the key is a C language string literal. In the "pvn" form,
2406 an additional parameter, "keylen", specifies the length of the
2407 string, which hence, may contain embedded-NUL characters. In the
2408 "sv" form, *key is an SV, and the key is the PV extracted from
2409 that. using "SvPV_const".
2410 "hash" is a precomputed hash of the key string, or zero if it has
2412 not been precomputed. This parameter is omitted from the "pvs"
2413 form, as it is computed automatically at compile time.
2414 The only flag currently used from the "flags" parameter is
2416 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2417 the "pv*" forms, it specifies whether the key octets are
2418 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2419 form uses the underlying SV to determine the UTF-8ness of the
2420 octets.
2421 SV * cophh_fetch_pv (const COPHH *cophh, const char *key,
2423 U32 hash, U32 flags)
2424 SV * cophh_fetch_pvn(const COPHH *cophh, const char *key,
2425 STRLEN keylen, U32 hash, U32 flags)
2426 SV * cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags)
2427 SV * cophh_fetch_sv (const COPHH *cophh, SV *key, U32 hash,
2428 U32 flags)
2429 "cophh_free"
2431 NOTE: "cophh_free" is experimental and may change or be removed
2432 without notice.
2433 Discard the cop hints hash "cophh", freeing all resources
2435 associated with it.
2436 void cophh_free(COPHH *cophh)
2438 "cophh_2hv"
2440 NOTE: "cophh_2hv" is experimental and may change or be removed
2441 without notice.
2442 Generates and returns a standard Perl hash representing the full
2444 set of key/value pairs in the cop hints hash "cophh". "flags" is
2445 currently unused and must be zero.
2446 HV * cophh_2hv(const COPHH *cophh, U32 flags)
2448 "cophh_new_empty"
2450 NOTE: "cophh_new_empty" is experimental and may change or be
2451 removed without notice.
2452 Generate and return a fresh cop hints hash containing no entries.
2454 COPHH * cophh_new_empty()
2456 "cophh_store_pv"
2458 "cophh_store_pvn"
2459 "cophh_store_pvs"
2460 "cophh_store_sv"
2461 NOTE: all these forms are experimental and may change or be removed
2462 without notice.
2463 These store a value, associated with a key, in the cop hints hash
2465 "cophh", and return the modified hash. The returned hash pointer
2466 is in general not the same as the hash pointer that was passed in.
2467 The input hash is consumed by the function, and the pointer to it
2468 must not be subsequently used. Use "cophh_copy" if you need both
2469 hashes.
2470 "value" is the scalar value to store for this key. "value" is
2472 copied by these functions, which thus do not take ownership of any
2473 reference to it, and hence later changes to the scalar will not be
2474 reflected in the value visible in the cop hints hash. Complex
2475 types of scalar will not be stored with referential integrity, but
2476 will be coerced to strings.
2477 The forms differ in how the key is specified. In all forms, the
2479 key is pointed to by "key". In the plain "pv" form, the key is a C
2480 language NUL-terminated string. In the "pvs" form, the key is a C
2481 language string literal. In the "pvn" form, an additional
2482 parameter, "keylen", specifies the length of the string, which
2483 hence, may contain embedded-NUL characters. In the "sv" form, *key
2484 is an SV, and the key is the PV extracted from that. using
2485 "SvPV_const".
2486 "hash" is a precomputed hash of the key string, or zero if it has
2488 not been precomputed. This parameter is omitted from the "pvs"
2489 form, as it is computed automatically at compile time.
2490 The only flag currently used from the "flags" parameter is
2492 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2493 the "pv*" forms, it specifies whether the key octets are
2494 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2495 form uses the underlying SV to determine the UTF-8ness of the
2496 octets.
2497 COPHH * cophh_store_pv (COPHH *cophh, const char *key, U32 hash,
2499 SV *value, U32 flags)
2500 COPHH * cophh_store_pvn(COPHH *cophh, const char *key,
2501 STRLEN keylen, U32 hash, SV *value,
2502 U32 flags)
2503 COPHH * cophh_store_pvs(COPHH *cophh, "key", SV *value,
2504 U32 flags)
2505 COPHH * cophh_store_sv (COPHH *cophh, SV *key, U32 hash,
2506 SV *value, U32 flags)
2507 "cop_hints_exists_pv"
2509 "cop_hints_exists_pvn"
2510 "cop_hints_exists_pvs"
2511 "cop_hints_exists_sv"
2512 These look up the hint entry in the cop "cop" with the key
2513 specified by "key" (and "keylen" in the "pvn" form), returning true
2514 if a value exists, and false otherwise.
2515 The forms differ in how the key is specified. In all forms, the
2517 key is pointed to by "key". In the plain "pv" form, the key is a C
2518 language NUL-terminated string. In the "pvs" form, the key is a C
2519 language string literal. In the "pvn" form, an additional
2520 parameter, "keylen", specifies the length of the string, which
2521 hence, may contain embedded-NUL characters. In the "sv" form, *key
2522 is an SV, and the key is the PV extracted from that. using
2523 "SvPV_const".
2524 "hash" is a precomputed hash of the key string, or zero if it has
2526 not been precomputed. This parameter is omitted from the "pvs"
2527 form, as it is computed automatically at compile time.
2528 The only flag currently used from the "flags" parameter is
2530 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2531 the "pv*" forms, it specifies whether the key octets are
2532 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2533 form uses the underlying SV to determine the UTF-8ness of the
2534 octets.
2535 bool cop_hints_exists_pv (const COP *cop, const char *key,
2537 U32 hash, U32 flags)
2538 bool cop_hints_exists_pvn(const COP *cop, const char *key,
2539 STRLEN keylen, U32 hash, U32 flags)
2540 bool cop_hints_exists_pvs(const COP *cop, "key", U32 flags)
2541 bool cop_hints_exists_sv (const COP *cop, SV *key, U32 hash,
2542 U32 flags)
2543 "cop_hints_fetch_pv"
2545 "cop_hints_fetch_pvn"
2546 "cop_hints_fetch_pvs"
2547 "cop_hints_fetch_sv"
2548 These look up the hint entry in the cop "cop" with the key
2549 specified by "key" (and "keylen" in the "pvn" form), returning that
2550 value as a mortal scalar copy, or &PL_sv_placeholder if there is no
2551 value associated with the key.
2552 The forms differ in how the key is specified. In the plain "pv"
2554 form, the key is a C language NUL-terminated string. In the "pvs"
2555 form, the key is a C language string literal. In the "pvn" form,
2556 an additional parameter, "keylen", specifies the length of the
2557 string, which hence, may contain embedded-NUL characters. In the
2558 "sv" form, *key is an SV, and the key is the PV extracted from
2559 that. using "SvPV_const".
2560 "hash" is a precomputed hash of the key string, or zero if it has
2562 not been precomputed. This parameter is omitted from the "pvs"
2563 form, as it is computed automatically at compile time.
2564 The only flag currently used from the "flags" parameter is
2566 "COPHH_KEY_UTF8". It is illegal to set this in the "sv" form. In
2567 the "pv*" forms, it specifies whether the key octets are
2568 interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The "sv"
2569 form uses the underlying SV to determine the UTF-8ness of the
2570 octets.
2571 SV * cop_hints_fetch_pv (const COP *cop, const char *key,
2573 U32 hash, U32 flags)
2574 SV * cop_hints_fetch_pvn(const COP *cop, const char *key,
2575 STRLEN keylen, U32 hash, U32 flags)
2576 SV * cop_hints_fetch_pvs(const COP *cop, "key", U32 flags)
2577 SV * cop_hints_fetch_sv (const COP *cop, SV *key, U32 hash,
2578 U32 flags)
2579 "cop_hints_2hv"
2581 Generates and returns a standard Perl hash representing the full
2582 set of hint entries in the cop "cop". "flags" is currently unused
2583 and must be zero.
2584 HV * cop_hints_2hv(const COP *cop, U32 flags)
2586 "CopLABEL"
2588 "CopLABEL_len"
2589 "CopLABEL_len_flags"
2590 These return the label attached to a cop.
2591 "CopLABEL_len" and "CopLABEL_len_flags" additionally store the
2593 number of bytes comprising the returned label into *len.
2594 "CopLABEL_len_flags" additionally returns the UTF-8ness of the
2596 returned label, by setting *flags to 0 or "SVf_UTF8".
2597 const char * CopLABEL (COP *const cop)
2599 const char * CopLABEL_len (COP *const cop, STRLEN *len)
2600 const char * CopLABEL_len_flags(COP *const cop, STRLEN *len,
2601 U32 *flags)
2602 "CopLINE"
2604 Returns the line number in the source code associated with the
2605 "COP" "c"
2606 line_t CopLINE(const COP * c)
2608 "CopSTASH"
2610 Returns the stash associated with "c".
2611 HV * CopSTASH(const COP * c)
2613 "CopSTASH_eq"
2615 Returns a boolean as to whether or not "hv" is the stash associated
2616 with "c".
2617 bool CopSTASH_eq(const COP * c, const HV * hv)
2619 "CopSTASHPV"
2621 Returns the package name of the stash associated with "c", or
2622 "NULL" if no associated stash
2623 char * CopSTASHPV(const COP * c)
2625 "CopSTASHPV_set"
2627 Set the package name of the stash associated with "c", to the NUL-
2628 terminated C string "p", creating the package if necessary.
2629 void CopSTASHPV_set(COP * c, const char * pv)
2631 "CopSTASH_set"
2633 Set the stash associated with "c" to "hv".
2634 bool CopSTASH_set(COP * c, HV * hv)
2636 "cop_store_label"
2638 NOTE: "cop_store_label" is experimental and may change or be
2639 removed without notice.
2640 Save a label into a "cop_hints_hash". You need to set flags to
2642 "SVf_UTF8" for a UTF-8 label. Any other flag is ignored.
2643 void cop_store_label(COP * const cop, const char *label,
2645 STRLEN len, U32 flags)
2646 "PERL_SI"
2648 Use this typedef to declare variables that are to hold "struct
2649 stackinfo".
2650 "PL_curcop"
2652 The currently active COP (control op) roughly representing the
2653 current statement in the source.
2654 On threaded perls, each thread has an independent copy of this
2656 variable; each initialized at creation time with the current value
2657 of the creating thread's copy.
2658 COP* PL_curcop
2660 "RCPV_LEN"
2662 Returns the length of a pv created with rcpv_new(). Note that this
2663 reflects the length of the string from the callers point of view,
2664 it does not include the mandatory null which is always injected at
2665 the end of the string by rcpv_new(). No checks are performed to
2666 ensure that "pv" was actually allocated with rcpv_new(), it is the
2667 callers responsibility to ensure that this is the case.
2668 RCPV * RCPV_LEN(char *pv)
2670 "RCPV_REFCNT_dec"
2672 Decrements the refcount for a "char *" pointer which was created
2673 with a call to rcpv_new(). Same as calling rcpv_free(). No checks
2674 are performed to ensure that "pv" was actually allocated with
2675 rcpv_new(), it is the callers responsibility to ensure that this is
2676 the case.
2677 RCPV * RCPV_REFCNT_dec(char *pv)
2679 "RCPV_REFCNT_inc"
2681 Increments the refcount for a "char *" pointer which was created
2682 with a call to rcpv_new(). Same as calling rcpv_copy(). No checks
2683 are performed to ensure that "pv" was actually allocated with
2684 rcpv_new(), it is the callers responsibility to ensure that this is
2685 the case.
2686 RCPV * RCPV_REFCNT_inc(char *pv)
2688 "RCPV_REFCOUNT"
2690 Returns the refcount for a pv created with rcpv_new(). No checks
2691 are performed to ensure that "pv" was actually allocated with
2692 rcpv_new(), it is the callers responsibility to ensure that this is
2693 the case.
2694 RCPV * RCPV_REFCOUNT(char *pv)
2696 "RCPVx"
2698 Returns the RCPV structure (struct rcpv) for a refcounted string pv
2699 created with rcpv_new(). No checks are performed to ensure that
2700 "pv" was actually allocated with rcpv_new(), it is the callers
2701 responsibility to ensure that this is the case.
2702 RCPV * RCPVx(char *pv)
2704
2706 "custom_op_register"
2707 Register a custom op. See "Custom Operators" in perlguts.
2708 NOTE: "custom_op_register" must be explicitly called as
2710 "Perl_custom_op_register" with an "aTHX_" parameter.
2711 void Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr,
2713 const XOP *xop)
2714 "Perl_custom_op_xop"
2716 Return the XOP structure for a given custom op. This macro should
2717 be considered internal to "OP_NAME" and the other access macros:
2718 use them instead. This macro does call a function. Prior to
2719 5.19.6, this was implemented as a function.
2720 const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
2722 "XopDISABLE"
2724 Temporarily disable a member of the XOP, by clearing the
2725 appropriate flag.
2726 void XopDISABLE(XOP *xop, token which)
2728 "XopENABLE"
2730 Reenable a member of the XOP which has been disabled.
2731 void XopENABLE(XOP *xop, token which)
2733 "XopENTRY"
2735 Return a member of the XOP structure. "which" is a cpp token
2736 indicating which entry to return. If the member is not set this
2737 will return a default value. The return type depends on "which".
2738 This macro evaluates its arguments more than once. If you are
2739 using "Perl_custom_op_xop" to retrieve a "XOP *" from a "OP *", use
2740 the more efficient "XopENTRYCUSTOM" instead.
2741 XopENTRY(XOP *xop, token which)
2743 "XopENTRYCUSTOM"
2745 Exactly like "XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o),
2746 which)" but more efficient. The "which" parameter is identical to
2747 "XopENTRY".
2748 XopENTRYCUSTOM(const OP *o, token which)
2750 "XopENTRY_set"
2752 Set a member of the XOP structure. "which" is a cpp token
2753 indicating which entry to set. See "Custom Operators" in perlguts
2754 for details about the available members and how they are used.
2755 This macro evaluates its argument more than once.
2756 void XopENTRY_set(XOP *xop, token which, value)
2758 "XopFLAGS"
2760 Return the XOP's flags.
2761 U32 XopFLAGS(XOP *xop)
2763
2765 This section documents functions to manipulate CVs which are code-
2766 values, meaning subroutines. For more information, see perlguts.
2767 "caller_cx"
2769 The XSUB-writer's equivalent of caller(). The returned
2770 "PERL_CONTEXT" structure can be interrogated to find all the
2771 information returned to Perl by "caller". Note that XSUBs don't
2772 get a stack frame, so "caller_cx(0, NULL)" will return information
2773 for the immediately-surrounding Perl code.
2774 This function skips over the automatic calls to &DB::sub made on
2776 the behalf of the debugger. If the stack frame requested was a sub
2777 called by "DB::sub", the return value will be the frame for the
2778 call to "DB::sub", since that has the correct line number/etc. for
2779 the call site. If dbcxp is non-"NULL", it will be set to a pointer
2780 to the frame for the sub call itself.
2781 const PERL_CONTEXT * caller_cx(I32 level,
2783 const PERL_CONTEXT **dbcxp)
2784 "CvDEPTH"
2786 Returns the recursion level of the CV "sv". Hence >= 2 indicates
2787 we are in a recursive call.
2788 I32 * CvDEPTH(const CV * const sv)
2790 "CvGV"
2792 Returns the GV associated with the CV "sv", reifying it if
2793 necessary.
2794 GV * CvGV(CV *sv)
2796 "CvSTASH"
2798 Returns the stash of the CV. A stash is the symbol table hash,
2799 containing the package-scoped variables in the package where the
2800 subroutine was defined. For more information, see perlguts.
2801 This also has a special use with XS AUTOLOAD subs. See
2803 "Autoloading with XSUBs" in perlguts.
2804 HV* CvSTASH(CV* cv)
2806 "find_runcv"
2808 Locate the CV corresponding to the currently executing sub or eval.
2809 If "db_seqp" is non_null, skip CVs that are in the DB package and
2810 populate *db_seqp with the cop sequence number at the point that
2811 the DB:: code was entered. (This allows debuggers to eval in the
2812 scope of the breakpoint rather than in the scope of the debugger
2813 itself.)
2814 CV * find_runcv(U32 *db_seqp)
2816 "get_cv"
2818 "get_cvn_flags"
2819 "get_cvs"
2820 These return the CV of the specified Perl subroutine. "flags" are
2821 passed to "gv_fetchpvn_flags". If "GV_ADD" is set and the Perl
2822 subroutine does not exist then it will be declared (which has the
2823 same effect as saying "sub name;"). If "GV_ADD" is not set and the
2824 subroutine does not exist, then NULL is returned.
2825 The forms differ only in how the subroutine is specified.. With
2827 "get_cvs", the name is a literal C string, enclosed in double
2828 quotes. With "get_cv", the name is given by the "name" parameter,
2829 which must be a NUL-terminated C string. With "get_cvn_flags", the
2830 name is also given by the "name" parameter, but it is a Perl string
2831 (possibly containing embedded NUL bytes), and its length in bytes
2832 is contained in the "len" parameter.
2833 NOTE: the perl_get_cv() form is deprecated.
2835 NOTE: the perl_get_cvn_flags() form is deprecated.
2837 NOTE: the perl_get_cvs() form is deprecated.
2839 CV * get_cv (const char *name, I32 flags)
2841 CV * get_cvn_flags(const char *name, STRLEN len, I32 flags)
2842 CV * get_cvs ("string", I32 flags)
2843 "Nullcv"
2845 "DEPRECATED!" It is planned to remove "Nullcv" from a future
2846 release of Perl. Do not use it for new code; remove it from
2847 existing code.
2848 Null CV pointer.
2850 (deprecated - use "(CV *)NULL" instead)
2852
2854 "av_dump"
2855 Dumps the contents of an AV to the "STDERR" filehandle, Similar to
2856 using Devel::Peek on an arrayref but does not expect an RV wrapper.
2857 Dumps contents to a depth of 3 levels deep.
2858 void av_dump(AV *av)
2860 "deb"
2862 "deb_nocontext"
2863 When perl is compiled with "-DDEBUGGING", this prints to STDERR the
2864 information given by the arguments, prefaced by the name of the
2865 file containing the script causing the call, and the line number
2866 within that file.
2867 If the "v" (verbose) debugging option is in effect, the process id
2869 is also printed.
2870 The two forms differ only in that "deb_nocontext" does not take a
2872 thread context ("aTHX") parameter, so is used in situations where
2873 the caller doesn't already have the thread context.
2874 NOTE: "deb" must be explicitly called as "Perl_deb" with an "aTHX_"
2876 parameter.
2877 void Perl_deb (pTHX_ const char *pat, ...)
2879 void deb_nocontext(const char *pat, ...)
2880 "debstack"
2882 Dump the current stack
2883 I32 debstack()
2885 "dump_all"
2887 Dumps the entire optree of the current program starting at
2888 "PL_main_root" to "STDERR". Also dumps the optrees for all visible
2889 subroutines in "PL_defstash".
2890 void dump_all()
2892 "dump_c_backtrace"
2894 Dumps the C backtrace to the given "fp".
2895 Returns true if a backtrace could be retrieved, false if not.
2897 bool dump_c_backtrace(PerlIO *fp, int max_depth, int skip)
2899 "dump_eval"
2901 Described in perlguts.
2902 void dump_eval()
2904 "dump_form"
2906 Dumps the contents of the format contained in the GV "gv" to
2907 "STDERR", or a message that one doesn't exist.
2908 void dump_form(const GV *gv)
2910 "dump_packsubs"
2912 Dumps the optrees for all visible subroutines in "stash".
2913 void dump_packsubs(const HV *stash)
2915 "dump_sub"
2917 Described in perlguts.
2918 void dump_sub(const GV *gv)
2920 "get_c_backtrace_dump"
2922 Returns a SV containing a dump of "depth" frames of the call stack,
2923 skipping the "skip" innermost ones. "depth" of 20 is usually
2924 enough.
2925 The appended output looks like:
2927 ...
2929 1 10e004812:0082 Perl_croak util.c:1716 /usr/bin/perl
2930 2 10df8d6d2:1d72 perl_parse perl.c:3975 /usr/bin/perl
2931 ...
2932 The fields are tab-separated. The first column is the depth (zero
2934 being the innermost non-skipped frame). In the hex:offset, the hex
2935 is where the program counter was in "S_parse_body", and the :offset
2936 (might be missing) tells how much inside the "S_parse_body" the
2937 program counter was.
2938 The "util.c:1716" is the source code file and line number.
2940 The /usr/bin/perl is obvious (hopefully).
2942 Unknowns are "-". Unknowns can happen unfortunately quite easily:
2944 if the platform doesn't support retrieving the information; if the
2945 binary is missing the debug information; if the optimizer has
2946 transformed the code by for example inlining.
2947 SV * get_c_backtrace_dump(int max_depth, int skip)
2949 "gv_dump"
2951 Dump the name and, if they differ, the effective name of the GV
2952 "gv" to "STDERR".
2953 void gv_dump(GV *gv)
2955 "HAS_BACKTRACE"
2957 This symbol, if defined, indicates that the backtrace() routine is
2958 available to get a stack trace. The execinfo.h header must be
2959 included to use this routine.
2960 "hv_dump"
2962 Dumps the contents of an HV to the "STDERR" filehandle. Similar to
2963 using Devel::Peek on an hashref but does not expect an RV wrapper.
2964 Dumps contents to a depth of 3 levels deep.
2965 void hv_dump(HV *hv)
2967 "magic_dump"
2969 Dumps the contents of the MAGIC "mg" to "STDERR".
2970 void magic_dump(const MAGIC *mg)
2972 "op_class"
2974 Given an op, determine what type of struct it has been allocated
2975 as. Returns one of the OPclass enums, such as OPclass_LISTOP.
2976 OPclass op_class(const OP *o)
2978 "op_dump"
2980 Dumps the optree starting at OP "o" to "STDERR".
2981 void op_dump(const OP *o)
2983 "PL_op"
2985 Described in perlhacktips.
2986 "PL_runops"
2988 Described in perlguts.
2989 "PL_sv_serial"
2991 Described in perlhacktips.
2992 "pmop_dump"
2994 Dump an OP that is related to Pattern Matching, such as
2995 "s/foo/bar/"; these require special handling.
2996 void pmop_dump(PMOP *pm)
2998 "sv_dump"
3000 Dumps the contents of an SV to the "STDERR" filehandle.
3001 For an example of its output, see Devel::Peek. If the item is an
3003 SvROK it will dump items to a depth of 4, otherwise it will dump
3004 only the top level item, which means that it will not dump the
3005 contents of an AV * or HV *. For that use av_dump() or hv_dump().
3006 void sv_dump(SV *sv)
3008 "sv_dump_depth"
3010 Dumps the contents of an SV to the "STDERR" filehandle to the depth
3011 requested. This function can be used on any SV derived type (GV,
3012 HV, AV) with an appropriate cast. This is a more flexible variant
3013 of sv_dump(). For example
3014 HV *hv = ...;
3016 sv_dump_depth((SV*)hv, 2);
3017 would dump the hv, its keys and values, but would not recurse into
3019 any RV values.
3020 void sv_dump_depth(SV *sv, I32 depth)
3022 "vdeb"
3024 This is like "deb", but "args" are an encapsulated argument list.
3025 void vdeb(const char *pat, va_list *args)
3027
3029 "form"
3030 "form_nocontext"
3031 These take a sprintf-style format pattern and conventional (non-SV)
3032 arguments and return the formatted string.
3033 (char *) Perl_form(pTHX_ const char* pat, ...)
3035 can be used any place a string (char *) is required:
3037 char * s = Perl_form("%d.%d",major,minor);
3039 They use a single (per-thread) private buffer so if you want to
3041 format several strings you must explicitly copy the earlier strings
3042 away (and free the copies when you are done).
3043 The two forms differ only in that "form_nocontext" does not take a
3045 thread context ("aTHX") parameter, so is used in situations where
3046 the caller doesn't already have the thread context.
3047 NOTE: "form" must be explicitly called as "Perl_form" with an
3049 "aTHX_" parameter.
3050 char * Perl_form (pTHX_ const char *pat, ...)
3052 char * form_nocontext(const char *pat, ...)
3053 "mess"
3055 "mess_nocontext"
3056 These take a sprintf-style format pattern and argument list, which
3057 are used to generate a string message. If the message does not end
3058 with a newline, then it will be extended with some indication of
3059 the current location in the code, as described for "mess_sv".
3060 Normally, the resulting message is returned in a new mortal SV.
3062 But during global destruction a single SV may be shared between
3063 uses of this function.
3064 The two forms differ only in that "mess_nocontext" does not take a
3066 thread context ("aTHX") parameter, so is used in situations where
3067 the caller doesn't already have the thread context.
3068 NOTE: "mess" must be explicitly called as "Perl_mess" with an
3070 "aTHX_" parameter.
3071 SV * Perl_mess (pTHX_ const char *pat, ...)
3073 SV * mess_nocontext(const char *pat, ...)
3074 "mess_sv"
3076 Expands a message, intended for the user, to include an indication
3077 of the current location in the code, if the message does not
3078 already appear to be complete.
3079 "basemsg" is the initial message or object. If it is a reference,
3081 it will be used as-is and will be the result of this function.
3082 Otherwise it is used as a string, and if it already ends with a
3083 newline, it is taken to be complete, and the result of this
3084 function will be the same string. If the message does not end with
3085 a newline, then a segment such as "at foo.pl line 37" will be
3086 appended, and possibly other clauses indicating the current state
3087 of execution. The resulting message will end with a dot and a
3088 newline.
3089 Normally, the resulting message is returned in a new mortal SV.
3091 During global destruction a single SV may be shared between uses of
3092 this function. If "consume" is true, then the function is
3093 permitted (but not required) to modify and return "basemsg" instead
3094 of allocating a new SV.
3095 SV * mess_sv(SV *basemsg, bool consume)
3097 "pv_display"
3099 Similar to
3100 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
3102 except that an additional "\0" will be appended to the string when
3104 len > cur and pv[cur] is "\0".
3105 Note that the final string may be up to 7 chars longer than pvlim.
3107 char * pv_display(SV *dsv, const char *pv, STRLEN cur,
3109 STRLEN len, STRLEN pvlim)
3110 "pv_escape"
3112 Escapes at most the first "count" chars of "pv" and puts the
3113 results into "dsv" such that the size of the escaped string will
3114 not exceed "max" chars and will not contain any incomplete escape
3115 sequences. The number of bytes escaped will be returned in the
3116 "STRLEN *escaped" parameter if it is not null. When the "dsv"
3117 parameter is null no escaping actually occurs, but the number of
3118 bytes that would be escaped were it not null will be calculated.
3119 If flags contains "PERL_PV_ESCAPE_QUOTE" then any double quotes in
3121 the string will also be escaped.
3122 Normally the SV will be cleared before the escaped string is
3124 prepared, but when "PERL_PV_ESCAPE_NOCLEAR" is set this will not
3125 occur.
3126 If "PERL_PV_ESCAPE_UNI" is set then the input string is treated as
3128 UTF-8. If "PERL_PV_ESCAPE_UNI_DETECT" is set then the input string
3129 is scanned using is_utf8_string() to determine if it is UTF-8.
3130 If "PERL_PV_ESCAPE_ALL" is set then all input chars will be output
3132 using "\x01F1" style escapes, otherwise if
3133 "PERL_PV_ESCAPE_NONASCII" is set, only non-ASCII chars will be
3134 escaped using this style; otherwise, only chars above 255 will be
3135 so escaped; other non printable chars will use octal or common
3136 escaped patterns like "\n". Otherwise, if
3137 "PERL_PV_ESCAPE_NOBACKSLASH" then all chars below 255 will be
3138 treated as printable and will be output as literals. The
3139 "PERL_PV_ESCAPE_NON_WC" modifies the previous rules to cause word
3140 chars, unicode or otherwise, to be output as literals, note this
3141 uses the *unicode* rules for deciding on word characters.
3142 If "PERL_PV_ESCAPE_FIRSTCHAR" is set then only the first char of
3144 the string will be escaped, regardless of max. If the output is to
3145 be in hex, then it will be returned as a plain hex sequence. Thus
3146 the output will either be a single char, an octal escape sequence,
3147 a special escape like "\n" or a hex value.
3148 If "PERL_PV_ESCAPE_RE" is set then the escape char used will be a
3150 "%" and not a "\\". This is because regexes very often contain
3151 backslashed sequences, whereas "%" is not a particularly common
3152 character in patterns.
3153 Returns a pointer to the escaped text as held by "dsv".
3155 char * pv_escape(SV *dsv, char const * const str,
3157 const STRLEN count, STRLEN max,
3158 STRLEN * const escaped, U32 flags)
3159 "pv_pretty"
3161 Converts a string into something presentable, handling escaping via
3162 pv_escape() and supporting quoting and ellipses.
3163 If the "PERL_PV_PRETTY_QUOTE" flag is set then the result will be
3165 double quoted with any double quotes in the string escaped.
3166 Otherwise if the "PERL_PV_PRETTY_LTGT" flag is set then the result
3167 be wrapped in angle brackets.
3168 If the "PERL_PV_PRETTY_ELLIPSES" flag is set and not all characters
3170 in string were output then an ellipsis "..." will be appended to
3171 the string. Note that this happens AFTER it has been quoted.
3172 If "start_color" is non-null then it will be inserted after the
3174 opening quote (if there is one) but before the escaped text. If
3175 "end_color" is non-null then it will be inserted after the escaped
3176 text but before any quotes or ellipses.
3177 Returns a pointer to the prettified text as held by "dsv".
3179 char * pv_pretty(SV *dsv, char const * const str,
3181 const STRLEN count, const STRLEN max,
3182 char const * const start_color,
3183 char const * const end_color, const U32 flags)
3184 "vform"
3186 Like "form" but but the arguments are an encapsulated argument
3187 list.
3188 char * vform(const char *pat, va_list *args)
3190 "vmess"
3192 "pat" and "args" are a sprintf-style format pattern and
3193 encapsulated argument list, respectively. These are used to
3194 generate a string message. If the message does not end with a
3195 newline, then it will be extended with some indication of the
3196 current location in the code, as described for "mess_sv".
3197 Normally, the resulting message is returned in a new mortal SV.
3199 During global destruction a single SV may be shared between uses of
3200 this function.
3201 SV * vmess(const char *pat, va_list *args)
3203
3205 "call_atexit"
3206 Add a function "fn" to the list of functions to be called at global
3207 destruction. "ptr" will be passed as an argument to "fn"; it can
3208 point to a "struct" so that you can pass anything you want.
3209 Note that under threads, "fn" may run multiple times. This is
3211 because the list is executed each time the current or any
3212 descendent thread terminates.
3213 void call_atexit(ATEXIT_t fn, void *ptr)
3215 "cv_clone"
3217 Clone a CV, making a lexical closure. "proto" supplies the
3218 prototype of the function: its code, pad structure, and other
3219 attributes. The prototype is combined with a capture of outer
3220 lexicals to which the code refers, which are taken from the
3221 currently-executing instance of the immediately surrounding code.
3222 CV * cv_clone(CV *proto)
3224 "cv_name"
3226 Returns an SV containing the name of the CV, mainly for use in
3227 error reporting. The CV may actually be a GV instead, in which
3228 case the returned SV holds the GV's name. Anything other than a GV
3229 or CV is treated as a string already holding the sub name, but this
3230 could change in the future.
3231 An SV may be passed as a second argument. If so, the name will be
3233 assigned to it and it will be returned. Otherwise the returned SV
3234 will be a new mortal.
3235 If "flags" has the "CV_NAME_NOTQUAL" bit set, then the package name
3237 will not be included. If the first argument is neither a CV nor a
3238 GV, this flag is ignored (subject to change).
3239 SV * cv_name(CV *cv, SV *sv, U32 flags)
3241 "cv_undef"
3243 Clear out all the active components of a CV. This can happen
3244 either by an explicit "undef &foo", or by the reference count going
3245 to zero. In the former case, we keep the "CvOUTSIDE" pointer, so
3246 that any anonymous children can still follow the full lexical scope
3247 chain.
3248 void cv_undef(CV *cv)
3250 "find_rundefsv"
3252 Returns the global variable $_.
3253 SV * find_rundefsv()
3255 "get_op_descs"
3257 "DEPRECATED!" It is planned to remove "get_op_descs" from a future
3258 release of Perl. Do not use it for new code; remove it from
3259 existing code.
3260 Return a pointer to the array of all the descriptions of the
3262 various OPs Given an opcode from the enum in opcodes.h,
3263 "PL_op_desc[opcode]" returns a pointer to a C language string
3264 giving its description.
3265 char ** get_op_descs()
3267 "get_op_names"
3269 "DEPRECATED!" It is planned to remove "get_op_names" from a future
3270 release of Perl. Do not use it for new code; remove it from
3271 existing code.
3272 Return a pointer to the array of all the names of the various OPs
3274 Given an opcode from the enum in opcodes.h, "PL_op_name[opcode]"
3275 returns a pointer to a C language string giving its name.
3276 char ** get_op_names()
3278 "HAS_SKIP_LOCALE_INIT"
3280 Described in perlembed.
3281 "intro_my"
3283 "Introduce" "my" variables to visible status. This is called
3284 during parsing at the end of each statement to make lexical
3285 variables visible to subsequent statements.
3286 U32 intro_my()
3288 "load_module"
3290 "load_module_nocontext"
3291 These load the module whose name is pointed to by the string part
3292 of "name". Note that the actual module name, not its filename,
3293 should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver, if
3294 specified and not NULL, provides version semantics similar to "use
3295 Foo::Bar VERSION". The optional trailing arguments can be used to
3296 specify arguments to the module's import() method, similar to "use
3297 Foo::Bar VERSION LIST"; their precise handling depends on the
3298 flags. The flags argument is a bitwise-ORed collection of any of
3299 "PERL_LOADMOD_DENY", "PERL_LOADMOD_NOIMPORT", or
3300 "PERL_LOADMOD_IMPORT_OPS" (or 0 for no flags).
3301 If "PERL_LOADMOD_NOIMPORT" is set, the module is loaded as if with
3303 an empty import list, as in "use Foo::Bar ()"; this is the only
3304 circumstance in which the trailing optional arguments may be
3305 omitted entirely. Otherwise, if "PERL_LOADMOD_IMPORT_OPS" is set,
3306 the trailing arguments must consist of exactly one "OP*",
3307 containing the op tree that produces the relevant import arguments.
3308 Otherwise, the trailing arguments must all be "SV*" values that
3309 will be used as import arguments; and the list must be terminated
3310 with "(SV*) NULL". If neither "PERL_LOADMOD_NOIMPORT" nor
3311 "PERL_LOADMOD_IMPORT_OPS" is set, the trailing "NULL" pointer is
3312 needed even if no import arguments are desired. The reference count
3313 for each specified "SV*" argument is decremented. In addition, the
3314 "name" argument is modified.
3315 If "PERL_LOADMOD_DENY" is set, the module is loaded as if with "no"
3317 rather than "use".
3318 "load_module" and "load_module_nocontext" have the same apparent
3320 signature, but the former hides the fact that it is accessing a
3321 thread context parameter. So use the latter when you get a
3322 compilation error about "pTHX".
3323 void load_module (U32 flags, SV *name, SV *ver, ...)
3325 void load_module_nocontext(U32 flags, SV *name, SV *ver, ...)
3326 "my_exit"
3328 A wrapper for the C library exit(3), honoring what "PL_exit_flags"
3329 in perlapi say to do.
3330 void my_exit(U32 status)
3332 "my_failure_exit"
3334 Exit the running Perl process with an error.
3335 On non-VMS platforms, this is essentially equivalent to
3337 ""my_exit"", using "errno", but forces an en error code of 255 if
3338 "errno" is 0.
3339 On VMS, it takes care to set the appropriate severity bits in the
3341 exit status.
3342 void my_failure_exit()
3344 "my_strlcat"
3346 The C library "strlcat" if available, or a Perl implementation of
3347 it. This operates on C "NUL"-terminated strings.
3348 my_strlcat() appends string "src" to the end of "dst". It will
3350 append at most "size - strlen(dst) - 1" characters. It will then
3351 "NUL"-terminate, unless "size" is 0 or the original "dst" string
3352 was longer than "size" (in practice this should not happen as it
3353 means that either "size" is incorrect or that "dst" is not a proper
3354 "NUL"-terminated string).
3355 Note that "size" is the full size of the destination buffer and the
3357 result is guaranteed to be "NUL"-terminated if there is room. Note
3358 that room for the "NUL" should be included in "size".
3359 The return value is the total length that "dst" would have if
3361 "size" is sufficiently large. Thus it is the initial length of
3362 "dst" plus the length of "src". If "size" is smaller than the
3363 return, the excess was not appended.
3364 Size_t my_strlcat(char *dst, const char *src, Size_t size)
3366 "my_strlcpy"
3368 The C library "strlcpy" if available, or a Perl implementation of
3369 it. This operates on C "NUL"-terminated strings.
3370 my_strlcpy() copies up to "size - 1" characters from the string
3372 "src" to "dst", "NUL"-terminating the result if "size" is not 0.
3373 The return value is the total length "src" would be if the copy
3375 completely succeeded. If it is larger than "size", the excess was
3376 not copied.
3377 Size_t my_strlcpy(char *dst, const char *src, Size_t size)
3379 "newPADNAMELIST"
3381 NOTE: "newPADNAMELIST" is experimental and may change or be removed
3382 without notice.
3383 Creates a new pad name list. "max" is the highest index for which
3385 space is allocated.
3386 PADNAMELIST * newPADNAMELIST(size_t max)
3388 "newPADNAMEouter"
3390 NOTE: "newPADNAMEouter" is experimental and may change or be
3391 removed without notice.
3392 Constructs and returns a new pad name. Only use this function for
3394 names that refer to outer lexicals. (See also "newPADNAMEpvn".)
3395 "outer" is the outer pad name that this one mirrors. The returned
3396 pad name has the "PADNAMEf_OUTER" flag already set.
3397 PADNAME * newPADNAMEouter(PADNAME *outer)
3399 "newPADNAMEpvn"
3401 NOTE: "newPADNAMEpvn" is experimental and may change or be removed
3402 without notice.
3403 Constructs and returns a new pad name. "s" must be a UTF-8 string.
3405 Do not use this for pad names that point to outer lexicals. See
3406 "newPADNAMEouter".
3407 PADNAME * newPADNAMEpvn(const char *s, STRLEN len)
3409 "nothreadhook"
3411 Stub that provides thread hook for perl_destruct when there are no
3412 threads.
3413 int nothreadhook()
3415 "pad_add_anon"
3417 Allocates a place in the currently-compiling pad (via "pad_alloc")
3418 for an anonymous function that is lexically scoped inside the
3419 currently-compiling function. The function "func" is linked into
3420 the pad, and its "CvOUTSIDE" link to the outer scope is weakened to
3421 avoid a reference loop.
3422 One reference count is stolen, so you may need to do
3424 SvREFCNT_inc(func).
3425 "optype" should be an opcode indicating the type of operation that
3427 the pad entry is to support. This doesn't affect operational
3428 semantics, but is used for debugging.
3429 PADOFFSET pad_add_anon(CV *func, I32 optype)
3431 "pad_add_name_pv"
3433 Exactly like "pad_add_name_pvn", but takes a nul-terminated string
3434 instead of a string/length pair.
3435 PADOFFSET pad_add_name_pv(const char *name, const U32 flags,
3437 HV *typestash, HV *ourstash)
3438 "pad_add_name_pvn"
3440 Allocates a place in the currently-compiling pad for a named
3441 lexical variable. Stores the name and other metadata in the name
3442 part of the pad, and makes preparations to manage the variable's
3443 lexical scoping. Returns the offset of the allocated pad slot.
3444 "namepv"/"namelen" specify the variable's name, including leading
3446 sigil. If "typestash" is non-null, the name is for a typed
3447 lexical, and this identifies the type. If "ourstash" is non-null,
3448 it's a lexical reference to a package variable, and this identifies
3449 the package. The following flags can be OR'ed together:
3450 padadd_OUR redundantly specifies if it's a package var
3452 padadd_STATE variable will retain value persistently
3453 padadd_NO_DUP_CHECK skip check for lexical shadowing
3454 padadd_FIELD specifies that the lexical is a field for a class
3455 PADOFFSET pad_add_name_pvn(const char *namepv, STRLEN namelen,
3457 U32 flags, HV *typestash,
3458 HV *ourstash)
3459 "pad_add_name_sv"
3461 Exactly like "pad_add_name_pvn", but takes the name string in the
3462 form of an SV instead of a string/length pair.
3463 PADOFFSET pad_add_name_sv(SV *name, U32 flags, HV *typestash,
3465 HV *ourstash)
3466 "pad_alloc"
3468 NOTE: "pad_alloc" is experimental and may change or be removed
3469 without notice.
3470 Allocates a place in the currently-compiling pad, returning the
3472 offset of the allocated pad slot. No name is initially attached to
3473 the pad slot. "tmptype" is a set of flags indicating the kind of
3474 pad entry required, which will be set in the value SV for the
3475 allocated pad entry:
3476 SVs_PADMY named lexical variable ("my", "our", "state")
3478 SVs_PADTMP unnamed temporary store
3479 SVf_READONLY constant shared between recursion levels
3480 "SVf_READONLY" has been supported here only since perl 5.20. To
3482 work with earlier versions as well, use "SVf_READONLY|SVs_PADTMP".
3483 "SVf_READONLY" does not cause the SV in the pad slot to be marked
3484 read-only, but simply tells "pad_alloc" that it will be made read-
3485 only (by the caller), or at least should be treated as such.
3486 "optype" should be an opcode indicating the type of operation that
3488 the pad entry is to support. This doesn't affect operational
3489 semantics, but is used for debugging.
3490 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
3492 "pad_findmy_pv"
3494 Exactly like "pad_findmy_pvn", but takes a nul-terminated string
3495 instead of a string/length pair.
3496 PADOFFSET pad_findmy_pv(const char *name, U32 flags)
3498 "pad_findmy_pvn"
3500 Given the name of a lexical variable, find its position in the
3501 currently-compiling pad. "namepv"/"namelen" specify the variable's
3502 name, including leading sigil. "flags" is reserved and must be
3503 zero. If it is not in the current pad but appears in the pad of
3504 any lexically enclosing scope, then a pseudo-entry for it is added
3505 in the current pad. Returns the offset in the current pad, or
3506 "NOT_IN_PAD" if no such lexical is in scope.
3507 PADOFFSET pad_findmy_pvn(const char *namepv, STRLEN namelen,
3509 U32 flags)
3510 "pad_findmy_sv"
3512 Exactly like "pad_findmy_pvn", but takes the name string in the
3513 form of an SV instead of a string/length pair.
3514 PADOFFSET pad_findmy_sv(SV *name, U32 flags)
3516 "padnamelist_fetch"
3518 NOTE: "padnamelist_fetch" is experimental and may change or be
3519 removed without notice.
3520 Fetches the pad name from the given index.
3522 PADNAME * padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
3524 "padnamelist_store"
3526 NOTE: "padnamelist_store" is experimental and may change or be
3527 removed without notice.
3528 Stores the pad name (which may be null) at the given index, freeing
3530 any existing pad name in that slot.
3531 PADNAME ** padnamelist_store(PADNAMELIST *pnl, SSize_t key,
3533 PADNAME *val)
3534 "pad_tidy"
3536 NOTE: "pad_tidy" is experimental and may change or be removed
3537 without notice.
3538 Tidy up a pad at the end of compilation of the code to which it
3540 belongs. Jobs performed here are: remove most stuff from the pads
3541 of anonsub prototypes; give it a @_; mark temporaries as such.
3542 "type" indicates the kind of subroutine:
3543 padtidy_SUB ordinary subroutine
3545 padtidy_SUBCLONE prototype for lexical closure
3546 padtidy_FORMAT format
3547 void pad_tidy(padtidy_type type)
3549 "perl_alloc"
3551 Allocates a new Perl interpreter. See perlembed.
3552 PerlInterpreter * perl_alloc()
3554 "PERL_ASYNC_CHECK"
3556 Described in perlinterp.
3557 void PERL_ASYNC_CHECK()
3559 "perl_clone"
3561 Create and return a new interpreter by cloning the current one.
3562 "perl_clone" takes these flags as parameters:
3564 "CLONEf_COPY_STACKS" - is used to, well, copy the stacks also,
3566 without it we only clone the data and zero the stacks, with it we
3567 copy the stacks and the new perl interpreter is ready to run at the
3568 exact same point as the previous one. The pseudo-fork code uses
3569 "COPY_STACKS" while the threads->create doesn't.
3570 "CLONEf_KEEP_PTR_TABLE" - "perl_clone" keeps a ptr_table with the
3572 pointer of the old variable as a key and the new variable as a
3573 value, this allows it to check if something has been cloned and not
3574 clone it again, but rather just use the value and increase the
3575 refcount. If "KEEP_PTR_TABLE" is not set then "perl_clone" will
3576 kill the ptr_table using the function
3577 "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;". A reason to
3578 keep it around is if you want to dup some of your own variables
3579 which are outside the graph that perl scans.
3580 "CLONEf_CLONE_HOST" - This is a win32 thing, it is ignored on unix,
3582 it tells perl's win32host code (which is c++) to clone itself, this
3583 is needed on win32 if you want to run two threads at the same time,
3584 if you just want to do some stuff in a separate perl interpreter
3585 and then throw it away and return to the original one, you don't
3586 need to do anything.
3587 PerlInterpreter * perl_clone(PerlInterpreter *proto_perl,
3589 UV flags)
3590 "perl_construct"
3592 Initializes a new Perl interpreter. See perlembed.
3593 void perl_construct(PerlInterpreter *my_perl)
3595 "perl_destruct"
3597 Shuts down a Perl interpreter. See perlembed for a tutorial.
3598 "my_perl" points to the Perl interpreter. It must have been
3600 previously created through the use of "perl_alloc" and
3601 "perl_construct". It may have been initialised through
3602 "perl_parse", and may have been used through "perl_run" and other
3603 means. This function should be called for any Perl interpreter
3604 that has been constructed with "perl_construct", even if subsequent
3605 operations on it failed, for example if "perl_parse" returned a
3606 non-zero value.
3607 If the interpreter's "PL_exit_flags" word has the
3609 "PERL_EXIT_DESTRUCT_END" flag set, then this function will execute
3610 code in "END" blocks before performing the rest of destruction. If
3611 it is desired to make any use of the interpreter between
3612 "perl_parse" and "perl_destruct" other than just calling
3613 "perl_run", then this flag should be set early on. This matters if
3614 "perl_run" will not be called, or if anything else will be done in
3615 addition to calling "perl_run".
3616 Returns a value be a suitable value to pass to the C library
3618 function "exit" (or to return from "main"), to serve as an exit
3619 code indicating the nature of the way the interpreter terminated.
3620 This takes into account any failure of "perl_parse" and any early
3621 exit from "perl_run". The exit code is of the type required by the
3622 host operating system, so because of differing exit code
3623 conventions it is not portable to interpret specific numeric values
3624 as having specific meanings.
3625 int perl_destruct(PerlInterpreter *my_perl)
3627 "perl_free"
3629 Releases a Perl interpreter. See perlembed.
3630 void perl_free(PerlInterpreter *my_perl)
3632 "PERL_GET_CONTEXT"
3634 Described in perlguts.
3635 "PerlInterpreter"
3637 Described in perlembed.
3638 "perl_parse"
3640 Tells a Perl interpreter to parse a Perl script. This performs
3641 most of the initialisation of a Perl interpreter. See perlembed
3642 for a tutorial.
3643 "my_perl" points to the Perl interpreter that is to parse the
3645 script. It must have been previously created through the use of
3646 "perl_alloc" and "perl_construct". "xsinit" points to a callback
3647 function that will be called to set up the ability for this Perl
3648 interpreter to load XS extensions, or may be null to perform no
3649 such setup.
3650 "argc" and "argv" supply a set of command-line arguments to the
3652 Perl interpreter, as would normally be passed to the "main"
3653 function of a C program. "argv[argc]" must be null. These
3654 arguments are where the script to parse is specified, either by
3655 naming a script file or by providing a script in a "-e" option. If
3656 $0 will be written to in the Perl interpreter, then the argument
3657 strings must be in writable memory, and so mustn't just be string
3658 constants.
3659 "env" specifies a set of environment variables that will be used by
3661 this Perl interpreter. If non-null, it must point to a null-
3662 terminated array of environment strings. If null, the Perl
3663 interpreter will use the environment supplied by the "environ"
3664 global variable.
3665 This function initialises the interpreter, and parses and compiles
3667 the script specified by the command-line arguments. This includes
3668 executing code in "BEGIN", "UNITCHECK", and "CHECK" blocks. It
3669 does not execute "INIT" blocks or the main program.
3670 Returns an integer of slightly tricky interpretation. The correct
3672 use of the return value is as a truth value indicating whether
3673 there was a failure in initialisation. If zero is returned, this
3674 indicates that initialisation was successful, and it is safe to
3675 proceed to call "perl_run" and make other use of it. If a non-zero
3676 value is returned, this indicates some problem that means the
3677 interpreter wants to terminate. The interpreter should not be just
3678 abandoned upon such failure; the caller should proceed to shut the
3679 interpreter down cleanly with "perl_destruct" and free it with
3680 "perl_free".
3681 For historical reasons, the non-zero return value also attempts to
3683 be a suitable value to pass to the C library function "exit" (or to
3684 return from "main"), to serve as an exit code indicating the nature
3685 of the way initialisation terminated. However, this isn't
3686 portable, due to differing exit code conventions. An attempt is
3687 made to return an exit code of the type required by the host
3688 operating system, but because it is constrained to be non-zero, it
3689 is not necessarily possible to indicate every type of exit. It is
3690 only reliable on Unix, where a zero exit code can be augmented with
3691 a set bit that will be ignored. In any case, this function is not
3692 the correct place to acquire an exit code: one should get that from
3693 "perl_destruct".
3694 int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit,
3696 int argc, char **argv, char **env)
3697 "perl_run"
3699 Tells a Perl interpreter to run its main program. See perlembed
3700 for a tutorial.
3701 "my_perl" points to the Perl interpreter. It must have been
3703 previously created through the use of "perl_alloc" and
3704 "perl_construct", and initialised through "perl_parse". This
3705 function should not be called if "perl_parse" returned a non-zero
3706 value, indicating a failure in initialisation or compilation.
3707 This function executes code in "INIT" blocks, and then executes the
3709 main program. The code to be executed is that established by the
3710 prior call to "perl_parse". If the interpreter's "PL_exit_flags"
3711 word does not have the "PERL_EXIT_DESTRUCT_END" flag set, then this
3712 function will also execute code in "END" blocks. If it is desired
3713 to make any further use of the interpreter after calling this
3714 function, then "END" blocks should be postponed to "perl_destruct"
3715 time by setting that flag.
3716 Returns an integer of slightly tricky interpretation. The correct
3718 use of the return value is as a truth value indicating whether the
3719 program terminated non-locally. If zero is returned, this
3720 indicates that the program ran to completion, and it is safe to
3721 make other use of the interpreter (provided that the
3722 "PERL_EXIT_DESTRUCT_END" flag was set as described above). If a
3723 non-zero value is returned, this indicates that the interpreter
3724 wants to terminate early. The interpreter should not be just
3725 abandoned because of this desire to terminate; the caller should
3726 proceed to shut the interpreter down cleanly with "perl_destruct"
3727 and free it with "perl_free".
3728 For historical reasons, the non-zero return value also attempts to
3730 be a suitable value to pass to the C library function "exit" (or to
3731 return from "main"), to serve as an exit code indicating the nature
3732 of the way the program terminated. However, this isn't portable,
3733 due to differing exit code conventions. An attempt is made to
3734 return an exit code of the type required by the host operating
3735 system, but because it is constrained to be non-zero, it is not
3736 necessarily possible to indicate every type of exit. It is only
3737 reliable on Unix, where a zero exit code can be augmented with a
3738 set bit that will be ignored. In any case, this function is not
3739 the correct place to acquire an exit code: one should get that from
3740 "perl_destruct".
3741 int perl_run(PerlInterpreter *my_perl)
3743 "PERL_SET_CONTEXT"
3745 Described in perlguts.
3746 void PERL_SET_CONTEXT(PerlInterpreter* i)
3748 "PERL_SYS_INIT"
3750 "PERL_SYS_INIT3"
3751 These provide system-specific tune up of the C runtime environment
3752 necessary to run Perl interpreters. Only one should be used, and
3753 it should be called only once, before creating any Perl
3754 interpreters.
3755 They differ in that "PERL_SYS_INIT3" also initializes "env".
3757 void PERL_SYS_INIT (int *argc, char*** argv)
3759 void PERL_SYS_INIT3(int *argc, char*** argv, char*** env)
3760 "PERL_SYS_TERM"
3762 Provides system-specific clean up of the C runtime environment
3763 after running Perl interpreters. This should be called only once,
3764 after freeing any remaining Perl interpreters.
3765 void PERL_SYS_TERM()
3767 "PL_exit_flags"
3769 Contains flags controlling perl's behaviour on exit():
3770 • "PERL_EXIT_DESTRUCT_END"
3772 If set, END blocks are executed when the interpreter is
3774 destroyed. This is normally set by perl itself after the
3775 interpreter is constructed.
3776 • "PERL_EXIT_ABORT"
3778 Call abort() on exit. This is used internally by perl itself
3780 to abort if exit is called while processing exit.
3781 • "PERL_EXIT_WARN"
3783 Warn on exit.
3785 • "PERL_EXIT_EXPECTED"
3787 Set by the "exit" in perlfunc operator.
3789 U8 PL_exit_flags
3791 "PL_origalen"
3793 Described in perlembed.
3794 "PL_perl_destruct_level"
3796 This value may be set when embedding for full cleanup.
3797 Possible values:
3799 • 0 - none
3801 • 1 - full
3803 • 2 or greater - full with checks.
3805 If $ENV{PERL_DESTRUCT_LEVEL} is set to an integer greater than the
3807 value of "PL_perl_destruct_level" its value is used instead.
3808 On threaded perls, each thread has an independent copy of this
3810 variable; each initialized at creation time with the current value
3811 of the creating thread's copy.
3812 signed char PL_perl_destruct_level
3814 "ptr_table_fetch"
3816 Look for "sv" in the pointer-mapping table "tbl", returning its
3817 value, or NULL if not found.
3818 void * ptr_table_fetch(PTR_TBL_t * const tbl,
3820 const void * const sv)
3821 "ptr_table_free"
3823 Clear and free a ptr table
3824 void ptr_table_free(PTR_TBL_t * const tbl)
3826 "ptr_table_new"
3828 Create a new pointer-mapping table
3829 PTR_TBL_t * ptr_table_new()
3831 "ptr_table_split"
3833 Double the hash bucket size of an existing ptr table
3834 void ptr_table_split(PTR_TBL_t * const tbl)
3836 "ptr_table_store"
3838 Add a new entry to a pointer-mapping table "tbl". In hash terms,
3839 "oldsv" is the key; Cnewsv> is the value.
3840 The names "old" and "new" are specific to the core's typical use of
3842 ptr_tables in thread cloning.
3843 void ptr_table_store(PTR_TBL_t * const tbl,
3845 const void * const oldsv,
3846 void * const newsv)
3847 "require_pv"
3849 Tells Perl to "require" the file named by the string argument. It
3850 is analogous to the Perl code "eval "require '$file'"". It's even
3851 implemented that way; consider using load_module instead.
3852 NOTE: the perl_require_pv() form is deprecated.
3854 void require_pv(const char *pv)
3856 "vload_module"
3858 Like "load_module" but the arguments are an encapsulated argument
3859 list.
3860 void vload_module(U32 flags, SV *name, SV *ver, va_list *args)
3862
3864 "sv_string_from_errnum"
3865 Generates the message string describing an OS error and returns it
3866 as an SV. "errnum" must be a value that "errno" could take,
3867 identifying the type of error.
3868 If "tgtsv" is non-null then the string will be written into that SV
3870 (overwriting existing content) and it will be returned. If "tgtsv"
3871 is a null pointer then the string will be written into a new mortal
3872 SV which will be returned.
3873 The message will be taken from whatever locale would be used by $!,
3875 and will be encoded in the SV in whatever manner would be used by
3876 $!. The details of this process are subject to future change.
3877 Currently, the message is taken from the C locale by default
3878 (usually producing an English message), and from the currently
3879 selected locale when in the scope of the "use locale" pragma. A
3880 heuristic attempt is made to decode the message from the locale's
3881 character encoding, but it will only be decoded as either UTF-8 or
3882 ISO-8859-1. It is always correctly decoded in a UTF-8 locale,
3883 usually in an ISO-8859-1 locale, and never in any other locale.
3884 The SV is always returned containing an actual string, and with no
3886 other OK bits set. Unlike $!, a message is even yielded for
3887 "errnum" zero (meaning success), and if no useful message is
3888 available then a useless string (currently empty) is returned.
3889 SV * sv_string_from_errnum(int errnum, SV *tgtsv)
3891
3893 "dXCPT"
3894 Set up necessary local variables for exception handling. See
3895 "Exception Handling" in perlguts.
3896 dXCPT;
3898 "JMPENV_JUMP"
3900 Described in perlinterp.
3901 void JMPENV_JUMP(int v)
3903 "JMPENV_PUSH"
3905 Described in perlinterp.
3906 void JMPENV_PUSH(int v)
3908 "PL_restartop"
3910 Described in perlinterp.
3911 "XCPT_CATCH"
3913 Introduces a catch block. See "Exception Handling" in perlguts.
3914 "XCPT_RETHROW"
3916 Rethrows a previously caught exception. See "Exception Handling"
3917 in perlguts.
3918 XCPT_RETHROW;
3920 "XCPT_TRY_END"
3922 Ends a try block. See "Exception Handling" in perlguts.
3923 "XCPT_TRY_START"
3925 Starts a try block. See "Exception Handling" in perlguts.
3926
3928 Also see "List of capability HAS_foo symbols".
3929 "DIRNAMLEN"
3931 This symbol, if defined, indicates to the C program that the length
3932 of directory entry names is provided by a "d_namlen" field.
3933 Otherwise you need to do strlen() on the "d_name" field.
3934 "DOSUID"
3936 This symbol, if defined, indicates that the C program should check
3937 the script that it is executing for setuid/setgid bits, and attempt
3938 to emulate setuid/setgid on systems that have disabled setuid #!
3939 scripts because the kernel can't do it securely. It is up to the
3940 package designer to make sure that this emulation is done securely.
3941 Among other things, it should do an fstat on the script it just
3942 opened to make sure it really is a setuid/setgid script, it should
3943 make sure the arguments passed correspond exactly to the argument
3944 on the #! line, and it should not trust any subprocesses to which
3945 it must pass the filename rather than the file descriptor of the
3946 script to be executed.
3947 "EOF_NONBLOCK"
3949 This symbol, if defined, indicates to the C program that a read()
3950 on a non-blocking file descriptor will return 0 on "EOF", and not
3951 the value held in "RD_NODATA" (-1 usually, in that case!).
3952 "FCNTL_CAN_LOCK"
3954 This symbol, if defined, indicates that fcntl() can be used for
3955 file locking. Normally on Unix systems this is defined. It may be
3956 undefined on "VMS".
3957 "FFLUSH_ALL"
3959 This symbol, if defined, tells that to flush all pending stdio
3960 output one must loop through all the stdio file handles stored in
3961 an array and fflush them. Note that if "fflushNULL" is defined,
3962 fflushall will not even be probed for and will be left undefined.
3963 "FFLUSH_NULL"
3965 This symbol, if defined, tells that fflush(NULL) correctly flushes
3966 all pending stdio output without side effects. In particular, on
3967 some platforms calling fflush(NULL) *still* corrupts "STDIN" if it
3968 is a pipe.
3969 "FILE_base"
3971 This macro is used to access the "_base" field (or equivalent) of
3972 the "FILE" structure pointed to by its argument. This macro will
3973 always be defined if "USE_STDIO_BASE" is defined.
3974 void * FILE_base(FILE * f)
3976 "FILE_bufsiz"
3978 This macro is used to determine the number of bytes in the I/O
3979 buffer pointed to by "_base" field (or equivalent) of the "FILE"
3980 structure pointed to its argument. This macro will always be
3981 defined if "USE_STDIO_BASE" is defined.
3982 Size_t FILE_bufsiz(FILE *f)
3984 "FILE_cnt"
3986 This macro is used to access the "_cnt" field (or equivalent) of
3987 the "FILE" structure pointed to by its argument. This macro will
3988 always be defined if "USE_STDIO_PTR" is defined.
3989 Size_t FILE_cnt(FILE * f)
3991 "FILE_ptr"
3993 This macro is used to access the "_ptr" field (or equivalent) of
3994 the "FILE" structure pointed to by its argument. This macro will
3995 always be defined if "USE_STDIO_PTR" is defined.
3996 void * FILE_ptr(FILE * f)
3998 "FLEXFILENAMES"
4000 This symbol, if defined, indicates that the system supports
4001 filenames longer than 14 characters.
4002 "HAS_DIR_DD_FD"
4004 This symbol, if defined, indicates that the "DIR"* dirstream
4005 structure contains a member variable named "dd_fd".
4006 "HAS_DUP2"
4008 This symbol, if defined, indicates that the "dup2" routine is
4009 available to duplicate file descriptors.
4010 "HAS_DUP3"
4012 This symbol, if defined, indicates that the "dup3" routine is
4013 available to duplicate file descriptors.
4014 "HAS_FAST_STDIO"
4016 This symbol, if defined, indicates that the "fast stdio" is
4017 available to manipulate the stdio buffers directly.
4018 "HAS_FCHDIR"
4020 This symbol, if defined, indicates that the "fchdir" routine is
4021 available to change directory using a file descriptor.
4022 "HAS_FCNTL"
4024 This symbol, if defined, indicates to the C program that the
4025 fcntl() function exists.
4026 "HAS_FDCLOSE"
4028 This symbol, if defined, indicates that the "fdclose" routine is
4029 available to free a "FILE" structure without closing the underlying
4030 file descriptor. This function appeared in "FreeBSD" 10.2.
4031 "HAS_FPATHCONF"
4033 This symbol, if defined, indicates that pathconf() is available to
4034 determine file-system related limits and options associated with a
4035 given open file descriptor.
4036 "HAS_FPOS64_T"
4038 This symbol will be defined if the C compiler supports "fpos64_t".
4039 "HAS_FSTATFS"
4041 This symbol, if defined, indicates that the "fstatfs" routine is
4042 available to stat filesystems by file descriptors.
4043 "HAS_FSTATVFS"
4045 This symbol, if defined, indicates that the "fstatvfs" routine is
4046 available to stat filesystems by file descriptors.
4047 "HAS_GETFSSTAT"
4049 This symbol, if defined, indicates that the "getfsstat" routine is
4050 available to stat filesystems in bulk.
4051 "HAS_GETMNT"
4053 This symbol, if defined, indicates that the "getmnt" routine is
4054 available to get filesystem mount info by filename.
4055 "HAS_GETMNTENT"
4057 This symbol, if defined, indicates that the "getmntent" routine is
4058 available to iterate through mounted file systems to get their
4059 info.
4060 "HAS_HASMNTOPT"
4062 This symbol, if defined, indicates that the "hasmntopt" routine is
4063 available to query the mount options of file systems.
4064 "HAS_LSEEK_PROTO"
4066 This symbol, if defined, indicates that the system provides a
4067 prototype for the lseek() function. Otherwise, it is up to the
4068 program to supply one. A good guess is
4069 extern off_t lseek(int, off_t, int);
4071 "HAS_MKDIR"
4073 This symbol, if defined, indicates that the "mkdir" routine is
4074 available to create directories. Otherwise you should fork off a
4075 new process to exec /bin/mkdir.
4076 "HAS_OFF64_T"
4078 This symbol will be defined if the C compiler supports "off64_t".
4079 "HAS_OPENAT"
4081 This symbol is defined if the openat() routine is available.
4082 "HAS_OPEN3"
4084 This manifest constant lets the C program know that the three
4085 argument form of open(2) is available.
4086 "HAS_POLL"
4088 This symbol, if defined, indicates that the "poll" routine is
4089 available to "poll" active file descriptors. Please check "I_POLL"
4090 and "I_SYS_POLL" to know which header should be included as well.
4091 "HAS_READDIR"
4093 This symbol, if defined, indicates that the "readdir" routine is
4094 available to read directory entries. You may have to include
4095 dirent.h. See "I_DIRENT".
4096 "HAS_READDIR64_R"
4098 This symbol, if defined, indicates that the "readdir64_r" routine
4099 is available to readdir64 re-entrantly.
4100 "HAS_REWINDDIR"
4102 This symbol, if defined, indicates that the "rewinddir" routine is
4103 available. You may have to include dirent.h. See "I_DIRENT".
4104 "HAS_RMDIR"
4106 This symbol, if defined, indicates that the "rmdir" routine is
4107 available to remove directories. Otherwise you should fork off a
4108 new process to exec /bin/rmdir.
4109 "HAS_SEEKDIR"
4111 This symbol, if defined, indicates that the "seekdir" routine is
4112 available. You may have to include dirent.h. See "I_DIRENT".
4113 "HAS_SELECT"
4115 This symbol, if defined, indicates that the "select" routine is
4116 available to "select" active file descriptors. If the timeout field
4117 is used, sys/time.h may need to be included.
4118 "HAS_SETVBUF"
4120 This symbol, if defined, indicates that the "setvbuf" routine is
4121 available to change buffering on an open stdio stream. to a line-
4122 buffered mode.
4123 "HAS_STDIO_STREAM_ARRAY"
4125 This symbol, if defined, tells that there is an array holding the
4126 stdio streams.
4127 "HAS_STRUCT_FS_DATA"
4129 This symbol, if defined, indicates that the "struct fs_data" to do
4130 statfs() is supported.
4131 "HAS_STRUCT_STATFS"
4133 This symbol, if defined, indicates that the "struct statfs" to do
4134 statfs() is supported.
4135 "HAS_STRUCT_STATFS_F_FLAGS"
4137 This symbol, if defined, indicates that the "struct statfs" does
4138 have the "f_flags" member containing the mount flags of the
4139 filesystem containing the file. This kind of "struct statfs" is
4140 coming from sys/mount.h ("BSD" 4.3), not from sys/statfs.h
4141 ("SYSV"). Older "BSDs" (like Ultrix) do not have statfs() and
4142 "struct statfs", they have ustat() and getmnt() with "struct ustat"
4143 and "struct fs_data".
4144 "HAS_TELLDIR"
4146 This symbol, if defined, indicates that the "telldir" routine is
4147 available. You may have to include dirent.h. See "I_DIRENT".
4148 "HAS_USTAT"
4150 This symbol, if defined, indicates that the "ustat" system call is
4151 available to query file system statistics by "dev_t".
4152 "I_FCNTL"
4154 This manifest constant tells the C program to include fcntl.h.
4155 #ifdef I_FCNTL
4157 #include <fcntl.h>
4158 #endif
4159 "I_SYS_DIR"
4161 This symbol, if defined, indicates to the C program that it should
4162 include sys/dir.h.
4163 #ifdef I_SYS_DIR
4165 #include <sys_dir.h>
4166 #endif
4167 "I_SYS_FILE"
4169 This symbol, if defined, indicates to the C program that it should
4170 include sys/file.h to get definition of "R_OK" and friends.
4171 #ifdef I_SYS_FILE
4173 #include <sys_file.h>
4174 #endif
4175 "I_SYS_NDIR"
4177 This symbol, if defined, indicates to the C program that it should
4178 include sys/ndir.h.
4179 #ifdef I_SYS_NDIR
4181 #include <sys_ndir.h>
4182 #endif
4183 "I_SYS_STATFS"
4185 This symbol, if defined, indicates that sys/statfs.h exists.
4186 #ifdef I_SYS_STATFS
4188 #include <sys_statfs.h>
4189 #endif
4190 "LSEEKSIZE"
4192 This symbol holds the number of bytes used by the "Off_t".
4193 "RD_NODATA"
4195 This symbol holds the return code from read() when no data is
4196 present on the non-blocking file descriptor. Be careful! If
4197 "EOF_NONBLOCK" is not defined, then you can't distinguish between
4198 no data and "EOF" by issuing a read(). You'll have to find another
4199 way to tell for sure!
4200 "READDIR64_R_PROTO"
4202 This symbol encodes the prototype of "readdir64_r". It is zero if
4203 "d_readdir64_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
4204 macros of reentr.h if "d_readdir64_r" is defined.
4205 "STDCHAR"
4207 This symbol is defined to be the type of char used in stdio.h. It
4208 has the values "unsigned char" or "char".
4209 "STDIO_CNT_LVALUE"
4211 This symbol is defined if the "FILE_cnt" macro can be used as an
4212 lvalue.
4213 "STDIO_PTR_LVAL_NOCHANGE_CNT"
4215 This symbol is defined if using the "FILE_ptr" macro as an lvalue
4216 to increase the pointer by n leaves File_cnt(fp) unchanged.
4217 "STDIO_PTR_LVAL_SETS_CNT"
4219 This symbol is defined if using the "FILE_ptr" macro as an lvalue
4220 to increase the pointer by n has the side effect of decreasing the
4221 value of File_cnt(fp) by n.
4222 "STDIO_PTR_LVALUE"
4224 This symbol is defined if the "FILE_ptr" macro can be used as an
4225 lvalue.
4226 "STDIO_STREAM_ARRAY"
4228 This symbol tells the name of the array holding the stdio streams.
4229 Usual values include "_iob", "__iob", and "__sF".
4230 "ST_INO_SIGN"
4232 This symbol holds the signedness of "struct stat"'s "st_ino". 1
4233 for unsigned, -1 for signed.
4234 "ST_INO_SIZE"
4236 This variable contains the size of "struct stat"'s "st_ino" in
4237 bytes.
4238 "VAL_EAGAIN"
4240 This symbol holds the errno error code set by read() when no data
4241 was present on the non-blocking file descriptor.
4242 "VAL_O_NONBLOCK"
4244 This symbol is to be used during open() or fcntl(F_SETFL) to turn
4245 on non-blocking I/O for the file descriptor. Note that there is no
4246 way back, i.e. you cannot turn it blocking again this way. If you
4247 wish to alternatively switch between blocking and non-blocking, use
4248 the ioctl(FIOSNBIO) call instead, but that is not supported by all
4249 devices.
4250 "VOID_CLOSEDIR"
4252 This symbol, if defined, indicates that the closedir() routine does
4253 not return a value.
4254
4256 Also "List of capability HAS_foo symbols" lists capabilities that arent
4257 in this section. For example "HAS_ASINH", for the hyperbolic sine
4258 function.
4259 "CASTFLAGS"
4261 This symbol contains flags that say what difficulties the compiler
4262 has casting odd floating values to unsigned long:
4263 0 = ok
4265 1 = couldn't cast < 0
4266 2 = couldn't cast >= 0x80000000
4267 4 = couldn't cast in argument expression list
4268 "CASTNEGFLOAT"
4270 This symbol is defined if the C compiler can cast negative numbers
4271 to unsigned longs, ints and shorts.
4272 "DOUBLE_HAS_INF"
4274 This symbol, if defined, indicates that the double has the
4275 infinity.
4276 "DOUBLE_HAS_NAN"
4278 This symbol, if defined, indicates that the double has the not-a-
4279 number.
4280 "DOUBLE_HAS_NEGATIVE_ZERO"
4282 This symbol, if defined, indicates that the double has the
4283 "negative_zero".
4284 "DOUBLE_HAS_SUBNORMALS"
4286 This symbol, if defined, indicates that the double has the
4287 subnormals (denormals).
4288 "DOUBLEINFBYTES"
4290 This symbol, if defined, is a comma-separated list of hexadecimal
4291 bytes for the double precision infinity.
4292 "DOUBLEKIND"
4294 "DOUBLEKIND" will be one of
4295 "DOUBLE_IS_IEEE_754_32_BIT_LITTLE_ENDIAN"
4296 "DOUBLE_IS_IEEE_754_32_BIT_BIG_ENDIAN"
4297 "DOUBLE_IS_IEEE_754_64_BIT_LITTLE_ENDIAN"
4298 "DOUBLE_IS_IEEE_754_64_BIT_BIG_ENDIAN"
4299 "DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN"
4300 "DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN"
4301 "DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_LE_BE"
4302 "DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_BE_LE"
4303 "DOUBLE_IS_VAX_F_FLOAT" "DOUBLE_IS_VAX_D_FLOAT"
4304 "DOUBLE_IS_VAX_G_FLOAT" "DOUBLE_IS_IBM_SINGLE_32_BIT"
4305 "DOUBLE_IS_IBM_DOUBLE_64_BIT" "DOUBLE_IS_CRAY_SINGLE_64_BIT"
4306 "DOUBLE_IS_UNKNOWN_FORMAT"
4307 "DOUBLEMANTBITS"
4309 This symbol, if defined, tells how many mantissa bits there are in
4310 double precision floating point format. Note that this is usually
4311 "DBL_MANT_DIG" minus one, since with the standard "IEEE" 754
4312 formats "DBL_MANT_DIG" includes the implicit bit, which doesn't
4313 really exist.
4314 "DOUBLENANBYTES"
4316 This symbol, if defined, is a comma-separated list of hexadecimal
4317 bytes (0xHH) for the double precision not-a-number.
4318 "DOUBLESIZE"
4320 This symbol contains the size of a double, so that the C
4321 preprocessor can make decisions based on it.
4322 "DOUBLE_STYLE_CRAY"
4324 This symbol, if defined, indicates that the double is the 64-bit
4325 "CRAY" mainframe format.
4326 "DOUBLE_STYLE_IBM"
4328 This symbol, if defined, indicates that the double is the 64-bit
4329 "IBM" mainframe format.
4330 "DOUBLE_STYLE_IEEE"
4332 This symbol, if defined, indicates that the double is the 64-bit
4333 "IEEE" 754.
4334 "DOUBLE_STYLE_VAX"
4336 This symbol, if defined, indicates that the double is the 64-bit
4337 "VAX" format D or G.
4338 "HAS_ATOLF"
4340 This symbol, if defined, indicates that the "atolf" routine is
4341 available to convert strings into long doubles.
4342 "HAS_CLASS"
4344 This symbol, if defined, indicates that the "class" routine is
4345 available to classify doubles. Available for example in "AIX".
4346 The returned values are defined in float.h and are:
4347 FP_PLUS_NORM Positive normalized, nonzero
4349 FP_MINUS_NORM Negative normalized, nonzero
4350 FP_PLUS_DENORM Positive denormalized, nonzero
4351 FP_MINUS_DENORM Negative denormalized, nonzero
4352 FP_PLUS_ZERO +0.0
4353 FP_MINUS_ZERO -0.0
4354 FP_PLUS_INF +INF
4355 FP_MINUS_INF -INF
4356 FP_NANS Signaling Not a Number (NaNS)
4357 FP_NANQ Quiet Not a Number (NaNQ)
4358 "HAS_FINITE"
4360 This symbol, if defined, indicates that the "finite" routine is
4361 available to check whether a double is "finite" (non-infinity non-
4362 NaN).
4363 "HAS_FINITEL"
4365 This symbol, if defined, indicates that the "finitel" routine is
4366 available to check whether a long double is finite (non-infinity
4367 non-NaN).
4368 "HAS_FPCLASS"
4370 This symbol, if defined, indicates that the "fpclass" routine is
4371 available to classify doubles. Available for example in
4372 Solaris/"SVR4". The returned values are defined in ieeefp.h and
4373 are:
4374 FP_SNAN signaling NaN
4376 FP_QNAN quiet NaN
4377 FP_NINF negative infinity
4378 FP_PINF positive infinity
4379 FP_NDENORM negative denormalized non-zero
4380 FP_PDENORM positive denormalized non-zero
4381 FP_NZERO negative zero
4382 FP_PZERO positive zero
4383 FP_NNORM negative normalized non-zero
4384 FP_PNORM positive normalized non-zero
4385 "HAS_FP_CLASS"
4387 This symbol, if defined, indicates that the "fp_class" routine is
4388 available to classify doubles. Available for example in Digital
4389 "UNIX". The returned values are defined in math.h and are:
4390 FP_SNAN Signaling NaN (Not-a-Number)
4392 FP_QNAN Quiet NaN (Not-a-Number)
4393 FP_POS_INF +infinity
4394 FP_NEG_INF -infinity
4395 FP_POS_NORM Positive normalized
4396 FP_NEG_NORM Negative normalized
4397 FP_POS_DENORM Positive denormalized
4398 FP_NEG_DENORM Negative denormalized
4399 FP_POS_ZERO +0.0 (positive zero)
4400 FP_NEG_ZERO -0.0 (negative zero)
4401 "HAS_FPCLASSIFY"
4403 This symbol, if defined, indicates that the "fpclassify" routine is
4404 available to classify doubles. Available for example in HP-UX.
4405 The returned values are defined in math.h and are
4406 FP_NORMAL Normalized
4408 FP_ZERO Zero
4409 FP_INFINITE Infinity
4410 FP_SUBNORMAL Denormalized
4411 FP_NAN NaN
4412 "HAS_FP_CLASSIFY"
4414 This symbol, if defined, indicates that the "fp_classify" routine
4415 is available to classify doubles. The values are defined in math.h
4416 FP_NORMAL Normalized
4418 FP_ZERO Zero
4419 FP_INFINITE Infinity
4420 FP_SUBNORMAL Denormalized
4421 FP_NAN NaN
4422 "HAS_FPCLASSL"
4424 This symbol, if defined, indicates that the "fpclassl" routine is
4425 available to classify long doubles. Available for example in
4426 "IRIX". The returned values are defined in ieeefp.h and are:
4427 FP_SNAN signaling NaN
4429 FP_QNAN quiet NaN
4430 FP_NINF negative infinity
4431 FP_PINF positive infinity
4432 FP_NDENORM negative denormalized non-zero
4433 FP_PDENORM positive denormalized non-zero
4434 FP_NZERO negative zero
4435 FP_PZERO positive zero
4436 FP_NNORM negative normalized non-zero
4437 FP_PNORM positive normalized non-zero
4438 "HAS_FP_CLASSL"
4440 This symbol, if defined, indicates that the "fp_classl" routine is
4441 available to classify long doubles. Available for example in
4442 Digital "UNIX". See for possible values "HAS_FP_CLASS".
4443 "HAS_FPGETROUND"
4445 This symbol, if defined, indicates that the "fpgetround" routine is
4446 available to get the floating point rounding mode.
4447 "HAS_FREXPL"
4449 This symbol, if defined, indicates that the "frexpl" routine is
4450 available to break a long double floating-point number into a
4451 normalized fraction and an integral power of 2.
4452 "HAS_ILOGB"
4454 This symbol, if defined, indicates that the "ilogb" routine is
4455 available to get integer exponent of a floating-point value.
4456 "HAS_ISFINITE"
4458 This symbol, if defined, indicates that the "isfinite" routine is
4459 available to check whether a double is finite (non-infinity non-
4460 NaN).
4461 "HAS_ISFINITEL"
4463 This symbol, if defined, indicates that the "isfinitel" routine is
4464 available to check whether a long double is finite. (non-infinity
4465 non-NaN).
4466 "HAS_ISINF"
4468 This symbol, if defined, indicates that the "isinf" routine is
4469 available to check whether a double is an infinity.
4470 "HAS_ISINFL"
4472 This symbol, if defined, indicates that the "isinfl" routine is
4473 available to check whether a long double is an infinity.
4474 "HAS_ISNAN"
4476 This symbol, if defined, indicates that the "isnan" routine is
4477 available to check whether a double is a NaN.
4478 "HAS_ISNANL"
4480 This symbol, if defined, indicates that the "isnanl" routine is
4481 available to check whether a long double is a NaN.
4482 "HAS_ISNORMAL"
4484 This symbol, if defined, indicates that the "isnormal" routine is
4485 available to check whether a double is normal (non-zero
4486 normalized).
4487 "HAS_J0L"
4489 This symbol, if defined, indicates to the C program that the j0l()
4490 function is available for Bessel functions of the first kind of the
4491 order zero, for long doubles.
4492 "HAS_J0"
4494 This symbol, if defined, indicates to the C program that the j0()
4495 function is available for Bessel functions of the first kind of the
4496 order zero, for doubles.
4497 "HAS_LDBL_DIG"
4499 This symbol, if defined, indicates that this system's float.h or
4500 limits.h defines the symbol "LDBL_DIG", which is the number of
4501 significant digits in a long double precision number. Unlike for
4502 "DBL_DIG", there's no good guess for "LDBL_DIG" if it is undefined.
4503 "HAS_LDEXPL"
4505 This symbol, if defined, indicates that the "ldexpl" routine is
4506 available to shift a long double floating-point number by an
4507 integral power of 2.
4508 "HAS_LLRINT"
4510 This symbol, if defined, indicates that the "llrint" routine is
4511 available to return the long long value closest to a double
4512 (according to the current rounding mode).
4513 "HAS_LLRINTL"
4515 This symbol, if defined, indicates that the "llrintl" routine is
4516 available to return the long long value closest to a long double
4517 (according to the current rounding mode).
4518 "HAS_LLROUNDL"
4520 This symbol, if defined, indicates that the "llroundl" routine is
4521 available to return the nearest long long value away from zero of
4522 the long double argument value.
4523 "HAS_LONG_DOUBLE"
4525 This symbol will be defined if the C compiler supports long
4526 doubles.
4527 "HAS_LRINT"
4529 This symbol, if defined, indicates that the "lrint" routine is
4530 available to return the integral value closest to a double
4531 (according to the current rounding mode).
4532 "HAS_LRINTL"
4534 This symbol, if defined, indicates that the "lrintl" routine is
4535 available to return the integral value closest to a long double
4536 (according to the current rounding mode).
4537 "HAS_LROUNDL"
4539 This symbol, if defined, indicates that the "lroundl" routine is
4540 available to return the nearest integral value away from zero of
4541 the long double argument value.
4542 "HAS_MODFL"
4544 This symbol, if defined, indicates that the "modfl" routine is
4545 available to split a long double x into a fractional part f and an
4546 integer part i such that |f| < 1.0 and (f + i) = x.
4547 "HAS_NAN"
4549 This symbol, if defined, indicates that the "nan" routine is
4550 available to generate NaN.
4551 "HAS_NEXTTOWARD"
4553 This symbol, if defined, indicates that the "nexttoward" routine is
4554 available to return the next machine representable long double from
4555 x in direction y.
4556 "HAS_REMAINDER"
4558 This symbol, if defined, indicates that the "remainder" routine is
4559 available to return the floating-point "remainder".
4560 "HAS_SCALBN"
4562 This symbol, if defined, indicates that the "scalbn" routine is
4563 available to multiply floating-point number by integral power of
4564 radix.
4565 "HAS_SIGNBIT"
4567 This symbol, if defined, indicates that the "signbit" routine is
4568 available to check if the given number has the sign bit set. This
4569 should include correct testing of -0.0. This will only be set if
4570 the signbit() routine is safe to use with the NV type used
4571 internally in perl. Users should call Perl_signbit(), which will
4572 be #defined to the system's signbit() function or macro if this
4573 symbol is defined.
4574 "HAS_SQRTL"
4576 This symbol, if defined, indicates that the "sqrtl" routine is
4577 available to do long double square roots.
4578 "HAS_STRTOD_L"
4580 This symbol, if defined, indicates that the "strtod_l" routine is
4581 available to convert strings to long doubles.
4582 "HAS_STRTOLD"
4584 This symbol, if defined, indicates that the "strtold" routine is
4585 available to convert strings to long doubles.
4586 "HAS_STRTOLD_L"
4588 This symbol, if defined, indicates that the "strtold_l" routine is
4589 available to convert strings to long doubles.
4590 "HAS_TRUNC"
4592 This symbol, if defined, indicates that the "trunc" routine is
4593 available to round doubles towards zero.
4594 "HAS_UNORDERED"
4596 This symbol, if defined, indicates that the "unordered" routine is
4597 available to check whether two doubles are "unordered"
4598 (effectively: whether either of them is NaN)
4599 "I_FENV"
4601 This symbol, if defined, indicates to the C program that it should
4602 include fenv.h to get the floating point environment definitions.
4603 #ifdef I_FENV
4605 #include <fenv.h>
4606 #endif
4607 "I_QUADMATH"
4609 This symbol, if defined, indicates that quadmath.h exists and
4610 should be included.
4611 #ifdef I_QUADMATH
4613 #include <quadmath.h>
4614 #endif
4615 "LONGDBLINFBYTES"
4617 This symbol, if defined, is a comma-separated list of hexadecimal
4618 bytes for the long double precision infinity.
4619 "LONGDBLMANTBITS"
4621 This symbol, if defined, tells how many mantissa bits there are in
4622 long double precision floating point format. Note that this can be
4623 "LDBL_MANT_DIG" minus one, since "LDBL_MANT_DIG" can include the
4624 "IEEE" 754 implicit bit. The common x86-style 80-bit long double
4625 does not have an implicit bit.
4626 "LONGDBLNANBYTES"
4628 This symbol, if defined, is a comma-separated list of hexadecimal
4629 bytes (0xHH) for the long double precision not-a-number.
4630 "LONG_DOUBLEKIND"
4632 "LONG_DOUBLEKIND" will be one of "LONG_DOUBLE_IS_DOUBLE"
4633 "LONG_DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN"
4634 "LONG_DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN"
4635 "LONG_DOUBLE_IS_X86_80_BIT_LITTLE_ENDIAN"
4636 "LONG_DOUBLE_IS_X86_80_BIT_BIG_ENDIAN"
4637 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_LE"
4638 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_BE"
4639 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_BE"
4640 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_LE"
4641 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LITTLE_ENDIAN"
4642 "LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BIG_ENDIAN"
4643 "LONG_DOUBLE_IS_VAX_H_FLOAT" "LONG_DOUBLE_IS_UNKNOWN_FORMAT" It is
4644 only defined if the system supports long doubles.
4645 "LONG_DOUBLESIZE"
4647 This symbol contains the size of a long double, so that the C
4648 preprocessor can make decisions based on it. It is only defined if
4649 the system supports long doubles. Note that this is "sizeof(long
4650 double)", which may include unused bytes.
4651 "LONG_DOUBLE_STYLE_IEEE"
4653 This symbol, if defined, indicates that the long double is any of
4654 the "IEEE" 754 style long doubles: "LONG_DOUBLE_STYLE_IEEE_STD",
4655 "LONG_DOUBLE_STYLE_IEEE_EXTENDED",
4656 "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE".
4657 "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
4659 This symbol, if defined, indicates that the long double is the
4660 128-bit double-double.
4661 "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
4663 This symbol, if defined, indicates that the long double is the
4664 80-bit "IEEE" 754. Note that despite the 'extended' this is less
4665 than the 'std', since this is an extension of the double precision.
4666 "LONG_DOUBLE_STYLE_IEEE_STD"
4668 This symbol, if defined, indicates that the long double is the
4669 128-bit "IEEE" 754.
4670 "LONG_DOUBLE_STYLE_VAX"
4672 This symbol, if defined, indicates that the long double is the
4673 128-bit "VAX" format H.
4674 "NV"
4676 Described in perlguts.
4677 "NVMANTBITS"
4679 This symbol, if defined, tells how many mantissa bits (not
4680 including implicit bit) there are in a Perl NV. This depends on
4681 which floating point type was chosen.
4682 "NV_OVERFLOWS_INTEGERS_AT"
4684 This symbol gives the largest integer value that NVs can hold. This
4685 value + 1.0 cannot be stored accurately. It is expressed as
4686 constant floating point expression to reduce the chance of
4687 decimal/binary conversion issues. If it can not be determined, the
4688 value 0 is given.
4689 "NV_PRESERVES_UV"
4691 This symbol, if defined, indicates that a variable of type "NVTYPE"
4692 can preserve all the bits of a variable of type "UVTYPE".
4693 "NV_PRESERVES_UV_BITS"
4695 This symbol contains the number of bits a variable of type "NVTYPE"
4696 can preserve of a variable of type "UVTYPE".
4697 "NVSIZE"
4699 This symbol contains the sizeof(NV). Note that some floating point
4700 formats have unused bytes. The most notable example is the x86*
4701 80-bit extended precision which comes in byte sizes of 12 and 16
4702 (for 32 and 64 bit platforms, respectively), but which only uses 10
4703 bytes. Perl compiled with "-Duselongdouble" on x86* is like this.
4704 "NVTYPE"
4706 This symbol defines the C type used for Perl's NV.
4707 "NV_ZERO_IS_ALLBITS_ZERO"
4709 This symbol, if defined, indicates that a variable of type "NVTYPE"
4710 stores 0.0 in memory as all bits zero.
4711
4713 This section contains configuration information not otherwise found in
4714 the more specialized sections of this document. At the end is a list
4715 of "#defines" whose name should be enough to tell you what they do, and
4716 a list of #defines which tell you if you need to "#include" files to
4717 get the corresponding functionality.
4718 "ASCIIish"
4720 A preprocessor symbol that is defined iff the system is an ASCII
4721 platform; this symbol would not be defined on "EBCDIC" platforms.
4722 #ifdef ASCIIish
4724 "BYTEORDER"
4726 This symbol holds the hexadecimal constant defined in byteorder, in
4727 a UV, i.e. 0x1234 or 0x4321 or 0x12345678, etc... If the compiler
4728 supports cross-compiling or multiple-architecture binaries, use
4729 compiler-defined macros to determine the byte order.
4730 "CHARBITS"
4732 This symbol contains the size of a char, so that the C preprocessor
4733 can make decisions based on it.
4734 "DB_VERSION_MAJOR_CFG"
4736 This symbol, if defined, defines the major version number of
4737 Berkeley DB found in the db.h header when Perl was configured.
4738 "DB_VERSION_MINOR_CFG"
4740 This symbol, if defined, defines the minor version number of
4741 Berkeley DB found in the db.h header when Perl was configured. For
4742 DB version 1 this is always 0.
4743 "DB_VERSION_PATCH_CFG"
4745 This symbol, if defined, defines the patch version number of
4746 Berkeley DB found in the db.h header when Perl was configured. For
4747 DB version 1 this is always 0.
4748 "DEFAULT_INC_EXCLUDES_DOT"
4750 This symbol, if defined, removes the legacy default behavior of
4751 including '.' at the end of @"INC".
4752 "DLSYM_NEEDS_UNDERSCORE"
4754 This symbol, if defined, indicates that we need to prepend an
4755 underscore to the symbol name before calling dlsym(). This only
4756 makes sense if you *have* dlsym, which we will presume is the case
4757 if you're using dl_dlopen.xs.
4758 "EBCDIC"
4760 This symbol, if defined, indicates that this system uses "EBCDIC"
4761 encoding.
4762 "HAS_CSH"
4764 This symbol, if defined, indicates that the C-shell exists.
4765 "HAS_GETHOSTNAME"
4767 This symbol, if defined, indicates that the C program may use the
4768 gethostname() routine to derive the host name. See also
4769 "HAS_UNAME" and "PHOSTNAME".
4770 "HAS_GNULIBC"
4772 This symbol, if defined, indicates to the C program that the "GNU"
4773 C library is being used. A better check is to use the "__GLIBC__"
4774 and "__GLIBC_MINOR__" symbols supplied with glibc.
4775 "HAS_LGAMMA"
4777 This symbol, if defined, indicates that the "lgamma" routine is
4778 available to do the log gamma function. See also "HAS_TGAMMA" and
4779 "HAS_LGAMMA_R".
4780 "HAS_LGAMMA_R"
4782 This symbol, if defined, indicates that the "lgamma_r" routine is
4783 available to do the log gamma function without using the global
4784 signgam variable.
4785 "HAS_NON_INT_BITFIELDS"
4787 This symbol, if defined, indicates that the C compiler accepts,
4788 without error or warning, "struct bitfields" that are declared with
4789 sizes other than plain 'int'; for example 'unsigned char' is
4790 accepted.
4791 "HAS_PRCTL_SET_NAME"
4793 This symbol, if defined, indicates that the prctl routine is
4794 available to set process title and supports "PR_SET_NAME".
4795 "HAS_PROCSELFEXE"
4797 This symbol is defined if "PROCSELFEXE_PATH" is a symlink to the
4798 absolute pathname of the executing program.
4799 "HAS_PSEUDOFORK"
4801 This symbol, if defined, indicates that an emulation of the fork
4802 routine is available.
4803 "HAS_REGCOMP"
4805 This symbol, if defined, indicates that the regcomp() routine is
4806 available to do some regular pattern matching (usually on "POSIX".2
4807 conforming systems).
4808 "HAS_SETPGID"
4810 This symbol, if defined, indicates that the "setpgid(pid, gpid)"
4811 routine is available to set process group ID.
4812 "HAS_SIGSETJMP"
4814 This variable indicates to the C program that the sigsetjmp()
4815 routine is available to save the calling process's registers and
4816 stack environment for later use by siglongjmp(), and to optionally
4817 save the process's signal mask. See "Sigjmp_buf", "Sigsetjmp", and
4818 "Siglongjmp".
4819 "HAS_STRUCT_CMSGHDR"
4821 This symbol, if defined, indicates that the "struct cmsghdr" is
4822 supported.
4823 "HAS_STRUCT_MSGHDR"
4825 This symbol, if defined, indicates that the "struct msghdr" is
4826 supported.
4827 "HAS_TGAMMA"
4829 This symbol, if defined, indicates that the "tgamma" routine is
4830 available to do the gamma function. See also "HAS_LGAMMA".
4831 "HAS_UNAME"
4833 This symbol, if defined, indicates that the C program may use the
4834 uname() routine to derive the host name. See also
4835 "HAS_GETHOSTNAME" and "PHOSTNAME".
4836 "HAS_UNION_SEMUN"
4838 This symbol, if defined, indicates that the "union semun" is
4839 defined by including sys/sem.h. If not, the user code probably
4840 needs to define it as:
4841 union semun {
4843 int val;
4844 struct semid_ds *buf;
4845 unsigned short *array;
4846 }
4847 "I_DIRENT"
4849 This symbol, if defined, indicates to the C program that it should
4850 include dirent.h. Using this symbol also triggers the definition of
4851 the "Direntry_t" define which ends up being '"struct dirent"' or
4852 '"struct direct"' depending on the availability of dirent.h.
4853 #ifdef I_DIRENT
4855 #include <dirent.h>
4856 #endif
4857 "I_POLL"
4859 This symbol, if defined, indicates that poll.h exists and should be
4860 included. (see also "HAS_POLL")
4861 #ifdef I_POLL
4863 #include <poll.h>
4864 #endif
4865 "I_SYS_RESOURCE"
4867 This symbol, if defined, indicates to the C program that it should
4868 include sys/resource.h.
4869 #ifdef I_SYS_RESOURCE
4871 #include <sys_resource.h>
4872 #endif
4873 "LIBM_LIB_VERSION"
4875 This symbol, if defined, indicates that libm exports "_LIB_VERSION"
4876 and that math.h defines the enum to manipulate it.
4877 "NEED_VA_COPY"
4879 This symbol, if defined, indicates that the system stores the
4880 variable argument list datatype, "va_list", in a format that cannot
4881 be copied by simple assignment, so that some other means must be
4882 used when copying is required. As such systems vary in their
4883 provision (or non-provision) of copying mechanisms, handy.h defines
4884 a platform- independent macro, "Perl_va_copy(src, dst)", to do the
4885 job.
4886 "OSNAME"
4888 This symbol contains the name of the operating system, as
4889 determined by Configure. You shouldn't rely on it too much; the
4890 specific feature tests from Configure are generally more reliable.
4891 "OSVERS"
4893 This symbol contains the version of the operating system, as
4894 determined by Configure. You shouldn't rely on it too much; the
4895 specific feature tests from Configure are generally more reliable.
4896 "PERL_USE_GCC_BRACE_GROUPS"
4898 This C pre-processor value, if defined, indicates that it is
4899 permissible to use the GCC brace groups extension. However, use of
4900 this extension is DISCOURAGED. Use a "static inline" function
4901 instead.
4902 The extension, of the form
4904 ({ statement ... })
4906 turns the block consisting of statement ... into an expression with
4908 a value, unlike plain C language blocks. This can present
4909 optimization possibilities, BUT, unless you know for sure that this
4910 will never be compiled without this extension being available and
4911 not forbidden, you need to specify an alternative. Thus two code
4912 paths have to be maintained, which can get out-of-sync. All these
4913 issues are solved by using a "static inline" function instead.
4914 Perl can be configured to not use this feature by passing the
4916 parameter "-Accflags=-DPERL_GCC_BRACE_GROUPS_FORBIDDEN" to
4917 Configure.
4918 #ifdef PERL_USE_GCC_BRACE_GROUPS
4920 "PHOSTNAME"
4922 This symbol, if defined, indicates the command to feed to the
4923 popen() routine to derive the host name. See also
4924 "HAS_GETHOSTNAME" and "HAS_UNAME". Note that the command uses a
4925 fully qualified path, so that it is safe even if used by a process
4926 with super-user privileges.
4927 "PROCSELFEXE_PATH"
4929 If "HAS_PROCSELFEXE" is defined this symbol is the filename of the
4930 symbolic link pointing to the absolute pathname of the executing
4931 program.
4932 "PTRSIZE"
4934 This symbol contains the size of a pointer, so that the C
4935 preprocessor can make decisions based on it. It will be
4936 "sizeof(void *)" if the compiler supports (void *); otherwise it
4937 will be "sizeof(char *)".
4938 "RANDBITS"
4940 This symbol indicates how many bits are produced by the function
4941 used to generate normalized random numbers. Values include 15, 16,
4942 31, and 48.
4943 "SELECT_MIN_BITS"
4945 This symbol holds the minimum number of bits operated by select.
4946 That is, if you do "select(n, ...)", how many bits at least will be
4947 cleared in the masks if some activity is detected. Usually this is
4948 either n or 32*ceil(n/32), especially many little-endians do the
4949 latter. This is only useful if you have select(), naturally.
4950 "SETUID_SCRIPTS_ARE_SECURE_NOW"
4952 This symbol, if defined, indicates that the bug that prevents
4953 setuid scripts from being secure is not present in this kernel.
4954 "ST_DEV_SIGN"
4956 This symbol holds the signedness of "struct stat"'s "st_dev". 1
4957 for unsigned, -1 for signed.
4958 "ST_DEV_SIZE"
4960 This variable contains the size of "struct stat"'s "st_dev" in
4961 bytes.
4962 List of capability "HAS_foo" symbols
4964 This is a list of those symbols that dont appear elsewhere in ths
4965 document that indicate if the current platform has a certain
4966 capability. Their names all begin with "HAS_". Only those symbols
4967 whose capability is directly derived from the name are listed here.
4968 All others have their meaning expanded out elsewhere in this document.
4969 This (relatively) compact list is because we think that the expansion
4970 would add little or no value and take up a lot of space (because there
4971 are so many). If you think certain ones should be expanded, send email
4972 to perl5-porters@perl.org <mailto:perl5-porters@perl.org>.
4973 Each symbol here will be "#define"d if and only if the platform has the
4975 capability. If you need more detail, see the corresponding entry in
4976 config.h. For convenience, the list is split so that the ones that
4977 indicate there is a reentrant version of a capability are listed
4978 separately
4979 "HAS_ACCEPT4", "HAS_ACCESS", "HAS_ACCESSX", "HAS_ACOSH",
4981 "HAS_AINTL", "HAS_ALARM", "HAS_ASINH", "HAS_ATANH", "HAS_ATOLL",
4982 "HAS_CBRT", "HAS_CHOWN", "HAS_CHROOT", "HAS_CHSIZE",
4983 "HAS_CLEARENV", "HAS_COPYSIGN", "HAS_COPYSIGNL", "HAS_CRYPT",
4984 "HAS_CTERMID", "HAS_CUSERID", "HAS_DIRFD", "HAS_DLADDR",
4985 "HAS_DLERROR", "HAS_EACCESS", "HAS_ENDHOSTENT", "HAS_ENDNETENT",
4986 "HAS_ENDPROTOENT", "HAS_ENDSERVENT", "HAS_ERF", "HAS_ERFC",
4987 "HAS_EXPM1", "HAS_EXP2", "HAS_FCHMOD", "HAS_FCHMODAT",
4988 "HAS_FCHOWN", "HAS_FDIM", "HAS_FD_SET", "HAS_FEGETROUND",
4989 "HAS_FFS", "HAS_FFSL", "HAS_FGETPOS", "HAS_FLOCK", "HAS_FMA",
4990 "HAS_FMAX", "HAS_FMIN", "HAS_FORK", "HAS_FSEEKO", "HAS_FSETPOS",
4991 "HAS_FSYNC", "HAS_FTELLO", "HAS__FWALK", "HAS_GAI_STRERROR",
4992 "HAS_GETADDRINFO", "HAS_GETCWD", "HAS_GETESPWNAM", "HAS_GETGROUPS",
4993 "HAS_GETHOSTBYADDR", "HAS_GETHOSTBYNAME", "HAS_GETHOSTENT",
4994 "HAS_GETLOGIN", "HAS_GETNAMEINFO", "HAS_GETNETBYADDR",
4995 "HAS_GETNETBYNAME", "HAS_GETNETENT", "HAS_GETPAGESIZE",
4996 "HAS_GETPGID", "HAS_GETPGRP", "HAS_GETPGRP2", "HAS_GETPPID",
4997 "HAS_GETPRIORITY", "HAS_GETPROTOBYNAME", "HAS_GETPROTOBYNUMBER",
4998 "HAS_GETPROTOENT", "HAS_GETPRPWNAM", "HAS_GETSERVBYNAME",
4999 "HAS_GETSERVBYPORT", "HAS_GETSERVENT", "HAS_GETSPNAM", "HAS_HTONL",
5000 "HAS_HTONS", "HAS_HYPOT", "HAS_ILOGBL", "HAS_INET_ATON",
5001 "HAS_INETNTOP", "HAS_INETPTON", "HAS_IP_MREQ",
5002 "HAS_IP_MREQ_SOURCE", "HAS_IPV6_MREQ", "HAS_IPV6_MREQ_SOURCE",
5003 "HAS_ISASCII", "HAS_ISBLANK", "HAS_ISLESS", "HAS_KILLPG",
5004 "HAS_LCHOWN", "HAS_LINK", "HAS_LINKAT", "HAS_LLROUND",
5005 "HAS_LOCKF", "HAS_LOGB", "HAS_LOG1P", "HAS_LOG2", "HAS_LROUND",
5006 "HAS_LSTAT", "HAS_MADVISE", "HAS_MBLEN", "HAS_MBRLEN",
5007 "HAS_MBRTOWC", "HAS_MBSTOWCS", "HAS_MBTOWC", "HAS_MEMMEM",
5008 "HAS_MEMRCHR", "HAS_MKDTEMP", "HAS_MKFIFO", "HAS_MKOSTEMP",
5009 "HAS_MKSTEMP", "HAS_MKSTEMPS", "HAS_MMAP", "HAS_MPROTECT",
5010 "HAS_MSG", "HAS_MSYNC", "HAS_MUNMAP", "HAS_NEARBYINT",
5011 "HAS_NEXTAFTER", "HAS_NICE", "HAS_NTOHL", "HAS_NTOHS",
5012 "HAS_PATHCONF", "HAS_PAUSE", "HAS_PHOSTNAME", "HAS_PIPE",
5013 "HAS_PIPE2", "HAS_PRCTL", "HAS_PTRDIFF_T", "HAS_READLINK",
5014 "HAS_READV", "HAS_RECVMSG", "HAS_REMQUO", "HAS_RENAME",
5015 "HAS_RENAMEAT", "HAS_RINT", "HAS_ROUND", "HAS_SCALBNL", "HAS_SEM",
5016 "HAS_SENDMSG", "HAS_SETEGID", "HAS_SETENV", "HAS_SETEUID",
5017 "HAS_SETGROUPS", "HAS_SETHOSTENT", "HAS_SETLINEBUF",
5018 "HAS_SETNETENT", "HAS_SETPGRP", "HAS_SETPGRP2", "HAS_SETPRIORITY",
5019 "HAS_SETPROCTITLE", "HAS_SETPROTOENT", "HAS_SETREGID",
5020 "HAS_SETRESGID", "HAS_SETRESUID", "HAS_SETREUID", "HAS_SETRGID",
5021 "HAS_SETRUID", "HAS_SETSERVENT", "HAS_SETSID", "HAS_SHM",
5022 "HAS_SIGACTION", "HAS_SIGPROCMASK", "HAS_SIN6_SCOPE_ID",
5023 "HAS_SNPRINTF", "HAS_STAT", "HAS_STRCOLL", "HAS_STRERROR_L",
5024 "HAS_STRLCAT", "HAS_STRLCPY", "HAS_STRNLEN", "HAS_STRTOD",
5025 "HAS_STRTOL", "HAS_STRTOLL", "HAS_STRTOQ", "HAS_STRTOUL",
5026 "HAS_STRTOULL", "HAS_STRTOUQ", "HAS_STRXFRM", "HAS_STRXFRM_L",
5027 "HAS_SYMLINK", "HAS_SYSCALL", "HAS_SYSCONF", "HAS_SYS_ERRLIST",
5028 "HAS_SYSTEM", "HAS_TCGETPGRP", "HAS_TCSETPGRP", "HAS_TOWLOWER",
5029 "HAS_TOWUPPER", "HAS_TRUNCATE", "HAS_TRUNCL", "HAS_UALARM",
5030 "HAS_UMASK", "HAS_UNLINKAT", "HAS_UNSETENV", "HAS_VFORK",
5031 "HAS_VSNPRINTF", "HAS_WAITPID", "HAS_WAIT4", "HAS_WCRTOMB",
5032 "HAS_WCSCMP", "HAS_WCSTOMBS", "HAS_WCSXFRM", "HAS_WCTOMB",
5033 "HAS_WRITEV"
5034 And, the reentrant capabilities:
5036 "HAS_CRYPT_R", "HAS_CTERMID_R", "HAS_DRAND48_R",
5038 "HAS_ENDHOSTENT_R", "HAS_ENDNETENT_R", "HAS_ENDPROTOENT_R",
5039 "HAS_ENDSERVENT_R", "HAS_GETGRGID_R", "HAS_GETGRNAM_R",
5040 "HAS_GETHOSTBYADDR_R", "HAS_GETHOSTBYNAME_R", "HAS_GETHOSTENT_R",
5041 "HAS_GETLOGIN_R", "HAS_GETNETBYADDR_R", "HAS_GETNETBYNAME_R",
5042 "HAS_GETNETENT_R", "HAS_GETPROTOBYNAME_R", "HAS_GETPROTOBYNUMBER_R",
5043 "HAS_GETPROTOENT_R", "HAS_GETPWNAM_R", "HAS_GETPWUID_R",
5044 "HAS_GETSERVBYNAME_R", "HAS_GETSERVBYPORT_R", "HAS_GETSERVENT_R",
5045 "HAS_GETSPNAM_R", "HAS_RANDOM_R", "HAS_READDIR_R",
5046 "HAS_SETHOSTENT_R", "HAS_SETNETENT_R", "HAS_SETPROTOENT_R",
5047 "HAS_SETSERVENT_R", "HAS_SRANDOM_R", "HAS_SRAND48_R",
5048 "HAS_STRERROR_R", "HAS_TMPNAM_R", "HAS_TTYNAME_R"
5049 Example usage:
5051 #ifdef HAS_STRNLEN
5053 use strnlen()
5054 #else
5055 use an alternative implementation
5056 #endif
5057 List of "#include" needed symbols
5059 This list contains symbols that indicate if certain "#include" files
5060 are present on the platform. If your code accesses the functionality
5061 that one of these is for, you will need to "#include" it if the symbol
5062 on this list is "#define"d. For more detail, see the corresponding
5063 entry in config.h.
5064 "I_ARPA_INET", "I_BFD", "I_CRYPT", "I_DBM", "I_DLFCN",
5066 "I_EXECINFO", "I_FP", "I_FP_CLASS", "I_GDBM", "I_GDBMNDBM",
5067 "I_GDBM_NDBM", "I_GRP", "I_IEEEFP", "I_INTTYPES", "I_LIBUTIL",
5068 "I_MNTENT", "I_NDBM", "I_NETDB", "I_NET_ERRNO", "I_NETINET_IN",
5069 "I_NETINET_TCP", "I_PROT", "I_PWD", "I_RPCSVC_DBM", "I_SGTTY",
5070 "I_SHADOW", "I_STDBOOL", "I_STDINT", "I_SUNMATH", "I_SYS_ACCESS",
5071 "I_SYS_IOCTL", "I_SYSLOG", "I_SYSMODE", "I_SYS_MOUNT",
5072 "I_SYS_PARAM", "I_SYS_POLL", "I_SYS_SECURITY", "I_SYS_SELECT",
5073 "I_SYS_STAT", "I_SYS_STATVFS", "I_SYS_SYSCALL", "I_SYS_TIME",
5074 "I_SYS_TIME_KERNEL", "I_SYS_TIMES", "I_SYS_TYPES", "I_SYSUIO",
5075 "I_SYS_UN", "I_SYSUTSNAME", "I_SYS_VFS", "I_SYS_WAIT", "I_TERMIO",
5076 "I_TERMIOS", "I_UNISTD", "I_USTAT", "I_VFORK", "I_WCHAR",
5077 "I_WCTYPE"
5078 Example usage:
5080 #ifdef I_WCHAR
5082 #include <wchar.h>
5083 #endif
5084
5086 These variables are global to an entire process. They are shared
5087 between all interpreters and all threads in a process. Any variables
5088 not documented here may be changed or removed without notice, so don't
5089 use them! If you feel you really do need to use an unlisted variable,
5090 first send email to perl5-porters@perl.org
5091 <mailto:perl5-porters@perl.org>. It may be that someone there will
5092 point out a way to accomplish what you need without using an internal
5093 variable. But if not, you should get a go-ahead to document and then
5094 use the variable.
5095 "PL_check"
5097 Array, indexed by opcode, of functions that will be called for the
5098 "check" phase of optree building during compilation of Perl code.
5099 For most (but not all) types of op, once the op has been initially
5100 built and populated with child ops it will be filtered through the
5101 check function referenced by the appropriate element of this array.
5102 The new op is passed in as the sole argument to the check function,
5103 and the check function returns the completed op. The check
5104 function may (as the name suggests) check the op for validity and
5105 signal errors. It may also initialise or modify parts of the ops,
5106 or perform more radical surgery such as adding or removing child
5107 ops, or even throw the op away and return a different op in its
5108 place.
5109 This array of function pointers is a convenient place to hook into
5111 the compilation process. An XS module can put its own custom check
5112 function in place of any of the standard ones, to influence the
5113 compilation of a particular type of op. However, a custom check
5114 function must never fully replace a standard check function (or
5115 even a custom check function from another module). A module
5116 modifying checking must instead wrap the preexisting check
5117 function. A custom check function must be selective about when to
5118 apply its custom behaviour. In the usual case where it decides not
5119 to do anything special with an op, it must chain the preexisting op
5120 function. Check functions are thus linked in a chain, with the
5121 core's base checker at the end.
5122 For thread safety, modules should not write directly to this array.
5124 Instead, use the function "wrap_op_checker".
5125 "PL_infix_plugin"
5127 NOTE: "PL_infix_plugin" is experimental and may change or be
5128 removed without notice.
5129 NOTE: This API exists entirely for the purpose of making the CPAN
5131 module "XS::Parse::Infix" work. It is not expected that additional
5132 modules will make use of it; rather, that they should use
5133 "XS::Parse::Infix" to provide parsing of new infix operators.
5134 Function pointer, pointing at a function used to handle extended
5136 infix operators. The function should be declared as
5137 int infix_plugin_function(pTHX_
5139 char *opname, STRLEN oplen,
5140 struct Perl_custom_infix **infix_ptr)
5141 The function is called from the tokenizer whenever a possible infix
5143 operator is seen. "opname" points to the operator name in the
5144 parser's input buffer, and "oplen" gives the maximum number of
5145 bytes of it that should be consumed; it is not null-terminated. The
5146 function is expected to examine the operator name and possibly
5147 other state such as %^H, to determine whether it wants to handle
5148 the operator name.
5149 As compared to the single stage of "PL_keyword_plugin", parsing of
5151 additional infix operators occurs in three separate stages. This is
5152 because of the more complex interactions it has with the parser, to
5153 ensure that operator precedence rules work correctly. These stages
5154 are co-ordinated by the use of an additional information structure.
5155 If the function wants to handle the infix operator, it must set the
5157 variable pointed to by "infix_ptr" to the address of a structure
5158 that provides this additional information about the subsequent
5159 parsing stages. If it does not, it should make a call to the next
5160 function in the chain.
5161 This structure has the following definition:
5163 struct Perl_custom_infix {
5165 enum Perl_custom_infix_precedence prec;
5166 void (*parse)(pTHX_ SV **opdata,
5167 struct Perl_custom_infix *);
5168 OP *(*build_op)(pTHX_ SV **opdata, OP *lhs, OP *rhs,
5169 struct Perl_custom_infix *);
5170 };
5171 The function must then return an integer giving the number of bytes
5173 consumed by the name of this operator. In the case of an operator
5174 whose name is composed of identifier characters, this must be equal
5175 to "oplen". In the case of an operator named by non-identifier
5176 characters, this is permitted to be shorter than "oplen", and any
5177 additional characters after it will not be claimed by the infix
5178 operator but instead will be consumed by the tokenizer and parser
5179 as normal.
5180 If the optional "parse" function is provided, it is called
5182 immediately by the parser to let the operator's definition consume
5183 any additional syntax from the source code. This should not be used
5184 for normal operand parsing, but it may be useful when implementing
5185 things like parametric operators or meta-operators that consume
5186 more syntax themselves. This function may use the variable pointed
5187 to by "opdata" to provide an SV containing additional data to be
5188 passed into the "build_op" function later on.
5189 The information structure gives the operator precedence level in
5191 the "prec" field. This is used to tell the parser how much of the
5192 surrounding syntax before and after should be considered as
5193 operands to the operator.
5194 The tokenizer and parser will then continue to operate as normal
5196 until enough additional input has been parsed to form both the
5197 left- and right-hand side operands to the operator, according to
5198 the precedence level. At this point the "build_op" function is
5199 called, being passed the left- and right-hand operands as optree
5200 fragments. It is expected to combine them into the resulting optree
5201 fragment, which it should return.
5202 After the "build_op" function has returned, if the variable pointed
5204 to by "opdata" was set to a non-"NULL" value, it will then be
5205 destroyed by calling SvREFCNT_dec().
5206 For thread safety, modules should not set this variable directly.
5208 Instead, use the function "wrap_infix_plugin".
5209 However, that all said, the introductory note above still applies.
5211 This variable is provided in core perl only for the benefit of the
5212 "XS::Parse::Infix" module. That module acts as a central registry
5213 for infix operators, automatically handling things like deparse
5214 support and discovery/reflection, and these abilities only work
5215 because it knows all the registered operators. Other modules should
5216 not use this interpreter variable directly to implement them
5217 because then those central features would no longer work properly.
5218 Furthermore, it is likely that this (experimental) API will be
5220 replaced in a future Perl version by a more complete API that fully
5221 implements the central registry and other semantics currently
5222 provided by "XS::Parse::Infix", once the module has had sufficient
5223 experimental testing time. This current mechanism exists only as an
5224 interim measure to get to that stage.
5225 "PL_keyword_plugin"
5227 NOTE: "PL_keyword_plugin" is experimental and may change or be
5228 removed without notice.
5229 Function pointer, pointing at a function used to handle extended
5231 keywords. The function should be declared as
5232 int keyword_plugin_function(pTHX_
5234 char *keyword_ptr, STRLEN keyword_len,
5235 OP **op_ptr)
5236 The function is called from the tokeniser, whenever a possible
5238 keyword is seen. "keyword_ptr" points at the word in the parser's
5239 input buffer, and "keyword_len" gives its length; it is not null-
5240 terminated. The function is expected to examine the word, and
5241 possibly other state such as %^H, to decide whether it wants to
5242 handle it as an extended keyword. If it does not, the function
5243 should return "KEYWORD_PLUGIN_DECLINE", and the normal parser
5244 process will continue.
5245 If the function wants to handle the keyword, it first must parse
5247 anything following the keyword that is part of the syntax
5248 introduced by the keyword. See "Lexer interface" for details.
5249 When a keyword is being handled, the plugin function must build a
5251 tree of "OP" structures, representing the code that was parsed.
5252 The root of the tree must be stored in *op_ptr. The function then
5253 returns a constant indicating the syntactic role of the construct
5254 that it has parsed: "KEYWORD_PLUGIN_STMT" if it is a complete
5255 statement, or "KEYWORD_PLUGIN_EXPR" if it is an expression. Note
5256 that a statement construct cannot be used inside an expression
5257 (except via "do BLOCK" and similar), and an expression is not a
5258 complete statement (it requires at least a terminating semicolon).
5259 When a keyword is handled, the plugin function may also have
5261 (compile-time) side effects. It may modify "%^H", define
5262 functions, and so on. Typically, if side effects are the main
5263 purpose of a handler, it does not wish to generate any ops to be
5264 included in the normal compilation. In this case it is still
5265 required to supply an op tree, but it suffices to generate a single
5266 null op.
5267 That's how the *PL_keyword_plugin function needs to behave overall.
5269 Conventionally, however, one does not completely replace the
5270 existing handler function. Instead, take a copy of
5271 "PL_keyword_plugin" before assigning your own function pointer to
5272 it. Your handler function should look for keywords that it is
5273 interested in and handle those. Where it is not interested, it
5274 should call the saved plugin function, passing on the arguments it
5275 received. Thus "PL_keyword_plugin" actually points at a chain of
5276 handler functions, all of which have an opportunity to handle
5277 keywords, and only the last function in the chain (built into the
5278 Perl core) will normally return "KEYWORD_PLUGIN_DECLINE".
5279 For thread safety, modules should not set this variable directly.
5281 Instead, use the function "wrap_keyword_plugin".
5282 "PL_phase"
5284 A value that indicates the current Perl interpreter's phase.
5285 Possible values include "PERL_PHASE_CONSTRUCT", "PERL_PHASE_START",
5286 "PERL_PHASE_CHECK", "PERL_PHASE_INIT", "PERL_PHASE_RUN",
5287 "PERL_PHASE_END", and "PERL_PHASE_DESTRUCT".
5288 For example, the following determines whether the interpreter is in
5290 global destruction:
5291 if (PL_phase == PERL_PHASE_DESTRUCT) {
5293 // we are in global destruction
5294 }
5295 "PL_phase" was introduced in Perl 5.14; in prior perls you can use
5297 "PL_dirty" (boolean) to determine whether the interpreter is in
5298 global destruction. (Use of "PL_dirty" is discouraged since 5.14.)
5299 enum perl_phase PL_phase
5301
5303 A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
5304 It is a structure that holds a pointer to a scalar, an array, a hash
5305 etc, corresponding to $foo, @foo, %foo.
5306 GVs are usually found as values in stashes (symbol table hashes) where
5308 Perl stores its global variables.
5309 A stash is a hash that contains all variables that are defined within a
5311 package. See "Stashes and Globs" in perlguts
5312 "amagic_call"
5314 Perform the overloaded (active magic) operation given by "method".
5315 "method" is one of the values found in overload.h.
5316 "flags" affects how the operation is performed, as follows:
5318 "AMGf_noleft"
5320 "left" is not to be used in this operation.
5321 "AMGf_noright"
5323 "right" is not to be used in this operation.
5324 "AMGf_unary"
5326 The operation is done only on just one operand.
5327 "AMGf_assign"
5329 The operation changes one of the operands, e.g., $x += 1
5330 SV * amagic_call(SV *left, SV *right, int method, int dir)
5332 "amagic_deref_call"
5334 Perform "method" overloading dereferencing on "ref", returning the
5335 dereferenced result. "method" must be one of the dereference
5336 operations given in overload.h.
5337 If overloading is inactive on "ref", returns "ref" itself.
5339 SV * amagic_deref_call(SV *ref, int method)
5341 "gv_add_by_type"
5343 Make sure there is a slot of type "type" in the GV "gv".
5344 GV * gv_add_by_type(GV *gv, svtype type)
5346 "Gv_AMupdate"
5348 Recalculates overload magic in the package given by "stash".
5349 Returns:
5351 1 on success and there is some overload
5353 0 if there is no overload
5354 -1 if some error occurred and it couldn't croak (because
5355 "destructing" is true).
5356 int Gv_AMupdate(HV *stash, bool destructing)
5358 "gv_autoload_pv"
5360 "gv_autoload_pvn"
5361 "gv_autoload_sv"
5362 These each search for an "AUTOLOAD" method, returning NULL if not
5363 found, or else returning a pointer to its GV, while setting the
5364 package $AUTOLOAD variable to "name" (fully qualified). Also, if
5365 found and the GV's CV is an XSUB, the CV's PV will be set to
5366 "name", and its stash will be set to the stash of the GV.
5367 Searching is done in "MRO" order, as specified in ""gv_fetchmeth"",
5369 beginning with "stash" if it isn't NULL.
5370 The forms differ only in how "name" is specified.
5372 In "gv_autoload_pv", "namepv" is a C language NUL-terminated
5374 string.
5375 In "gv_autoload_pvn", "name" points to the first byte of the name,
5377 and an additional parameter, "len", specifies its length in bytes.
5378 Hence, *name may contain embedded-NUL characters.
5379 In "gv_autoload_sv", *namesv is an SV, and the name is the PV
5381 extracted from that using ""SvPV"". If the SV is marked as being
5382 in UTF-8, the extracted PV will also be.
5383 GV * gv_autoload_pv (HV *stash, const char *namepv, U32 flags)
5385 GV * gv_autoload_pvn(HV *stash, const char *name, STRLEN len,
5386 U32 flags)
5387 GV * gv_autoload_sv (HV *stash, SV *namesv, U32 flags)
5388 "gv_autoload4"
5390 Equivalent to "gv_autoload_pvn".
5391 GV * gv_autoload4(HV *stash, const char *name, STRLEN len,
5393 I32 method)
5394 "GvAV"
5396 Return the AV from the GV.
5397 AV* GvAV(GV* gv)
5399 "gv_AVadd"
5401 "gv_HVadd"
5402 "gv_IOadd"
5403 "gv_SVadd"
5404 Make sure there is a slot of the given type (AV, HV, IO, SV) in the
5405 GV "gv".
5406 GV * gv_AVadd(GV *gv)
5408 "gv_const_sv"
5410 If "gv" is a typeglob whose subroutine entry is a constant sub
5411 eligible for inlining, or "gv" is a placeholder reference that
5412 would be promoted to such a typeglob, then returns the value
5413 returned by the sub. Otherwise, returns "NULL".
5414 SV * gv_const_sv(GV *gv)
5416 "GvCV"
5418 Return the CV from the GV.
5419 CV* GvCV(GV* gv)
5421 "gv_efullname3"
5423 "gv_efullname4"
5424 "gv_fullname3"
5425 "gv_fullname4"
5426 Place the full package name of "gv" into "sv". The "gv_e*" forms
5427 return instead the effective package name (see "HvENAME").
5428 If "prefix" is non-NULL, it is considered to be a C language NUL-
5430 terminated string, and the stored name will be prefaced with it.
5431 The other difference between the functions is that the *4 forms
5433 have an extra parameter, "keepmain". If "true" an initial "main::"
5434 in the name is kept; if "false" it is stripped. With the *3 forms,
5435 it is always kept.
5436 void gv_efullname3(SV *sv, const GV *gv, const char *prefix)
5438 void gv_efullname4(SV *sv, const GV *gv, const char *prefix,
5439 bool keepmain)
5440 void gv_fullname3 (SV *sv, const GV *gv, const char *prefix)
5441 void gv_fullname4 (SV *sv, const GV *gv, const char *prefix,
5442 bool keepmain)
5443 "gv_fetchfile"
5445 "gv_fetchfile_flags"
5446 These return the debugger glob for the file (compiled by Perl)
5447 whose name is given by the "name" parameter.
5448 There are currently exactly two differences between these
5450 functions.
5451 The "name" parameter to "gv_fetchfile" is a C string, meaning it is
5453 "NUL"-terminated; whereas the "name" parameter to
5454 "gv_fetchfile_flags" is a Perl string, whose length (in bytes) is
5455 passed in via the "namelen" parameter This means the name may
5456 contain embedded "NUL" characters. "namelen" doesn't exist in
5457 plain "gv_fetchfile").
5458 The other difference is that "gv_fetchfile_flags" has an extra
5460 "flags" parameter, which is currently completely ignored, but
5461 allows for possible future extensions.
5462 GV * gv_fetchfile (const char *name)
5464 GV * gv_fetchfile_flags(const char * const name,
5465 const STRLEN len, const U32 flags)
5466 "gv_fetchmeth"
5468 "gv_fetchmeth_pv"
5469 "gv_fetchmeth_pvn"
5470 "gv_fetchmeth_sv"
5471 These each look for a glob with name "name", containing a defined
5472 subroutine, returning the GV of that glob if found, or "NULL" if
5473 not.
5474 "stash" is always searched (first), unless it is "NULL".
5476 If "stash" is NULL, or was searched but nothing was found in it,
5478 and the "GV_SUPER" bit is set in "flags", stashes accessible via
5479 @ISA are searched next. Searching is conducted according to "MRO"
5480 order.
5481 Finally, if no matches were found so far, and the "GV_NOUNIVERSAL"
5483 flag in "flags" is not set, "UNIVERSAL::" is searched.
5484 The argument "level" should be either 0 or -1. If -1, the function
5486 will return without any side effects or caching. If 0, the
5487 function makes sure there is a glob named "name" in "stash",
5488 creating one if necessary. The subroutine slot in the glob will be
5489 set to any subroutine found in the "stash" and "SUPER::" search,
5490 hence caching any "SUPER::" result. Note that subroutines found in
5491 "UNIVERSAL::" are not cached.
5492 The GV returned from these may be a method cache entry, which is
5494 not visible to Perl code. So when calling "call_sv", you should
5495 not use the GV directly; instead, you should use the method's CV,
5496 which can be obtained from the GV with the "GvCV" macro.
5497 The only other significant value for "flags" is "SVf_UTF8",
5499 indicating that "name" is to be treated as being encoded in UTF-8.
5500 Plain "gv_fetchmeth" lacks a "flags" parameter, hence always
5502 searches in "stash", then "UNIVERSAL::", and "name" is never UTF-8.
5503 Otherwise it is exactly like "gv_fetchmeth_pvn".
5504 The other forms do have a "flags" parameter, and differ only in how
5506 the glob name is specified.
5507 In "gv_fetchmeth_pv", "name" is a C language NUL-terminated string.
5509 In "gv_fetchmeth_pvn", "name" points to the first byte of the name,
5511 and an additional parameter, "len", specifies its length in bytes.
5512 Hence, the name may contain embedded-NUL characters.
5513 In "gv_fetchmeth_sv", *name is an SV, and the name is the PV
5515 extracted from that, using ""SvPV"". If the SV is marked as being
5516 in UTF-8, the extracted PV will also be.
5517 GV * gv_fetchmeth (HV *stash, const char *name, STRLEN len,
5519 I32 level)
5520 GV * gv_fetchmeth_pv (HV *stash, const char *name, I32 level,
5521 U32 flags)
5522 GV * gv_fetchmeth_pvn(HV *stash, const char *name, STRLEN len,
5523 I32 level, U32 flags)
5524 GV * gv_fetchmeth_sv (HV *stash, SV *namesv, I32 level,
5525 U32 flags)
5526 "gv_fetchmeth_autoload"
5528 This is the old form of "gv_fetchmeth_pvn_autoload", which has no
5529 flags parameter.
5530 GV * gv_fetchmeth_autoload(HV *stash, const char *name,
5532 STRLEN len, I32 level)
5533 "gv_fetchmethod"
5535 See "gv_fetchmethod_autoload".
5536 GV * gv_fetchmethod(HV *stash, const char *name)
5538 "gv_fetchmethod_autoload"
5540 Returns the glob which contains the subroutine to call to invoke
5541 the method on the "stash". In fact in the presence of autoloading
5542 this may be the glob for "AUTOLOAD". In this case the
5543 corresponding variable $AUTOLOAD is already setup.
5544 The third parameter of "gv_fetchmethod_autoload" determines whether
5546 AUTOLOAD lookup is performed if the given method is not present:
5547 non-zero means yes, look for AUTOLOAD; zero means no, don't look
5548 for AUTOLOAD. Calling "gv_fetchmethod" is equivalent to calling
5549 "gv_fetchmethod_autoload" with a non-zero "autoload" parameter.
5550 These functions grant "SUPER" token as a prefix of the method name.
5552 Note that if you want to keep the returned glob for a long time,
5553 you need to check for it being "AUTOLOAD", since at the later time
5554 the call may load a different subroutine due to $AUTOLOAD changing
5555 its value. Use the glob created as a side effect to do this.
5556 These functions have the same side-effects as "gv_fetchmeth" with
5558 "level==0". The warning against passing the GV returned by
5559 "gv_fetchmeth" to "call_sv" applies equally to these functions.
5560 GV * gv_fetchmethod_autoload(HV *stash, const char *name,
5562 I32 autoload)
5563 "gv_fetchmeth_pv_autoload"
5565 Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-
5566 terminated string instead of a string/length pair.
5567 GV * gv_fetchmeth_pv_autoload(HV *stash, const char *name,
5569 I32 level, U32 flags)
5570 "gv_fetchmeth_pvn_autoload"
5572 Same as gv_fetchmeth_pvn(), but looks for autoloaded subroutines
5573 too. Returns a glob for the subroutine.
5574 For an autoloaded subroutine without a GV, will create a GV even if
5576 "level < 0". For an autoloaded subroutine without a stub, GvCV()
5577 of the result may be zero.
5578 Currently, the only significant value for "flags" is "SVf_UTF8".
5580 GV * gv_fetchmeth_pvn_autoload(HV *stash, const char *name,
5582 STRLEN len, I32 level, U32 flags)
5583 "gv_fetchmeth_sv_autoload"
5585 Exactly like "gv_fetchmeth_pvn_autoload", but takes the name string
5586 in the form of an SV instead of a string/length pair.
5587 GV * gv_fetchmeth_sv_autoload(HV *stash, SV *namesv, I32 level,
5589 U32 flags)
5590 "gv_fetchpv"
5592 "gv_fetchpvn"
5593 "gv_fetchpvn_flags"
5594 "gv_fetchpvs"
5595 "gv_fetchsv"
5596 "gv_fetchsv_nomg"
5597 These all return the GV of type "sv_type" whose name is given by
5598 the inputs, or NULL if no GV of that name and type could be found.
5599 See "Stashes and Globs" in perlguts.
5600 The only differences are how the input name is specified, and if
5602 'get' magic is normally used in getting that name.
5603 Don't be fooled by the fact that only one form has "flags" in its
5605 name. They all have a "flags" parameter in fact, and all the flag
5606 bits have the same meanings for all
5607 If any of the flags "GV_ADD", "GV_ADDMG", "GV_ADDWARN",
5609 "GV_ADDMULTI", or "GV_NOINIT" is set, a GV is created if none
5610 already exists for the input name and type. However, "GV_ADDMG"
5611 will only do the creation for magical GV's. For all of these flags
5612 except "GV_NOINIT", "gv_init_pvn" is called after the addition.
5613 "GV_ADDWARN" is used when the caller expects that adding won't be
5614 necessary because the symbol should already exist; but if not, add
5615 it anyway, with a warning that it was unexpectedly absent. The
5616 "GV_ADDMULTI" flag means to pretend that the GV has been seen
5617 before (i.e., suppress "Used once" warnings).
5618 The flag "GV_NOADD_NOINIT" causes "gv_init_pvn" not be to called if
5620 the GV existed but isn't PVGV.
5621 If the "SVf_UTF8" bit is set, the name is treated as being encoded
5623 in UTF-8; otherwise the name won't be considered to be UTF-8 in the
5624 "pv"-named forms, and the UTF-8ness of the underlying SVs will be
5625 used in the "sv" forms.
5626 If the flag "GV_NOTQUAL" is set, the caller warrants that the input
5628 name is a plain symbol name, not qualified with a package,
5629 otherwise the name is checked for being a qualified one.
5630 In "gv_fetchpv", "nambeg" is a C string, NUL-terminated with no
5632 intermediate NULs.
5633 In "gv_fetchpvs", "name" is a literal C string, hence is enclosed
5635 in double quotes.
5636 "gv_fetchpvn" and "gv_fetchpvn_flags" are identical. In these,
5638 <nambeg> is a Perl string whose byte length is given by "full_len",
5639 and may contain embedded NULs.
5640 In "gv_fetchsv" and "gv_fetchsv_nomg", the name is extracted from
5642 the PV of the input "name" SV. The only difference between these
5643 two forms is that 'get' magic is normally done on "name" in
5644 "gv_fetchsv", and always skipped with "gv_fetchsv_nomg". Including
5645 "GV_NO_SVGMAGIC" in the "flags" parameter to "gv_fetchsv" makes it
5646 behave identically to "gv_fetchsv_nomg".
5647 GV * gv_fetchpv (const char *nambeg, I32 flags,
5649 const svtype sv_type)
5650 GV * gv_fetchpvn (const char * nambeg, STRLEN full_len,
5651 I32 flags, const svtype sv_type)
5652 GV * gv_fetchpvn_flags(const char *name, STRLEN len, I32 flags,
5653 const svtype sv_type)
5654 GV * gv_fetchpvs ("name", I32 flags, const svtype sv_type)
5655 GV * gv_fetchsv (SV *name, I32 flags, const svtype sv_type)
5656 GV * gv_fetchsv_nomg (SV *name, I32 flags, const svtype sv_type)
5657 "GvHV"
5659 Return the HV from the GV.
5660 HV* GvHV(GV* gv)
5662 "gv_init"
5664 The old form of gv_init_pvn(). It does not work with UTF-8
5665 strings, as it has no flags parameter. If the "multi" parameter is
5666 set, the "GV_ADDMULTI" flag will be passed to gv_init_pvn().
5667 void gv_init(GV *gv, HV *stash, const char *name, STRLEN len,
5669 int multi)
5670 "gv_init_pv"
5672 Same as gv_init_pvn(), but takes a nul-terminated string for the
5673 name instead of separate char * and length parameters.
5674 void gv_init_pv(GV *gv, HV *stash, const char *name, U32 flags)
5676 "gv_init_pvn"
5678 Converts a scalar into a typeglob. This is an incoercible
5679 typeglob; assigning a reference to it will assign to one of its
5680 slots, instead of overwriting it as happens with typeglobs created
5681 by "SvSetSV". Converting any scalar that is SvOK() may produce
5682 unpredictable results and is reserved for perl's internal use.
5683 "gv" is the scalar to be converted.
5685 "stash" is the parent stash/package, if any.
5687 "name" and "len" give the name. The name must be unqualified; that
5689 is, it must not include the package name. If "gv" is a stash
5690 element, it is the caller's responsibility to ensure that the name
5691 passed to this function matches the name of the element. If it
5692 does not match, perl's internal bookkeeping will get out of sync.
5693 "flags" can be set to "SVf_UTF8" if "name" is a UTF-8 string, or
5695 the return value of SvUTF8(sv). It can also take the "GV_ADDMULTI"
5696 flag, which means to pretend that the GV has been seen before
5697 (i.e., suppress "Used once" warnings).
5698 void gv_init_pvn(GV *gv, HV *stash, const char *name, STRLEN len,
5700 U32 flags)
5701 "gv_init_sv"
5703 Same as gv_init_pvn(), but takes an SV * for the name instead of
5704 separate char * and length parameters. "flags" is currently
5705 unused.
5706 void gv_init_sv(GV *gv, HV *stash, SV *namesv, U32 flags)
5708 "gv_name_set"
5710 Set the name for GV "gv" to "name" which is "len" bytes long. Thus
5711 it may contain embedded NUL characters.
5712 If "flags" contains "SVf_UTF8", the name is treated as being
5714 encoded in UTF-8; otherwise not.
5715 void gv_name_set(GV *gv, const char *name, U32 len, U32 flags)
5717 "gv_stashpv"
5719 Returns a pointer to the stash for a specified package. Uses
5720 "strlen" to determine the length of "name", then calls
5721 gv_stashpvn().
5722 HV * gv_stashpv(const char *name, I32 flags)
5724 "gv_stashpvn"
5726 Returns a pointer to the stash for a specified package. The
5727 "namelen" parameter indicates the length of the "name", in bytes.
5728 "flags" is passed to gv_fetchpvn_flags(), so if set to "GV_ADD"
5729 then the package will be created if it does not already exist. If
5730 the package does not exist and "flags" is 0 (or any other setting
5731 that does not create packages) then "NULL" is returned.
5732 Flags may be one of:
5734 GV_ADD Create and initialize the package if doesn't
5736 already exist
5737 GV_NOADD_NOINIT Don't create the package,
5738 GV_ADDMG GV_ADD iff the GV is magical
5739 GV_NOINIT GV_ADD, but don't initialize
5740 GV_NOEXPAND Don't expand SvOK() entries to PVGV
5741 SVf_UTF8 The name is in UTF-8
5742 The most important of which are probably "GV_ADD" and "SVf_UTF8".
5744 Note, use of "gv_stashsv" instead of "gv_stashpvn" where possible
5746 is strongly recommended for performance reasons.
5747 HV * gv_stashpvn(const char *name, U32 namelen, I32 flags)
5749 "gv_stashpvs"
5751 Like "gv_stashpvn", but takes a literal string instead of a
5752 string/length pair.
5753 HV* gv_stashpvs("name", I32 create)
5755 "gv_stashsv"
5757 Returns a pointer to the stash for a specified package. See
5758 "gv_stashpvn".
5759 Note this interface is strongly preferred over "gv_stashpvn" for
5761 performance reasons.
5762 HV * gv_stashsv(SV *sv, I32 flags)
5764 "GvSV"
5766 Return the SV from the GV.
5767 Prior to Perl v5.9.3, this would add a scalar if none existed.
5769 Nowadays, use "GvSVn" for that, or compile perl with
5770 "-DPERL_CREATE_GVSV". See perl5100delta.
5771 SV* GvSV(GV* gv)
5773 "GvSVn"
5775 Like "GvSV", but creates an empty scalar if none already exists.
5776 SV* GvSVn(GV* gv)
5778 "newGVgen"
5780 "newGVgen_flags"
5781 Create a new, guaranteed to be unique, GV in the package given by
5782 the NUL-terminated C language string "pack", and return a pointer
5783 to it.
5784 For "newGVgen" or if "flags" in "newGVgen_flags" is 0, "pack" is to
5786 be considered to be encoded in Latin-1. The only other legal
5787 "flags" value is "SVf_UTF8", which indicates "pack" is to be
5788 considered to be encoded in UTF-8.
5789 GV * newGVgen (const char *pack)
5791 GV * newGVgen_flags(const char *pack, U32 flags)
5792 "PL_curstash"
5794 The stash for the package code will be compiled into.
5795 On threaded perls, each thread has an independent copy of this
5797 variable; each initialized at creation time with the current value
5798 of the creating thread's copy.
5799 HV* PL_curstash
5801 "PL_defgv"
5803 The GV representing *_. Useful for access to $_.
5804 On threaded perls, each thread has an independent copy of this
5806 variable; each initialized at creation time with the current value
5807 of the creating thread's copy.
5808 GV * PL_defgv
5810 "PL_defoutgv"
5812 See "setdefout".
5813 "PL_defstash"
5815 Described in perlguts.
5816 "save_gp"
5818 Saves the current GP of gv on the save stack to be restored on
5819 scope exit.
5820 If "empty" is true, replace the GP with a new GP.
5822 If "empty" is false, mark "gv" with "GVf_INTRO" so the next
5824 reference assigned is localized, which is how
5825 " local *foo = $someref; " works.
5826 void save_gp(GV *gv, I32 empty)
5828 "setdefout"
5830 Sets "PL_defoutgv", the default file handle for output, to the
5831 passed in typeglob. As "PL_defoutgv" "owns" a reference on its
5832 typeglob, the reference count of the passed in typeglob is
5833 increased by one, and the reference count of the typeglob that
5834 "PL_defoutgv" points to is decreased by one.
5835 void setdefout(GV *gv)
5837
5839 These functions provide convenient and thread-safe means of
5840 manipulating hook variables.
5841 "rcpv_copy"
5843 refcount increment a shared memory refcounted string, and when the
5844 refcount goes to 0 free it using PerlMemShared_free().
5845 It is the callers responsibility to ensure that the pv is the
5847 result of a rcpv_new() call.
5848 Returns the same pointer that was passed in.
5850 new = rcpv_copy(pv);
5852 char * rcpv_copy(char * const pv)
5854 "rcpv_free"
5856 refcount decrement a shared memory refcounted string, and when the
5857 refcount goes to 0 free it using perlmemshared_free().
5858 it is the callers responsibility to ensure that the pv is the
5860 result of a rcpv_new() call.
5861 Always returns NULL so it can be used like this:
5863 thing = rcpv_free(thing);
5865 char * rcpv_free(char * const pv)
5867 "rcpv_new"
5869 Create a new shared memory refcounted string with the requested
5870 size, and with the requested initialization and a refcount of 1.
5871 The actual space allocated will be 1 byte more than requested and
5872 rcpv_new() will ensure that the extra byte is a null regardless of
5873 any flags settings.
5874 If the RCPVf_NO_COPY flag is set then the pv argument will be
5876 ignored, otherwise the contents of the pv pointer will be copied
5877 into the new buffer or if it is NULL the function will do nothing
5878 and return NULL.
5879 If the RCPVf_USE_STRLEN flag is set then the len argument is
5881 ignored and recomputed using strlen(pv). It is an error to combine
5882 RCPVf_USE_STRLEN and RCPVf_NO_COPY at the same time.
5883 Under DEBUGGING rcpv_new() will assert() if it is asked to create a
5885 0 length shared string unless the RCPVf_ALLOW_EMPTY flag is set.
5886 The return value from the function is suitable for passing into
5888 rcpv_copy() and rcpv_free(). To access the RCPV * from the returned
5889 value use the RCPVx() macro. The 'len' member of the RCPV struct
5890 stores the allocated length (including the extra byte), but the
5891 RCPV_LEN() macro returns the requested length (not including the
5892 extra byte).
5893 Note that rcpv_new() does NOT use a hash table or anything like
5895 that to dedupe inputs given the same text content. Each call with a
5896 non-null pv parameter will produce a distinct pointer with its own
5897 refcount regardless of the input content.
5898 char * rcpv_new(const char * const pv, STRLEN len, U32 flags)
5900 "wrap_op_checker"
5902 Puts a C function into the chain of check functions for a specified
5903 op type. This is the preferred way to manipulate the "PL_check"
5904 array. "opcode" specifies which type of op is to be affected.
5905 "new_checker" is a pointer to the C function that is to be added to
5906 that opcode's check chain, and "old_checker_p" points to the
5907 storage location where a pointer to the next function in the chain
5908 will be stored. The value of "new_checker" is written into the
5909 "PL_check" array, while the value previously stored there is
5910 written to *old_checker_p.
5911 "PL_check" is global to an entire process, and a module wishing to
5913 hook op checking may find itself invoked more than once per
5914 process, typically in different threads. To handle that situation,
5915 this function is idempotent. The location *old_checker_p must
5916 initially (once per process) contain a null pointer. A C variable
5917 of static duration (declared at file scope, typically also marked
5918 "static" to give it internal linkage) will be implicitly
5919 initialised appropriately, if it does not have an explicit
5920 initialiser. This function will only actually modify the check
5921 chain if it finds *old_checker_p to be null. This function is also
5922 thread safe on the small scale. It uses appropriate locking to
5923 avoid race conditions in accessing "PL_check".
5924 When this function is called, the function referenced by
5926 "new_checker" must be ready to be called, except for *old_checker_p
5927 being unfilled. In a threading situation, "new_checker" may be
5928 called immediately, even before this function has returned.
5929 *old_checker_p will always be appropriately set before
5930 "new_checker" is called. If "new_checker" decides not to do
5931 anything special with an op that it is given (which is the usual
5932 case for most uses of op check hooking), it must chain the check
5933 function referenced by *old_checker_p.
5934 Taken all together, XS code to hook an op checker should typically
5936 look something like this:
5937 static Perl_check_t nxck_frob;
5939 static OP *myck_frob(pTHX_ OP *op) {
5940 ...
5941 op = nxck_frob(aTHX_ op);
5942 ...
5943 return op;
5944 }
5945 BOOT:
5946 wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
5947 If you want to influence compilation of calls to a specific
5949 subroutine, then use "cv_set_call_checker_flags" rather than
5950 hooking checking of all "entersub" ops.
5951 void wrap_op_checker(Optype opcode, Perl_check_t new_checker,
5953 Perl_check_t *old_checker_p)
5954
5956 A HV structure represents a Perl hash. It consists mainly of an array
5957 of pointers, each of which points to a linked list of HE structures.
5958 The array is indexed by the hash function of the key, so each linked
5959 list represents all the hash entries with the same hash value. Each HE
5960 contains a pointer to the actual value, plus a pointer to a HEK
5961 structure which holds the key and hash value.
5962 "get_hv"
5964 Returns the HV of the specified Perl hash. "flags" are passed to
5965 "gv_fetchpv". If "GV_ADD" is set and the Perl variable does not
5966 exist then it will be created. If "flags" is zero (ignoring
5967 "SVf_UTF8") and the variable does not exist then "NULL" is
5968 returned.
5969 NOTE: the perl_get_hv() form is deprecated.
5971 HV * get_hv(const char *name, I32 flags)
5973 "HE"
5975 Described in perlguts.
5976 "HEf_SVKEY"
5978 This flag, used in the length slot of hash entries and magic
5979 structures, specifies the structure contains an "SV*" pointer where
5980 a "char*" pointer is to be expected. (For information only--not to
5981 be used).
5982 "HeHASH"
5984 Returns the computed hash stored in the hash entry.
5985 U32 HeHASH(HE* he)
5987 "HeKEY"
5989 Returns the actual pointer stored in the key slot of the hash
5990 entry. The pointer may be either "char*" or "SV*", depending on
5991 the value of HeKLEN(). Can be assigned to. The HePV() or
5992 HeSVKEY() macros are usually preferable for finding the value of a
5993 key.
5994 void* HeKEY(HE* he)
5996 "HeKLEN"
5998 If this is negative, and amounts to "HEf_SVKEY", it indicates the
5999 entry holds an "SV*" key. Otherwise, holds the actual length of
6000 the key. Can be assigned to. The HePV() macro is usually
6001 preferable for finding key lengths.
6002 STRLEN HeKLEN(HE* he)
6004 "HePV"
6006 Returns the key slot of the hash entry as a "char*" value, doing
6007 any necessary dereferencing of possibly "SV*" keys. The length of
6008 the string is placed in "len" (this is a macro, so do not use
6009 &len). If you do not care about what the length of the key is, you
6010 may use the global variable "PL_na", though this is rather less
6011 efficient than using a local variable. Remember though, that hash
6012 keys in perl are free to contain embedded nulls, so using strlen()
6013 or similar is not a good way to find the length of hash keys. This
6014 is very similar to the SvPV() macro described elsewhere in this
6015 document. See also "HeUTF8".
6016 If you are using "HePV" to get values to pass to newSVpvn() to
6018 create a new SV, you should consider using
6019 "newSVhek(HeKEY_hek(he))" as it is more efficient.
6020 char* HePV(HE* he, STRLEN len)
6022 "HeSVKEY"
6024 Returns the key as an "SV*", or "NULL" if the hash entry does not
6025 contain an "SV*" key.
6026 SV* HeSVKEY(HE* he)
6028 "HeSVKEY_force"
6030 Returns the key as an "SV*". Will create and return a temporary
6031 mortal "SV*" if the hash entry contains only a "char*" key.
6032 SV* HeSVKEY_force(HE* he)
6034 "HeSVKEY_set"
6036 Sets the key to a given "SV*", taking care to set the appropriate
6037 flags to indicate the presence of an "SV*" key, and returns the
6038 same "SV*".
6039 SV* HeSVKEY_set(HE* he, SV* sv)
6041 "HeUTF8"
6043 Returns whether the "char *" value returned by "HePV" is encoded in
6044 UTF-8, doing any necessary dereferencing of possibly "SV*" keys.
6045 The value returned will be 0 or non-0, not necessarily 1 (or even a
6046 value with any low bits set), so do not blindly assign this to a
6047 "bool" variable, as "bool" may be a typedef for "char".
6048 U32 HeUTF8(HE* he)
6050 "HeVAL"
6052 Returns the value slot (type "SV*") stored in the hash entry. Can
6053 be assigned to.
6054 SV *foo= HeVAL(hv);
6056 HeVAL(hv)= sv;
6057 SV* HeVAL(HE* he)
6059 "HV"
6061 Described in perlguts.
6062 "hv_assert"
6064 Check that a hash is in an internally consistent state.
6065 NOTE: "hv_assert" must be explicitly called as "Perl_hv_assert"
6067 with an "aTHX_" parameter.
6068 void Perl_hv_assert(pTHX_ HV *hv)
6070 "hv_bucket_ratio"
6072 NOTE: "hv_bucket_ratio" is experimental and may change or be
6073 removed without notice.
6074 If the hash is tied dispatches through to the SCALAR tied method,
6076 otherwise if the hash contains no keys returns 0, otherwise returns
6077 a mortal sv containing a string specifying the number of used
6078 buckets, followed by a slash, followed by the number of available
6079 buckets.
6080 This function is expensive, it must scan all of the buckets to
6082 determine which are used, and the count is NOT cached. In a large
6083 hash this could be a lot of buckets.
6084 SV * hv_bucket_ratio(HV *hv)
6086 "hv_clear"
6088 Frees all the elements of a hash, leaving it empty. The XS
6089 equivalent of "%hash = ()". See also "hv_undef".
6090 See "av_clear" for a note about the hash possibly being invalid on
6092 return.
6093 void hv_clear(HV *hv)
6095 "hv_clear_placeholders"
6097 Clears any placeholders from a hash. If a restricted hash has any
6098 of its keys marked as readonly and the key is subsequently deleted,
6099 the key is not actually deleted but is marked by assigning it a
6100 value of &PL_sv_placeholder. This tags it so it will be ignored by
6101 future operations such as iterating over the hash, but will still
6102 allow the hash to have a value reassigned to the key at some future
6103 point. This function clears any such placeholder keys from the
6104 hash. See Hash::Util::lock_keys() for an example of its use.
6105 void hv_clear_placeholders(HV *hv)
6107 "hv_copy_hints_hv"
6109 A specialised version of "newHVhv" for copying "%^H". "ohv" must
6110 be a pointer to a hash (which may have "%^H" magic, but should be
6111 generally non-magical), or "NULL" (interpreted as an empty hash).
6112 The content of "ohv" is copied to a new hash, which has the
6113 "%^H"-specific magic added to it. A pointer to the new hash is
6114 returned.
6115 HV * hv_copy_hints_hv(HV * const ohv)
6117 "hv_delete"
6119 Deletes a key/value pair in the hash. The value's SV is removed
6120 from the hash, made mortal, and returned to the caller. The
6121 absolute value of "klen" is the length of the key. If "klen" is
6122 negative the key is assumed to be in UTF-8-encoded Unicode. The
6123 "flags" value will normally be zero; if set to "G_DISCARD" then
6124 "NULL" will be returned. "NULL" will also be returned if the key
6125 is not found.
6126 SV * hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
6128 "hv_delete_ent"
6130 Deletes a key/value pair in the hash. The value SV is removed from
6131 the hash, made mortal, and returned to the caller. The "flags"
6132 value will normally be zero; if set to "G_DISCARD" then "NULL" will
6133 be returned. "NULL" will also be returned if the key is not found.
6134 "hash" can be a valid precomputed hash value, or 0 to ask for it to
6135 be computed.
6136 SV * hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
6138 "HvENAME"
6140 Returns the effective name of a stash, or NULL if there is none.
6141 The effective name represents a location in the symbol table where
6142 this stash resides. It is updated automatically when packages are
6143 aliased or deleted. A stash that is no longer in the symbol table
6144 has no effective name. This name is preferable to "HvNAME" for use
6145 in MRO linearisations and isa caches.
6146 char* HvENAME(HV* stash)
6148 "HvENAMELEN"
6150 Returns the length of the stash's effective name.
6151 STRLEN HvENAMELEN(HV *stash)
6153 "HvENAMEUTF8"
6155 Returns true if the effective name is in UTF-8 encoding.
6156 unsigned char HvENAMEUTF8(HV *stash)
6158 "hv_exists"
6160 Returns a boolean indicating whether the specified hash key exists.
6161 The absolute value of "klen" is the length of the key. If "klen"
6162 is negative the key is assumed to be in UTF-8-encoded Unicode.
6163 bool hv_exists(HV *hv, const char *key, I32 klen)
6165 "hv_exists_ent"
6167 Returns a boolean indicating whether the specified hash key exists.
6168 "hash" can be a valid precomputed hash value, or 0 to ask for it to
6169 be computed.
6170 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
6172 "hv_fetch"
6174 Returns the SV which corresponds to the specified key in the hash.
6175 The absolute value of "klen" is the length of the key. If "klen"
6176 is negative the key is assumed to be in UTF-8-encoded Unicode. If
6177 "lval" is set then the fetch will be part of a store. This means
6178 that if there is no value in the hash associated with the given
6179 key, then one is created and a pointer to it is returned. The
6180 "SV*" it points to can be assigned to. But always check that the
6181 return value is non-null before dereferencing it to an "SV*".
6182 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
6184 for more information on how to use this function on tied hashes.
6185 SV ** hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
6187 "hv_fetch_ent"
6189 Returns the hash entry which corresponds to the specified key in
6190 the hash. "hash" must be a valid precomputed hash number for the
6191 given "key", or 0 if you want the function to compute it. IF
6192 "lval" is set then the fetch will be part of a store. Make sure
6193 the return value is non-null before accessing it. The return value
6194 when "hv" is a tied hash is a pointer to a static location, so be
6195 sure to make a copy of the structure if you need to store it
6196 somewhere.
6197 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
6199 for more information on how to use this function on tied hashes.
6200 HE * hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
6202 "hv_fetchs"
6204 Like "hv_fetch", but takes a literal string instead of a
6205 string/length pair.
6206 SV** hv_fetchs(HV* tb, "key", I32 lval)
6208 "HvFILL"
6210 Returns the number of hash buckets that happen to be in use.
6211 As of perl 5.25 this function is used only for debugging purposes,
6213 and the number of used hash buckets is not in any way cached, thus
6214 this function can be costly to execute as it must iterate over all
6215 the buckets in the hash.
6216 STRLEN HvFILL(HV *const hv)
6218 "HvHasAUX"
6220 Returns true if the HV has a "struct xpvhv_aux" extension. Use this
6221 to check whether it is valid to call HvAUX().
6222 bool HvHasAUX(HV *const hv)
6224 "hv_iterinit"
6226 Prepares a starting point to traverse a hash table. Returns the
6227 number of keys in the hash, including placeholders (i.e. the same
6228 as HvTOTALKEYS(hv)). The return value is currently only meaningful
6229 for hashes without tie magic.
6230 NOTE: Before version 5.004_65, "hv_iterinit" used to return the
6232 number of hash buckets that happen to be in use. If you still need
6233 that esoteric value, you can get it through the macro HvFILL(hv).
6234 I32 hv_iterinit(HV *hv)
6236 "hv_iterkey"
6238 Returns the key from the current position of the hash iterator.
6239 See "hv_iterinit".
6240 char * hv_iterkey(HE *entry, I32 *retlen)
6242 "hv_iterkeysv"
6244 Returns the key as an "SV*" from the current position of the hash
6245 iterator. The return value will always be a mortal copy of the
6246 key. Also see "hv_iterinit".
6247 SV * hv_iterkeysv(HE *entry)
6249 "hv_iternext"
6251 Returns entries from a hash iterator. See "hv_iterinit".
6252 You may call "hv_delete" or "hv_delete_ent" on the hash entry that
6254 the iterator currently points to, without losing your place or
6255 invalidating your iterator. Note that in this case the current
6256 entry is deleted from the hash with your iterator holding the last
6257 reference to it. Your iterator is flagged to free the entry on the
6258 next call to "hv_iternext", so you must not discard your iterator
6259 immediately else the entry will leak - call "hv_iternext" to
6260 trigger the resource deallocation.
6261 HE * hv_iternext(HV *hv)
6263 "hv_iternext_flags"
6265 NOTE: "hv_iternext_flags" is experimental and may change or be
6266 removed without notice.
6267 Returns entries from a hash iterator. See "hv_iterinit" and
6269 "hv_iternext". The "flags" value will normally be zero; if
6270 "HV_ITERNEXT_WANTPLACEHOLDERS" is set the placeholders keys (for
6271 restricted hashes) will be returned in addition to normal keys. By
6272 default placeholders are automatically skipped over. Currently a
6273 placeholder is implemented with a value that is &PL_sv_placeholder.
6274 Note that the implementation of placeholders and restricted hashes
6275 may change, and the implementation currently is insufficiently
6276 abstracted for any change to be tidy.
6277 HE * hv_iternext_flags(HV *hv, I32 flags)
6279 "hv_iternextsv"
6281 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in one
6282 operation.
6283 SV * hv_iternextsv(HV *hv, char **key, I32 *retlen)
6285 "hv_iterval"
6287 Returns the value from the current position of the hash iterator.
6288 See "hv_iterkey".
6289 SV * hv_iterval(HV *hv, HE *entry)
6291 "hv_ksplit"
6293 Attempt to grow the hash "hv" so it has at least "newmax" buckets
6294 available. Perl chooses the actual number for its convenience.
6295 This is the same as doing the following in Perl code:
6297 keys %hv = newmax;
6299 void hv_ksplit(HV *hv, IV newmax)
6301 "hv_magic"
6303 Adds magic to a hash. See "sv_magic".
6304 void hv_magic(HV *hv, GV *gv, int how)
6306 "HvNAME"
6308 Returns the package name of a stash, or "NULL" if "stash" isn't a
6309 stash. See "SvSTASH", "CvSTASH".
6310 char* HvNAME(HV* stash)
6312 "HvNAMELEN"
6314 Returns the length of the stash's name.
6315 Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them
6317 STRLEN HvNAMELEN(HV *stash)
6319 "hv_name_set"
6321 "hv_name_sets"
6322 These each set the name of stash "hv" to the specified name.
6323 They differ only in how the name is specified.
6325 In "hv_name_sets", the name is a literal C string, enclosed in
6327 double quotes.
6328 In "hv_name_set", "name" points to the first byte of the name, and
6330 an additional parameter, "len", specifies its length in bytes.
6331 Hence, the name may contain embedded-NUL characters.
6332 If "SVf_UTF8" is set in "flags", the name is treated as being in
6334 UTF-8; otherwise not.
6335 If "HV_NAME_SETALL" is set in "flags", both the name and the
6337 effective name are set.
6338 void hv_name_set (HV *hv, const char *name, U32 len, U32 flags)
6340 void hv_name_sets(HV *hv, "name", U32 flags)
6341 "HvNAMEUTF8"
6343 Returns true if the name is in UTF-8 encoding.
6344 unsigned char HvNAMEUTF8(HV *stash)
6346 "hv_scalar"
6348 Evaluates the hash in scalar context and returns the result.
6349 When the hash is tied dispatches through to the SCALAR method,
6351 otherwise returns a mortal SV containing the number of keys in the
6352 hash.
6353 Note, prior to 5.25 this function returned what is now returned by
6355 the hv_bucket_ratio() function.
6356 SV * hv_scalar(HV *hv)
6358 "hv_store"
6360 "hv_stores"
6361 These each store SV "val" with the specified key in hash "hv",
6362 returning NULL if the operation failed or if the value did not need
6363 to be actually stored within the hash (as in the case of tied
6364 hashes). Otherwise it can be dereferenced to get the original
6365 "SV*".
6366 They differ only in how the hash key is specified.
6368 In "hv_stores", the key is a C language string literal, enclosed in
6370 double quotes. It is never treated as being in UTF-8.
6371 In "hv_store", "key" is either NULL or points to the first byte of
6373 the string specifying the key, and its length in bytes is given by
6374 the absolute value of an additional parameter, "klen". A NULL key
6375 indicates the key is to be treated as "undef", and "klen" is
6376 ignored; otherwise the key string may contain embedded-NUL bytes.
6377 If "klen" is negative, the string is treated as being encoded in
6378 UTF-8; otherwise not.
6379 "hv_store" has another extra parameter, "hash", a precomputed hash
6381 of the key string, or zero if it has not been precomputed. This
6382 parameter is omitted from "hv_stores", as it is computed
6383 automatically at compile time.
6384 If <hv> is NULL, NULL is returned and no action is taken.
6386 If "val" is NULL, it is treated as being "undef"; otherwise the
6388 caller is responsible for suitably incrementing the reference count
6389 of "val" before the call, and decrementing it if the function
6390 returned "NULL". Effectively a successful "hv_store" takes
6391 ownership of one reference to "val". This is usually what you
6392 want; a newly created SV has a reference count of one, so if all
6393 your code does is create SVs then store them in a hash, "hv_store"
6394 will own the only reference to the new SV, and your code doesn't
6395 need to do anything further to tidy up.
6396 "hv_store" is not implemented as a call to ""hv_store_ent"", and
6398 does not create a temporary SV for the key, so if your key data is
6399 not already in SV form then use "hv_store" in preference to
6400 "hv_store_ent".
6401 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
6403 for more information on how to use this function on tied hashes.
6404 SV ** hv_store (HV *hv, const char *key, I32 klen, SV *val,
6406 U32 hash)
6407 SV ** hv_stores(HV *hv, "key", SV *val)
6408 "hv_store_ent"
6410 Stores "val" in a hash. The hash key is specified as "key". The
6411 "hash" parameter is the precomputed hash value; if it is zero then
6412 Perl will compute it. The return value is the new hash entry so
6413 created. It will be "NULL" if the operation failed or if the value
6414 did not need to be actually stored within the hash (as in the case
6415 of tied hashes). Otherwise the contents of the return value can be
6416 accessed using the "He?" macros described here. Note that the
6417 caller is responsible for suitably incrementing the reference count
6418 of "val" before the call, and decrementing it if the function
6419 returned NULL. Effectively a successful "hv_store_ent" takes
6420 ownership of one reference to "val". This is usually what you
6421 want; a newly created SV has a reference count of one, so if all
6422 your code does is create SVs then store them in a hash, "hv_store"
6423 will own the only reference to the new SV, and your code doesn't
6424 need to do anything further to tidy up. Note that "hv_store_ent"
6425 only reads the "key"; unlike "val" it does not take ownership of
6426 it, so maintaining the correct reference count on "key" is entirely
6427 the caller's responsibility. The reason it does not take
6428 ownership, is that "key" is not used after this function returns,
6429 and so can be freed immediately. "hv_store" is not implemented as
6430 a call to "hv_store_ent", and does not create a temporary SV for
6431 the key, so if your key data is not already in SV form then use
6432 "hv_store" in preference to "hv_store_ent".
6433 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts
6435 for more information on how to use this function on tied hashes.
6436 HE * hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
6438 "hv_undef"
6440 Undefines the hash. The XS equivalent of undef(%hash).
6441 As well as freeing all the elements of the hash (like hv_clear()),
6443 this also frees any auxiliary data and storage associated with the
6444 hash.
6445 See "av_clear" for a note about the hash possibly being invalid on
6447 return.
6448 void hv_undef(HV *hv)
6450 "newHV"
6452 Creates a new HV. The reference count is set to 1.
6453 HV * newHV()
6455 "newHVhv"
6457 The content of "ohv" is copied to a new hash. A pointer to the new
6458 hash is returned.
6459 HV * newHVhv(HV *hv)
6461 "Nullhv"
6463 "DEPRECATED!" It is planned to remove "Nullhv" from a future
6464 release of Perl. Do not use it for new code; remove it from
6465 existing code.
6466 Null HV pointer.
6468 (deprecated - use "(HV *)NULL" instead)
6470 "PERL_HASH"
6472 Described in perlguts.
6473 void PERL_HASH(U32 hash, char *key, STRLEN klen)
6475 "PL_modglobal"
6477 "PL_modglobal" is a general purpose, interpreter global HV for use
6478 by extensions that need to keep information on a per-interpreter
6479 basis. In a pinch, it can also be used as a symbol table for
6480 extensions to share data among each other. It is a good idea to
6481 use keys prefixed by the package name of the extension that owns
6482 the data.
6483 On threaded perls, each thread has an independent copy of this
6485 variable; each initialized at creation time with the current value
6486 of the creating thread's copy.
6487 HV* PL_modglobal
6489
6491 "do_close"
6492 Close an I/O stream. This implements Perl ""close"" in perlfunc.
6493 "gv" is the glob associated with the stream.
6495 "is_explict" is "true" if this is an explicit close of the stream;
6497 "false" if it is part of another operation, such as closing a pipe
6498 (which involves implicitly closing both ends).
6499 Returns "true" if successful; otherwise returns "false" and sets
6501 "errno" to indicate the cause.
6502 bool do_close(GV *gv, bool is_explicit)
6504 "IoDIRP"
6506 Described in perlguts.
6507 DIR * IoDIRP(IO *io)
6509 "IOf_FLUSH"
6511 Described in perlguts.
6512 "IoFLAGS"
6514 Described in perlguts.
6515 U8 IoFLAGS(IO *io)
6517 "IOf_UNTAINT"
6519 Described in perlguts.
6520 "IoIFP"
6522 Described in perlguts.
6523 PerlIO * IoIFP(IO *io)
6525 "IoOFP"
6527 Described in perlguts.
6528 PerlIO * IoOFP(IO *io)
6530 "IoTYPE"
6532 Described in perlguts.
6533 char IoTYPE(IO *io)
6535 "my_chsize"
6537 The C library chsize(3) if available, or a Perl implementation of
6538 it.
6539 I32 my_chsize(int fd, Off_t length)
6541 "my_dirfd"
6543 The C library dirfd(3) if available, or a Perl implementation of
6544 it, or die if not easily emulatable.
6545 int my_dirfd(DIR *dir)
6547 "my_pclose"
6549 A wrapper for the C library pclose(3). Don't use the latter, as
6550 the Perl version knows things that interact with the rest of the
6551 perl interpreter.
6552 I32 my_pclose(PerlIO *ptr)
6554 "my_popen"
6556 A wrapper for the C library popen(3). Don't use the latter, as the
6557 Perl version knows things that interact with the rest of the perl
6558 interpreter.
6559 PerlIO * my_popen(const char *cmd, const char *mode)
6561 "newIO"
6563 Create a new IO, setting the reference count to 1.
6564 IO * newIO()
6566 "PERL_FLUSHALL_FOR_CHILD"
6568 This defines a way to flush all output buffers. This may be a
6569 performance issue, so we allow people to disable it. Also, if we
6570 are using stdio, there are broken implementations of fflush(NULL)
6571 out there, Solaris being the most prominent.
6572 void PERL_FLUSHALL_FOR_CHILD
6574 "PerlIO_apply_layers"
6576 "PerlIO_binmode"
6577 "PerlIO_canset_cnt"
6578 "PerlIO_clearerr"
6579 "PerlIO_close"
6580 "PerlIO_debug"
6581 "PerlIO_eof"
6582 "PerlIO_error"
6583 "PerlIO_exportFILE"
6584 "PerlIO_fast_gets"
6585 "PerlIO_fdopen"
6586 "PerlIO_fileno"
6587 "PerlIO_fill"
6588 "PerlIO_findFILE"
6589 "PerlIO_flush"
6590 "PerlIO_get_base"
6591 "PerlIO_get_bufsiz"
6592 "PerlIO_get_cnt"
6593 "PerlIO_get_ptr"
6594 "PerlIO_getc"
6595 "PerlIO_getpos"
6596 "PerlIO_has_base"
6597 "PerlIO_has_cntptr"
6598 "PerlIO_importFILE"
6599 "PerlIO_open"
6600 "PerlIO_printf"
6601 "PerlIO_putc"
6602 "PerlIO_puts"
6603 "PerlIO_read"
6604 "PerlIO_releaseFILE"
6605 "PerlIO_reopen"
6606 "PerlIO_rewind"
6607 "PerlIO_seek"
6608 "PerlIO_set_cnt"
6609 "PerlIO_set_ptrcnt"
6610 "PerlIO_setlinebuf"
6611 "PerlIO_setpos"
6612 "PerlIO_stderr"
6613 "PerlIO_stdin"
6614 "PerlIO_stdout"
6615 "PerlIO_stdoutf"
6616 "PerlIO_tell"
6617 "PerlIO_ungetc"
6618 "PerlIO_unread"
6619 "PerlIO_vprintf"
6620 "PerlIO_write"
6621 Described in perlapio.
6622 int PerlIO_apply_layers(PerlIO *f, const char *mode,
6624 const char *layers)
6625 int PerlIO_binmode (PerlIO *f, int ptype, int imode,
6626 const char *layers)
6627 int PerlIO_canset_cnt (PerlIO *f)
6628 void PerlIO_clearerr (PerlIO *f)
6629 int PerlIO_close (PerlIO *f)
6630 void PerlIO_debug (const char *fmt, ...)
6631 int PerlIO_eof (PerlIO *f)
6632 int PerlIO_error (PerlIO *f)
6633 FILE * PerlIO_exportFILE (PerlIO *f, const char *mode)
6634 int PerlIO_fast_gets (PerlIO *f)
6635 PerlIO * PerlIO_fdopen (int fd, const char *mode)
6636 int PerlIO_fileno (PerlIO *f)
6637 int PerlIO_fill (PerlIO *f)
6638 FILE * PerlIO_findFILE (PerlIO *f)
6639 int PerlIO_flush (PerlIO *f)
6640 STDCHAR * PerlIO_get_base (PerlIO *f)
6641 SSize_t PerlIO_get_bufsiz (PerlIO *f)
6642 SSize_t PerlIO_get_cnt (PerlIO *f)
6643 STDCHAR * PerlIO_get_ptr (PerlIO *f)
6644 int PerlIO_getc (PerlIO *d)
6645 int PerlIO_getpos (PerlIO *f, SV *save)
6646 int PerlIO_has_base (PerlIO *f)
6647 int PerlIO_has_cntptr (PerlIO *f)
6648 PerlIO * PerlIO_importFILE (FILE *stdio, const char *mode)
6649 PerlIO * PerlIO_open (const char *path, const char *mode)
6650 int PerlIO_printf (PerlIO *f, const char *fmt, ...)
6651 int PerlIO_putc (PerlIO *f, int ch)
6652 int PerlIO_puts (PerlIO *f, const char *string)
6653 SSize_t PerlIO_read (PerlIO *f, void *vbuf,
6654 Size_t count)
6655 void PerlIO_releaseFILE (PerlIO *f, FILE *stdio)
6656 PerlIO * PerlIO_reopen (const char *path, const char *mode,
6657 PerlIO *old)
6658 void PerlIO_rewind (PerlIO *f)
6659 int PerlIO_seek (PerlIO *f, Off_t offset,
6660 int whence)
6661 void PerlIO_set_cnt (PerlIO *f, SSize_t cnt)
6662 void PerlIO_set_ptrcnt (PerlIO *f, STDCHAR *ptr,
6663 SSize_t cnt)
6664 void PerlIO_setlinebuf (PerlIO *f)
6665 int PerlIO_setpos (PerlIO *f, SV *saved)
6666 PerlIO * PerlIO_stderr (PerlIO *f, const char *mode,
6667 const char *layers)
6668 PerlIO * PerlIO_stdin (PerlIO *f, const char *mode,
6669 const char *layers)
6670 PerlIO * PerlIO_stdout (PerlIO *f, const char *mode,
6671 const char *layers)
6672 int PerlIO_stdoutf (const char *fmt, ...)
6673 Off_t PerlIO_tell (PerlIO *f)
6674 int PerlIO_ungetc (PerlIO *f, int ch)
6675 SSize_t PerlIO_unread (PerlIO *f, const void *vbuf,
6676 Size_t count)
6677 int PerlIO_vprintf (PerlIO *f, const char *fmt,
6678 va_list args)
6679 SSize_t PerlIO_write (PerlIO *f, const void *vbuf,
6680 Size_t count)
6681 "PERLIO_F_APPEND"
6683 "PERLIO_F_CANREAD"
6684 "PERLIO_F_CANWRITE"
6685 "PERLIO_F_CRLF"
6686 "PERLIO_F_EOF"
6687 "PERLIO_F_ERROR"
6688 "PERLIO_F_FASTGETS"
6689 "PERLIO_F_LINEBUF"
6690 "PERLIO_F_OPEN"
6691 "PERLIO_F_RDBUF"
6692 "PERLIO_F_TEMP"
6693 "PERLIO_F_TRUNCATE"
6694 "PERLIO_F_UNBUF"
6695 "PERLIO_F_UTF8"
6696 "PERLIO_F_WRBUF"
6697 Described in perliol.
6698 "PERLIO_FUNCS_CAST"
6700 Cast the pointer "func" to be of type "PerlIO_funcs *".
6701 "PERLIO_FUNCS_DECL"
6703 Declare "ftab" to be a PerlIO function table, that is, of type
6704 "PerlIO_funcs".
6705 PERLIO_FUNCS_DECL(PerlIO * ftab)
6707 "PERLIO_K_BUFFERED"
6709 "PERLIO_K_CANCRLF"
6710 "PERLIO_K_FASTGETS"
6711 "PERLIO_K_MULTIARG"
6712 "PERLIO_K_RAW"
6713 Described in perliol.
6714 "PERLIO_NOT_STDIO"
6716 Described in perlapio.
6717 "PL_maxsysfd"
6719 Described in perliol.
6720 "repeatcpy"
6722 Make "count" copies of the "len" bytes beginning at "from", placing
6723 them into memory beginning at "to", which must be big enough to
6724 accommodate them all.
6725 void repeatcpy(char *to, const char *from, I32 len, IV count)
6727 "USE_STDIO"
6729 Described in perlapio.
6730
6732 "CASTI32"
6733 This symbol is defined if the C compiler can cast negative or large
6734 floating point numbers to 32-bit ints.
6735 "HAS_INT64_T"
6737 This symbol will defined if the C compiler supports "int64_t".
6738 Usually the inttypes.h needs to be included, but sometimes
6739 sys/types.h is enough.
6740 "HAS_LONG_LONG"
6742 This symbol will be defined if the C compiler supports long long.
6743 "HAS_QUAD"
6745 This symbol, if defined, tells that there's a 64-bit integer type,
6746 "Quad_t", and its unsigned counterpart, "Uquad_t". "QUADKIND" will
6747 be one of "QUAD_IS_INT", "QUAD_IS_LONG", "QUAD_IS_LONG_LONG",
6748 "QUAD_IS_INT64_T", or "QUAD_IS___INT64".
6749 "I32df"
6751 This symbol defines the format string used for printing a Perl I32
6752 as a signed decimal integer.
6753 "INT16_C"
6755 "INT32_C"
6756 "INT64_C"
6757 Returns a token the C compiler recognizes for the constant "number"
6758 of the corresponding integer type on the machine.
6759 If the machine does not have a 64-bit type, "INT64_C" is undefined.
6761 Use "INTMAX_C" to get the largest type available on the platform.
6762 I16 INT16_C(number)
6764 I32 INT32_C(number)
6765 I64 INT64_C(number)
6766 "INTMAX_C"
6768 Returns a token the C compiler recognizes for the constant "number"
6769 of the widest integer type on the machine. For example, if the
6770 machine has "long long"s, INTMAX_C(-1) would yield
6771 -1LL
6773 See also, for example, "INT32_C".
6775 Use "IV" to declare variables of the maximum usable size on this
6777 platform.
6778 INTMAX_C(number)
6780 "INTSIZE"
6782 This symbol contains the value of sizeof(int) so that the C
6783 preprocessor can make decisions based on it.
6784 "I8SIZE"
6786 This symbol contains the sizeof(I8).
6787 "I16SIZE"
6789 This symbol contains the sizeof(I16).
6790 "I32SIZE"
6792 This symbol contains the sizeof(I32).
6793 "I64SIZE"
6795 This symbol contains the sizeof(I64).
6796 "I8TYPE"
6798 This symbol defines the C type used for Perl's I8.
6799 "I16TYPE"
6801 This symbol defines the C type used for Perl's I16.
6802 "I32TYPE"
6804 This symbol defines the C type used for Perl's I32.
6805 "I64TYPE"
6807 This symbol defines the C type used for Perl's I64.
6808 "IV"
6810 "I8"
6811 "I16"
6812 "I32"
6813 "I64"
6814 Described in perlguts.
6815 "IV_MAX"
6817 The largest signed integer that fits in an IV on this platform.
6818 IV IV_MAX
6820 "IV_MIN"
6822 The negative signed integer furthest away from 0 that fits in an IV
6823 on this platform.
6824 IV IV_MIN
6826 "IVSIZE"
6828 This symbol contains the sizeof(IV).
6829 "IVTYPE"
6831 This symbol defines the C type used for Perl's IV.
6832 "line_t"
6834 The typedef to use to declare variables that are to hold line
6835 numbers.
6836 "LONGLONGSIZE"
6838 This symbol contains the size of a long long, so that the C
6839 preprocessor can make decisions based on it. It is only defined if
6840 the system supports long long.
6841 "LONGSIZE"
6843 This symbol contains the value of sizeof(long) so that the C
6844 preprocessor can make decisions based on it.
6845 "memzero"
6847 Set the "l" bytes starting at *d to all zeroes.
6848 void memzero(void * d, Size_t l)
6850 "PERL_INT_FAST8_T"
6852 "PERL_INT_FAST16_T"
6853 "PERL_UINT_FAST8_T"
6854 "PERL_UINT_FAST16_T"
6855 These are equivalent to the correspondingly-named C99 typedefs on
6856 platforms that have those; they evaluate to "int" and "unsigned
6857 int" on platforms that don't, so that you can portably take
6858 advantage of this C99 feature.
6859 "PERL_INT_MAX"
6861 "PERL_INT_MIN"
6862 "PERL_LONG_MAX"
6863 "PERL_LONG_MIN"
6864 "PERL_QUAD_MAX"
6865 "PERL_QUAD_MIN"
6866 "PERL_SHORT_MAX"
6867 "PERL_SHORT_MIN"
6868 "PERL_UCHAR_MAX"
6869 "PERL_UCHAR_MIN"
6870 "PERL_UINT_MAX"
6871 "PERL_UINT_MIN"
6872 "PERL_ULONG_MAX"
6873 "PERL_ULONG_MIN"
6874 "PERL_UQUAD_MAX"
6875 "PERL_UQUAD_MIN"
6876 "PERL_USHORT_MAX"
6877 "PERL_USHORT_MIN"
6878 These give the largest and smallest number representable in the
6879 current platform in variables of the corresponding types.
6880 For signed types, the smallest representable number is the most
6882 negative number, the one furthest away from zero.
6883 For C99 and later compilers, these correspond to things like
6885 "INT_MAX", which are available to the C code. But these constants,
6886 furnished by Perl, allow code compiled on earlier compilers to
6887 portably have access to the same constants.
6888 int PERL_INT_MAX
6890 int PERL_INT_MIN
6891 long PERL_LONG_MAX
6892 long PERL_LONG_MIN
6893 IV PERL_QUAD_MAX
6894 IV PERL_QUAD_MIN
6895 short PERL_SHORT_MAX
6896 short PERL_SHORT_MIN
6897 U8 PERL_UCHAR_MAX
6898 U8 PERL_UCHAR_MIN
6899 unsigned int PERL_UINT_MAX
6900 unsigned int PERL_UINT_MIN
6901 unsigned long PERL_ULONG_MAX
6902 unsigned long PERL_ULONG_MIN
6903 UV PERL_UQUAD_MAX
6904 UV PERL_UQUAD_MIN
6905 unsigned short PERL_USHORT_MAX
6906 unsigned short PERL_USHORT_MIN
6907 "SHORTSIZE"
6909 This symbol contains the value of sizeof(short) so that the C
6910 preprocessor can make decisions based on it.
6911 "UINT16_C"
6913 "UINT32_C"
6914 "UINT64_C"
6915 Returns a token the C compiler recognizes for the constant "number"
6916 of the corresponding unsigned integer type on the machine.
6917 If the machine does not have a 64-bit type, "UINT64_C" is
6919 undefined. Use "UINTMAX_C" to get the largest type available on
6920 the platform.
6921 U16 UINT16_C(number)
6923 U32 UINT32_C(number)
6924 U64 UINT64_C(number)
6925 "UINTMAX_C"
6927 Returns a token the C compiler recognizes for the constant "number"
6928 of the widest unsigned integer type on the machine. For example,
6929 if the machine has "long"s, UINTMAX_C(1) would yield
6930 1UL
6932 See also, for example, "UINT32_C".
6934 Use "UV" to declare variables of the maximum usable size on this
6936 platform.
6937 UINTMAX_C(number)
6939 "U32of"
6941 This symbol defines the format string used for printing a Perl U32
6942 as an unsigned octal integer.
6943 "U8SIZE"
6945 This symbol contains the sizeof(U8).
6946 "U16SIZE"
6948 This symbol contains the sizeof(U16).
6949 "U32SIZE"
6951 This symbol contains the sizeof(U32).
6952 "U64SIZE"
6954 This symbol contains the sizeof(U64).
6955 "U8TYPE"
6957 This symbol defines the C type used for Perl's U8.
6958 "U16TYPE"
6960 This symbol defines the C type used for Perl's U16.
6961 "U32TYPE"
6963 This symbol defines the C type used for Perl's U32.
6964 "U64TYPE"
6966 This symbol defines the C type used for Perl's U64.
6967 "U32uf"
6969 This symbol defines the format string used for printing a Perl U32
6970 as an unsigned decimal integer.
6971 "UV"
6973 "U8"
6974 "U16"
6975 "U32"
6976 "U64"
6977 Described in perlguts.
6978 "UV_MAX"
6980 The largest unsigned integer that fits in a UV on this platform.
6981 UV UV_MAX
6983 "UV_MIN"
6985 The smallest unsigned integer that fits in a UV on this platform.
6986 It should equal zero.
6987 UV UV_MIN
6989 "UVSIZE"
6991 This symbol contains the sizeof(UV).
6992 "UVTYPE"
6994 This symbol defines the C type used for Perl's UV.
6995 "U32Xf"
6997 This symbol defines the format string used for printing a Perl U32
6998 as an unsigned hexadecimal integer in uppercase "ABCDEF".
6999 "U32xf"
7001 This symbol defines the format string used for printing a Perl U32
7002 as an unsigned hexadecimal integer in lowercase abcdef.
7003 "WIDEST_UTYPE"
7005 Yields the widest unsigned integer type on the platform, currently
7006 either "U32" or "U64". This can be used in declarations such as
7007 WIDEST_UTYPE my_uv;
7009 or casts
7011 my_uv = (WIDEST_UTYPE) val;
7013
7015 These are used for formatting the corresponding type For example,
7016 instead of saying
7017 Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\n", iv);
7019 use
7021 Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\n", iv);
7023 This keeps you from having to know if, say an IV, needs to be printed
7025 as %d, %ld, or something else.
7026 "HvNAMEf"
7028 Described in perlguts.
7029 "HvNAMEf_QUOTEDPREFIX"
7031 Described in perlguts.
7032 "IVdf"
7034 This symbol defines the format string used for printing a Perl IV
7035 as a signed decimal integer.
7036 "NVef"
7038 This symbol defines the format string used for printing a Perl NV
7039 using %e-ish floating point format.
7040 "NVff"
7042 This symbol defines the format string used for printing a Perl NV
7043 using %f-ish floating point format.
7044 "NVgf"
7046 This symbol defines the format string used for printing a Perl NV
7047 using %g-ish floating point format.
7048 "PERL_PRIeldbl"
7050 This symbol, if defined, contains the string used by stdio to
7051 format long doubles (format 'e') for output.
7052 "PERL_PRIfldbl"
7054 This symbol, if defined, contains the string used by stdio to
7055 format long doubles (format 'f') for output.
7056 "PERL_PRIgldbl"
7058 This symbol, if defined, contains the string used by stdio to
7059 format long doubles (format 'g') for output.
7060 "PERL_SCNfldbl"
7062 This symbol, if defined, contains the string used by stdio to
7063 format long doubles (format 'f') for input.
7064 "PRINTF_FORMAT_NULL_OK"
7066 Allows "__printf__" format to be null when checking printf-style
7067 "SVf"
7069 Described in perlguts.
7070 "SVfARG"
7072 Described in perlguts.
7073 SVfARG(SV *sv)
7075 "SVf_QUOTEDPREFIX"
7077 Described in perlguts.
7078 "UTF8f"
7080 Described in perlguts.
7081 "UTF8fARG"
7083 Described in perlguts.
7084 UTF8fARG(bool is_utf8, Size_t byte_len, char *str)
7086 "UTF8f_QUOTEDPREFIX"
7088 Described in perlguts.
7089 "UVf"
7091 "DEPRECATED!" It is planned to remove "UVf" from a future release
7092 of Perl. Do not use it for new code; remove it from existing code.
7093 Obsolete form of "UVuf", which you should convert to instead use
7095 const char * UVf
7097 "UVof"
7099 This symbol defines the format string used for printing a Perl UV
7100 as an unsigned octal integer.
7101 "UVuf"
7103 This symbol defines the format string used for printing a Perl UV
7104 as an unsigned decimal integer.
7105 "UVXf"
7107 This symbol defines the format string used for printing a Perl UV
7108 as an unsigned hexadecimal integer in uppercase "ABCDEF".
7109 "UVxf"
7111 This symbol defines the format string used for printing a Perl UV
7112 as an unsigned hexadecimal integer in lowercase abcdef.
7113
7115 This is the lower layer of the Perl parser, managing characters and
7116 tokens.
7117 "BHK"
7119 Described in perlguts.
7120 "lex_bufutf8"
7122 NOTE: "lex_bufutf8" is experimental and may change or be removed
7123 without notice.
7124 Indicates whether the octets in the lexer buffer
7126 ("PL_parser->linestr") should be interpreted as the UTF-8 encoding
7127 of Unicode characters. If not, they should be interpreted as
7128 Latin-1 characters. This is analogous to the "SvUTF8" flag for
7129 scalars.
7130 In UTF-8 mode, it is not guaranteed that the lexer buffer actually
7132 contains valid UTF-8. Lexing code must be robust in the face of
7133 invalid encoding.
7134 The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
7136 significant, but not the whole story regarding the input character
7137 encoding. Normally, when a file is being read, the scalar contains
7138 octets and its "SvUTF8" flag is off, but the octets should be
7139 interpreted as UTF-8 if the "use utf8" pragma is in effect. During
7140 a string eval, however, the scalar may have the "SvUTF8" flag on,
7141 and in this case its octets should be interpreted as UTF-8 unless
7142 the "use bytes" pragma is in effect. This logic may change in the
7143 future; use this function instead of implementing the logic
7144 yourself.
7145 bool lex_bufutf8()
7147 "lex_discard_to"
7149 NOTE: "lex_discard_to" is experimental and may change or be removed
7150 without notice.
7151 Discards the first part of the "PL_parser->linestr" buffer, up to
7153 "ptr". The remaining content of the buffer will be moved, and all
7154 pointers into the buffer updated appropriately. "ptr" must not be
7155 later in the buffer than the position of "PL_parser->bufptr": it is
7156 not permitted to discard text that has yet to be lexed.
7157 Normally it is not necessarily to do this directly, because it
7159 suffices to use the implicit discarding behaviour of
7160 "lex_next_chunk" and things based on it. However, if a token
7161 stretches across multiple lines, and the lexing code has kept
7162 multiple lines of text in the buffer for that purpose, then after
7163 completion of the token it would be wise to explicitly discard the
7164 now-unneeded earlier lines, to avoid future multi-line tokens
7165 growing the buffer without bound.
7166 void lex_discard_to(char *ptr)
7168 "lex_grow_linestr"
7170 NOTE: "lex_grow_linestr" is experimental and may change or be
7171 removed without notice.
7172 Reallocates the lexer buffer ("PL_parser->linestr") to accommodate
7174 at least "len" octets (including terminating "NUL"). Returns a
7175 pointer to the reallocated buffer. This is necessary before making
7176 any direct modification of the buffer that would increase its
7177 length. "lex_stuff_pvn" provides a more convenient way to insert
7178 text into the buffer.
7179 Do not use "SvGROW" or "sv_grow" directly on "PL_parser->linestr";
7181 this function updates all of the lexer's variables that point
7182 directly into the buffer.
7183 char * lex_grow_linestr(STRLEN len)
7185 "lex_next_chunk"
7187 NOTE: "lex_next_chunk" is experimental and may change or be removed
7188 without notice.
7189 Reads in the next chunk of text to be lexed, appending it to
7191 "PL_parser->linestr". This should be called when lexing code has
7192 looked to the end of the current chunk and wants to know more. It
7193 is usual, but not necessary, for lexing to have consumed the
7194 entirety of the current chunk at this time.
7195 If "PL_parser->bufptr" is pointing to the very end of the current
7197 chunk (i.e., the current chunk has been entirely consumed),
7198 normally the current chunk will be discarded at the same time that
7199 the new chunk is read in. If "flags" has the "LEX_KEEP_PREVIOUS"
7200 bit set, the current chunk will not be discarded. If the current
7201 chunk has not been entirely consumed, then it will not be discarded
7202 regardless of the flag.
7203 Returns true if some new text was added to the buffer, or false if
7205 the buffer has reached the end of the input text.
7206 bool lex_next_chunk(U32 flags)
7208 "lex_peek_unichar"
7210 NOTE: "lex_peek_unichar" is experimental and may change or be
7211 removed without notice.
7212 Looks ahead one (Unicode) character in the text currently being
7214 lexed. Returns the codepoint (unsigned integer value) of the next
7215 character, or -1 if lexing has reached the end of the input text.
7216 To consume the peeked character, use "lex_read_unichar".
7217 If the next character is in (or extends into) the next chunk of
7219 input text, the next chunk will be read in. Normally the current
7220 chunk will be discarded at the same time, but if "flags" has the
7221 "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
7222 discarded.
7223 If the input is being interpreted as UTF-8 and a UTF-8 encoding
7225 error is encountered, an exception is generated.
7226 I32 lex_peek_unichar(U32 flags)
7228 "lex_read_space"
7230 NOTE: "lex_read_space" is experimental and may change or be removed
7231 without notice.
7232 Reads optional spaces, in Perl style, in the text currently being
7234 lexed. The spaces may include ordinary whitespace characters and
7235 Perl-style comments. "#line" directives are processed if
7236 encountered. "PL_parser->bufptr" is moved past the spaces, so that
7237 it points at a non-space character (or the end of the input text).
7238 If spaces extend into the next chunk of input text, the next chunk
7240 will be read in. Normally the current chunk will be discarded at
7241 the same time, but if "flags" has the "LEX_KEEP_PREVIOUS" bit set,
7242 then the current chunk will not be discarded.
7243 void lex_read_space(U32 flags)
7245 "lex_read_to"
7247 NOTE: "lex_read_to" is experimental and may change or be removed
7248 without notice.
7249 Consume text in the lexer buffer, from "PL_parser->bufptr" up to
7251 "ptr". This advances "PL_parser->bufptr" to match "ptr",
7252 performing the correct bookkeeping whenever a newline character is
7253 passed. This is the normal way to consume lexed text.
7254 Interpretation of the buffer's octets can be abstracted out by
7256 using the slightly higher-level functions "lex_peek_unichar" and
7257 "lex_read_unichar".
7258 void lex_read_to(char *ptr)
7260 "lex_read_unichar"
7262 NOTE: "lex_read_unichar" is experimental and may change or be
7263 removed without notice.
7264 Reads the next (Unicode) character in the text currently being
7266 lexed. Returns the codepoint (unsigned integer value) of the
7267 character read, and moves "PL_parser->bufptr" past the character,
7268 or returns -1 if lexing has reached the end of the input text. To
7269 non-destructively examine the next character, use
7270 "lex_peek_unichar" instead.
7271 If the next character is in (or extends into) the next chunk of
7273 input text, the next chunk will be read in. Normally the current
7274 chunk will be discarded at the same time, but if "flags" has the
7275 "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
7276 discarded.
7277 If the input is being interpreted as UTF-8 and a UTF-8 encoding
7279 error is encountered, an exception is generated.
7280 I32 lex_read_unichar(U32 flags)
7282 "lex_start"
7284 NOTE: "lex_start" is experimental and may change or be removed
7285 without notice.
7286 Creates and initialises a new lexer/parser state object, supplying
7288 a context in which to lex and parse from a new source of Perl code.
7289 A pointer to the new state object is placed in "PL_parser". An
7290 entry is made on the save stack so that upon unwinding, the new
7291 state object will be destroyed and the former value of "PL_parser"
7292 will be restored. Nothing else need be done to clean up the
7293 parsing context.
7294 The code to be parsed comes from "line" and "rsfp". "line", if
7296 non-null, provides a string (in SV form) containing code to be
7297 parsed. A copy of the string is made, so subsequent modification
7298 of "line" does not affect parsing. "rsfp", if non-null, provides
7299 an input stream from which code will be read to be parsed. If both
7300 are non-null, the code in "line" comes first and must consist of
7301 complete lines of input, and "rsfp" supplies the remainder of the
7302 source.
7303 The "flags" parameter is reserved for future use. Currently it is
7305 only used by perl internally, so extensions should always pass
7306 zero.
7307 void lex_start(SV *line, PerlIO *rsfp, U32 flags)
7309 "lex_stuff_pv"
7311 NOTE: "lex_stuff_pv" is experimental and may change or be removed
7312 without notice.
7313 Insert characters into the lexer buffer ("PL_parser->linestr"),
7315 immediately after the current lexing point ("PL_parser->bufptr"),
7316 reallocating the buffer if necessary. This means that lexing code
7317 that runs later will see the characters as if they had appeared in
7318 the input. It is not recommended to do this as part of normal
7319 parsing, and most uses of this facility run the risk of the
7320 inserted characters being interpreted in an unintended manner.
7321 The string to be inserted is represented by octets starting at "pv"
7323 and continuing to the first nul. These octets are interpreted as
7324 either UTF-8 or Latin-1, according to whether the "LEX_STUFF_UTF8"
7325 flag is set in "flags". The characters are recoded for the lexer
7326 buffer, according to how the buffer is currently being interpreted
7327 ("lex_bufutf8"). If it is not convenient to nul-terminate a string
7328 to be inserted, the "lex_stuff_pvn" function is more appropriate.
7329 void lex_stuff_pv(const char *pv, U32 flags)
7331 "lex_stuff_pvn"
7333 NOTE: "lex_stuff_pvn" is experimental and may change or be removed
7334 without notice.
7335 Insert characters into the lexer buffer ("PL_parser->linestr"),
7337 immediately after the current lexing point ("PL_parser->bufptr"),
7338 reallocating the buffer if necessary. This means that lexing code
7339 that runs later will see the characters as if they had appeared in
7340 the input. It is not recommended to do this as part of normal
7341 parsing, and most uses of this facility run the risk of the
7342 inserted characters being interpreted in an unintended manner.
7343 The string to be inserted is represented by "len" octets starting
7345 at "pv". These octets are interpreted as either UTF-8 or Latin-1,
7346 according to whether the "LEX_STUFF_UTF8" flag is set in "flags".
7347 The characters are recoded for the lexer buffer, according to how
7348 the buffer is currently being interpreted ("lex_bufutf8"). If a
7349 string to be inserted is available as a Perl scalar, the
7350 "lex_stuff_sv" function is more convenient.
7351 void lex_stuff_pvn(const char *pv, STRLEN len, U32 flags)
7353 "lex_stuff_pvs"
7355 NOTE: "lex_stuff_pvs" is experimental and may change or be removed
7356 without notice.
7357 Like "lex_stuff_pvn", but takes a literal string instead of a
7359 string/length pair.
7360 void lex_stuff_pvs("pv", U32 flags)
7362 "lex_stuff_sv"
7364 NOTE: "lex_stuff_sv" is experimental and may change or be removed
7365 without notice.
7366 Insert characters into the lexer buffer ("PL_parser->linestr"),
7368 immediately after the current lexing point ("PL_parser->bufptr"),
7369 reallocating the buffer if necessary. This means that lexing code
7370 that runs later will see the characters as if they had appeared in
7371 the input. It is not recommended to do this as part of normal
7372 parsing, and most uses of this facility run the risk of the
7373 inserted characters being interpreted in an unintended manner.
7374 The string to be inserted is the string value of "sv". The
7376 characters are recoded for the lexer buffer, according to how the
7377 buffer is currently being interpreted ("lex_bufutf8"). If a string
7378 to be inserted is not already a Perl scalar, the "lex_stuff_pvn"
7379 function avoids the need to construct a scalar.
7380 void lex_stuff_sv(SV *sv, U32 flags)
7382 "lex_unstuff"
7384 NOTE: "lex_unstuff" is experimental and may change or be removed
7385 without notice.
7386 Discards text about to be lexed, from "PL_parser->bufptr" up to
7388 "ptr". Text following "ptr" will be moved, and the buffer
7389 shortened. This hides the discarded text from any lexing code that
7390 runs later, as if the text had never appeared.
7391 This is not the normal way to consume lexed text. For that, use
7393 "lex_read_to".
7394 void lex_unstuff(char *ptr)
7396 "parse_arithexpr"
7398 NOTE: "parse_arithexpr" is experimental and may change or be
7399 removed without notice.
7400 Parse a Perl arithmetic expression. This may contain operators of
7402 precedence down to the bit shift operators. The expression must be
7403 followed (and thus terminated) either by a comparison or lower-
7404 precedence operator or by something that would normally terminate
7405 an expression such as semicolon. If "flags" has the
7406 "PARSE_OPTIONAL" bit set, then the expression is optional,
7407 otherwise it is mandatory. It is up to the caller to ensure that
7408 the dynamic parser state ("PL_parser" et al) is correctly set to
7409 reflect the source of the code to be parsed and the lexical context
7410 for the expression.
7411 The op tree representing the expression is returned. If an
7413 optional expression is absent, a null pointer is returned,
7414 otherwise the pointer will be non-null.
7415 If an error occurs in parsing or compilation, in most cases a valid
7417 op tree is returned anyway. The error is reflected in the parser
7418 state, normally resulting in a single exception at the top level of
7419 parsing which covers all the compilation errors that occurred.
7420 Some compilation errors, however, will throw an exception
7421 immediately.
7422 OP * parse_arithexpr(U32 flags)
7424 "parse_barestmt"
7426 NOTE: "parse_barestmt" is experimental and may change or be removed
7427 without notice.
7428 Parse a single unadorned Perl statement. This may be a normal
7430 imperative statement or a declaration that has compile-time effect.
7431 It does not include any label or other affixture. It is up to the
7432 caller to ensure that the dynamic parser state ("PL_parser" et al)
7433 is correctly set to reflect the source of the code to be parsed and
7434 the lexical context for the statement.
7435 The op tree representing the statement is returned. This may be a
7437 null pointer if the statement is null, for example if it was
7438 actually a subroutine definition (which has compile-time side
7439 effects). If not null, it will be ops directly implementing the
7440 statement, suitable to pass to "newSTATEOP". It will not normally
7441 include a "nextstate" or equivalent op (except for those embedded
7442 in a scope contained entirely within the statement).
7443 If an error occurs in parsing or compilation, in most cases a valid
7445 op tree (most likely null) is returned anyway. The error is
7446 reflected in the parser state, normally resulting in a single
7447 exception at the top level of parsing which covers all the
7448 compilation errors that occurred. Some compilation errors,
7449 however, will throw an exception immediately.
7450 The "flags" parameter is reserved for future use, and must always
7452 be zero.
7453 OP * parse_barestmt(U32 flags)
7455 "parse_block"
7457 NOTE: "parse_block" is experimental and may change or be removed
7458 without notice.
7459 Parse a single complete Perl code block. This consists of an
7461 opening brace, a sequence of statements, and a closing brace. The
7462 block constitutes a lexical scope, so "my" variables and various
7463 compile-time effects can be contained within it. It is up to the
7464 caller to ensure that the dynamic parser state ("PL_parser" et al)
7465 is correctly set to reflect the source of the code to be parsed and
7466 the lexical context for the statement.
7467 The op tree representing the code block is returned. This is
7469 always a real op, never a null pointer. It will normally be a
7470 "lineseq" list, including "nextstate" or equivalent ops. No ops to
7471 construct any kind of runtime scope are included by virtue of it
7472 being a block.
7473 If an error occurs in parsing or compilation, in most cases a valid
7475 op tree (most likely null) is returned anyway. The error is
7476 reflected in the parser state, normally resulting in a single
7477 exception at the top level of parsing which covers all the
7478 compilation errors that occurred. Some compilation errors,
7479 however, will throw an exception immediately.
7480 The "flags" parameter is reserved for future use, and must always
7482 be zero.
7483 OP * parse_block(U32 flags)
7485 "parse_fullexpr"
7487 NOTE: "parse_fullexpr" is experimental and may change or be removed
7488 without notice.
7489 Parse a single complete Perl expression. This allows the full
7491 expression grammar, including the lowest-precedence operators such
7492 as "or". The expression must be followed (and thus terminated) by
7493 a token that an expression would normally be terminated by: end-of-
7494 file, closing bracketing punctuation, semicolon, or one of the
7495 keywords that signals a postfix expression-statement modifier. If
7496 "flags" has the "PARSE_OPTIONAL" bit set, then the expression is
7497 optional, otherwise it is mandatory. It is up to the caller to
7498 ensure that the dynamic parser state ("PL_parser" et al) is
7499 correctly set to reflect the source of the code to be parsed and
7500 the lexical context for the expression.
7501 The op tree representing the expression is returned. If an
7503 optional expression is absent, a null pointer is returned,
7504 otherwise the pointer will be non-null.
7505 If an error occurs in parsing or compilation, in most cases a valid
7507 op tree is returned anyway. The error is reflected in the parser
7508 state, normally resulting in a single exception at the top level of
7509 parsing which covers all the compilation errors that occurred.
7510 Some compilation errors, however, will throw an exception
7511 immediately.
7512 OP * parse_fullexpr(U32 flags)
7514 "parse_fullstmt"
7516 NOTE: "parse_fullstmt" is experimental and may change or be removed
7517 without notice.
7518 Parse a single complete Perl statement. This may be a normal
7520 imperative statement or a declaration that has compile-time effect,
7521 and may include optional labels. It is up to the caller to ensure
7522 that the dynamic parser state ("PL_parser" et al) is correctly set
7523 to reflect the source of the code to be parsed and the lexical
7524 context for the statement.
7525 The op tree representing the statement is returned. This may be a
7527 null pointer if the statement is null, for example if it was
7528 actually a subroutine definition (which has compile-time side
7529 effects). If not null, it will be the result of a "newSTATEOP"
7530 call, normally including a "nextstate" or equivalent op.
7531 If an error occurs in parsing or compilation, in most cases a valid
7533 op tree (most likely null) is returned anyway. The error is
7534 reflected in the parser state, normally resulting in a single
7535 exception at the top level of parsing which covers all the
7536 compilation errors that occurred. Some compilation errors,
7537 however, will throw an exception immediately.
7538 The "flags" parameter is reserved for future use, and must always
7540 be zero.
7541 OP * parse_fullstmt(U32 flags)
7543 "parse_label"
7545 NOTE: "parse_label" is experimental and may change or be removed
7546 without notice.
7547 Parse a single label, possibly optional, of the type that may
7549 prefix a Perl statement. It is up to the caller to ensure that the
7550 dynamic parser state ("PL_parser" et al) is correctly set to
7551 reflect the source of the code to be parsed. If "flags" has the
7552 "PARSE_OPTIONAL" bit set, then the label is optional, otherwise it
7553 is mandatory.
7554 The name of the label is returned in the form of a fresh scalar.
7556 If an optional label is absent, a null pointer is returned.
7557 If an error occurs in parsing, which can only occur if the label is
7559 mandatory, a valid label is returned anyway. The error is
7560 reflected in the parser state, normally resulting in a single
7561 exception at the top level of parsing which covers all the
7562 compilation errors that occurred.
7563 SV * parse_label(U32 flags)
7565 "parse_listexpr"
7567 NOTE: "parse_listexpr" is experimental and may change or be removed
7568 without notice.
7569 Parse a Perl list expression. This may contain operators of
7571 precedence down to the comma operator. The expression must be
7572 followed (and thus terminated) either by a low-precedence logic
7573 operator such as "or" or by something that would normally terminate
7574 an expression such as semicolon. If "flags" has the
7575 "PARSE_OPTIONAL" bit set, then the expression is optional,
7576 otherwise it is mandatory. It is up to the caller to ensure that
7577 the dynamic parser state ("PL_parser" et al) is correctly set to
7578 reflect the source of the code to be parsed and the lexical context
7579 for the expression.
7580 The op tree representing the expression is returned. If an
7582 optional expression is absent, a null pointer is returned,
7583 otherwise the pointer will be non-null.
7584 If an error occurs in parsing or compilation, in most cases a valid
7586 op tree is returned anyway. The error is reflected in the parser
7587 state, normally resulting in a single exception at the top level of
7588 parsing which covers all the compilation errors that occurred.
7589 Some compilation errors, however, will throw an exception
7590 immediately.
7591 OP * parse_listexpr(U32 flags)
7593 "parse_stmtseq"
7595 NOTE: "parse_stmtseq" is experimental and may change or be removed
7596 without notice.
7597 Parse a sequence of zero or more Perl statements. These may be
7599 normal imperative statements, including optional labels, or
7600 declarations that have compile-time effect, or any mixture thereof.
7601 The statement sequence ends when a closing brace or end-of-file is
7602 encountered in a place where a new statement could have validly
7603 started. It is up to the caller to ensure that the dynamic parser
7604 state ("PL_parser" et al) is correctly set to reflect the source of
7605 the code to be parsed and the lexical context for the statements.
7606 The op tree representing the statement sequence is returned. This
7608 may be a null pointer if the statements were all null, for example
7609 if there were no statements or if there were only subroutine
7610 definitions (which have compile-time side effects). If not null,
7611 it will be a "lineseq" list, normally including "nextstate" or
7612 equivalent ops.
7613 If an error occurs in parsing or compilation, in most cases a valid
7615 op tree is returned anyway. The error is reflected in the parser
7616 state, normally resulting in a single exception at the top level of
7617 parsing which covers all the compilation errors that occurred.
7618 Some compilation errors, however, will throw an exception
7619 immediately.
7620 The "flags" parameter is reserved for future use, and must always
7622 be zero.
7623 OP * parse_stmtseq(U32 flags)
7625 "parse_subsignature"
7627 NOTE: "parse_subsignature" is experimental and may change or be
7628 removed without notice.
7629 Parse a subroutine signature declaration. This is the contents of
7631 the parentheses following a named or anonymous subroutine
7632 declaration when the "signatures" feature is enabled. Note that
7633 this function neither expects nor consumes the opening and closing
7634 parentheses around the signature; it is the caller's job to handle
7635 these.
7636 This function must only be called during parsing of a subroutine;
7638 after "start_subparse" has been called. It might allocate lexical
7639 variables on the pad for the current subroutine.
7640 The op tree to unpack the arguments from the stack at runtime is
7642 returned. This op tree should appear at the beginning of the
7643 compiled function. The caller may wish to use "op_append_list" to
7644 build their function body after it, or splice it together with the
7645 body before calling "newATTRSUB".
7646 The "flags" parameter is reserved for future use, and must always
7648 be zero.
7649 OP * parse_subsignature(U32 flags)
7651 "parse_termexpr"
7653 NOTE: "parse_termexpr" is experimental and may change or be removed
7654 without notice.
7655 Parse a Perl term expression. This may contain operators of
7657 precedence down to the assignment operators. The expression must
7658 be followed (and thus terminated) either by a comma or lower-
7659 precedence operator or by something that would normally terminate
7660 an expression such as semicolon. If "flags" has the
7661 "PARSE_OPTIONAL" bit set, then the expression is optional,
7662 otherwise it is mandatory. It is up to the caller to ensure that
7663 the dynamic parser state ("PL_parser" et al) is correctly set to
7664 reflect the source of the code to be parsed and the lexical context
7665 for the expression.
7666 The op tree representing the expression is returned. If an
7668 optional expression is absent, a null pointer is returned,
7669 otherwise the pointer will be non-null.
7670 If an error occurs in parsing or compilation, in most cases a valid
7672 op tree is returned anyway. The error is reflected in the parser
7673 state, normally resulting in a single exception at the top level of
7674 parsing which covers all the compilation errors that occurred.
7675 Some compilation errors, however, will throw an exception
7676 immediately.
7677 OP * parse_termexpr(U32 flags)
7679 "PL_parser"
7681 Pointer to a structure encapsulating the state of the parsing
7682 operation currently in progress. The pointer can be locally
7683 changed to perform a nested parse without interfering with the
7684 state of an outer parse. Individual members of "PL_parser" have
7685 their own documentation.
7686 "PL_parser->bufend"
7688 NOTE: "PL_parser->bufend" is experimental and may change or be
7689 removed without notice.
7690 Direct pointer to the end of the chunk of text currently being
7692 lexed, the end of the lexer buffer. This is equal to
7693 "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)". A "NUL"
7694 character (zero octet) is always located at the end of the buffer,
7695 and does not count as part of the buffer's contents.
7696 "PL_parser->bufptr"
7698 NOTE: "PL_parser->bufptr" is experimental and may change or be
7699 removed without notice.
7700 Points to the current position of lexing inside the lexer buffer.
7702 Characters around this point may be freely examined, within the
7703 range delimited by SvPVX("PL_parser->linestr") and
7704 "PL_parser->bufend". The octets of the buffer may be intended to
7705 be interpreted as either UTF-8 or Latin-1, as indicated by
7706 "lex_bufutf8".
7707 Lexing code (whether in the Perl core or not) moves this pointer
7709 past the characters that it consumes. It is also expected to
7710 perform some bookkeeping whenever a newline character is consumed.
7711 This movement can be more conveniently performed by the function
7712 "lex_read_to", which handles newlines appropriately.
7713 Interpretation of the buffer's octets can be abstracted out by
7715 using the slightly higher-level functions "lex_peek_unichar" and
7716 "lex_read_unichar".
7717 "PL_parser->linestart"
7719 NOTE: "PL_parser->linestart" is experimental and may change or be
7720 removed without notice.
7721 Points to the start of the current line inside the lexer buffer.
7723 This is useful for indicating at which column an error occurred,
7724 and not much else. This must be updated by any lexing code that
7725 consumes a newline; the function "lex_read_to" handles this detail.
7726 "PL_parser->linestr"
7728 NOTE: "PL_parser->linestr" is experimental and may change or be
7729 removed without notice.
7730 Buffer scalar containing the chunk currently under consideration of
7732 the text currently being lexed. This is always a plain string
7733 scalar (for which "SvPOK" is true). It is not intended to be used
7734 as a scalar by normal scalar means; instead refer to the buffer
7735 directly by the pointer variables described below.
7736 The lexer maintains various "char*" pointers to things in the
7738 "PL_parser->linestr" buffer. If "PL_parser->linestr" is ever
7739 reallocated, all of these pointers must be updated. Don't attempt
7740 to do this manually, but rather use "lex_grow_linestr" if you need
7741 to reallocate the buffer.
7742 The content of the text chunk in the buffer is commonly exactly one
7744 complete line of input, up to and including a newline terminator,
7745 but there are situations where it is otherwise. The octets of the
7746 buffer may be intended to be interpreted as either UTF-8 or
7747 Latin-1. The function "lex_bufutf8" tells you which. Do not use
7748 the "SvUTF8" flag on this scalar, which may disagree with it.
7749 For direct examination of the buffer, the variable
7751 "PL_parser->bufend" points to the end of the buffer. The current
7752 lexing position is pointed to by "PL_parser->bufptr". Direct use
7753 of these pointers is usually preferable to examination of the
7754 scalar through normal scalar means.
7755 "suspend_compcv"
7757 Implements part of the concept of a "suspended compilation CV",
7758 which can be used to pause the parser and compiler during parsing a
7759 CV in order to come back to it later on.
7760 This function saves the current state of the subroutine under
7762 compilation ("PL_compcv") into the supplied buffer. This should be
7763 used initially to create the state in the buffer, as the final
7764 thing before a "LEAVE" within a block.
7765 ENTER;
7767 start_subparse(0);
7768 ...
7769 suspend_compcv(&buffer);
7771 LEAVE;
7772 Once suspended, the "resume_compcv" or "resume_compcv_and_save"
7774 function can later be used to continue the parsing from the point
7775 this stopped.
7776 void suspend_compcv(struct suspended_compcv *buffer)
7778 "wrap_infix_plugin"
7780 NOTE: "wrap_infix_plugin" is experimental and may change or be
7781 removed without notice.
7782 NOTE: This API exists entirely for the purpose of making the CPAN
7784 module "XS::Parse::Infix" work. It is not expected that additional
7785 modules will make use of it; rather, that they should use
7786 "XS::Parse::Infix" to provide parsing of new infix operators.
7787 Puts a C function into the chain of infix plugins. This is the
7789 preferred way to manipulate the "PL_infix_plugin" variable.
7790 "new_plugin" is a pointer to the C function that is to be added to
7791 the infix plugin chain, and "old_plugin_p" points to a storage
7792 location where a pointer to the next function in the chain will be
7793 stored. The value of "new_plugin" is written into the
7794 "PL_infix_plugin" variable, while the value previously stored there
7795 is written to *old_plugin_p.
7796 Direct access to "PL_infix_plugin" should be avoided.
7798 void wrap_infix_plugin(Perl_infix_plugin_t new_plugin,
7800 Perl_infix_plugin_t *old_plugin_p)
7801 "wrap_keyword_plugin"
7803 NOTE: "wrap_keyword_plugin" is experimental and may change or be
7804 removed without notice.
7805 Puts a C function into the chain of keyword plugins. This is the
7807 preferred way to manipulate the "PL_keyword_plugin" variable.
7808 "new_plugin" is a pointer to the C function that is to be added to
7809 the keyword plugin chain, and "old_plugin_p" points to the storage
7810 location where a pointer to the next function in the chain will be
7811 stored. The value of "new_plugin" is written into the
7812 "PL_keyword_plugin" variable, while the value previously stored
7813 there is written to *old_plugin_p.
7814 "PL_keyword_plugin" is global to an entire process, and a module
7816 wishing to hook keyword parsing may find itself invoked more than
7817 once per process, typically in different threads. To handle that
7818 situation, this function is idempotent. The location *old_plugin_p
7819 must initially (once per process) contain a null pointer. A C
7820 variable of static duration (declared at file scope, typically also
7821 marked "static" to give it internal linkage) will be implicitly
7822 initialised appropriately, if it does not have an explicit
7823 initialiser. This function will only actually modify the plugin
7824 chain if it finds *old_plugin_p to be null. This function is also
7825 thread safe on the small scale. It uses appropriate locking to
7826 avoid race conditions in accessing "PL_keyword_plugin".
7827 When this function is called, the function referenced by
7829 "new_plugin" must be ready to be called, except for *old_plugin_p
7830 being unfilled. In a threading situation, "new_plugin" may be
7831 called immediately, even before this function has returned.
7832 *old_plugin_p will always be appropriately set before "new_plugin"
7833 is called. If "new_plugin" decides not to do anything special with
7834 the identifier that it is given (which is the usual case for most
7835 calls to a keyword plugin), it must chain the plugin function
7836 referenced by *old_plugin_p.
7837 Taken all together, XS code to install a keyword plugin should
7839 typically look something like this:
7840 static Perl_keyword_plugin_t next_keyword_plugin;
7842 static OP *my_keyword_plugin(pTHX_
7843 char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
7844 {
7845 if (memEQs(keyword_ptr, keyword_len,
7846 "my_new_keyword")) {
7847 ...
7848 } else {
7849 return next_keyword_plugin(aTHX_
7850 keyword_ptr, keyword_len, op_ptr);
7851 }
7852 }
7853 BOOT:
7854 wrap_keyword_plugin(my_keyword_plugin,
7855 &next_keyword_plugin);
7856 Direct access to "PL_keyword_plugin" should be avoided.
7858 void wrap_keyword_plugin(Perl_keyword_plugin_t new_plugin,
7860 Perl_keyword_plugin_t *old_plugin_p)
7861
7863 "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
7864 This macro should be used as a statement. It declares a private
7865 variable (whose name begins with an underscore) that is needed by
7866 the other macros in this section. Failing to include this
7867 correctly should lead to a syntax error. For compatibility with
7868 C89 C compilers it should be placed in a block before any
7869 executable statements.
7870 void DECLARATION_FOR_LC_NUMERIC_MANIPULATION
7872 "foldEQ_locale"
7874 Returns true if the leading "len" bytes of the strings "s1" and
7875 "s2" are the same case-insensitively in the current locale; false
7876 otherwise.
7877 I32 foldEQ_locale(const char *a, const char *b, I32 len)
7879 "HAS_DUPLOCALE"
7881 This symbol, if defined, indicates that the "duplocale" routine is
7882 available to duplicate a locale object.
7883 "HAS_FREELOCALE"
7885 This symbol, if defined, indicates that the "freelocale" routine is
7886 available to deallocates the resources associated with a locale
7887 object.
7888 "HAS_LC_MONETARY_2008"
7890 This symbol, if defined, indicates that the localeconv routine is
7891 available and has the additional members added in "POSIX"
7892 1003.1-2008.
7893 "HAS_LOCALECONV"
7895 This symbol, if defined, indicates that the "localeconv" routine is
7896 available for numeric and monetary formatting conventions.
7897 "HAS_LOCALECONV_L"
7899 This symbol, if defined, indicates that the "localeconv_l" routine
7900 is available to query certain information about a locale.
7901 "HAS_NEWLOCALE"
7903 This symbol, if defined, indicates that the "newlocale" routine is
7904 available to return a new locale object or modify an existing
7905 locale object.
7906 "HAS_NL_LANGINFO"
7908 This symbol, if defined, indicates that the "nl_langinfo" routine
7909 is available to return local data. You will also need langinfo.h
7910 and therefore "I_LANGINFO".
7911 "HAS_NL_LANGINFO_L"
7913 This symbol, when defined, indicates presence of the
7914 nl_langinfo_l() function
7915 "HAS_QUERYLOCALE"
7917 This symbol, if defined, indicates that the "querylocale" routine
7918 is available to return the name of the locale for a category mask.
7919 "HAS_SETLOCALE"
7921 This symbol, if defined, indicates that the "setlocale" routine is
7922 available to handle locale-specific ctype implementations.
7923 "HAS_SETLOCALE_R"
7925 This symbol, if defined, indicates that the "setlocale_r" routine
7926 is available to setlocale re-entrantly.
7927 "HAS_THREAD_SAFE_NL_LANGINFO_L"
7929 This symbol, when defined, indicates presence of the
7930 nl_langinfo_l() function, and that it is thread-safe.
7931 "HAS_USELOCALE"
7933 This symbol, if defined, indicates that the "uselocale" routine is
7934 available to set the current locale for the calling thread.
7935 "I_LANGINFO"
7937 This symbol, if defined, indicates that langinfo.h exists and
7938 should be included.
7939 #ifdef I_LANGINFO
7941 #include <langinfo.h>
7942 #endif
7943 "I_LOCALE"
7945 This symbol, if defined, indicates to the C program that it should
7946 include locale.h.
7947 #ifdef I_LOCALE
7949 #include <locale.h>
7950 #endif
7951 "IN_LOCALE"
7953 Evaluates to TRUE if the plain locale pragma without a parameter
7954 ("use locale") is in effect.
7955 bool IN_LOCALE
7957 "IN_LOCALE_COMPILETIME"
7959 Evaluates to TRUE if, when compiling a perl program (including an
7960 "eval") if the plain locale pragma without a parameter
7961 ("use locale") is in effect.
7962 bool IN_LOCALE_COMPILETIME
7964 "IN_LOCALE_RUNTIME"
7966 Evaluates to TRUE if, when executing a perl program (including an
7967 "eval") if the plain locale pragma without a parameter
7968 ("use locale") is in effect.
7969 bool IN_LOCALE_RUNTIME
7971 "I_XLOCALE"
7973 This symbol, if defined, indicates to the C program that the header
7974 xlocale.h is available. See also "NEED_XLOCALE_H"
7975 #ifdef I_XLOCALE
7977 #include <xlocale.h>
7978 #endif
7979 "NEED_XLOCALE_H"
7981 This symbol, if defined, indicates that the C program should
7982 include xlocale.h to get newlocale() and its friends.
7983 "Perl_langinfo"
7985 "Perl_langinfo8"
7986 "Perl_langinfo" is an (almost) drop-in replacement for the system
7987 nl_langinfo(3), taking the same "item" parameter values, and
7988 returning the same information. But it is more thread-safe than
7989 regular nl_langinfo(), and hides the quirks of Perl's locale
7990 handling from your code, and can be used on systems that lack a
7991 native "nl_langinfo".
7992 However, you should instead use the improved version of this:
7994 "Perl_langinfo8", which behaves identically except for an
7995 additional parameter, a pointer to a variable declared as
7996 ""utf8ness_t"", into which it returns to you how you should treat
7997 the returned string with regards to it being encoded in UTF-8 or
7998 not.
7999 Concerning the differences between these and plain nl_langinfo():
8001 a. "Perl_langinfo8" has an extra parameter, described above.
8003 Besides this, the other reason they aren't quite a drop-in
8004 replacement is actually an advantage. The "const"ness of the
8005 return allows the compiler to catch attempts to write into the
8006 returned buffer, which is illegal and could cause run-time
8007 crashes.
8008 b. They deliver the correct results for the "RADIXCHAR" and
8010 "THOUSEP" items, without you having to write extra code. The
8011 reason for the extra code would be because these are from the
8012 "LC_NUMERIC" locale category, which is normally kept set by
8013 Perl so that the radix is a dot, and the separator is the empty
8014 string, no matter what the underlying locale is supposed to be,
8015 and so to get the expected results, you have to temporarily
8016 toggle into the underlying locale, and later toggle back. (You
8017 could use plain "nl_langinfo" and
8018 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" for this but then you
8019 wouldn't get the other advantages of Perl_langinfo(); not
8020 keeping "LC_NUMERIC" in the C (or equivalent) locale would
8021 break a lot of CPAN, which is expecting the radix (decimal
8022 point) character to be a dot.)
8023 c. The system function they replace can have its static return
8025 buffer trashed, not only by a subsequent call to that function,
8026 but by a "freelocale", "setlocale", or other locale change.
8027 The returned buffer of these functions is not changed until the
8028 next call to one or the other, so the buffer is never in a
8029 trashed state.
8030 d. The return buffer is per-thread, so it also is never
8032 overwritten by a call to these functions from another thread;
8033 unlike the function it replaces.
8034 e. But most importantly, they work on systems that don't have
8036 "nl_langinfo", such as Windows, hence making your code more
8037 portable. Of the fifty-some possible items specified by the
8038 POSIX 2008 standard,
8039 <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
8040 only one is completely unimplemented, though on non-Windows
8041 platforms, another significant one is not fully implemented).
8042 They use various techniques to recover the other items,
8043 including calling localeconv(3), and strftime(3), both of which
8044 are specified in C89, so should be always be available. Later
8045 strftime() versions have additional capabilities; What the C
8046 locale yields or "" is returned for any item not available on
8047 your system.
8048 It is important to note that, when called with an item that is
8050 recovered by using "localeconv", the buffer from any previous
8051 explicit call to localeconv(3) will be overwritten. But you
8052 shouldn't be using "localeconv" anyway because it is is very
8053 much not thread-safe, and suffers from the same problems
8054 outlined in item 'b.' above for the fields it returns that are
8055 controlled by the LC_NUMERIC locale category. Instead, avoid
8056 all of those problems by calling "Perl_localeconv", which is
8057 thread-safe; or by using the methods given in perlcall to call
8058 POSIX::localeconv(), which is also thread-safe.
8059 The details for those items which may deviate from what this
8061 emulation returns and what a native nl_langinfo() would return are
8062 specified in I18N::Langinfo.
8063 When using "Perl_langinfo8" (or plain "Perl_langinfo") on systems
8065 that don't have a native nl_langinfo(), you must
8066 #include "perl_langinfo.h"
8068 before the "perl.h" "#include". You can replace your langinfo.h
8070 "#include" with this one. (Doing it this way keeps out the symbols
8071 that plain langinfo.h would try to import into the namespace for
8072 code that doesn't need it.)
8073 const char * Perl_langinfo (const int item)
8075 const char * Perl_langinfo8(const int item, utf8ness_t *utf8ness)
8076 "Perl_localeconv"
8078 This is a thread-safe version of the libc localeconv(3). It is the
8079 same as POSIX::localeconv (returning a hash of the localeconv()
8080 fields), but directly callable from XS code.
8081 HV * Perl_localeconv(pTHX)
8083 "Perl_setlocale"
8085 This is an (almost) drop-in replacement for the system
8086 setlocale(3), taking the same parameters, and returning the same
8087 information, except that it returns the correct underlying
8088 "LC_NUMERIC" locale. Regular "setlocale" will instead return "C"
8089 if the underlying locale has a non-dot decimal point character, or
8090 a non-empty thousands separator for displaying floating point
8091 numbers. This is because perl keeps that locale category such that
8092 it has a dot and empty separator, changing the locale briefly
8093 during the operations where the underlying one is required.
8094 "Perl_setlocale" knows about this, and compensates; regular
8095 "setlocale" doesn't.
8096 Another reason it isn't completely a drop-in replacement is that it
8098 is declared to return "const char *", whereas the system setlocale
8099 omits the "const" (presumably because its API was specified long
8100 ago, and can't be updated; it is illegal to change the information
8101 "setlocale" returns; doing so leads to segfaults.)
8102 Finally, "Perl_setlocale" works under all circumstances, whereas
8104 plain "setlocale" can be completely ineffective on some platforms
8105 under some configurations.
8106 Changing the locale is not a good idea when more than one thread is
8108 running, except on systems where the predefined variable
8109 "${^SAFE_LOCALES}" is 1. This is because on such systems the
8110 locale is global to the whole process and not local to just the
8111 thread calling the function. So changing it in one thread
8112 instantaneously changes it in all. On some such systems, the
8113 system setlocale() is ineffective, returning the wrong information,
8114 and failing to actually change the locale. z/OS refuses to try to
8115 change the locale once a second thread is created.
8116 "Perl_setlocale", should give you accurate results of what actually
8117 happened on these problematic platforms, returning NULL if the
8118 system forbade the locale change.
8119 The return points to a per-thread static buffer, which is
8121 overwritten the next time "Perl_setlocale" is called from the same
8122 thread.
8123 const char * Perl_setlocale(const int category,
8125 const char *locale)
8126 "RESTORE_LC_NUMERIC"
8128 This is used in conjunction with one of the macros
8129 "STORE_LC_NUMERIC_SET_TO_NEEDED" and
8130 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
8131 "LC_NUMERIC" state.
8132 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
8134 made to declare at compile time a private variable used by this
8135 macro and the two "STORE" ones. This macro should be called as a
8136 single statement, not an expression, but with an empty argument
8137 list, like this:
8138 {
8140 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
8141 ...
8142 RESTORE_LC_NUMERIC();
8143 ...
8144 }
8145 void RESTORE_LC_NUMERIC()
8147 "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
8149 This symbol, if defined, indicates that the setlocale routine is
8150 available and it accepts any input locale name as valid.
8151 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
8153 This is used by XS code that is "LC_NUMERIC" locale-aware to force
8154 the locale for category "LC_NUMERIC" to be what perl thinks is the
8155 current underlying locale. (The perl interpreter could be wrong
8156 about what the underlying locale actually is if some C or XS code
8157 has called the C library function setlocale(3) behind its back;
8158 calling "sync_locale" before calling this macro will update perl's
8159 records.)
8160 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
8162 made to declare at compile time a private variable used by this
8163 macro. This macro should be called as a single statement, not an
8164 expression, but with an empty argument list, like this:
8165 {
8167 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
8168 ...
8169 STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
8170 ...
8171 RESTORE_LC_NUMERIC();
8172 ...
8173 }
8174 The private variable is used to save the current locale state, so
8176 that the requisite matching call to "RESTORE_LC_NUMERIC" can
8177 restore it.
8178 On threaded perls not operating with thread-safe functionality,
8180 this macro uses a mutex to force a critical section. Therefore the
8181 matching RESTORE should be close by, and guaranteed to be called.
8182 void STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
8184 "STORE_LC_NUMERIC_SET_TO_NEEDED"
8186 This is used to help wrap XS or C code that is "LC_NUMERIC" locale-
8187 aware. This locale category is generally kept set to a locale
8188 where the decimal radix character is a dot, and the separator
8189 between groups of digits is empty. This is because most XS code
8190 that reads floating point numbers is expecting them to have this
8191 syntax.
8192 This macro makes sure the current "LC_NUMERIC" state is set
8194 properly, to be aware of locale if the call to the XS or C code
8195 from the Perl program is from within the scope of a "use locale";
8196 or to ignore locale if the call is instead from outside such scope.
8197 This macro is the start of wrapping the C or XS code; the wrap
8199 ending is done by calling the "RESTORE_LC_NUMERIC" macro after the
8200 operation. Otherwise the state can be changed that will adversely
8201 affect other XS code.
8202 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been
8204 made to declare at compile time a private variable used by this
8205 macro. This macro should be called as a single statement, not an
8206 expression, but with an empty argument list, like this:
8207 {
8209 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
8210 ...
8211 STORE_LC_NUMERIC_SET_TO_NEEDED();
8212 ...
8213 RESTORE_LC_NUMERIC();
8214 ...
8215 }
8216 On threaded perls not operating with thread-safe functionality,
8218 this macro uses a mutex to force a critical section. Therefore the
8219 matching RESTORE should be close by, and guaranteed to be called;
8220 see "WITH_LC_NUMERIC_SET_TO_NEEDED" for a more contained way to
8221 ensure that.
8222 void STORE_LC_NUMERIC_SET_TO_NEEDED()
8224 "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
8226 Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
8227 provided as the precalculated value of IN_LC(LC_NUMERIC). It is the
8228 caller's responsibility to ensure that the status of "PL_compiling"
8229 and "PL_hints" cannot have changed since the precalculation.
8230 void STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric)
8232 "WITH_LC_NUMERIC_SET_TO_NEEDED"
8234 This macro invokes the supplied statement or block within the
8235 context of a "STORE_LC_NUMERIC_SET_TO_NEEDED" ..
8236 "RESTORE_LC_NUMERIC" pair if required, so eg:
8237 WITH_LC_NUMERIC_SET_TO_NEEDED(
8239 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
8240 );
8241 is equivalent to:
8243 {
8245 #ifdef USE_LOCALE_NUMERIC
8246 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
8247 STORE_LC_NUMERIC_SET_TO_NEEDED();
8248 #endif
8249 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
8250 #ifdef USE_LOCALE_NUMERIC
8251 RESTORE_LC_NUMERIC();
8252 #endif
8253 }
8254 void WITH_LC_NUMERIC_SET_TO_NEEDED(block)
8256 "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
8258 Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
8259 as the precalculated value of IN_LC(LC_NUMERIC). It is the caller's
8260 responsibility to ensure that the status of "PL_compiling" and
8261 "PL_hints" cannot have changed since the precalculation.
8262 void WITH_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric, block)
8264
8266 "Magic" is special data attached to SV structures in order to give them
8267 "magical" properties. When any Perl code tries to read from, or assign
8268 to, an SV marked as magical, it calls the 'get' or 'set' function
8269 associated with that SV's magic. A get is called prior to reading an
8270 SV, in order to give it a chance to update its internal value (get on
8271 $. writes the line number of the last read filehandle into the SV's IV
8272 slot), while set is called after an SV has been written to, in order to
8273 allow it to make use of its changed value (set on $/ copies the SV's
8274 new value to the PL_rs global variable).
8275 Magic is implemented as a linked list of MAGIC structures attached to
8277 the SV. Each MAGIC struct holds the type of the magic, a pointer to an
8278 array of functions that implement the get(), set(), length() etc
8279 functions, plus space for some flags and pointers. For example, a tied
8280 variable has a MAGIC structure that contains a pointer to the object
8281 associated with the tie.
8282 "mg_clear"
8284 Clear something magical that the SV represents. See "sv_magic".
8285 int mg_clear(SV *sv)
8287 "mg_copy"
8289 Copies the magic from one SV to another. See "sv_magic".
8290 int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
8292 "MGf_COPY"
8294 "MGf_DUP"
8295 "MGf_LOCAL"
8296 Described in perlguts.
8297 "mg_find"
8299 Finds the magic pointer for "type" matching the SV. See
8300 "sv_magic".
8301 MAGIC * mg_find(const SV *sv, int type)
8303 "mg_findext"
8305 Finds the magic pointer of "type" with the given "vtbl" for the
8306 "SV". See "sv_magicext".
8307 MAGIC * mg_findext(const SV *sv, int type, const MGVTBL *vtbl)
8309 "mg_free"
8311 Free any magic storage used by the SV. See "sv_magic".
8312 int mg_free(SV *sv)
8314 "mg_freeext"
8316 Remove any magic of type "how" using virtual table "vtbl" from the
8317 SV "sv". See "sv_magic".
8318 "mg_freeext(sv, how, NULL)" is equivalent to "mg_free_type(sv,
8320 how)".
8321 void mg_freeext(SV *sv, int how, const MGVTBL *vtbl)
8323 "mg_free_type"
8325 Remove any magic of type "how" from the SV "sv". See "sv_magic".
8326 void mg_free_type(SV *sv, int how)
8328 "mg_get"
8330 Do magic before a value is retrieved from the SV. The type of SV
8331 must be >= "SVt_PVMG". See "sv_magic".
8332 int mg_get(SV *sv)
8334 "mg_magical"
8336 Turns on the magical status of an SV. See "sv_magic".
8337 void mg_magical(SV *sv)
8339 "mg_set"
8341 Do magic after a value is assigned to the SV. See "sv_magic".
8342 int mg_set(SV *sv)
8344 "MGVTBL"
8346 Described in perlguts.
8347 "PERL_MAGIC_arylen"
8349 "PERL_MAGIC_arylen_p"
8350 "PERL_MAGIC_backref"
8351 "PERL_MAGIC_bm"
8352 "PERL_MAGIC_checkcall"
8353 "PERL_MAGIC_collxfrm"
8354 "PERL_MAGIC_dbfile"
8355 "PERL_MAGIC_dbline"
8356 "PERL_MAGIC_debugvar"
8357 "PERL_MAGIC_defelem"
8358 "PERL_MAGIC_destruct"
8359 "PERL_MAGIC_env"
8360 "PERL_MAGIC_envelem"
8361 "PERL_MAGIC_ext"
8362 "PERL_MAGIC_extvalue"
8363 "PERL_MAGIC_fm"
8364 "PERL_MAGIC_hints"
8365 "PERL_MAGIC_hintselem"
8366 "PERL_MAGIC_hook"
8367 "PERL_MAGIC_hookelem"
8368 "PERL_MAGIC_isa"
8369 "PERL_MAGIC_isaelem"
8370 "PERL_MAGIC_lvref"
8371 "PERL_MAGIC_nkeys"
8372 "PERL_MAGIC_nonelem"
8373 "PERL_MAGIC_overload_table"
8374 "PERL_MAGIC_pos"
8375 "PERL_MAGIC_qr"
8376 "PERL_MAGIC_regdata"
8377 "PERL_MAGIC_regdatum"
8378 "PERL_MAGIC_regex_global"
8379 "PERL_MAGIC_rhash"
8380 "PERL_MAGIC_shared"
8381 "PERL_MAGIC_shared_scalar"
8382 "PERL_MAGIC_sig"
8383 "PERL_MAGIC_sigelem"
8384 "PERL_MAGIC_substr"
8385 "PERL_MAGIC_sv"
8386 "PERL_MAGIC_symtab"
8387 "PERL_MAGIC_taint"
8388 "PERL_MAGIC_tied"
8389 "PERL_MAGIC_tiedelem"
8390 "PERL_MAGIC_tiedscalar"
8391 "PERL_MAGIC_utf8"
8392 "PERL_MAGIC_uvar"
8393 "PERL_MAGIC_uvar_elem"
8394 "PERL_MAGIC_vec"
8395 "PERL_MAGIC_vstring"
8396 Described in perlguts.
8397 "SvTIED_obj"
8399 Described in perlinterp.
8400 SvTIED_obj(SV *sv, MAGIC *mg)
8402
8404 "dump_mstats"
8405 When enabled by compiling with "-DDEBUGGING_MSTATS", print out
8406 statistics about malloc as two lines of numbers, one showing the
8407 length of the free list for each size category, the second showing
8408 the number of mallocs - frees for each size category.
8409 "s", if not NULL, is used as a phrase to include in the output,
8411 such as "after compilation".
8412 void dump_mstats(const char *s)
8414 "HASATTRIBUTE_MALLOC"
8416 Can we handle "GCC" attribute for malloc-style functions.
8417 "HAS_MALLOC_GOOD_SIZE"
8419 This symbol, if defined, indicates that the "malloc_good_size"
8420 routine is available for use.
8421 "HAS_MALLOC_SIZE"
8423 This symbol, if defined, indicates that the "malloc_size" routine
8424 is available for use.
8425 "I_MALLOCMALLOC"
8427 This symbol, if defined, indicates to the C program that it should
8428 include malloc/malloc.h.
8429 #ifdef I_MALLOCMALLOC
8431 #include <mallocmalloc.h>
8432 #endif
8433 "MYMALLOC"
8435 This symbol, if defined, indicates that we're using our own malloc.
8436 "Newx"
8438 "safemalloc"
8439 The XSUB-writer's interface to the C "malloc" function.
8440 Memory obtained by this should ONLY be freed with "Safefree".
8442 In 5.9.3, Newx() and friends replace the older New() API, and drops
8444 the first parameter, x, a debug aid which allowed callers to
8445 identify themselves. This aid has been superseded by a new build
8446 option, PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhacktips). The
8447 older API is still there for use in XS modules supporting older
8448 perls.
8449 void Newx (void* ptr, int nitems, type)
8451 void* safemalloc(size_t size)
8452 "Newxc"
8454 The XSUB-writer's interface to the C "malloc" function, with cast.
8455 See also "Newx".
8456 Memory obtained by this should ONLY be freed with "Safefree".
8458 void Newxc(void* ptr, int nitems, type, cast)
8460 "Newxz"
8462 "safecalloc"
8463 The XSUB-writer's interface to the C "malloc" function. The
8464 allocated memory is zeroed with "memzero". See also "Newx".
8465 Memory obtained by this should ONLY be freed with "Safefree".
8467 void Newxz (void* ptr, int nitems, type)
8469 void* safecalloc(size_t nitems, size_t item_size)
8470 "PERL_MALLOC_WRAP"
8472 This symbol, if defined, indicates that we'd like malloc wrap
8473 checks.
8474 "Renew"
8476 "saferealloc"
8477 The XSUB-writer's interface to the C "realloc" function.
8478 Memory obtained by this should ONLY be freed with "Safefree".
8480 void Renew (void* ptr, int nitems, type)
8482 void* saferealloc(void *ptr, size_t size)
8483 "Renewc"
8485 The XSUB-writer's interface to the C "realloc" function, with cast.
8486 Memory obtained by this should ONLY be freed with "Safefree".
8488 void Renewc(void* ptr, int nitems, type, cast)
8490 "Safefree"
8492 The XSUB-writer's interface to the C "free" function.
8493 This should ONLY be used on memory obtained using "Newx" and
8495 friends.
8496 void Safefree(void* ptr)
8498 "safesyscalloc"
8500 Safe version of system's calloc()
8501 Malloc_t safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
8503 "safesysfree"
8505 Safe version of system's free()
8506 Free_t safesysfree(Malloc_t where)
8508 "safesysmalloc"
8510 Paranoid version of system's malloc()
8511 Malloc_t safesysmalloc(MEM_SIZE nbytes)
8513 "safesysrealloc"
8515 Paranoid version of system's realloc()
8516 Malloc_t safesysrealloc(Malloc_t where, MEM_SIZE nbytes)
8518
8520 These functions are related to the method resolution order of perl
8521 classes Also see perlmroapi.
8522 "HvMROMETA"
8524 Described in perlmroapi.
8525 struct mro_meta * HvMROMETA(HV *hv)
8527 "mro_get_from_name"
8529 Returns the previously registered mro with the given "name", or
8530 NULL if not registered. See ""mro_register"".
8531 NOTE: "mro_get_from_name" must be explicitly called as
8533 "Perl_mro_get_from_name" with an "aTHX_" parameter.
8534 const struct mro_alg * Perl_mro_get_from_name(pTHX_ SV *name)
8536 "mro_get_linear_isa"
8538 Returns the mro linearisation for the given stash. By default,
8539 this will be whatever "mro_get_linear_isa_dfs" returns unless some
8540 other MRO is in effect for the stash. The return value is a read-
8541 only AV* whose values are string SVs giving class names.
8542 You are responsible for SvREFCNT_inc() on the return value if you
8544 plan to store it anywhere semi-permanently (otherwise it might be
8545 deleted out from under you the next time the cache is invalidated).
8546 AV * mro_get_linear_isa(HV *stash)
8548 "MRO_GET_PRIVATE_DATA"
8550 Described in perlmroapi.
8551 SV* MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta,
8553 const struct mro_alg *const which)
8554 "mro_method_changed_in"
8556 Invalidates method caching on any child classes of the given stash,
8557 so that they might notice the changes in this one.
8558 Ideally, all instances of "PL_sub_generation++" in perl source
8560 outside of mro.c should be replaced by calls to this.
8561 Perl automatically handles most of the common ways a method might
8563 be redefined. However, there are a few ways you could change a
8564 method in a stash without the cache code noticing, in which case
8565 you need to call this method afterwards:
8566 1) Directly manipulating the stash HV entries from XS code.
8568 2) Assigning a reference to a readonly scalar constant into a stash
8570 entry in order to create a constant subroutine (like constant.pm
8571 does).
8572 This same method is available from pure perl via,
8574 mro::method_changed_in(classname).
8575 void mro_method_changed_in(HV *stash)
8577 "mro_register"
8579 Registers a custom mro plugin. See perlmroapi for details on this
8580 and other mro functions.
8581 NOTE: "mro_register" must be explicitly called as
8583 "Perl_mro_register" with an "aTHX_" parameter.
8584 void Perl_mro_register(pTHX_ const struct mro_alg *mro)
8586 "mro_set_mro"
8588 Set "meta" to the value contained in the registered mro plugin
8589 whose name is "name".
8590 Croaks if "name" hasn't been registered
8592 NOTE: "mro_set_mro" must be explicitly called as "Perl_mro_set_mro"
8594 with an "aTHX_" parameter.
8595 void Perl_mro_set_mro(pTHX_ struct mro_meta * const meta,
8597 SV * const name)
8598 "mro_set_private_data"
8600 Described in perlmroapi.
8601 NOTE: "mro_set_private_data" must be explicitly called as
8603 "Perl_mro_set_private_data" with an "aTHX_" parameter.
8604 SV * Perl_mro_set_private_data(pTHX_
8606 struct mro_meta * const smeta,
8607 const struct mro_alg * const which,
8608 SV * const data)
8609
8611 "dMULTICALL"
8612 Declare local variables for a multicall. See "LIGHTWEIGHT
8613 CALLBACKS" in perlcall.
8614 dMULTICALL;
8616 "MULTICALL"
8618 Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in
8619 perlcall.
8620 MULTICALL;
8622 "POP_MULTICALL"
8624 Closing bracket for a lightweight callback. See "LIGHTWEIGHT
8625 CALLBACKS" in perlcall.
8626 POP_MULTICALL;
8628 "PUSH_MULTICALL"
8630 Opening bracket for a lightweight callback. See "LIGHTWEIGHT
8631 CALLBACKS" in perlcall.
8632 PUSH_MULTICALL(CV* the_cv);
8634
8636 "Atol"
8637 "DEPRECATED!" It is planned to remove "Atol" from a future release
8638 of Perl. Do not use it for new code; remove it from existing code.
8639 Described in perlhacktips.
8641 Atol(const char * nptr)
8643 "Atoul"
8645 "DEPRECATED!" It is planned to remove "Atoul" from a future
8646 release of Perl. Do not use it for new code; remove it from
8647 existing code.
8648 Described in perlhacktips.
8650 Atoul(const char * nptr)
8652 "Drand01"
8654 This macro is to be used to generate uniformly distributed random
8655 numbers over the range [0., 1.[. You may have to supply an 'extern
8656 double drand48();' in your program since SunOS 4.1.3 doesn't
8657 provide you with anything relevant in its headers. See
8658 "HAS_DRAND48_PROTO".
8659 double Drand01()
8661 "Gconvert"
8663 This preprocessor macro is defined to convert a floating point
8664 number to a string without a trailing decimal point. This emulates
8665 the behavior of sprintf("%g"), but is sometimes much more
8666 efficient. If gconvert() is not available, but gcvt() drops the
8667 trailing decimal point, then gcvt() is used. If all else fails, a
8668 macro using sprintf("%g") is used. Arguments for the Gconvert macro
8669 are: value, number of digits, whether trailing zeros should be
8670 retained, and the output buffer. The usual values are:
8671 d_Gconvert='gconvert((x),(n),(t),(b))'
8673 d_Gconvert='gcvt((x),(n),(b))'
8674 d_Gconvert='sprintf((b),"%.*g",(n),(x))'
8675 The last two assume trailing zeros should not be kept.
8677 char * Gconvert(double x, Size_t n, bool t, char * b)
8679 "grok_atoUV"
8681 parse a string, looking for a decimal unsigned integer.
8682 On entry, "pv" points to the beginning of the string; "valptr"
8684 points to a UV that will receive the converted value, if found;
8685 "endptr" is either NULL or points to a variable that points to one
8686 byte beyond the point in "pv" that this routine should examine. If
8687 "endptr" is NULL, "pv" is assumed to be NUL-terminated.
8688 Returns FALSE if "pv" doesn't represent a valid unsigned integer
8690 value (with no leading zeros). Otherwise it returns TRUE, and sets
8691 *valptr to that value.
8692 If you constrain the portion of "pv" that is looked at by this
8694 function (by passing a non-NULL "endptr"), and if the initial bytes
8695 of that portion form a valid value, it will return TRUE, setting
8696 *endptr to the byte following the final digit of the value. But if
8697 there is no constraint at what's looked at, all of "pv" must be
8698 valid in order for TRUE to be returned. *endptr is unchanged from
8699 its value on input if FALSE is returned;
8700 The only characters this accepts are the decimal digits '0'..'9'.
8702 As opposed to atoi(3) or strtol(3), "grok_atoUV" does NOT allow
8704 optional leading whitespace, nor negative inputs. If such features
8705 are required, the calling code needs to explicitly implement those.
8706 Note that this function returns FALSE for inputs that would
8708 overflow a UV, or have leading zeros. Thus a single 0 is accepted,
8709 but not 00 nor 01, 002, etc.
8710 Background: "atoi" has severe problems with illegal inputs, it
8712 cannot be used for incremental parsing, and therefore should be
8713 avoided "atoi" and "strtol" are also affected by locale settings,
8714 which can also be seen as a bug (global state controlled by user
8715 environment).
8716 bool grok_atoUV(const char *pv, UV *valptr, const char **endptr)
8718 "grok_bin"
8720 converts a string representing a binary number to numeric form.
8721 On entry "start" and *len_p give the string to scan, *flags gives
8723 conversion flags, and "result" should be "NULL" or a pointer to an
8724 NV. The scan stops at the end of the string, or at just before the
8725 first invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
8726 in *flags, encountering an invalid character (except NUL) will also
8727 trigger a warning. On return *len_p is set to the length of the
8728 scanned string, and *flags gives output flags.
8729 If the value is <= "UV_MAX" it is returned as a UV, the output
8731 flags are clear, and nothing is written to *result. If the value
8732 is > "UV_MAX", "grok_bin" returns "UV_MAX", sets
8733 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
8734 approximation of the correct value into *result (which is an NV; or
8735 the approximation is discarded if "result" is NULL).
8736 The binary number may optionally be prefixed with "0b" or "b"
8738 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
8739 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
8741 pairs of digits may be separated from each other by a single
8742 underscore; also a single leading underscore is accepted.
8743 UV grok_bin(const char *start, STRLEN *len_p, I32 *flags,
8745 NV *result)
8746 "grok_hex"
8748 converts a string representing a hex number to numeric form.
8749 On entry "start" and *len_p give the string to scan, *flags gives
8751 conversion flags, and "result" should be "NULL" or a pointer to an
8752 NV. The scan stops at the end of the string, or at just before the
8753 first invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
8754 in *flags, encountering an invalid character (except NUL) will also
8755 trigger a warning. On return *len_p is set to the length of the
8756 scanned string, and *flags gives output flags.
8757 If the value is <= "UV_MAX" it is returned as a UV, the output
8759 flags are clear, and nothing is written to *result. If the value
8760 is > "UV_MAX", "grok_hex" returns "UV_MAX", sets
8761 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
8762 approximation of the correct value into *result (which is an NV; or
8763 the approximation is discarded if "result" is NULL).
8764 The hex number may optionally be prefixed with "0x" or "x" unless
8766 "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
8767 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
8769 pairs of digits may be separated from each other by a single
8770 underscore; also a single leading underscore is accepted.
8771 UV grok_hex(const char *start, STRLEN *len_p, I32 *flags,
8773 NV *result)
8774 "grok_infnan"
8776 Helper for grok_number(), accepts various ways of spelling
8777 "infinity" or "not a number", and returns one of the following flag
8778 combinations:
8779 IS_NUMBER_INFINITY
8781 IS_NUMBER_NAN
8782 IS_NUMBER_INFINITY | IS_NUMBER_NEG
8783 IS_NUMBER_NAN | IS_NUMBER_NEG
8784 0
8785 possibly |-ed with "IS_NUMBER_TRAILING".
8787 If an infinity or a not-a-number is recognized, *sp will point to
8789 one byte past the end of the recognized string. If the recognition
8790 fails, zero is returned, and *sp will not move.
8791 int grok_infnan(const char **sp, const char *send)
8793 "grok_number"
8795 Identical to grok_number_flags() with "flags" set to zero.
8796 int grok_number(const char *pv, STRLEN len, UV *valuep)
8798 "grok_number_flags"
8800 Recognise (or not) a number. The type of the number is returned (0
8801 if unrecognised), otherwise it is a bit-ORed combination of
8802 "IS_NUMBER_IN_UV", "IS_NUMBER_GREATER_THAN_UV_MAX",
8803 "IS_NUMBER_NOT_INT", "IS_NUMBER_NEG", "IS_NUMBER_INFINITY",
8804 "IS_NUMBER_NAN" (defined in perl.h).
8805 If the value of the number can fit in a UV, it is returned in
8807 *valuep. "IS_NUMBER_IN_UV" will be set to indicate that *valuep is
8808 valid, "IS_NUMBER_IN_UV" will never be set unless *valuep is valid,
8809 but *valuep may have been assigned to during processing even though
8810 "IS_NUMBER_IN_UV" is not set on return. If "valuep" is "NULL",
8811 "IS_NUMBER_IN_UV" will be set for the same cases as when "valuep"
8812 is non-"NULL", but no actual assignment (or SEGV) will occur.
8813 "IS_NUMBER_NOT_INT" will be set with "IS_NUMBER_IN_UV" if trailing
8815 decimals were seen (in which case *valuep gives the true value
8816 truncated to an integer), and "IS_NUMBER_NEG" if the number is
8817 negative (in which case *valuep holds the absolute value).
8818 "IS_NUMBER_IN_UV" is not set if "e" notation was used or the number
8819 is larger than a UV.
8820 "flags" allows only "PERL_SCAN_TRAILING", which allows for trailing
8822 non-numeric text on an otherwise successful grok, setting
8823 "IS_NUMBER_TRAILING" on the result.
8824 int grok_number_flags(const char *pv, STRLEN len, UV *valuep,
8826 U32 flags)
8827 "GROK_NUMERIC_RADIX"
8829 A synonym for "grok_numeric_radix"
8830 bool GROK_NUMERIC_RADIX(NN const char **sp, NN const char *send)
8832 "grok_numeric_radix"
8834 Scan and skip for a numeric decimal separator (radix).
8835 bool grok_numeric_radix(const char **sp, const char *send)
8837 "grok_oct"
8839 converts a string representing an octal number to numeric form.
8840 On entry "start" and *len_p give the string to scan, *flags gives
8842 conversion flags, and "result" should be "NULL" or a pointer to an
8843 NV. The scan stops at the end of the string, or at just before the
8844 first invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
8845 in *flags, encountering an invalid character (except NUL) will also
8846 trigger a warning. On return *len_p is set to the length of the
8847 scanned string, and *flags gives output flags.
8848 If the value is <= "UV_MAX" it is returned as a UV, the output
8850 flags are clear, and nothing is written to *result. If the value
8851 is > "UV_MAX", "grok_oct" returns "UV_MAX", sets
8852 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes an
8853 approximation of the correct value into *result (which is an NV; or
8854 the approximation is discarded if "result" is NULL).
8855 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or all
8857 pairs of digits may be separated from each other by a single
8858 underscore; also a single leading underscore is accepted.
8859 The "PERL_SCAN_DISALLOW_PREFIX" flag is always treated as being set
8861 for this function.
8862 UV grok_oct(const char *start, STRLEN *len_p, I32 *flags,
8864 NV *result)
8865 "isinfnan"
8867 Perl_isinfnan() is a utility function that returns true if the NV
8868 argument is either an infinity or a "NaN", false otherwise. To
8869 test in more detail, use Perl_isinf() and Perl_isnan().
8870 This is also the logical inverse of Perl_isfinite().
8872 bool isinfnan(NV nv)
8874 "my_atof"
8876 "atof"(3), but properly works with Perl locale handling, accepting
8877 a dot radix character always, but also the current locale's radix
8878 character if and only if called from within the lexical scope of a
8879 Perl "use locale" statement.
8880 N.B. "s" must be NUL terminated.
8882 NV my_atof(const char *s)
8884 "my_strtod"
8886 This function is equivalent to the libc strtod() function, and is
8887 available even on platforms that lack plain strtod(). Its return
8888 value is the best available precision depending on platform
8889 capabilities and Configure options.
8890 It properly handles the locale radix character, meaning it expects
8892 a dot except when called from within the scope of "use locale", in
8893 which case the radix character should be that specified by the
8894 current locale.
8895 The synonym Strtod() may be used instead.
8897 NV my_strtod(const char * const s, char **e)
8899 "PERL_ABS"
8901 Typeless "abs" or "fabs", etc. (The usage below indicates it is
8902 for integers, but it works for any type.) Use instead of these,
8903 since the C library ones force their argument to be what it is
8904 expecting, potentially leading to disaster. But also beware that
8905 this evaluates its argument twice, so no "x++".
8906 int PERL_ABS(int x)
8908 "Perl_acos"
8910 "Perl_asin"
8911 "Perl_atan"
8912 "Perl_atan2"
8913 "Perl_ceil"
8914 "Perl_cos"
8915 "Perl_cosh"
8916 "Perl_exp"
8917 "Perl_floor"
8918 "Perl_fmod"
8919 "Perl_frexp"
8920 "Perl_isfinite"
8921 "Perl_isinf"
8922 "Perl_isnan"
8923 "Perl_ldexp"
8924 "Perl_log"
8925 "Perl_log10"
8926 "Perl_modf"
8927 "Perl_pow"
8928 "Perl_sin"
8929 "Perl_sinh"
8930 "Perl_sqrt"
8931 "Perl_tan"
8932 "Perl_tanh"
8933 These perform the corresponding mathematical operation on the
8934 operand(s), using the libc function designed for the task that has
8935 just enough precision for an NV on this platform. If no such
8936 function with sufficient precision exists, the highest precision
8937 one available is used.
8938 NV Perl_acos (NV x)
8940 NV Perl_asin (NV x)
8941 NV Perl_atan (NV x)
8942 NV Perl_atan2 (NV x, NV y)
8943 NV Perl_ceil (NV x)
8944 NV Perl_cos (NV x)
8945 NV Perl_cosh (NV x)
8946 NV Perl_exp (NV x)
8947 NV Perl_floor (NV x)
8948 NV Perl_fmod (NV x, NV y)
8949 NV Perl_frexp (NV x, int *exp)
8950 IV Perl_isfinite(NV x)
8951 IV Perl_isinf (NV x)
8952 IV Perl_isnan (NV x)
8953 NV Perl_ldexp (NV x, int exp)
8954 NV Perl_log (NV x)
8955 NV Perl_log10 (NV x)
8956 NV Perl_modf (NV x, NV *iptr)
8957 NV Perl_pow (NV x, NV y)
8958 NV Perl_sin (NV x)
8959 NV Perl_sinh (NV x)
8960 NV Perl_sqrt (NV x)
8961 NV Perl_tan (NV x)
8962 NV Perl_tanh (NV x)
8963 "Perl_signbit"
8965 NOTE: "Perl_signbit" is experimental and may change or be removed
8966 without notice.
8967 Return a non-zero integer if the sign bit on an NV is set, and 0 if
8969 it is not.
8970 If Configure detects this system has a signbit() that will work
8972 with our NVs, then we just use it via the "#define" in perl.h.
8973 Otherwise, fall back on this implementation. The main use of this
8974 function is catching -0.0.
8975 "Configure" notes: This function is called 'Perl_signbit' instead
8977 of a plain 'signbit' because it is easy to imagine a system having
8978 a signbit() function or macro that doesn't happen to work with our
8979 particular choice of NVs. We shouldn't just re-"#define" "signbit"
8980 as "Perl_signbit" and expect the standard system headers to be
8981 happy. Also, this is a no-context function (no "pTHX_") because
8982 Perl_signbit() is usually re-"#defined" in perl.h as a simple macro
8983 call to the system's signbit(). Users should just always call
8984 Perl_signbit().
8985 int Perl_signbit(NV f)
8987 "PL_hexdigit"
8989 This array, indexed by an integer, converts that value into the
8990 character that represents it. For example, if the input is 8, the
8991 return will be a string whose first character is '8'. What is
8992 actually returned is a pointer into a string. All you are
8993 interested in is the first character of that string. To get
8994 uppercase letters (for the values 10..15), add 16 to the index.
8995 Hence, "PL_hexdigit[11]" is 'b', and "PL_hexdigit[11+16]" is 'B'.
8996 Adding 16 to an index whose representation is '0'..'9' yields the
8997 same as not adding 16. Indices outside the range 0..31 result in
8998 (bad) undedefined behavior.
8999 "READ_XDIGIT"
9001 Returns the value of an ASCII-range hex digit and advances the
9002 string pointer. Behaviour is only well defined when isXDIGIT(*str)
9003 is true.
9004 U8 READ_XDIGIT(char str*)
9006 "scan_bin"
9008 For backwards compatibility. Use "grok_bin" instead.
9009 NV scan_bin(const char *start, STRLEN len, STRLEN *retlen)
9011 "scan_hex"
9013 For backwards compatibility. Use "grok_hex" instead.
9014 NV scan_hex(const char *start, STRLEN len, STRLEN *retlen)
9016 "scan_oct"
9018 For backwards compatibility. Use "grok_oct" instead.
9019 NV scan_oct(const char *start, STRLEN len, STRLEN *retlen)
9021 "seedDrand01"
9023 This symbol defines the macro to be used in seeding the random
9024 number generator (see "Drand01").
9025 void seedDrand01(Rand_seed_t x)
9027 "Strtod"
9029 This is a synonym for "my_strtod".
9030 NV Strtod(NN const char * const s, NULLOK char ** e)
9032 "Strtol"
9034 Platform and configuration independent "strtol". This expands to
9035 the appropriate "strotol"-like function based on the platform and
9036 Configure options>. For example it could expand to "strtoll" or
9037 "strtoq" instead of "strtol".
9038 NV Strtol(NN const char * const s, NULLOK char ** e, int base)
9040 "Strtoul"
9042 Platform and configuration independent "strtoul". This expands to
9043 the appropriate "strotoul"-like function based on the platform and
9044 Configure options>. For example it could expand to "strtoull" or
9045 "strtouq" instead of "strtoul".
9046 NV Strtoul(NN const char * const s, NULLOK char ** e, int base)
9048
9050 "alloccopstash"
9051 NOTE: "alloccopstash" is experimental and may change or be removed
9052 without notice.
9053 Available only under threaded builds, this function allocates an
9055 entry in "PL_stashpad" for the stash passed to it.
9056 PADOFFSET alloccopstash(HV *hv)
9058 "BINOP"
9060 Described in perlguts.
9061 "block_end"
9063 Handles compile-time scope exit. "floor" is the savestack index
9064 returned by "block_start", and "seq" is the body of the block.
9065 Returns the block, possibly modified.
9066 OP * block_end(I32 floor, OP *seq)
9068 "block_start"
9070 Handles compile-time scope entry. Arranges for hints to be
9071 restored on block exit and also handles pad sequence numbers to
9072 make lexical variables scope right. Returns a savestack index for
9073 use with "block_end".
9074 int block_start(int full)
9076 "ck_entersub_args_list"
9078 Performs the default fixup of the arguments part of an "entersub"
9079 op tree. This consists of applying list context to each of the
9080 argument ops. This is the standard treatment used on a call marked
9081 with "&", or a method call, or a call through a subroutine
9082 reference, or any other call where the callee can't be identified
9083 at compile time, or a call where the callee has no prototype.
9084 OP * ck_entersub_args_list(OP *entersubop)
9086 "ck_entersub_args_proto"
9088 Performs the fixup of the arguments part of an "entersub" op tree
9089 based on a subroutine prototype. This makes various modifications
9090 to the argument ops, from applying context up to inserting "refgen"
9091 ops, and checking the number and syntactic types of arguments, as
9092 directed by the prototype. This is the standard treatment used on
9093 a subroutine call, not marked with "&", where the callee can be
9094 identified at compile time and has a prototype.
9095 "protosv" supplies the subroutine prototype to be applied to the
9097 call. It may be a normal defined scalar, of which the string value
9098 will be used. Alternatively, for convenience, it may be a
9099 subroutine object (a "CV*" that has been cast to "SV*") which has a
9100 prototype. The prototype supplied, in whichever form, does not
9101 need to match the actual callee referenced by the op tree.
9102 If the argument ops disagree with the prototype, for example by
9104 having an unacceptable number of arguments, a valid op tree is
9105 returned anyway. The error is reflected in the parser state,
9106 normally resulting in a single exception at the top level of
9107 parsing which covers all the compilation errors that occurred. In
9108 the error message, the callee is referred to by the name defined by
9109 the "namegv" parameter.
9110 OP * ck_entersub_args_proto(OP *entersubop, GV *namegv,
9112 SV *protosv)
9113 "ck_entersub_args_proto_or_list"
9115 Performs the fixup of the arguments part of an "entersub" op tree
9116 either based on a subroutine prototype or using default list-
9117 context processing. This is the standard treatment used on a
9118 subroutine call, not marked with "&", where the callee can be
9119 identified at compile time.
9120 "protosv" supplies the subroutine prototype to be applied to the
9122 call, or indicates that there is no prototype. It may be a normal
9123 scalar, in which case if it is defined then the string value will
9124 be used as a prototype, and if it is undefined then there is no
9125 prototype. Alternatively, for convenience, it may be a subroutine
9126 object (a "CV*" that has been cast to "SV*"), of which the
9127 prototype will be used if it has one. The prototype (or lack
9128 thereof) supplied, in whichever form, does not need to match the
9129 actual callee referenced by the op tree.
9130 If the argument ops disagree with the prototype, for example by
9132 having an unacceptable number of arguments, a valid op tree is
9133 returned anyway. The error is reflected in the parser state,
9134 normally resulting in a single exception at the top level of
9135 parsing which covers all the compilation errors that occurred. In
9136 the error message, the callee is referred to by the name defined by
9137 the "namegv" parameter.
9138 OP * ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
9140 SV *protosv)
9141 "cv_const_sv"
9143 If "cv" is a constant sub eligible for inlining, returns the
9144 constant value returned by the sub. Otherwise, returns "NULL".
9145 Constant subs can be created with "newCONSTSUB" or as described in
9147 "Constant Functions" in perlsub.
9148 SV * cv_const_sv(const CV * const cv)
9150 "cv_get_call_checker"
9152 The original form of "cv_get_call_checker_flags", which does not
9153 return checker flags. When using a checker function returned by
9154 this function, it is only safe to call it with a genuine GV as its
9155 "namegv" argument.
9156 void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
9158 SV **ckobj_p)
9159 "cv_get_call_checker_flags"
9161 Retrieves the function that will be used to fix up a call to "cv".
9162 Specifically, the function is applied to an "entersub" op tree for
9163 a subroutine call, not marked with "&", where the callee can be
9164 identified at compile time as "cv".
9165 The C-level function pointer is returned in *ckfun_p, an SV
9167 argument for it is returned in *ckobj_p, and control flags are
9168 returned in *ckflags_p. The function is intended to be called in
9169 this manner:
9170 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
9172 In this call, "entersubop" is a pointer to the "entersub" op, which
9174 may be replaced by the check function, and "namegv" supplies the
9175 name that should be used by the check function to refer to the
9176 callee of the "entersub" op if it needs to emit any diagnostics.
9177 It is permitted to apply the check function in non-standard
9178 situations, such as to a call to a different subroutine or to a
9179 method call.
9180 "namegv" may not actually be a GV. If the
9182 "CALL_CHECKER_REQUIRE_GV" bit is clear in *ckflags_p, it is
9183 permitted to pass a CV or other SV instead, anything that can be
9184 used as the first argument to "cv_name". If the
9185 "CALL_CHECKER_REQUIRE_GV" bit is set in *ckflags_p then the check
9186 function requires "namegv" to be a genuine GV.
9187 By default, the check function is
9189 Perl_ck_entersub_args_proto_or_list, the SV parameter is "cv"
9190 itself, and the "CALL_CHECKER_REQUIRE_GV" flag is clear. This
9191 implements standard prototype processing. It can be changed, for a
9192 particular subroutine, by "cv_set_call_checker_flags".
9193 If the "CALL_CHECKER_REQUIRE_GV" bit is set in "gflags" then it
9195 indicates that the caller only knows about the genuine GV version
9196 of "namegv", and accordingly the corresponding bit will always be
9197 set in *ckflags_p, regardless of the check function's recorded
9198 requirements. If the "CALL_CHECKER_REQUIRE_GV" bit is clear in
9199 "gflags" then it indicates the caller knows about the possibility
9200 of passing something other than a GV as "namegv", and accordingly
9201 the corresponding bit may be either set or clear in *ckflags_p,
9202 indicating the check function's recorded requirements.
9203 "gflags" is a bitset passed into "cv_get_call_checker_flags", in
9205 which only the "CALL_CHECKER_REQUIRE_GV" bit currently has a
9206 defined meaning (for which see above). All other bits should be
9207 clear.
9208 void cv_get_call_checker_flags(CV *cv, U32 gflags,
9210 Perl_call_checker *ckfun_p,
9211 SV **ckobj_p, U32 *ckflags_p)
9212 "cv_set_call_checker"
9214 The original form of "cv_set_call_checker_flags", which passes it
9215 the "CALL_CHECKER_REQUIRE_GV" flag for backward-compatibility. The
9216 effect of that flag setting is that the check function is
9217 guaranteed to get a genuine GV as its "namegv" argument.
9218 void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
9220 SV *ckobj)
9221 "cv_set_call_checker_flags"
9223 Sets the function that will be used to fix up a call to "cv".
9224 Specifically, the function is applied to an "entersub" op tree for
9225 a subroutine call, not marked with "&", where the callee can be
9226 identified at compile time as "cv".
9227 The C-level function pointer is supplied in "ckfun", an SV argument
9229 for it is supplied in "ckobj", and control flags are supplied in
9230 "ckflags". The function should be defined like this:
9231 STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
9233 It is intended to be called in this manner:
9235 entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
9237 In this call, "entersubop" is a pointer to the "entersub" op, which
9239 may be replaced by the check function, and "namegv" supplies the
9240 name that should be used by the check function to refer to the
9241 callee of the "entersub" op if it needs to emit any diagnostics.
9242 It is permitted to apply the check function in non-standard
9243 situations, such as to a call to a different subroutine or to a
9244 method call.
9245 "namegv" may not actually be a GV. For efficiency, perl may pass a
9247 CV or other SV instead. Whatever is passed can be used as the
9248 first argument to "cv_name". You can force perl to pass a GV by
9249 including "CALL_CHECKER_REQUIRE_GV" in the "ckflags".
9250 "ckflags" is a bitset, in which only the "CALL_CHECKER_REQUIRE_GV"
9252 bit currently has a defined meaning (for which see above). All
9253 other bits should be clear.
9254 The current setting for a particular CV can be retrieved by
9256 "cv_get_call_checker_flags".
9257 void cv_set_call_checker_flags(CV *cv, Perl_call_checker ckfun,
9259 SV *ckobj, U32 ckflags)
9260 "finalize_optree"
9262 This function finalizes the optree. Should be called directly
9263 after the complete optree is built. It does some additional
9264 checking which can't be done in the normal "ck_"xxx functions and
9265 makes the tree thread-safe.
9266 void finalize_optree(OP *o)
9268 "forbid_outofblock_ops"
9270 NOTE: "forbid_outofblock_ops" is experimental and may change or be
9271 removed without notice.
9272 Checks an optree that implements a block, to ensure there are no
9274 control-flow ops that attempt to leave the block. Any "OP_RETURN"
9275 is forbidden, as is any "OP_GOTO". Loops are analysed, so any
9276 LOOPEX op ("OP_NEXT", "OP_LAST" or "OP_REDO") that affects a loop
9277 that contains it within the block are permitted, but those that do
9278 not are forbidden.
9279 If any of these forbidden constructions are detected, an exception
9281 is thrown by using the op name and the blockname argument to
9282 construct a suitable message.
9283 This function alone is not sufficient to ensure the optree does not
9285 perform any of these forbidden activities during runtime, as it
9286 might call a different function that performs a non-local LOOPEX,
9287 or a string-eval() that performs a "goto", or various other things.
9288 It is intended purely as a compile-time check for those that could
9289 be detected statically. Additional runtime checks may be required
9290 depending on the circumstance it is used for.
9291 Note currently that all "OP_GOTO" ops are forbidden, even in cases
9293 where they might otherwise be safe to execute. This may be
9294 permitted in a later version.
9295 void forbid_outofblock_ops(OP *o, const char *blockname)
9297 "LINKLIST"
9299 Given the root of an optree, link the tree in execution order using
9300 the "op_next" pointers and return the first op executed. If this
9301 has already been done, it will not be redone, and "o->op_next" will
9302 be returned. If "o->op_next" is not already set, "o" should be at
9303 least an "UNOP".
9304 OP* LINKLIST(OP *o)
9306 "LISTOP"
9308 Described in perlguts.
9309 "LOGOP"
9311 Described in perlguts.
9312 "LOOP"
9314 Described in perlguts.
9315 "newARGDEFELEMOP"
9317 Constructs and returns a new "OP_ARGDEFELEM" op which provides a
9318 defaulting expression given by "expr" for the signature parameter
9319 at the index given by "argindex". The expression optree is consumed
9320 by this function and becomes part of the returned optree.
9321 OP * newARGDEFELEMOP(I32 flags, OP *expr, I32 argindex)
9323 "newASSIGNOP"
9325 Constructs, checks, and returns an assignment op. "left" and
9326 "right" supply the parameters of the assignment; they are consumed
9327 by this function and become part of the constructed op tree.
9328 If "optype" is "OP_ANDASSIGN", "OP_ORASSIGN", or "OP_DORASSIGN",
9330 then a suitable conditional optree is constructed. If "optype" is
9331 the opcode of a binary operator, such as "OP_BIT_OR", then an op is
9332 constructed that performs the binary operation and assigns the
9333 result to the left argument. Either way, if "optype" is non-zero
9334 then "flags" has no effect.
9335 If "optype" is zero, then a plain scalar or list assignment is
9337 constructed. Which type of assignment it is is automatically
9338 determined. "flags" gives the eight bits of "op_flags", except
9339 that "OPf_KIDS" will be set automatically, and, shifted up eight
9340 bits, the eight bits of "op_private", except that the bit with
9341 value 1 or 2 is automatically set as required.
9342 OP * newASSIGNOP(I32 flags, OP *left, I32 optype, OP *right)
9344 "newATTRSUB"
9346 Construct a Perl subroutine, also performing some surrounding jobs.
9347 This is the same as ""newATTRSUB_x"" in perlintern with its
9349 "o_is_gv" parameter set to FALSE. This means that if "o" is null,
9350 the new sub will be anonymous; otherwise the name will be derived
9351 from "o" in the way described (as with all other details) in
9352 ""newATTRSUB_x"" in perlintern.
9353 CV * newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs,
9355 OP *block)
9356 "newBINOP"
9358 Constructs, checks, and returns an op of any binary type. "type"
9359 is the opcode. "flags" gives the eight bits of "op_flags", except
9360 that "OPf_KIDS" will be set automatically, and, shifted up eight
9361 bits, the eight bits of "op_private", except that the bit with
9362 value 1 or 2 is automatically set as required. "first" and "last"
9363 supply up to two ops to be the direct children of the binary op;
9364 they are consumed by this function and become part of the
9365 constructed op tree.
9366 OP * newBINOP(I32 type, I32 flags, OP *first, OP *last)
9368 "newCONDOP"
9370 Constructs, checks, and returns a conditional-expression
9371 ("cond_expr") op. "flags" gives the eight bits of "op_flags",
9372 except that "OPf_KIDS" will be set automatically, and, shifted up
9373 eight bits, the eight bits of "op_private", except that the bit
9374 with value 1 is automatically set. "first" supplies the expression
9375 selecting between the two branches, and "trueop" and "falseop"
9376 supply the branches; they are consumed by this function and become
9377 part of the constructed op tree.
9378 OP * newCONDOP(I32 flags, OP *first, OP *trueop, OP *falseop)
9380 "newCONSTSUB"
9382 Behaves like "newCONSTSUB_flags", except that "name" is nul-
9383 terminated rather than of counted length, and no flags are set.
9384 (This means that "name" is always interpreted as Latin-1.)
9385 CV * newCONSTSUB(HV *stash, const char *name, SV *sv)
9387 "newCONSTSUB_flags"
9389 Construct a constant subroutine, also performing some surrounding
9390 jobs. A scalar constant-valued subroutine is eligible for inlining
9391 at compile-time, and in Perl code can be created by
9392 "sub FOO () { 123 }". Other kinds of constant subroutine have
9393 other treatment.
9394 The subroutine will have an empty prototype and will ignore any
9396 arguments when called. Its constant behaviour is determined by
9397 "sv". If "sv" is null, the subroutine will yield an empty list.
9398 If "sv" points to a scalar, the subroutine will always yield that
9399 scalar. If "sv" points to an array, the subroutine will always
9400 yield a list of the elements of that array in list context, or the
9401 number of elements in the array in scalar context. This function
9402 takes ownership of one counted reference to the scalar or array,
9403 and will arrange for the object to live as long as the subroutine
9404 does. If "sv" points to a scalar then the inlining assumes that
9405 the value of the scalar will never change, so the caller must
9406 ensure that the scalar is not subsequently written to. If "sv"
9407 points to an array then no such assumption is made, so it is
9408 ostensibly safe to mutate the array or its elements, but whether
9409 this is really supported has not been determined.
9410 The subroutine will have "CvFILE" set according to "PL_curcop".
9412 Other aspects of the subroutine will be left in their default
9413 state. The caller is free to mutate the subroutine beyond its
9414 initial state after this function has returned.
9415 If "name" is null then the subroutine will be anonymous, with its
9417 "CvGV" referring to an "__ANON__" glob. If "name" is non-null then
9418 the subroutine will be named accordingly, referenced by the
9419 appropriate glob. "name" is a string of length "len" bytes giving
9420 a sigilless symbol name, in UTF-8 if "flags" has the "SVf_UTF8" bit
9421 set and in Latin-1 otherwise. The name may be either qualified or
9422 unqualified. If the name is unqualified then it defaults to being
9423 in the stash specified by "stash" if that is non-null, or to
9424 "PL_curstash" if "stash" is null. The symbol is always added to
9425 the stash if necessary, with "GV_ADDMULTI" semantics.
9426 "flags" should not have bits set other than "SVf_UTF8".
9428 If there is already a subroutine of the specified name, then the
9430 new sub will replace the existing one in the glob. A warning may
9431 be generated about the redefinition.
9432 If the subroutine has one of a few special names, such as "BEGIN"
9434 or "END", then it will be claimed by the appropriate queue for
9435 automatic running of phase-related subroutines. In this case the
9436 relevant glob will be left not containing any subroutine, even if
9437 it did contain one before. Execution of the subroutine will likely
9438 be a no-op, unless "sv" was a tied array or the caller modified the
9439 subroutine in some interesting way before it was executed. In the
9440 case of "BEGIN", the treatment is buggy: the sub will be executed
9441 when only half built, and may be deleted prematurely, possibly
9442 causing a crash.
9443 The function returns a pointer to the constructed subroutine. If
9445 the sub is anonymous then ownership of one counted reference to the
9446 subroutine is transferred to the caller. If the sub is named then
9447 the caller does not get ownership of a reference. In most such
9448 cases, where the sub has a non-phase name, the sub will be alive at
9449 the point it is returned by virtue of being contained in the glob
9450 that names it. A phase-named subroutine will usually be alive by
9451 virtue of the reference owned by the phase's automatic run queue.
9452 A "BEGIN" subroutine may have been destroyed already by the time
9453 this function returns, but currently bugs occur in that case before
9454 the caller gets control. It is the caller's responsibility to
9455 ensure that it knows which of these situations applies.
9456 CV * newCONSTSUB_flags(HV *stash, const char *name, STRLEN len,
9458 U32 flags, SV *sv)
9459 "newDEFEROP"
9461 NOTE: "newDEFEROP" is experimental and may change or be removed
9462 without notice.
9463 Constructs and returns a deferred-block statement that implements
9465 the "defer" semantics. The "block" optree is consumed by this
9466 function and becomes part of the returned optree.
9467 The "flags" argument carries additional flags to set on the
9469 returned op, including the "op_private" field.
9470 OP * newDEFEROP(I32 flags, OP *block)
9472 "newDEFSVOP"
9474 Constructs and returns an op to access $_.
9475 OP * newDEFSVOP()
9477 "newFOROP"
9479 Constructs, checks, and returns an op tree expressing a "foreach"
9480 loop (iteration through a list of values). This is a heavyweight
9481 loop, with structure that allows exiting the loop by "last" and
9482 suchlike.
9483 "sv" optionally supplies the variable(s) that will be aliased to
9485 each item in turn; if null, it defaults to $_. "expr" supplies the
9486 list of values to iterate over. "block" supplies the main body of
9487 the loop, and "cont" optionally supplies a "continue" block that
9488 operates as a second half of the body. All of these optree inputs
9489 are consumed by this function and become part of the constructed op
9490 tree.
9491 "flags" gives the eight bits of "op_flags" for the "leaveloop" op
9493 and, shifted up eight bits, the eight bits of "op_private" for the
9494 "leaveloop" op, except that (in both cases) some bits will be set
9495 automatically.
9496 OP * newFOROP(I32 flags, OP *sv, OP *expr, OP *block, OP *cont)
9498 "newGIVENOP"
9500 Constructs, checks, and returns an op tree expressing a "given"
9501 block. "cond" supplies the expression to whose value $_ will be
9502 locally aliased, and "block" supplies the body of the "given"
9503 construct; they are consumed by this function and become part of
9504 the constructed op tree. "defsv_off" must be zero (it used to
9505 identity the pad slot of lexical $_).
9506 OP * newGIVENOP(OP *cond, OP *block, PADOFFSET defsv_off)
9508 "newGVOP"
9510 Constructs, checks, and returns an op of any type that involves an
9511 embedded reference to a GV. "type" is the opcode. "flags" gives
9512 the eight bits of "op_flags". "gv" identifies the GV that the op
9513 should reference; calling this function does not transfer ownership
9514 of any reference to it.
9515 OP * newGVOP(I32 type, I32 flags, GV *gv)
9517 "newLISTOP"
9519 Constructs, checks, and returns an op of any list type. "type" is
9520 the opcode. "flags" gives the eight bits of "op_flags", except
9521 that "OPf_KIDS" will be set automatically if required. "first" and
9522 "last" supply up to two ops to be direct children of the list op;
9523 they are consumed by this function and become part of the
9524 constructed op tree.
9525 For most list operators, the check function expects all the kid ops
9527 to be present already, so calling "newLISTOP(OP_JOIN, ...)" (e.g.)
9528 is not appropriate. What you want to do in that case is create an
9529 op of type "OP_LIST", append more children to it, and then call
9530 "op_convert_list". See "op_convert_list" for more information.
9531 OP * newLISTOP(I32 type, I32 flags, OP *first, OP *last)
9533 "newLOGOP"
9535 Constructs, checks, and returns a logical (flow control) op.
9536 "type" is the opcode. "flags" gives the eight bits of "op_flags",
9537 except that "OPf_KIDS" will be set automatically, and, shifted up
9538 eight bits, the eight bits of "op_private", except that the bit
9539 with value 1 is automatically set. "first" supplies the expression
9540 controlling the flow, and "other" supplies the side (alternate)
9541 chain of ops; they are consumed by this function and become part of
9542 the constructed op tree.
9543 OP * newLOGOP(I32 optype, I32 flags, OP *first, OP *other)
9545 "newLOOPEX"
9547 Constructs, checks, and returns a loop-exiting op (such as "goto"
9548 or "last"). "type" is the opcode. "label" supplies the parameter
9549 determining the target of the op; it is consumed by this function
9550 and becomes part of the constructed op tree.
9551 OP * newLOOPEX(I32 type, OP *label)
9553 "newLOOPOP"
9555 Constructs, checks, and returns an op tree expressing a loop. This
9556 is only a loop in the control flow through the op tree; it does not
9557 have the heavyweight loop structure that allows exiting the loop by
9558 "last" and suchlike. "flags" gives the eight bits of "op_flags"
9559 for the top-level op, except that some bits will be set
9560 automatically as required. "expr" supplies the expression
9561 controlling loop iteration, and "block" supplies the body of the
9562 loop; they are consumed by this function and become part of the
9563 constructed op tree. "debuggable" is currently unused and should
9564 always be 1.
9565 OP * newLOOPOP(I32 flags, I32 debuggable, OP *expr, OP *block)
9567 "newMETHOP"
9569 Constructs, checks, and returns an op of method type with a method
9570 name evaluated at runtime. "type" is the opcode. "flags" gives
9571 the eight bits of "op_flags", except that "OPf_KIDS" will be set
9572 automatically, and, shifted up eight bits, the eight bits of
9573 "op_private", except that the bit with value 1 is automatically
9574 set. "dynamic_meth" supplies an op which evaluates method name; it
9575 is consumed by this function and become part of the constructed op
9576 tree. Supported optypes: "OP_METHOD".
9577 OP * newMETHOP(I32 type, I32 flags, OP *dynamic_meth)
9579 "newMETHOP_named"
9581 Constructs, checks, and returns an op of method type with a
9582 constant method name. "type" is the opcode. "flags" gives the
9583 eight bits of "op_flags", and, shifted up eight bits, the eight
9584 bits of "op_private". "const_meth" supplies a constant method
9585 name; it must be a shared COW string. Supported optypes:
9586 "OP_METHOD_NAMED".
9587 OP * newMETHOP_named(I32 type, I32 flags, SV * const_meth)
9589 "newNULLLIST"
9591 Constructs, checks, and returns a new "stub" op, which represents
9592 an empty list expression.
9593 OP * newNULLLIST()
9595 "newOP"
9597 Constructs, checks, and returns an op of any base type (any type
9598 that has no extra fields). "type" is the opcode. "flags" gives
9599 the eight bits of "op_flags", and, shifted up eight bits, the eight
9600 bits of "op_private".
9601 OP * newOP(I32 optype, I32 flags)
9603 "newPADOP"
9605 Constructs, checks, and returns an op of any type that involves a
9606 reference to a pad element. "type" is the opcode. "flags" gives
9607 the eight bits of "op_flags". A pad slot is automatically
9608 allocated, and is populated with "sv"; this function takes
9609 ownership of one reference to it.
9610 This function only exists if Perl has been compiled to use
9612 ithreads.
9613 OP * newPADOP(I32 type, I32 flags, SV *sv)
9615 "newPMOP"
9617 Constructs, checks, and returns an op of any pattern matching type.
9618 "type" is the opcode. "flags" gives the eight bits of "op_flags"
9619 and, shifted up eight bits, the eight bits of "op_private".
9620 OP * newPMOP(I32 type, I32 flags)
9622 "newPVOP"
9624 Constructs, checks, and returns an op of any type that involves an
9625 embedded C-level pointer (PV). "type" is the opcode. "flags"
9626 gives the eight bits of "op_flags". "pv" supplies the C-level
9627 pointer. Depending on the op type, the memory referenced by "pv"
9628 may be freed when the op is destroyed. If the op is of a freeing
9629 type, "pv" must have been allocated using "PerlMemShared_malloc".
9630 OP * newPVOP(I32 type, I32 flags, char *pv)
9632 "newRANGE"
9634 Constructs and returns a "range" op, with subordinate "flip" and
9635 "flop" ops. "flags" gives the eight bits of "op_flags" for the
9636 "flip" op and, shifted up eight bits, the eight bits of
9637 "op_private" for both the "flip" and "range" ops, except that the
9638 bit with value 1 is automatically set. "left" and "right" supply
9639 the expressions controlling the endpoints of the range; they are
9640 consumed by this function and become part of the constructed op
9641 tree.
9642 OP * newRANGE(I32 flags, OP *left, OP *right)
9644 "newSLICEOP"
9646 Constructs, checks, and returns an "lslice" (list slice) op.
9647 "flags" gives the eight bits of "op_flags", except that "OPf_KIDS"
9648 will be set automatically, and, shifted up eight bits, the eight
9649 bits of "op_private", except that the bit with value 1 or 2 is
9650 automatically set as required. "listval" and "subscript" supply
9651 the parameters of the slice; they are consumed by this function and
9652 become part of the constructed op tree.
9653 OP * newSLICEOP(I32 flags, OP *subscript, OP *listop)
9655 "newSTATEOP"
9657 Constructs a state op (COP). The state op is normally a
9658 "nextstate" op, but will be a "dbstate" op if debugging is enabled
9659 for currently-compiled code. The state op is populated from
9660 "PL_curcop" (or "PL_compiling"). If "label" is non-null, it
9661 supplies the name of a label to attach to the state op; this
9662 function takes ownership of the memory pointed at by "label", and
9663 will free it. "flags" gives the eight bits of "op_flags" for the
9664 state op.
9665 If "o" is null, the state op is returned. Otherwise the state op
9667 is combined with "o" into a "lineseq" list op, which is returned.
9668 "o" is consumed by this function and becomes part of the returned
9669 op tree.
9670 OP * newSTATEOP(I32 flags, char *label, OP *o)
9672 "newSUB"
9674 Like "newATTRSUB", but without attributes.
9675 CV * newSUB(I32 floor, OP *o, OP *proto, OP *block)
9677 "newSVOP"
9679 Constructs, checks, and returns an op of any type that involves an
9680 embedded SV. "type" is the opcode. "flags" gives the eight bits
9681 of "op_flags". "sv" gives the SV to embed in the op; this function
9682 takes ownership of one reference to it.
9683 OP * newSVOP(I32 type, I32 flags, SV *sv)
9685 "newTRYCATCHOP"
9687 NOTE: "newTRYCATCHOP" is experimental and may change or be removed
9688 without notice.
9689 Constructs and returns a conditional execution statement that
9691 implements the "try"/"catch" semantics. First the op tree in
9692 "tryblock" is executed, inside a context that traps exceptions. If
9693 an exception occurs then the optree in "catchblock" is executed,
9694 with the trapped exception set into the lexical variable given by
9695 "catchvar" (which must be an op of type "OP_PADSV"). All the
9696 optrees are consumed by this function and become part of the
9697 returned op tree.
9698 The "flags" argument is currently ignored.
9700 OP * newTRYCATCHOP(I32 flags, OP *tryblock, OP *catchvar,
9702 OP *catchblock)
9703 "newUNOP"
9705 Constructs, checks, and returns an op of any unary type. "type" is
9706 the opcode. "flags" gives the eight bits of "op_flags", except
9707 that "OPf_KIDS" will be set automatically if required, and, shifted
9708 up eight bits, the eight bits of "op_private", except that the bit
9709 with value 1 is automatically set. "first" supplies an optional op
9710 to be the direct child of the unary op; it is consumed by this
9711 function and become part of the constructed op tree.
9712 OP * newUNOP(I32 type, I32 flags, OP *first)
9714 "newUNOP_AUX"
9716 Similar to "newUNOP", but creates an "UNOP_AUX" struct instead,
9717 with "op_aux" initialised to "aux"
9718 OP * newUNOP_AUX(I32 type, I32 flags, OP *first,
9720 UNOP_AUX_item *aux)
9721 "newWHENOP"
9723 Constructs, checks, and returns an op tree expressing a "when"
9724 block. "cond" supplies the test expression, and "block" supplies
9725 the block that will be executed if the test evaluates to true; they
9726 are consumed by this function and become part of the constructed op
9727 tree. "cond" will be interpreted DWIMically, often as a comparison
9728 against $_, and may be null to generate a "default" block.
9729 OP * newWHENOP(OP *cond, OP *block)
9731 "newWHILEOP"
9733 Constructs, checks, and returns an op tree expressing a "while"
9734 loop. This is a heavyweight loop, with structure that allows
9735 exiting the loop by "last" and suchlike.
9736 "loop" is an optional preconstructed "enterloop" op to use in the
9738 loop; if it is null then a suitable op will be constructed
9739 automatically. "expr" supplies the loop's controlling expression.
9740 "block" supplies the main body of the loop, and "cont" optionally
9741 supplies a "continue" block that operates as a second half of the
9742 body. All of these optree inputs are consumed by this function and
9743 become part of the constructed op tree.
9744 "flags" gives the eight bits of "op_flags" for the "leaveloop" op
9746 and, shifted up eight bits, the eight bits of "op_private" for the
9747 "leaveloop" op, except that (in both cases) some bits will be set
9748 automatically. "debuggable" is currently unused and should always
9749 be 1. "has_my" can be supplied as true to force the loop body to
9750 be enclosed in its own scope.
9751 OP * newWHILEOP(I32 flags, I32 debuggable, LOOP *loop, OP *expr,
9753 OP *block, OP *cont, I32 has_my)
9754 "newXS"
9756 Used by "xsubpp" to hook up XSUBs as Perl subs. "filename" needs
9757 to be static storage, as it is used directly as CvFILE(), without a
9758 copy being made.
9759 "OA_BASEOP"
9761 "OA_BINOP"
9762 "OA_COP"
9763 "OA_LISTOP"
9764 "OA_LOGOP"
9765 "OA_LOOP"
9766 "OA_PADOP"
9767 "OA_PMOP"
9768 "OA_PVOP_OR_SVOP"
9769 "OA_SVOP"
9770 "OA_UNOP"
9771 Described in perlguts.
9772 "OP"
9774 Described in perlguts.
9775 "op_append_elem"
9777 Append an item to the list of ops contained directly within a list-
9778 type op, returning the lengthened list. "first" is the list-type
9779 op, and "last" is the op to append to the list. "optype" specifies
9780 the intended opcode for the list. If "first" is not already a list
9781 of the right type, it will be upgraded into one. If either "first"
9782 or "last" is null, the other is returned unchanged.
9783 OP * op_append_elem(I32 optype, OP *first, OP *last)
9785 "op_append_list"
9787 Concatenate the lists of ops contained directly within two list-
9788 type ops, returning the combined list. "first" and "last" are the
9789 list-type ops to concatenate. "optype" specifies the intended
9790 opcode for the list. If either "first" or "last" is not already a
9791 list of the right type, it will be upgraded into one. If either
9792 "first" or "last" is null, the other is returned unchanged.
9793 OP * op_append_list(I32 optype, OP *first, OP *last)
9795 "OP_CLASS"
9797 Return the class of the provided OP: that is, which of the *OP
9798 structures it uses. For core ops this currently gets the
9799 information out of "PL_opargs", which does not always accurately
9800 reflect the type used; in v5.26 onwards, see also the function
9801 "op_class" which can do a better job of determining the used type.
9802 For custom ops the type is returned from the registration, and it
9804 is up to the registree to ensure it is accurate. The value
9805 returned will be one of the "OA_"* constants from op.h.
9806 U32 OP_CLASS(OP *o)
9808 "op_contextualize"
9810 Applies a syntactic context to an op tree representing an
9811 expression. "o" is the op tree, and "context" must be "G_SCALAR",
9812 "G_LIST", or "G_VOID" to specify the context to apply. The
9813 modified op tree is returned.
9814 OP * op_contextualize(OP *o, I32 context)
9816 "op_convert_list"
9818 Converts "o" into a list op if it is not one already, and then
9819 converts it into the specified "type", calling its check function,
9820 allocating a target if it needs one, and folding constants.
9821 A list-type op is usually constructed one kid at a time via
9823 "newLISTOP", "op_prepend_elem" and "op_append_elem". Then finally
9824 it is passed to "op_convert_list" to make it the right type.
9825 OP * op_convert_list(I32 optype, I32 flags, OP *o)
9827 "OP_DESC"
9829 Return a short description of the provided OP.
9830 const char * OP_DESC(OP *o)
9832 "op_force_list"
9834 Promotes o and any siblings to be an "OP_LIST" if it is not
9835 already. If a new "OP_LIST" op was created, its first child will be
9836 "OP_PUSHMARK". The returned node itself will be nulled, leaving
9837 only its children.
9838 This is often what you want to do before putting the optree into
9840 list context; as
9841 o = op_contextualize(op_force_list(o), G_LIST);
9843 OP * op_force_list(OP *o)
9845 "op_free"
9847 Free an op and its children. Only use this when an op is no longer
9848 linked to from any optree.
9849 Remember that any op with "OPf_KIDS" set is expected to have a
9851 valid "op_first" pointer. If you are attempting to free an op but
9852 preserve its child op, make sure to clear that flag before calling
9853 op_free(). For example:
9854 OP *kid = o->op_first; o->op_first = NULL;
9856 o->op_flags &= ~OPf_KIDS;
9857 op_free(o);
9858 void op_free(OP *arg)
9860 "OpHAS_SIBLING"
9862 Returns true if "o" has a sibling
9863 bool OpHAS_SIBLING(OP *o)
9865 "OpLASTSIB_set"
9867 Marks "o" as having no further siblings and marks o as having the
9868 specified parent. See also "OpMORESIB_set" and "OpMAYBESIB_set".
9869 For a higher-level interface, see "op_sibling_splice".
9870 void OpLASTSIB_set(OP *o, OP *parent)
9872 "op_linklist"
9874 This function is the implementation of the "LINKLIST" macro. It
9875 should not be called directly.
9876 OP * op_linklist(OP *o)
9878 "op_lvalue"
9880 NOTE: "op_lvalue" is experimental and may change or be removed
9881 without notice.
9882 Propagate lvalue ("modifiable") context to an op and its children.
9884 "type" represents the context type, roughly based on the type of op
9885 that would do the modifying, although local() is represented by
9886 "OP_NULL", because it has no op type of its own (it is signalled by
9887 a flag on the lvalue op).
9888 This function detects things that can't be modified, such as
9890 "$x+1", and generates errors for them. For example, "$x+1 = 2"
9891 would cause it to be called with an op of type "OP_ADD" and a
9892 "type" argument of "OP_SASSIGN".
9893 It also flags things that need to behave specially in an lvalue
9895 context, such as "$$x = 5" which might have to vivify a reference
9896 in $x.
9897 OP * op_lvalue(OP *o, I32 type)
9899 "OpMAYBESIB_set"
9901 Conditionally does "OpMORESIB_set" or "OpLASTSIB_set" depending on
9902 whether "sib" is non-null. For a higher-level interface, see
9903 "op_sibling_splice".
9904 void OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
9906 "OpMORESIB_set"
9908 Sets the sibling of "o" to the non-zero value "sib". See also
9909 "OpLASTSIB_set" and "OpMAYBESIB_set". For a higher-level interface,
9910 see "op_sibling_splice".
9911 void OpMORESIB_set(OP *o, OP *sib)
9913 "OP_NAME"
9915 Return the name of the provided OP. For core ops this looks up the
9916 name from the op_type; for custom ops from the op_ppaddr.
9917 const char * OP_NAME(OP *o)
9919 "op_null"
9921 Neutralizes an op when it is no longer needed, but is still linked
9922 to from other ops.
9923 void op_null(OP *o)
9925 "op_parent"
9927 Returns the parent OP of "o", if it has a parent. Returns "NULL"
9928 otherwise.
9929 OP * op_parent(OP *o)
9931 "op_prepend_elem"
9933 Prepend an item to the list of ops contained directly within a
9934 list-type op, returning the lengthened list. "first" is the op to
9935 prepend to the list, and "last" is the list-type op. "optype"
9936 specifies the intended opcode for the list. If "last" is not
9937 already a list of the right type, it will be upgraded into one. If
9938 either "first" or "last" is null, the other is returned unchanged.
9939 OP * op_prepend_elem(I32 optype, OP *first, OP *last)
9941 "op_scope"
9943 NOTE: "op_scope" is experimental and may change or be removed
9944 without notice.
9945 Wraps up an op tree with some additional ops so that at runtime a
9947 dynamic scope will be created. The original ops run in the new
9948 dynamic scope, and then, provided that they exit normally, the
9949 scope will be unwound. The additional ops used to create and
9950 unwind the dynamic scope will normally be an "enter"/"leave" pair,
9951 but a "scope" op may be used instead if the ops are simple enough
9952 to not need the full dynamic scope structure.
9953 OP * op_scope(OP *o)
9955 "OpSIBLING"
9957 Returns the sibling of "o", or "NULL" if there is no sibling
9958 OP* OpSIBLING(OP *o)
9960 "op_sibling_splice"
9962 A general function for editing the structure of an existing chain
9963 of op_sibling nodes. By analogy with the perl-level splice()
9964 function, allows you to delete zero or more sequential nodes,
9965 replacing them with zero or more different nodes. Performs the
9966 necessary op_first/op_last housekeeping on the parent node and
9967 op_sibling manipulation on the children. The last deleted node
9968 will be marked as the last node by updating the
9969 op_sibling/op_sibparent or op_moresib field as appropriate.
9970 Note that op_next is not manipulated, and nodes are not freed; that
9972 is the responsibility of the caller. It also won't create a new
9973 list op for an empty list etc; use higher-level functions like
9974 op_append_elem() for that.
9975 "parent" is the parent node of the sibling chain. It may passed as
9977 "NULL" if the splicing doesn't affect the first or last op in the
9978 chain.
9979 "start" is the node preceding the first node to be spliced.
9981 Node(s) following it will be deleted, and ops will be inserted
9982 after it. If it is "NULL", the first node onwards is deleted, and
9983 nodes are inserted at the beginning.
9984 "del_count" is the number of nodes to delete. If zero, no nodes
9986 are deleted. If -1 or greater than or equal to the number of
9987 remaining kids, all remaining kids are deleted.
9988 "insert" is the first of a chain of nodes to be inserted in place
9990 of the nodes. If "NULL", no nodes are inserted.
9991 The head of the chain of deleted ops is returned, or "NULL" if no
9993 ops were deleted.
9994 For example:
9996 action before after returns
9998 ------ ----- ----- -------
9999 P P
10001 splice(P, A, 2, X-Y-Z) | | B-C
10002 A-B-C-D A-X-Y-Z-D
10003 P P
10005 splice(P, NULL, 1, X-Y) | | A
10006 A-B-C-D X-Y-B-C-D
10007 P P
10009 splice(P, NULL, 3, NULL) | | A-B-C
10010 A-B-C-D D
10011 P P
10013 splice(P, B, 0, X-Y) | | NULL
10014 A-B-C-D A-B-X-Y-C-D
10015 For lower-level direct manipulation of "op_sibparent" and
10017 "op_moresib", see "OpMORESIB_set", "OpLASTSIB_set",
10018 "OpMAYBESIB_set".
10019 OP * op_sibling_splice(OP *parent, OP *start, int del_count,
10021 OP *insert)
10022 "optimize_optree"
10024 This function applies some optimisations to the optree in top-down
10025 order. It is called before the peephole optimizer, which processes
10026 ops in execution order. Note that finalize_optree() also does a
10027 top-down scan, but is called *after* the peephole optimizer.
10028 void optimize_optree(OP *o)
10030 "OP_TYPE_IS"
10032 Returns true if the given OP is not a "NULL" pointer and if it is
10033 of the given type.
10034 The negation of this macro, "OP_TYPE_ISNT" is also available as
10036 well as "OP_TYPE_IS_NN" and "OP_TYPE_ISNT_NN" which elide the NULL
10037 pointer check.
10038 bool OP_TYPE_IS(OP *o, Optype type)
10040 "OP_TYPE_IS_OR_WAS"
10042 Returns true if the given OP is not a NULL pointer and if it is of
10043 the given type or used to be before being replaced by an OP of type
10044 OP_NULL.
10045 The negation of this macro, "OP_TYPE_ISNT_AND_WASNT" is also
10047 available as well as "OP_TYPE_IS_OR_WAS_NN" and
10048 "OP_TYPE_ISNT_AND_WASNT_NN" which elide the "NULL" pointer check.
10049 bool OP_TYPE_IS_OR_WAS(OP *o, Optype type)
10051 "op_wrap_finally"
10053 NOTE: "op_wrap_finally" is experimental and may change or be
10054 removed without notice.
10055 Wraps the given "block" optree fragment in its own scoped block,
10057 arranging for the "finally" optree fragment to be invoked when
10058 leaving that block for any reason. Both optree fragments are
10059 consumed and the combined result is returned.
10060 OP * op_wrap_finally(OP *block, OP *finally)
10062 "peep_t"
10064 Described in perlguts.
10065 "Perl_cpeep_t"
10067 Described in perlguts.
10068 "PL_opfreehook"
10070 When non-"NULL", the function pointed by this variable will be
10071 called each time an OP is freed with the corresponding OP as the
10072 argument. This allows extensions to free any extra attribute they
10073 have locally attached to an OP. It is also assured to first fire
10074 for the parent OP and then for its kids.
10075 When you replace this variable, it is considered a good practice to
10077 store the possibly previously installed hook and that you recall it
10078 inside your own.
10079 On threaded perls, each thread has an independent copy of this
10081 variable; each initialized at creation time with the current value
10082 of the creating thread's copy.
10083 Perl_ophook_t PL_opfreehook
10085 "PL_peepp"
10087 Pointer to the per-subroutine peephole optimiser. This is a
10088 function that gets called at the end of compilation of a Perl
10089 subroutine (or equivalently independent piece of Perl code) to
10090 perform fixups of some ops and to perform small-scale
10091 optimisations. The function is called once for each subroutine
10092 that is compiled, and is passed, as sole parameter, a pointer to
10093 the op that is the entry point to the subroutine. It modifies the
10094 op tree in place.
10095 The peephole optimiser should never be completely replaced.
10097 Rather, add code to it by wrapping the existing optimiser. The
10098 basic way to do this can be seen in "Compile pass 3: peephole
10099 optimization" in perlguts. If the new code wishes to operate on
10100 ops throughout the subroutine's structure, rather than just at the
10101 top level, it is likely to be more convenient to wrap the
10102 "PL_rpeepp" hook.
10103 On threaded perls, each thread has an independent copy of this
10105 variable; each initialized at creation time with the current value
10106 of the creating thread's copy.
10107 peep_t PL_peepp
10109 "PL_rpeepp"
10111 Pointer to the recursive peephole optimiser. This is a function
10112 that gets called at the end of compilation of a Perl subroutine (or
10113 equivalently independent piece of Perl code) to perform fixups of
10114 some ops and to perform small-scale optimisations. The function is
10115 called once for each chain of ops linked through their "op_next"
10116 fields; it is recursively called to handle each side chain. It is
10117 passed, as sole parameter, a pointer to the op that is at the head
10118 of the chain. It modifies the op tree in place.
10119 The peephole optimiser should never be completely replaced.
10121 Rather, add code to it by wrapping the existing optimiser. The
10122 basic way to do this can be seen in "Compile pass 3: peephole
10123 optimization" in perlguts. If the new code wishes to operate only
10124 on ops at a subroutine's top level, rather than throughout the
10125 structure, it is likely to be more convenient to wrap the
10126 "PL_peepp" hook.
10127 On threaded perls, each thread has an independent copy of this
10129 variable; each initialized at creation time with the current value
10130 of the creating thread's copy.
10131 peep_t PL_rpeepp
10133 "PMOP"
10135 Described in perlguts.
10136 "rv2cv_op_cv"
10138 Examines an op, which is expected to identify a subroutine at
10139 runtime, and attempts to determine at compile time which subroutine
10140 it identifies. This is normally used during Perl compilation to
10141 determine whether a prototype can be applied to a function call.
10142 "cvop" is the op being considered, normally an "rv2cv" op. A
10143 pointer to the identified subroutine is returned, if it could be
10144 determined statically, and a null pointer is returned if it was not
10145 possible to determine statically.
10146 Currently, the subroutine can be identified statically if the RV
10148 that the "rv2cv" is to operate on is provided by a suitable "gv" or
10149 "const" op. A "gv" op is suitable if the GV's CV slot is
10150 populated. A "const" op is suitable if the constant value must be
10151 an RV pointing to a CV. Details of this process may change in
10152 future versions of Perl. If the "rv2cv" op has the
10153 "OPpENTERSUB_AMPER" flag set then no attempt is made to identify
10154 the subroutine statically: this flag is used to suppress compile-
10155 time magic on a subroutine call, forcing it to use default runtime
10156 behaviour.
10157 If "flags" has the bit "RV2CVOPCV_MARK_EARLY" set, then the
10159 handling of a GV reference is modified. If a GV was examined and
10160 its CV slot was found to be empty, then the "gv" op has the
10161 "OPpEARLY_CV" flag set. If the op is not optimised away, and the
10162 CV slot is later populated with a subroutine having a prototype,
10163 that flag eventually triggers the warning "called too early to
10164 check prototype".
10165 If "flags" has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then instead
10167 of returning a pointer to the subroutine it returns a pointer to
10168 the GV giving the most appropriate name for the subroutine in this
10169 context. Normally this is just the "CvGV" of the subroutine, but
10170 for an anonymous ("CvANON") subroutine that is referenced through a
10171 GV it will be the referencing GV. The resulting "GV*" is cast to
10172 "CV*" to be returned. A null pointer is returned as usual if there
10173 is no statically-determinable subroutine.
10174 CV * rv2cv_op_cv(OP *cvop, U32 flags)
10176 "UNOP"
10178 Described in perlguts.
10179 "XOP"
10181 Described in perlguts.
10182
10184 "packlist"
10185 The engine implementing pack() Perl function.
10186 void packlist(SV *cat, const char *pat, const char *patend,
10188 SV **beglist, SV **endlist)
10189 "unpackstring"
10191 The engine implementing the unpack() Perl function.
10192 Using the template "pat..patend", this function unpacks the string
10194 "s..strend" into a number of mortal SVs, which it pushes onto the
10195 perl argument (@_) stack (so you will need to issue a "PUTBACK"
10196 before and "SPAGAIN" after the call to this function). It returns
10197 the number of pushed elements.
10198 The "strend" and "patend" pointers should point to the byte
10200 following the last character of each string.
10201 Although this function returns its values on the perl argument
10203 stack, it doesn't take any parameters from that stack (and thus in
10204 particular there's no need to do a "PUSHMARK" before calling it,
10205 unlike "call_pv" for example).
10206 SSize_t unpackstring(const char *pat, const char *patend,
10208 const char *s, const char *strend,
10209 U32 flags)
10210
10212 "CvPADLIST"
10213 NOTE: "CvPADLIST" is experimental and may change or be removed
10214 without notice.
10215 CV's can have CvPADLIST(cv) set to point to a PADLIST. This is the
10217 CV's scratchpad, which stores lexical variables and opcode
10218 temporary and per-thread values.
10219 For these purposes "formats" are a kind-of CV; eval""s are too
10221 (except they're not callable at will and are always thrown away
10222 after the eval"" is done executing). Require'd files are simply
10223 evals without any outer lexical scope.
10224 XSUBs do not have a "CvPADLIST". "dXSTARG" fetches values from
10226 "PL_curpad", but that is really the callers pad (a slot of which is
10227 allocated by every entersub). Do not get or set "CvPADLIST" if a CV
10228 is an XSUB (as determined by CvISXSUB()), "CvPADLIST" slot is
10229 reused for a different internal purpose in XSUBs.
10230 The PADLIST has a C array where pads are stored.
10232 The 0th entry of the PADLIST is a PADNAMELIST which represents the
10234 "names" or rather the "static type information" for lexicals. The
10235 individual elements of a PADNAMELIST are PADNAMEs. Future
10236 refactorings might stop the PADNAMELIST from being stored in the
10237 PADLIST's array, so don't rely on it. See "PadlistNAMES".
10238 The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the
10240 stack frame at that depth of recursion into the CV. The 0th slot
10241 of a frame AV is an AV which is @_. Other entries are storage for
10242 variables and op targets.
10243 Iterating over the PADNAMELIST iterates over all possible pad
10245 items. Pad slots for targets ("SVs_PADTMP") and GVs end up having
10246 &PL_padname_undef "names", while slots for constants have
10247 &PL_padname_const "names" (see "pad_alloc"). That
10248 &PL_padname_undef and &PL_padname_const are used is an
10249 implementation detail subject to change. To test for them, use
10250 "!PadnamePV(name)" and "PadnamePV(name) && !PadnameLEN(name)",
10251 respectively.
10252 Only "my"/"our" variable slots get valid names. The rest are op
10254 targets/GVs/constants which are statically allocated or resolved at
10255 compile time. These don't have names by which they can be looked
10256 up from Perl code at run time through eval"" the way "my"/"our"
10257 variables can be. Since they can't be looked up by "name" but only
10258 by their index allocated at compile time (which is usually in
10259 "PL_op->op_targ"), wasting a name SV for them doesn't make sense.
10260 The pad names in the PADNAMELIST have their PV holding the name of
10262 the variable. The "COP_SEQ_RANGE_LOW" and "_HIGH" fields form a
10263 range (low+1..high inclusive) of cop_seq numbers for which the name
10264 is valid. During compilation, these fields may hold the special
10265 value PERL_PADSEQ_INTRO to indicate various stages:
10266 COP_SEQ_RANGE_LOW _HIGH
10268 ----------------- -----
10269 PERL_PADSEQ_INTRO 0 variable not yet introduced:
10270 { my ($x
10271 valid-seq# PERL_PADSEQ_INTRO variable in scope:
10272 { my ($x);
10273 valid-seq# valid-seq# compilation of scope complete:
10274 { my ($x); .... }
10275 When a lexical var hasn't yet been introduced, it already exists
10277 from the perspective of duplicate declarations, but not for
10278 variable lookups, e.g.
10279 my ($x, $x); # '"my" variable $x masks earlier declaration'
10281 my $x = $x; # equal to my $x = $::x;
10282 For typed lexicals "PadnameTYPE" points at the type stash. For
10284 "our" lexicals, "PadnameOURSTASH" points at the stash of the
10285 associated global (so that duplicate "our" declarations in the same
10286 package can be detected). "PadnameGEN" is sometimes used to store
10287 the generation number during compilation.
10288 If "PadnameOUTER" is set on the pad name, then that slot in the
10290 frame AV is a REFCNT'ed reference to a lexical from "outside".
10291 Such entries are sometimes referred to as 'fake'. In this case,
10292 the name does not use 'low' and 'high' to store a cop_seq range,
10293 since it is in scope throughout. Instead 'high' stores some flags
10294 containing info about the real lexical (is it declared in an anon,
10295 and is it capable of being instantiated multiple times?), and for
10296 fake ANONs, 'low' contains the index within the parent's pad where
10297 the lexical's value is stored, to make cloning quicker.
10298 If the 'name' is "&" the corresponding entry in the PAD is a CV
10300 representing a possible closure.
10301 Note that formats are treated as anon subs, and are cloned each
10303 time write is called (if necessary).
10304 The flag "SVs_PADSTALE" is cleared on lexicals each time the my()
10306 is executed, and set on scope exit. This allows the "Variable $x
10307 is not available" warning to be generated in evals, such as
10308 { my $x = 1; sub f { eval '$x'} } f();
10310 For state vars, "SVs_PADSTALE" is overloaded to mean 'not yet
10312 initialised', but this internal state is stored in a separate pad
10313 entry.
10314 PADLIST * CvPADLIST(CV *cv)
10316 "pad_add_name_pvs"
10318 Exactly like "pad_add_name_pvn", but takes a literal string instead
10319 of a string/length pair.
10320 PADOFFSET pad_add_name_pvs("name", U32 flags, HV *typestash,
10322 HV *ourstash)
10323 "PadARRAY"
10325 NOTE: "PadARRAY" is experimental and may change or be removed
10326 without notice.
10327 The C array of pad entries.
10329 SV ** PadARRAY(PAD * pad)
10331 "pad_findmy_pvs"
10333 Exactly like "pad_findmy_pvn", but takes a literal string instead
10334 of a string/length pair.
10335 PADOFFSET pad_findmy_pvs("name", U32 flags)
10337 "PadlistARRAY"
10339 NOTE: "PadlistARRAY" is experimental and may change or be removed
10340 without notice.
10341 The C array of a padlist, containing the pads. Only subscript it
10343 with numbers >= 1, as the 0th entry is not guaranteed to remain
10344 usable.
10345 PAD ** PadlistARRAY(PADLIST * padlist)
10347 "PadlistMAX"
10349 NOTE: "PadlistMAX" is experimental and may change or be removed
10350 without notice.
10351 The index of the last allocated space in the padlist. Note that
10353 the last pad may be in an earlier slot. Any entries following it
10354 will be "NULL" in that case.
10355 SSize_t PadlistMAX(PADLIST * padlist)
10357 "PadlistNAMES"
10359 NOTE: "PadlistNAMES" is experimental and may change or be removed
10360 without notice.
10361 The names associated with pad entries.
10363 PADNAMELIST * PadlistNAMES(PADLIST * padlist)
10365 "PadlistNAMESARRAY"
10367 NOTE: "PadlistNAMESARRAY" is experimental and may change or be
10368 removed without notice.
10369 The C array of pad names.
10371 PADNAME ** PadlistNAMESARRAY(PADLIST * padlist)
10373 "PadlistNAMESMAX"
10375 NOTE: "PadlistNAMESMAX" is experimental and may change or be
10376 removed without notice.
10377 The index of the last pad name.
10379 SSize_t PadlistNAMESMAX(PADLIST * padlist)
10381 "PadlistREFCNT"
10383 NOTE: "PadlistREFCNT" is experimental and may change or be removed
10384 without notice.
10385 The reference count of the padlist. Currently this is always 1.
10387 U32 PadlistREFCNT(PADLIST * padlist)
10389 "PadMAX"
10391 NOTE: "PadMAX" is experimental and may change or be removed without
10392 notice.
10393 The index of the last pad entry.
10395 SSize_t PadMAX(PAD * pad)
10397 "PadnameLEN"
10399 NOTE: "PadnameLEN" is experimental and may change or be removed
10400 without notice.
10401 The length of the name.
10403 STRLEN PadnameLEN(PADNAME * pn)
10405 "PadnamelistARRAY"
10407 NOTE: "PadnamelistARRAY" is experimental and may change or be
10408 removed without notice.
10409 The C array of pad names.
10411 PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl)
10413 "PadnamelistMAX"
10415 NOTE: "PadnamelistMAX" is experimental and may change or be removed
10416 without notice.
10417 The index of the last pad name.
10419 SSize_t PadnamelistMAX(PADNAMELIST * pnl)
10421 "PadnamelistREFCNT"
10423 NOTE: "PadnamelistREFCNT" is experimental and may change or be
10424 removed without notice.
10425 The reference count of the pad name list.
10427 SSize_t PadnamelistREFCNT(PADNAMELIST * pnl)
10429 "PadnamelistREFCNT_dec"
10431 NOTE: "PadnamelistREFCNT_dec" is experimental and may change or be
10432 removed without notice.
10433 Lowers the reference count of the pad name list.
10435 void PadnamelistREFCNT_dec(PADNAMELIST * pnl)
10437 "PadnamePV"
10439 NOTE: "PadnamePV" is experimental and may change or be removed
10440 without notice.
10441 The name stored in the pad name struct. This returns "NULL" for a
10443 target slot.
10444 char * PadnamePV(PADNAME * pn)
10446 "PadnameREFCNT"
10448 NOTE: "PadnameREFCNT" is experimental and may change or be removed
10449 without notice.
10450 The reference count of the pad name.
10452 SSize_t PadnameREFCNT(PADNAME * pn)
10454 "PadnameREFCNT_dec"
10456 NOTE: "PadnameREFCNT_dec" is experimental and may change or be
10457 removed without notice.
10458 Lowers the reference count of the pad name.
10460 void PadnameREFCNT_dec(PADNAME * pn)
10462 "PadnameREFCNT_inc"
10464 NOTE: "PadnameREFCNT_inc" is experimental and may change or be
10465 removed without notice.
10466 Increases the reference count of the pad name. Returns the pad
10468 name itself.
10469 PADNAME * PadnameREFCNT_inc(PADNAME * pn)
10471 "PadnameSV"
10473 NOTE: "PadnameSV" is experimental and may change or be removed
10474 without notice.
10475 Returns the pad name as a mortal SV.
10477 SV * PadnameSV(PADNAME * pn)
10479 "PadnameUTF8"
10481 NOTE: "PadnameUTF8" is experimental and may change or be removed
10482 without notice.
10483 Whether PadnamePV is in UTF-8. Currently, this is always true.
10485 bool PadnameUTF8(PADNAME * pn)
10487 "pad_new"
10489 Create a new padlist, updating the global variables for the
10490 currently-compiling padlist to point to the new padlist. The
10491 following flags can be OR'ed together:
10492 padnew_CLONE this pad is for a cloned CV
10494 padnew_SAVE save old globals on the save stack
10495 padnew_SAVESUB also save extra stuff for start of sub
10496 PADLIST * pad_new(int flags)
10498 "PL_comppad"
10500 NOTE: "PL_comppad" is experimental and may change or be removed
10501 without notice.
10502 During compilation, this points to the array containing the values
10504 part of the pad for the currently-compiling code. (At runtime a CV
10505 may have many such value arrays; at compile time just one is
10506 constructed.) At runtime, this points to the array containing the
10507 currently-relevant values for the pad for the currently-executing
10508 code.
10509 "PL_comppad_name"
10511 NOTE: "PL_comppad_name" is experimental and may change or be
10512 removed without notice.
10513 During compilation, this points to the array containing the names
10515 part of the pad for the currently-compiling code.
10516 "PL_curpad"
10518 NOTE: "PL_curpad" is experimental and may change or be removed
10519 without notice.
10520 Points directly to the body of the "PL_comppad" array. (I.e., this
10522 is PadARRAY(PL_comppad).)
10523 "SVs_PADMY"
10525 "DEPRECATED!" It is planned to remove "SVs_PADMY" from a future
10526 release of Perl. Do not use it for new code; remove it from
10527 existing code.
10528 Described in perlguts.
10530 "SVs_PADTMP"
10532 Described in perlguts.
10533
10535 "GRPASSWD"
10536 This symbol, if defined, indicates to the C program that "struct
10537 group" in grp.h contains "gr_passwd".
10538 "HAS_ENDGRENT"
10540 This symbol, if defined, indicates that the getgrent routine is
10541 available for finalizing sequential access of the group database.
10542 "HAS_ENDGRENT_R"
10544 This symbol, if defined, indicates that the "endgrent_r" routine is
10545 available to endgrent re-entrantly.
10546 "HAS_ENDPWENT"
10548 This symbol, if defined, indicates that the "endpwent" routine is
10549 available for finalizing sequential access of the passwd database.
10550 "HAS_ENDPWENT_R"
10552 This symbol, if defined, indicates that the "endpwent_r" routine is
10553 available to endpwent re-entrantly.
10554 "HAS_GETGRENT"
10556 This symbol, if defined, indicates that the "getgrent" routine is
10557 available for sequential access of the group database.
10558 "HAS_GETGRENT_R"
10560 This symbol, if defined, indicates that the "getgrent_r" routine is
10561 available to getgrent re-entrantly.
10562 "HAS_GETPWENT"
10564 This symbol, if defined, indicates that the "getpwent" routine is
10565 available for sequential access of the passwd database. If this is
10566 not available, the older getpw() function may be available.
10567 "HAS_GETPWENT_R"
10569 This symbol, if defined, indicates that the "getpwent_r" routine is
10570 available to getpwent re-entrantly.
10571 "HAS_SETGRENT"
10573 This symbol, if defined, indicates that the "setgrent" routine is
10574 available for initializing sequential access of the group database.
10575 "HAS_SETGRENT_R"
10577 This symbol, if defined, indicates that the "setgrent_r" routine is
10578 available to setgrent re-entrantly.
10579 "HAS_SETPWENT"
10581 This symbol, if defined, indicates that the "setpwent" routine is
10582 available for initializing sequential access of the passwd
10583 database.
10584 "HAS_SETPWENT_R"
10586 This symbol, if defined, indicates that the "setpwent_r" routine is
10587 available to setpwent re-entrantly.
10588 "PWAGE"
10590 This symbol, if defined, indicates to the C program that "struct
10591 passwd" contains "pw_age".
10592 "PWCHANGE"
10594 This symbol, if defined, indicates to the C program that "struct
10595 passwd" contains "pw_change".
10596 "PWCLASS"
10598 This symbol, if defined, indicates to the C program that "struct
10599 passwd" contains "pw_class".
10600 "PWCOMMENT"
10602 This symbol, if defined, indicates to the C program that "struct
10603 passwd" contains "pw_comment".
10604 "PWEXPIRE"
10606 This symbol, if defined, indicates to the C program that "struct
10607 passwd" contains "pw_expire".
10608 "PWGECOS"
10610 This symbol, if defined, indicates to the C program that "struct
10611 passwd" contains "pw_gecos".
10612 "PWPASSWD"
10614 This symbol, if defined, indicates to the C program that "struct
10615 passwd" contains "pw_passwd".
10616 "PWQUOTA"
10618 This symbol, if defined, indicates to the C program that "struct
10619 passwd" contains "pw_quota".
10620
10622 "CSH"
10623 This symbol, if defined, contains the full pathname of csh.
10624 "LOC_SED"
10626 This symbol holds the complete pathname to the sed program.
10627 "SH_PATH"
10629 This symbol contains the full pathname to the shell used on this on
10630 this system to execute Bourne shell scripts. Usually, this will be
10631 /bin/sh, though it's possible that some systems will have /bin/ksh,
10632 /bin/pdksh, /bin/ash, /bin/bash, or even something such as
10633 D:/bin/sh.exe.
10634
10636 "CRYPT_R_PROTO"
10637 This symbol encodes the prototype of "crypt_r". It is zero if
10638 "d_crypt_r" is undef, and one of the "REENTRANT_PROTO_T_ABC" macros
10639 of reentr.h if "d_crypt_r" is defined.
10640 "CTERMID_R_PROTO"
10642 This symbol encodes the prototype of "ctermid_r". It is zero if
10643 "d_ctermid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10644 macros of reentr.h if "d_ctermid_r" is defined.
10645 "DRAND48_R_PROTO"
10647 This symbol encodes the prototype of "drand48_r". It is zero if
10648 "d_drand48_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10649 macros of reentr.h if "d_drand48_r" is defined.
10650 "ENDGRENT_R_PROTO"
10652 This symbol encodes the prototype of "endgrent_r". It is zero if
10653 "d_endgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10654 macros of reentr.h if "d_endgrent_r" is defined.
10655 "ENDHOSTENT_R_PROTO"
10657 This symbol encodes the prototype of "endhostent_r". It is zero if
10658 "d_endhostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10659 macros of reentr.h if "d_endhostent_r" is defined.
10660 "ENDNETENT_R_PROTO"
10662 This symbol encodes the prototype of "endnetent_r". It is zero if
10663 "d_endnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10664 macros of reentr.h if "d_endnetent_r" is defined.
10665 "ENDPROTOENT_R_PROTO"
10667 This symbol encodes the prototype of "endprotoent_r". It is zero
10668 if "d_endprotoent_r" is undef, and one of the
10669 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_endprotoent_r" is
10670 defined.
10671 "ENDPWENT_R_PROTO"
10673 This symbol encodes the prototype of "endpwent_r". It is zero if
10674 "d_endpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10675 macros of reentr.h if "d_endpwent_r" is defined.
10676 "ENDSERVENT_R_PROTO"
10678 This symbol encodes the prototype of "endservent_r". It is zero if
10679 "d_endservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10680 macros of reentr.h if "d_endservent_r" is defined.
10681 "GDBMNDBM_H_USES_PROTOTYPES"
10683 This symbol, if defined, indicates that gdbm/ndbm.h uses real
10684 "ANSI" C prototypes instead of K&R style function declarations
10685 without any parameter information. While "ANSI" C prototypes are
10686 supported in C++, K&R style function declarations will yield
10687 errors.
10688 "GDBM_NDBM_H_USES_PROTOTYPES"
10690 This symbol, if defined, indicates that <gdbm-ndbm.h> uses real
10691 "ANSI" C prototypes instead of K&R style function declarations
10692 without any parameter information. While "ANSI" C prototypes are
10693 supported in C++, K&R style function declarations will yield
10694 errors.
10695 "GETGRENT_R_PROTO"
10697 This symbol encodes the prototype of "getgrent_r". It is zero if
10698 "d_getgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10699 macros of reentr.h if "d_getgrent_r" is defined.
10700 "GETGRGID_R_PROTO"
10702 This symbol encodes the prototype of "getgrgid_r". It is zero if
10703 "d_getgrgid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10704 macros of reentr.h if "d_getgrgid_r" is defined.
10705 "GETGRNAM_R_PROTO"
10707 This symbol encodes the prototype of "getgrnam_r". It is zero if
10708 "d_getgrnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10709 macros of reentr.h if "d_getgrnam_r" is defined.
10710 "GETHOSTBYADDR_R_PROTO"
10712 This symbol encodes the prototype of "gethostbyaddr_r". It is zero
10713 if "d_gethostbyaddr_r" is undef, and one of the
10714 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_gethostbyaddr_r"
10715 is defined.
10716 "GETHOSTBYNAME_R_PROTO"
10718 This symbol encodes the prototype of "gethostbyname_r". It is zero
10719 if "d_gethostbyname_r" is undef, and one of the
10720 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_gethostbyname_r"
10721 is defined.
10722 "GETHOSTENT_R_PROTO"
10724 This symbol encodes the prototype of "gethostent_r". It is zero if
10725 "d_gethostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10726 macros of reentr.h if "d_gethostent_r" is defined.
10727 "GETLOGIN_R_PROTO"
10729 This symbol encodes the prototype of "getlogin_r". It is zero if
10730 "d_getlogin_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10731 macros of reentr.h if "d_getlogin_r" is defined.
10732 "GETNETBYADDR_R_PROTO"
10734 This symbol encodes the prototype of "getnetbyaddr_r". It is zero
10735 if "d_getnetbyaddr_r" is undef, and one of the
10736 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getnetbyaddr_r" is
10737 defined.
10738 "GETNETBYNAME_R_PROTO"
10740 This symbol encodes the prototype of "getnetbyname_r". It is zero
10741 if "d_getnetbyname_r" is undef, and one of the
10742 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getnetbyname_r" is
10743 defined.
10744 "GETNETENT_R_PROTO"
10746 This symbol encodes the prototype of "getnetent_r". It is zero if
10747 "d_getnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10748 macros of reentr.h if "d_getnetent_r" is defined.
10749 "GETPROTOBYNAME_R_PROTO"
10751 This symbol encodes the prototype of "getprotobyname_r". It is
10752 zero if "d_getprotobyname_r" is undef, and one of the
10753 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getprotobyname_r"
10754 is defined.
10755 "GETPROTOBYNUMBER_R_PROTO"
10757 This symbol encodes the prototype of "getprotobynumber_r". It is
10758 zero if "d_getprotobynumber_r" is undef, and one of the
10759 "REENTRANT_PROTO_T_ABC" macros of reentr.h if
10760 "d_getprotobynumber_r" is defined.
10761 "GETPROTOENT_R_PROTO"
10763 This symbol encodes the prototype of "getprotoent_r". It is zero
10764 if "d_getprotoent_r" is undef, and one of the
10765 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getprotoent_r" is
10766 defined.
10767 "GETPWENT_R_PROTO"
10769 This symbol encodes the prototype of "getpwent_r". It is zero if
10770 "d_getpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10771 macros of reentr.h if "d_getpwent_r" is defined.
10772 "GETPWNAM_R_PROTO"
10774 This symbol encodes the prototype of "getpwnam_r". It is zero if
10775 "d_getpwnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10776 macros of reentr.h if "d_getpwnam_r" is defined.
10777 "GETPWUID_R_PROTO"
10779 This symbol encodes the prototype of "getpwuid_r". It is zero if
10780 "d_getpwuid_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10781 macros of reentr.h if "d_getpwuid_r" is defined.
10782 "GETSERVBYNAME_R_PROTO"
10784 This symbol encodes the prototype of "getservbyname_r". It is zero
10785 if "d_getservbyname_r" is undef, and one of the
10786 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getservbyname_r"
10787 is defined.
10788 "GETSERVBYPORT_R_PROTO"
10790 This symbol encodes the prototype of "getservbyport_r". It is zero
10791 if "d_getservbyport_r" is undef, and one of the
10792 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_getservbyport_r"
10793 is defined.
10794 "GETSERVENT_R_PROTO"
10796 This symbol encodes the prototype of "getservent_r". It is zero if
10797 "d_getservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10798 macros of reentr.h if "d_getservent_r" is defined.
10799 "GETSPNAM_R_PROTO"
10801 This symbol encodes the prototype of "getspnam_r". It is zero if
10802 "d_getspnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10803 macros of reentr.h if "d_getspnam_r" is defined.
10804 "HAS_DBMINIT_PROTO"
10806 This symbol, if defined, indicates that the system provides a
10807 prototype for the dbminit() function. Otherwise, it is up to the
10808 program to supply one. A good guess is
10809 extern int dbminit(char *);
10811 "HAS_DRAND48_PROTO"
10813 This symbol, if defined, indicates that the system provides a
10814 prototype for the drand48() function. Otherwise, it is up to the
10815 program to supply one. A good guess is
10816 extern double drand48(void);
10818 "HAS_FLOCK_PROTO"
10820 This symbol, if defined, indicates that the system provides a
10821 prototype for the flock() function. Otherwise, it is up to the
10822 program to supply one. A good guess is
10823 extern int flock(int, int);
10825 "HAS_GETHOST_PROTOS"
10827 This symbol, if defined, indicates that netdb.h includes prototypes
10828 for gethostent(), gethostbyname(), and gethostbyaddr(). Otherwise,
10829 it is up to the program to guess them. See netdbtype.U (part of
10830 metaconfig) for probing for various "Netdb_xxx_t" types.
10831 "HAS_GETNET_PROTOS"
10833 This symbol, if defined, indicates that netdb.h includes prototypes
10834 for getnetent(), getnetbyname(), and getnetbyaddr(). Otherwise, it
10835 is up to the program to guess them. See netdbtype.U (part of
10836 metaconfig) for probing for various "Netdb_xxx_t" types.
10837 "HAS_GETPROTO_PROTOS"
10839 This symbol, if defined, indicates that netdb.h includes prototypes
10840 for getprotoent(), getprotobyname(), and getprotobyaddr().
10841 Otherwise, it is up to the program to guess them. See netdbtype.U
10842 (part of metaconfig) for probing for various "Netdb_xxx_t" types.
10843 "HAS_GETSERV_PROTOS"
10845 This symbol, if defined, indicates that netdb.h includes prototypes
10846 for getservent(), getservbyname(), and getservbyaddr(). Otherwise,
10847 it is up to the program to guess them. See netdbtype.U (part of
10848 metaconfig) for probing for various "Netdb_xxx_t" types.
10849 "HAS_MODFL_PROTO"
10851 This symbol, if defined, indicates that the system provides a
10852 prototype for the modfl() function. Otherwise, it is up to the
10853 program to supply one.
10854 "HAS_SBRK_PROTO"
10856 This symbol, if defined, indicates that the system provides a
10857 prototype for the sbrk() function. Otherwise, it is up to the
10858 program to supply one. Good guesses are
10859 extern void* sbrk(int);
10861 extern void* sbrk(size_t);
10862 "HAS_SETRESGID_PROTO"
10864 This symbol, if defined, indicates that the system provides a
10865 prototype for the setresgid() function. Otherwise, it is up to the
10866 program to supply one. Good guesses are
10867 extern int setresgid(uid_t ruid, uid_t euid, uid_t suid);
10869 "HAS_SETRESUID_PROTO"
10871 This symbol, if defined, indicates that the system provides a
10872 prototype for the setresuid() function. Otherwise, it is up to the
10873 program to supply one. Good guesses are
10874 extern int setresuid(uid_t ruid, uid_t euid, uid_t suid);
10876 "HAS_SHMAT_PROTOTYPE"
10878 This symbol, if defined, indicates that the sys/shm.h includes a
10879 prototype for shmat(). Otherwise, it is up to the program to guess
10880 one. "Shmat_t" "shmat(int, Shmat_t, int)" is a good guess, but not
10881 always right so it should be emitted by the program only when
10882 "HAS_SHMAT_PROTOTYPE" is not defined to avoid conflicting defs.
10883 "HAS_SOCKATMARK_PROTO"
10885 This symbol, if defined, indicates that the system provides a
10886 prototype for the sockatmark() function. Otherwise, it is up to
10887 the program to supply one. A good guess is
10888 extern int sockatmark(int);
10890 "HAS_SYSCALL_PROTO"
10892 This symbol, if defined, indicates that the system provides a
10893 prototype for the syscall() function. Otherwise, it is up to the
10894 program to supply one. Good guesses are
10895 extern int syscall(int, ...);
10897 extern int syscall(long, ...);
10898 "HAS_TELLDIR_PROTO"
10900 This symbol, if defined, indicates that the system provides a
10901 prototype for the telldir() function. Otherwise, it is up to the
10902 program to supply one. A good guess is
10903 extern long telldir(DIR*);
10905 "NDBM_H_USES_PROTOTYPES"
10907 This symbol, if defined, indicates that ndbm.h uses real "ANSI" C
10908 prototypes instead of K&R style function declarations without any
10909 parameter information. While "ANSI" C prototypes are supported in
10910 C++, K&R style function declarations will yield errors.
10911 "RANDOM_R_PROTO"
10913 This symbol encodes the prototype of "random_r". It is zero if
10914 "d_random_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10915 macros of reentr.h if "d_random_r" is defined.
10916 "READDIR_R_PROTO"
10918 This symbol encodes the prototype of "readdir_r". It is zero if
10919 "d_readdir_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10920 macros of reentr.h if "d_readdir_r" is defined.
10921 "SETGRENT_R_PROTO"
10923 This symbol encodes the prototype of "setgrent_r". It is zero if
10924 "d_setgrent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10925 macros of reentr.h if "d_setgrent_r" is defined.
10926 "SETHOSTENT_R_PROTO"
10928 This symbol encodes the prototype of "sethostent_r". It is zero if
10929 "d_sethostent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10930 macros of reentr.h if "d_sethostent_r" is defined.
10931 "SETLOCALE_R_PROTO"
10933 This symbol encodes the prototype of "setlocale_r". It is zero if
10934 "d_setlocale_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10935 macros of reentr.h if "d_setlocale_r" is defined.
10936 "SETNETENT_R_PROTO"
10938 This symbol encodes the prototype of "setnetent_r". It is zero if
10939 "d_setnetent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10940 macros of reentr.h if "d_setnetent_r" is defined.
10941 "SETPROTOENT_R_PROTO"
10943 This symbol encodes the prototype of "setprotoent_r". It is zero
10944 if "d_setprotoent_r" is undef, and one of the
10945 "REENTRANT_PROTO_T_ABC" macros of reentr.h if "d_setprotoent_r" is
10946 defined.
10947 "SETPWENT_R_PROTO"
10949 This symbol encodes the prototype of "setpwent_r". It is zero if
10950 "d_setpwent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10951 macros of reentr.h if "d_setpwent_r" is defined.
10952 "SETSERVENT_R_PROTO"
10954 This symbol encodes the prototype of "setservent_r". It is zero if
10955 "d_setservent_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10956 macros of reentr.h if "d_setservent_r" is defined.
10957 "SRANDOM_R_PROTO"
10959 This symbol encodes the prototype of "srandom_r". It is zero if
10960 "d_srandom_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10961 macros of reentr.h if "d_srandom_r" is defined.
10962 "SRAND48_R_PROTO"
10964 This symbol encodes the prototype of "srand48_r". It is zero if
10965 "d_srand48_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10966 macros of reentr.h if "d_srand48_r" is defined.
10967 "STRERROR_R_PROTO"
10969 This symbol encodes the prototype of "strerror_r". It is zero if
10970 "d_strerror_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10971 macros of reentr.h if "d_strerror_r" is defined.
10972 "TMPNAM_R_PROTO"
10974 This symbol encodes the prototype of "tmpnam_r". It is zero if
10975 "d_tmpnam_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10976 macros of reentr.h if "d_tmpnam_r" is defined.
10977 "TTYNAME_R_PROTO"
10979 This symbol encodes the prototype of "ttyname_r". It is zero if
10980 "d_ttyname_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
10981 macros of reentr.h if "d_ttyname_r" is defined.
10982
10984 "pregcomp"
10985 Described in perlreguts.
10986 REGEXP * pregcomp(SV * const pattern, const U32 flags)
10988 "pregexec"
10990 Described in perlreguts.
10991 I32 pregexec(REGEXP * const prog, char *stringarg, char *strend,
10993 char *strbeg, SSize_t minend, SV *screamer,
10994 U32 nosave)
10995 "re_compile"
10997 Compile the regular expression pattern "pattern", returning a
10998 pointer to the compiled object for later matching with the internal
10999 regex engine.
11000 This function is typically used by a custom regexp engine ".comp()"
11002 function to hand off to the core regexp engine those patterns it
11003 doesn't want to handle itself (typically passing through the same
11004 flags it was called with). In almost all other cases, a regexp
11005 should be compiled by calling ""pregcomp"" to compile using the
11006 currently active regexp engine.
11007 If "pattern" is already a "REGEXP", this function does nothing but
11009 return a pointer to the input. Otherwise the PV is extracted and
11010 treated like a string representing a pattern. See perlre.
11011 The possible flags for "rx_flags" are documented in perlreapi.
11013 Their names all begin with "RXf_".
11014 REGEXP * re_compile(SV * const pattern, U32 orig_rx_flags)
11016 "re_dup_guts"
11018 Duplicate a regexp.
11019 This routine is expected to clone a given regexp structure. It is
11021 only compiled under USE_ITHREADS.
11022 After all of the core data stored in struct regexp is duplicated
11024 the "regexp_engine.dupe" method is used to copy any private data
11025 stored in the *pprivate pointer. This allows extensions to handle
11026 any duplication they need to do.
11027 void re_dup_guts(const REGEXP *sstr, REGEXP *dstr,
11029 CLONE_PARAMS *param)
11030 "REGEX_LOCALE_CHARSET"
11032 Described in perlreapi.
11033 "REGEXP"
11035 Described in perlreapi.
11036 "regexp_engine"
11038 When a regexp is compiled, its "engine" field is then set to point
11039 at the appropriate structure, so that when it needs to be used Perl
11040 can find the right routines to do so.
11041 In order to install a new regexp handler, $^H{regcomp} is set to an
11043 integer which (when casted appropriately) resolves to one of these
11044 structures. When compiling, the "comp" method is executed, and the
11045 resulting "regexp" structure's engine field is expected to point
11046 back at the same structure.
11047 The pTHX_ symbol in the definition is a macro used by Perl under
11049 threading to provide an extra argument to the routine holding a
11050 pointer back to the interpreter that is executing the regexp. So
11051 under threading all routines get an extra argument.
11052 "regexp_paren_pair"
11054 Described in perlreapi.
11055 "regmatch_info"
11057 Some basic information about the current match that is created by
11058 Perl_regexec_flags and then passed to regtry(), regmatch() etc. It
11059 is allocated as a local var on the stack, so nothing should be
11060 stored in it that needs preserving or clearing up on croak(). For
11061 that, see the aux_info and aux_info_eval members of the
11062 regmatch_state union.
11063 "REXEC_COPY_SKIP_POST"
11065 "REXEC_COPY_SKIP_PRE"
11066 "REXEC_COPY_STR"
11067 Described in perlreapi.
11068 "RXapif_ALL"
11070 "RXapif_CLEAR"
11071 "RXapif_DELETE"
11072 "RXapif_EXISTS"
11073 "RXapif_FETCH"
11074 "RXapif_FIRSTKEY"
11075 "RXapif_NEXTKEY"
11076 "RXapif_ONE"
11077 "RXapif_REGNAME"
11078 "RXapif_REGNAMES"
11079 "RXapif_REGNAMES_COUNT"
11080 "RXapif_SCALAR"
11081 "RXapif_STORE"
11082 Described in perlreapi.
11083 "RX_BUFF_IDX_CARET_FULLMATCH"
11085 "RX_BUFF_IDX_CARET_POSTMATCH"
11086 "RX_BUFF_IDX_CARET_PREMATCH"
11087 "RX_BUFF_IDX_FULLMATCH"
11088 "RX_BUFF_IDX_POSTMATCH"
11089 "RX_BUFF_IDX_PREMATCH"
11090 Described in perlreapi.
11091 "RXf_NO_INPLACE_SUBST"
11093 "RXf_NULL"
11094 "RXf_SKIPWHITE"
11095 "RXf_SPLIT"
11096 "RXf_START_ONLY"
11097 "RXf_WHITE"
11098 Described in perlreapi.
11099 "RXf_PMf_EXTENDED"
11101 "RXf_PMf_FOLD"
11102 "RXf_PMf_KEEPCOPY"
11103 "RXf_PMf_MULTILINE"
11104 "RXf_PMf_SINGLELINE"
11105 Described in perlreapi.
11106 "RX_MATCH_COPIED"
11108 Described in perlreapi.
11109 RX_MATCH_COPIED(const REGEXP * rx)
11111 "RX_OFFS"
11113 Described in perlreapi.
11114 RX_OFFS(const REGEXP * rx_sv)
11116 "SvRX"
11118 Convenience macro to get the REGEXP from a SV. This is
11119 approximately equivalent to the following snippet:
11120 if (SvMAGICAL(sv))
11122 mg_get(sv);
11123 if (SvROK(sv))
11124 sv = MUTABLE_SV(SvRV(sv));
11125 if (SvTYPE(sv) == SVt_REGEXP)
11126 return (REGEXP*) sv;
11127 "NULL" will be returned if a REGEXP* is not found.
11129 REGEXP * SvRX(SV *sv)
11131 "SvRXOK"
11133 Returns a boolean indicating whether the SV (or the one it
11134 references) is a REGEXP.
11135 If you want to do something with the REGEXP* later use SvRX instead
11137 and check for NULL.
11138 bool SvRXOK(SV* sv)
11140 "SV_SAVED_COPY"
11142 Described in perlreapi.
11143
11145 These are used in the simple report generation feature of Perl. See
11146 perlform.
11147 "IoBOTTOM_GV"
11149 Described in perlguts.
11150 GV * IoBOTTOM_GV(IO *io)
11152 "IoBOTTOM_NAME"
11154 Described in perlguts.
11155 char * IoBOTTOM_NAME(IO *io)
11157 "IoFMT_GV"
11159 Described in perlguts.
11160 GV * IoFMT_GV(IO *io)
11162 "IoFMT_NAME"
11164 Described in perlguts.
11165 char * IoFMT_NAME(IO *io)
11167 "IoLINES"
11169 Described in perlguts.
11170 IV IoLINES(IO *io)
11172 "IoLINES_LEFT"
11174 Described in perlguts.
11175 IV IoLINES_LEFT(IO *io)
11177 "IoPAGE"
11179 Described in perlguts.
11180 IV IoPAGE(IO *io)
11182 "IoPAGE_LEN"
11184 Described in perlguts.
11185 IV IoPAGE_LEN(IO *io)
11187 "IoTOP_GV"
11189 Described in perlguts.
11190 GV * IoTOP_GV(IO *io)
11192 "IoTOP_NAME"
11194 Described in perlguts.
11195 char * IoTOP_NAME(IO *io)
11197
11199 "HAS_SIGINFO_SI_ADDR"
11200 This symbol, if defined, indicates that "siginfo_t" has the
11201 "si_addr" member
11202 "HAS_SIGINFO_SI_BAND"
11204 This symbol, if defined, indicates that "siginfo_t" has the
11205 "si_band" member
11206 "HAS_SIGINFO_SI_ERRNO"
11208 This symbol, if defined, indicates that "siginfo_t" has the
11209 "si_errno" member
11210 "HAS_SIGINFO_SI_PID"
11212 This symbol, if defined, indicates that "siginfo_t" has the
11213 "si_pid" member
11214 "HAS_SIGINFO_SI_STATUS"
11216 This symbol, if defined, indicates that "siginfo_t" has the
11217 "si_status" member
11218 "HAS_SIGINFO_SI_UID"
11220 This symbol, if defined, indicates that "siginfo_t" has the
11221 "si_uid" member
11222 "HAS_SIGINFO_SI_VALUE"
11224 This symbol, if defined, indicates that "siginfo_t" has the
11225 "si_value" member
11226 "PERL_SIGNALS_UNSAFE_FLAG"
11228 If this bit in "PL_signals" is set, the system is uing the pre-Perl
11229 5.8 unsafe signals. See "PERL_SIGNALS" in perlrun and "Deferred
11230 Signals (Safe Signals)" in perlipc.
11231 U32 PERL_SIGNALS_UNSAFE_FLAG
11233 "rsignal"
11235 A wrapper for the C library functions sigaction(2) or signal(2).
11236 Use this instead of those libc functions, as the Perl version gives
11237 the safest available implementation, and knows things that interact
11238 with the rest of the perl interpreter.
11239 Sighandler_t rsignal(int i, Sighandler_t t)
11241 "rsignal_state"
11243 Returns a the current signal handler for signal "signo". See
11244 ""rsignal"".
11245 Sighandler_t rsignal_state(int i)
11247 "Sigjmp_buf"
11249 This is the buffer type to be used with Sigsetjmp and Siglongjmp.
11250 "Siglongjmp"
11252 This macro is used in the same way as siglongjmp(), but will invoke
11253 traditional longjmp() if siglongjmp isn't available. See
11254 "HAS_SIGSETJMP".
11255 void Siglongjmp(jmp_buf env, int val)
11257 "SIG_NAME"
11259 This symbol contains a list of signal names in order of signal
11260 number. This is intended to be used as a static array
11261 initialization, like this:
11262 char *sig_name[] = { SIG_NAME };
11264 The signals in the list are separated with commas, and each signal
11266 is surrounded by double quotes. There is no leading "SIG" in the
11267 signal name, i.e. "SIGQUIT" is known as ""QUIT"". Gaps in the
11268 signal numbers (up to "NSIG") are filled in with "NUMnn", etc.,
11269 where nn is the actual signal number (e.g. "NUM37"). The signal
11270 number for "sig_name[i]" is stored in "sig_num[i]". The last
11271 element is 0 to terminate the list with a "NULL". This corresponds
11272 to the 0 at the end of the "sig_name_init" list. Note that this
11273 variable is initialized from the "sig_name_init", not from
11274 "sig_name" (which is unused).
11275 "SIG_NUM"
11277 This symbol contains a list of signal numbers, in the same order as
11278 the "SIG_NAME" list. It is suitable for static array
11279 initialization, as in:
11280 int sig_num[] = { SIG_NUM };
11282 The signals in the list are separated with commas, and the indices
11284 within that list and the "SIG_NAME" list match, so it's easy to
11285 compute the signal name from a number or vice versa at the price of
11286 a small dynamic linear lookup. Duplicates are allowed, but are
11287 moved to the end of the list. The signal number corresponding to
11288 "sig_name[i]" is "sig_number[i]". if (i < "NSIG") then
11289 "sig_number[i]" == i. The last element is 0, corresponding to the
11290 0 at the end of the "sig_name_init" list. Note that this variable
11291 is initialized from the "sig_num_init", not from "sig_num" (which
11292 is unused).
11293 "Sigsetjmp"
11295 This macro is used in the same way as sigsetjmp(), but will invoke
11296 traditional setjmp() if sigsetjmp isn't available. See
11297 "HAS_SIGSETJMP".
11298 int Sigsetjmp(jmp_buf env, int savesigs)
11300 "SIG_SIZE"
11302 This variable contains the number of elements of the "SIG_NAME" and
11303 "SIG_NUM" arrays, excluding the final "NULL" entry.
11304 "whichsig"
11306 "whichsig_pv"
11307 "whichsig_pvn"
11308 "whichsig_sv"
11309 These all convert a signal name into its corresponding signal
11310 number; returning -1 if no corresponding number was found.
11311 They differ only in the source of the signal name:
11313 "whichsig_pv" takes the name from the "NUL"-terminated string
11315 starting at "sig".
11316 "whichsig" is merely a different spelling, a synonym, of
11318 "whichsig_pv".
11319 "whichsig_pvn" takes the name from the string starting at "sig",
11321 with length "len" bytes.
11322 "whichsig_sv" takes the name from the PV stored in the SV "sigsv".
11324 I32 whichsig (const char *sig)
11326 I32 whichsig_pv (const char *sig)
11327 I32 whichsig_pvn(const char *sig, STRLEN len)
11328 I32 whichsig_sv (SV *sigsv)
11329
11331 These variables give details as to where various libraries,
11332 installation destinations, etc., go, as well as what various
11333 installation options were selected
11334 "ARCHLIB"
11336 This variable, if defined, holds the name of the directory in which
11337 the user wants to put architecture-dependent public library files
11338 for perl5. It is most often a local directory such as
11339 /usr/local/lib. Programs using this variable must be prepared to
11340 deal with filename expansion. If "ARCHLIB" is the same as
11341 "PRIVLIB", it is not defined, since presumably the program already
11342 searches "PRIVLIB".
11343 "ARCHLIB_EXP"
11345 This symbol contains the ~name expanded version of "ARCHLIB", to be
11346 used in programs that are not prepared to deal with ~ expansion at
11347 run-time.
11348 "ARCHNAME"
11350 This symbol holds a string representing the architecture name. It
11351 may be used to construct an architecture-dependant pathname where
11352 library files may be held under a private library, for instance.
11353 "BIN"
11355 This symbol holds the path of the bin directory where the package
11356 will be installed. Program must be prepared to deal with ~name
11357 substitution.
11358 "BIN_EXP"
11360 This symbol is the filename expanded version of the "BIN" symbol,
11361 for programs that do not want to deal with that at run-time.
11362 "INSTALL_USR_BIN_PERL"
11364 This symbol, if defined, indicates that Perl is to be installed
11365 also as /usr/bin/perl.
11366 "MULTIARCH"
11368 This symbol, if defined, signifies that the build process will
11369 produce some binary files that are going to be used in a cross-
11370 platform environment. This is the case for example with the NeXT
11371 "fat" binaries that contain executables for several "CPUs".
11372 "PERL_INC_VERSION_LIST"
11374 This variable specifies the list of subdirectories in over which
11375 perl.c:incpush() and lib/lib.pm will automatically search when
11376 adding directories to @"INC", in a format suitable for a C
11377 initialization string. See the "inc_version_list" entry in
11378 Porting/Glossary for more details.
11379 "PERL_OTHERLIBDIRS"
11381 This variable contains a colon-separated set of paths for the perl
11382 binary to search for additional library files or modules. These
11383 directories will be tacked to the end of @"INC". Perl will
11384 automatically search below each path for version- and architecture-
11385 specific directories. See "PERL_INC_VERSION_LIST" for more
11386 details.
11387 "PERL_RELOCATABLE_INC"
11389 This symbol, if defined, indicates that we'd like to relocate
11390 entries in @"INC" at run time based on the location of the perl
11391 binary.
11392 "PERL_TARGETARCH"
11394 This symbol, if defined, indicates the target architecture Perl has
11395 been cross-compiled to. Undefined if not a cross-compile.
11396 "PERL_USE_DEVEL"
11398 This symbol, if defined, indicates that Perl was configured with
11399 "-Dusedevel", to enable development features. This should not be
11400 done for production builds.
11401 "PERL_VENDORARCH"
11403 If defined, this symbol contains the name of a private library.
11404 The library is private in the sense that it needn't be in anyone's
11405 execution path, but it should be accessible by the world. It may
11406 have a ~ on the front. The standard distribution will put nothing
11407 in this directory. Vendors who distribute perl may wish to place
11408 their own architecture-dependent modules and extensions in this
11409 directory with
11410 MakeMaker Makefile.PL INSTALLDIRS=vendor
11412 or equivalent. See "INSTALL" for details.
11414 "PERL_VENDORARCH_EXP"
11416 This symbol contains the ~name expanded version of
11417 "PERL_VENDORARCH", to be used in programs that are not prepared to
11418 deal with ~ expansion at run-time.
11419 "PERL_VENDORLIB_EXP"
11421 This symbol contains the ~name expanded version of "VENDORLIB", to
11422 be used in programs that are not prepared to deal with ~ expansion
11423 at run-time.
11424 "PERL_VENDORLIB_STEM"
11426 This define is "PERL_VENDORLIB_EXP" with any trailing version-
11427 specific component removed. The elements in "inc_version_list"
11428 ("inc_version_list".U (part of metaconfig)) can be tacked onto this
11429 variable to generate a list of directories to search.
11430 "PRIVLIB"
11432 This symbol contains the name of the private library for this
11433 package. The library is private in the sense that it needn't be in
11434 anyone's execution path, but it should be accessible by the world.
11435 The program should be prepared to do ~ expansion.
11436 "PRIVLIB_EXP"
11438 This symbol contains the ~name expanded version of "PRIVLIB", to be
11439 used in programs that are not prepared to deal with ~ expansion at
11440 run-time.
11441 "SITEARCH"
11443 This symbol contains the name of the private library for this
11444 package. The library is private in the sense that it needn't be in
11445 anyone's execution path, but it should be accessible by the world.
11446 The program should be prepared to do ~ expansion. The standard
11447 distribution will put nothing in this directory. After perl has
11448 been installed, users may install their own local architecture-
11449 dependent modules in this directory with
11450 MakeMaker Makefile.PL
11452 or equivalent. See "INSTALL" for details.
11454 "SITEARCH_EXP"
11456 This symbol contains the ~name expanded version of "SITEARCH", to
11457 be used in programs that are not prepared to deal with ~ expansion
11458 at run-time.
11459 "SITELIB"
11461 This symbol contains the name of the private library for this
11462 package. The library is private in the sense that it needn't be in
11463 anyone's execution path, but it should be accessible by the world.
11464 The program should be prepared to do ~ expansion. The standard
11465 distribution will put nothing in this directory. After perl has
11466 been installed, users may install their own local architecture-
11467 independent modules in this directory with
11468 MakeMaker Makefile.PL
11470 or equivalent. See "INSTALL" for details.
11472 "SITELIB_EXP"
11474 This symbol contains the ~name expanded version of "SITELIB", to be
11475 used in programs that are not prepared to deal with ~ expansion at
11476 run-time.
11477 "SITELIB_STEM"
11479 This define is "SITELIB_EXP" with any trailing version-specific
11480 component removed. The elements in "inc_version_list"
11481 ("inc_version_list".U (part of metaconfig)) can be tacked onto this
11482 variable to generate a list of directories to search.
11483 "STARTPERL"
11485 This variable contains the string to put in front of a perl script
11486 to make sure (one hopes) that it runs with perl and not some shell.
11487 "USE_64_BIT_ALL"
11489 This symbol, if defined, indicates that 64-bit integers should be
11490 used when available. If not defined, the native integers will be
11491 used (be they 32 or 64 bits). The maximal possible 64-bitness is
11492 employed: LP64 or "ILP64", meaning that you will be able to use
11493 more than 2 gigabytes of memory. This mode is even more binary
11494 incompatible than "USE_64_BIT_INT". You may not be able to run the
11495 resulting executable in a 32-bit "CPU" at all or you may need at
11496 least to reboot your OS to 64-bit mode.
11497 "USE_64_BIT_INT"
11499 This symbol, if defined, indicates that 64-bit integers should be
11500 used when available. If not defined, the native integers will be
11501 employed (be they 32 or 64 bits). The minimal possible 64-bitness
11502 is used, just enough to get 64-bit integers into Perl. This may
11503 mean using for example "long longs", while your memory may still be
11504 limited to 2 gigabytes.
11505 "USE_BSD_GETPGRP"
11507 This symbol, if defined, indicates that getpgrp needs one arguments
11508 whereas "USG" one needs none.
11509 "USE_BSD_SETPGRP"
11511 This symbol, if defined, indicates that setpgrp needs two arguments
11512 whereas "USG" one needs none. See also "HAS_SETPGID" for a "POSIX"
11513 interface.
11514 "USE_C_BACKTRACE"
11516 This symbol, if defined, indicates that Perl should be built with
11517 support for backtrace.
11518 "USE_CPLUSPLUS"
11520 This symbol, if defined, indicates that a C++ compiler was used to
11521 compiled Perl and will be used to compile extensions.
11522 "USE_CROSS_COMPILE"
11524 This symbol, if defined, indicates that Perl is being cross-
11525 compiled.
11526 "USE_DTRACE"
11528 This symbol, if defined, indicates that Perl should be built with
11529 support for DTrace.
11530 "USE_DYNAMIC_LOADING"
11532 This symbol, if defined, indicates that dynamic loading of some
11533 sort is available.
11534 "USE_FAST_STDIO"
11536 This symbol, if defined, indicates that Perl should be built to use
11537 'fast stdio'. Defaults to define in Perls 5.8 and earlier, to
11538 undef later.
11539 "USE_ITHREADS"
11541 This symbol, if defined, indicates that Perl should be built to use
11542 the interpreter-based threading implementation.
11543 "USE_KERN_PROC_PATHNAME"
11545 This symbol, if defined, indicates that we can use sysctl with
11546 "KERN_PROC_PATHNAME" to get a full path for the executable, and
11547 hence convert $^X to an absolute path.
11548 "USE_LARGE_FILES"
11550 This symbol, if defined, indicates that large file support should
11551 be used when available.
11552 "USE_LONG_DOUBLE"
11554 This symbol, if defined, indicates that long doubles should be used
11555 when available.
11556 "USE_MORE_BITS"
11558 This symbol, if defined, indicates that 64-bit interfaces and long
11559 doubles should be used when available.
11560 "USE_NSGETEXECUTABLEPATH"
11562 This symbol, if defined, indicates that we can use
11563 "_NSGetExecutablePath" and realpath to get a full path for the
11564 executable, and hence convert $^X to an absolute path.
11565 "USE_PERLIO"
11567 This symbol, if defined, indicates that the PerlIO abstraction
11568 should be used throughout. If not defined, stdio should be used in
11569 a fully backward compatible manner.
11570 "USE_QUADMATH"
11572 This symbol, if defined, indicates that the quadmath library should
11573 be used when available.
11574 "USE_REENTRANT_API"
11576 This symbol, if defined, indicates that Perl should try to use the
11577 various "_r" versions of library functions. This is extremely
11578 experimental.
11579 "USE_SEMCTL_SEMID_DS"
11581 This symbol, if defined, indicates that "struct semid_ds" * is used
11582 for semctl "IPC_STAT".
11583 "USE_SEMCTL_SEMUN"
11585 This symbol, if defined, indicates that "union semun" is used for
11586 semctl "IPC_STAT".
11587 "USE_SITECUSTOMIZE"
11589 This symbol, if defined, indicates that sitecustomize should be
11590 used.
11591 "USE_SOCKS"
11593 This symbol, if defined, indicates that Perl should be built to use
11594 socks.
11595 "USE_STAT_BLOCKS"
11597 This symbol is defined if this system has a stat structure
11598 declaring "st_blksize" and "st_blocks".
11599 "USE_STDIO_BASE"
11601 This symbol is defined if the "_base" field (or similar) of the
11602 stdio "FILE" structure can be used to access the stdio buffer for a
11603 file handle. If this is defined, then the FILE_base(fp) macro will
11604 also be defined and should be used to access this field. Also, the
11605 FILE_bufsiz(fp) macro will be defined and should be used to
11606 determine the number of bytes in the buffer. "USE_STDIO_BASE" will
11607 never be defined unless "USE_STDIO_PTR" is.
11608 "USE_STDIO_PTR"
11610 This symbol is defined if the "_ptr" and "_cnt" fields (or similar)
11611 of the stdio "FILE" structure can be used to access the stdio
11612 buffer for a file handle. If this is defined, then the
11613 FILE_ptr(fp) and FILE_cnt(fp) macros will also be defined and
11614 should be used to access these fields.
11615 "USE_STRICT_BY_DEFAULT"
11617 This symbol, if defined, enables additional defaults. At this time
11618 it only enables implicit strict by default.
11619 "USE_THREADS"
11621 This symbol, if defined, indicates that Perl should be built to use
11622 threads. At present, it is a synonym for and "USE_ITHREADS", but
11623 eventually the source ought to be changed to use this to mean
11624 "_any_" threading implementation.
11625
11627 "HAS_SOCKADDR_IN6"
11628 This symbol, if defined, indicates the availability of "struct
11629 sockaddr_in6";
11630 "HAS_SOCKADDR_SA_LEN"
11632 This symbol, if defined, indicates that the "struct sockaddr"
11633 structure has a member called "sa_len", indicating the length of
11634 the structure.
11635 "HAS_SOCKADDR_STORAGE"
11637 This symbol, if defined, indicates the availability of "struct
11638 sockaddr_storage";
11639 "HAS_SOCKATMARK"
11641 This symbol, if defined, indicates that the "sockatmark" routine is
11642 available to test whether a socket is at the out-of-band mark.
11643 "HAS_SOCKET"
11645 This symbol, if defined, indicates that the "BSD" "socket"
11646 interface is supported.
11647 "HAS_SOCKETPAIR"
11649 This symbol, if defined, indicates that the "BSD" socketpair() call
11650 is supported.
11651 "HAS_SOCKS5_INIT"
11653 This symbol, if defined, indicates that the "socks5_init" routine
11654 is available to initialize "SOCKS" 5.
11655 "I_SOCKS"
11657 This symbol, if defined, indicates that socks.h exists and should
11658 be included.
11659 #ifdef I_SOCKS
11661 #include <socks.h>
11662 #endif
11663 "I_SYS_SOCKIO"
11665 This symbol, if defined, indicates the sys/sockio.h should be
11666 included to get socket ioctl options, like "SIOCATMARK".
11667 #ifdef I_SYS_SOCKIO
11669 #include <sys_sockio.h>
11670 #endif
11671
11673 "apply_builtin_cv_attributes"
11674 Given an OP_LIST containing attribute definitions, filter it for
11675 known builtin attributes to apply to the cv, returning a possibly-
11676 smaller list containing just the remaining ones.
11677 OP * apply_builtin_cv_attributes(CV *cv, OP *attrlist)
11679 "filter_add"
11681 Described in perlfilter.
11682 SV * filter_add(filter_t funcp, SV *datasv)
11684 "filter_del"
11686 Delete most recently added instance of the filter function argument
11687 void filter_del(filter_t funcp)
11689 "filter_read"
11691 Described in perlfilter.
11692 I32 filter_read(int idx, SV *buf_sv, int maxlen)
11694 "scan_vstring"
11696 Returns a pointer to the next character after the parsed vstring,
11697 as well as updating the passed in sv.
11698 Function must be called like
11700 sv = sv_2mortal(newSV(5));
11702 s = scan_vstring(s,e,sv);
11703 where s and e are the start and end of the string. The sv should
11705 already be large enough to store the vstring passed in, for
11706 performance reasons.
11707 This function may croak if fatal warnings are enabled in the
11709 calling scope, hence the sv_2mortal in the example (to prevent a
11710 leak). Make sure to do SvREFCNT_inc afterwards if you use
11711 sv_2mortal.
11712 char * scan_vstring(const char *s, const char * const e, SV *sv)
11714 "start_subparse"
11716 Set things up for parsing a subroutine.
11717 If "is_format" is non-zero, the input is to be considered a format
11719 sub (a specialised sub used to implement perl's "format" feature);
11720 else a normal "sub".
11721 "flags" are added to the flags for "PL_compcv". "flags" may
11723 include the "CVf_IsMETHOD" bit, which causes the new subroutine to
11724 be a method.
11725 This returns the value of "PL_savestack_ix" that was in effect upon
11727 entry to the function;
11728 I32 start_subparse(I32 is_format, U32 flags)
11730
11732 "dMARK"
11733 Declare a stack marker variable, "mark", for the XSUB. See "MARK"
11734 and "dORIGMARK".
11735 dMARK;
11737 "dORIGMARK"
11739 Saves the original stack mark for the XSUB. See "ORIGMARK".
11740 dORIGMARK;
11742 "dSP"
11744 Declares a local copy of perl's stack pointer for the XSUB,
11745 available via the "SP" macro. See "SP".
11746 dSP;
11748 "dTARGET"
11750 Declare that this function uses "TARG", and initializes it
11751 dTARGET;
11753 "EXTEND"
11755 Used to extend the argument stack for an XSUB's return values.
11756 Once used, guarantees that there is room for at least "nitems" to
11757 be pushed onto the stack.
11758 void EXTEND(SP, SSize_t nitems)
11760 "MARK"
11762 Stack marker variable for the XSUB. See "dMARK".
11763 "mPUSHi"
11765 Push an integer onto the stack. The stack must have room for this
11766 element. Does not use "TARG". See also "PUSHi", "mXPUSHi" and
11767 "XPUSHi".
11768 void mPUSHi(IV iv)
11770 "mPUSHn"
11772 Push a double onto the stack. The stack must have room for this
11773 element. Does not use "TARG". See also "PUSHn", "mXPUSHn" and
11774 "XPUSHn".
11775 void mPUSHn(NV nv)
11777 "mPUSHp"
11779 Push a string onto the stack. The stack must have room for this
11780 element. The "len" indicates the length of the string. Does not
11781 use "TARG". See also "PUSHp", "mXPUSHp" and "XPUSHp".
11782 void mPUSHp(char* str, STRLEN len)
11784 "mPUSHpvs"
11786 A variation on "mPUSHp" that takes a literal string and calculates
11787 its size directly.
11788 void mPUSHpvs("literal string")
11790 "mPUSHs"
11792 Push an SV onto the stack and mortalizes the SV. The stack must
11793 have room for this element. Does not use "TARG". See also "PUSHs"
11794 and "mXPUSHs".
11795 void mPUSHs(SV* sv)
11797 "mPUSHu"
11799 Push an unsigned integer onto the stack. The stack must have room
11800 for this element. Does not use "TARG". See also "PUSHu",
11801 "mXPUSHu" and "XPUSHu".
11802 void mPUSHu(UV uv)
11804 "mXPUSHi"
11806 Push an integer onto the stack, extending the stack if necessary.
11807 Does not use "TARG". See also "XPUSHi", "mPUSHi" and "PUSHi".
11808 void mXPUSHi(IV iv)
11810 "mXPUSHn"
11812 Push a double onto the stack, extending the stack if necessary.
11813 Does not use "TARG". See also "XPUSHn", "mPUSHn" and "PUSHn".
11814 void mXPUSHn(NV nv)
11816 "mXPUSHp"
11818 Push a string onto the stack, extending the stack if necessary.
11819 The "len" indicates the length of the string. Does not use "TARG".
11820 See also "XPUSHp", "mPUSHp" and "PUSHp".
11821 void mXPUSHp(char* str, STRLEN len)
11823 "mXPUSHpvs"
11825 A variation on "mXPUSHp" that takes a literal string and calculates
11826 its size directly.
11827 void mXPUSHpvs("literal string")
11829 "mXPUSHs"
11831 Push an SV onto the stack, extending the stack if necessary and
11832 mortalizes the SV. Does not use "TARG". See also "XPUSHs" and
11833 "mPUSHs".
11834 void mXPUSHs(SV* sv)
11836 "mXPUSHu"
11838 Push an unsigned integer onto the stack, extending the stack if
11839 necessary. Does not use "TARG". See also "XPUSHu", "mPUSHu" and
11840 "PUSHu".
11841 void mXPUSHu(UV uv)
11843 "newXSproto"
11845 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl
11846 prototypes to the subs.
11847 "ORIGMARK"
11849 The original stack mark for the XSUB. See "dORIGMARK".
11850 "PL_markstack"
11852 Described in perlguts.
11853 "PL_markstack_ptr"
11855 Described in perlguts.
11856 "PL_savestack"
11858 Described in perlguts.
11859 "PL_savestack_ix"
11861 Described in perlguts.
11862 "PL_scopestack"
11864 Described in perlguts.
11865 "PL_scopestack_ix"
11867 Described in perlguts.
11868 "PL_scopestack_name"
11870 Described in perlguts.
11871 "PL_stack_base"
11873 Described in perlguts.
11874 "PL_stack_sp"
11876 Described in perlguts.
11877 "PL_tmps_floor"
11879 Described in perlguts.
11880 "PL_tmps_ix"
11882 Described in perlguts.
11883 "PL_tmps_stack"
11885 Described in perlguts.
11886 "POPi"
11888 Pops an integer off the stack.
11889 IV POPi
11891 "POPl"
11893 Pops a long off the stack.
11894 long POPl
11896 "POPn"
11898 Pops a double off the stack.
11899 NV POPn
11901 "POPp"
11903 Pops a string off the stack.
11904 char* POPp
11906 "POPpbytex"
11908 Pops a string off the stack which must consist of bytes i.e.
11909 characters < 256.
11910 char* POPpbytex
11912 "POPpx"
11914 Pops a string off the stack. Identical to POPp. There are two
11915 names for historical reasons.
11916 char* POPpx
11918 "POPs"
11920 Pops an SV off the stack.
11921 SV* POPs
11923 "POPu"
11925 Pops an unsigned integer off the stack.
11926 UV POPu
11928 "POPul"
11930 Pops an unsigned long off the stack.
11931 long POPul
11933 "PUSHi"
11935 Push an integer onto the stack. The stack must have room for this
11936 element. Handles 'set' magic. Uses "TARG", so "dTARGET" or
11937 "dXSTARG" should be called to declare it. Do not call multiple
11938 "TARG"-oriented macros to return lists from XSUB's - see "mPUSHi"
11939 instead. See also "XPUSHi" and "mXPUSHi".
11940 void PUSHi(IV iv)
11942 "PUSHMARK"
11944 Opening bracket for arguments on a callback. See "PUTBACK" and
11945 perlcall.
11946 void PUSHMARK(SP)
11948 "PUSHmortal"
11950 Push a new mortal SV onto the stack. The stack must have room for
11951 this element. Does not use "TARG". See also "PUSHs",
11952 "XPUSHmortal" and "XPUSHs".
11953 void PUSHmortal
11955 "PUSHn"
11957 Push a double onto the stack. The stack must have room for this
11958 element. Handles 'set' magic. Uses "TARG", so "dTARGET" or
11959 "dXSTARG" should be called to declare it. Do not call multiple
11960 "TARG"-oriented macros to return lists from XSUB's - see "mPUSHn"
11961 instead. See also "XPUSHn" and "mXPUSHn".
11962 void PUSHn(NV nv)
11964 "PUSHp"
11966 Push a string onto the stack. The stack must have room for this
11967 element. The "len" indicates the length of the string. Handles
11968 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG" should be
11969 called to declare it. Do not call multiple "TARG"-oriented macros
11970 to return lists from XSUB's - see "mPUSHp" instead. See also
11971 "XPUSHp" and "mXPUSHp".
11972 void PUSHp(char* str, STRLEN len)
11974 "PUSHpvs"
11976 A variation on "PUSHp" that takes a literal string and calculates
11977 its size directly.
11978 void PUSHpvs("literal string")
11980 "PUSHs"
11982 Push an SV onto the stack. The stack must have room for this
11983 element. Does not handle 'set' magic. Does not use "TARG". See
11984 also "PUSHmortal", "XPUSHs", and "XPUSHmortal".
11985 void PUSHs(SV* sv)
11987 "PUSHu"
11989 Push an unsigned integer onto the stack. The stack must have room
11990 for this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
11991 or "dXSTARG" should be called to declare it. Do not call multiple
11992 "TARG"-oriented macros to return lists from XSUB's - see "mPUSHu"
11993 instead. See also "XPUSHu" and "mXPUSHu".
11994 void PUSHu(UV uv)
11996 "PUTBACK"
11998 Closing bracket for XSUB arguments. This is usually handled by
11999 "xsubpp". See "PUSHMARK" and perlcall for other uses.
12000 PUTBACK;
12002 "SAVEt_INT"
12004 Described in perlguts.
12005 "SP"
12007 Stack pointer. This is usually handled by "xsubpp". See "dSP" and
12008 "SPAGAIN".
12009 "SPAGAIN"
12011 Refetch the stack pointer. Used after a callback. See perlcall.
12012 SPAGAIN;
12014 "SSNEW"
12016 "SSNEWa"
12017 "SSNEWat"
12018 "SSNEWt"
12019 These temporarily allocates data on the savestack, returning an
12020 SSize_t index into the savestack, because a pointer would get
12021 broken if the savestack is moved on reallocation. Use ""SSPTR"" to
12022 convert the returned index into a pointer.
12023 The forms differ in that plain "SSNEW" allocates "size" bytes;
12025 "SSNEWt" and "SSNEWat" allocate "size" objects, each of which is
12026 type "type"; and <SSNEWa> and "SSNEWat" make sure to align the new
12027 data to an "align" boundary. The most useful value for the
12028 alignment is likely to be ""MEM_ALIGNBYTES"". The alignment will
12029 be preserved through savestack reallocation only if realloc returns
12030 data aligned to a size divisible by "align"!
12031 SSize_t SSNEW (Size_t size)
12033 SSize_t SSNEWa (Size_t_size, Size_t align)
12034 SSize_t SSNEWat(Size_t_size, type, Size_t align)
12035 SSize_t SSNEWt (Size_t size, type)
12036 "SSPTR"
12038 "SSPTRt"
12039 These convert the "index" returned by L/<"SSNEW"> and kin into
12040 actual pointers.
12041 The difference is that "SSPTR" casts the result to "type", and
12043 "SSPTRt" casts it to a pointer of that "type".
12044 type SSPTR (SSize_t index, type)
12046 type * SSPTRt(SSize_t index, type)
12047 "TARG"
12049 "TARG" is short for "target". It is an entry in the pad that an
12050 OPs "op_targ" refers to. It is scratchpad space, often used as a
12051 return value for the OP, but some use it for other purposes.
12052 TARG;
12054 "TOPs"
12056 Described in perlguts.
12057 "XPUSHi"
12059 Push an integer onto the stack, extending the stack if necessary.
12060 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG" should
12061 be called to declare it. Do not call multiple "TARG"-oriented
12062 macros to return lists from XSUB's - see "mXPUSHi" instead. See
12063 also "PUSHi" and "mPUSHi".
12064 void XPUSHi(IV iv)
12066 "XPUSHmortal"
12068 Push a new mortal SV onto the stack, extending the stack if
12069 necessary. Does not use "TARG". See also "XPUSHs", "PUSHmortal"
12070 and "PUSHs".
12071 void XPUSHmortal
12073 "XPUSHn"
12075 Push a double onto the stack, extending the stack if necessary.
12076 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG" should
12077 be called to declare it. Do not call multiple "TARG"-oriented
12078 macros to return lists from XSUB's - see "mXPUSHn" instead. See
12079 also "PUSHn" and "mPUSHn".
12080 void XPUSHn(NV nv)
12082 "XPUSHp"
12084 Push a string onto the stack, extending the stack if necessary.
12085 The "len" indicates the length of the string. Handles 'set' magic.
12086 Uses "TARG", so "dTARGET" or "dXSTARG" should be called to declare
12087 it. Do not call multiple "TARG"-oriented macros to return lists
12088 from XSUB's - see "mXPUSHp" instead. See also "PUSHp" and
12089 "mPUSHp".
12090 void XPUSHp(char* str, STRLEN len)
12092 "XPUSHpvs"
12094 A variation on "XPUSHp" that takes a literal string and calculates
12095 its size directly.
12096 void XPUSHpvs("literal string")
12098 "XPUSHs"
12100 Push an SV onto the stack, extending the stack if necessary. Does
12101 not handle 'set' magic. Does not use "TARG". See also
12102 "XPUSHmortal", "PUSHs" and "PUSHmortal".
12103 void XPUSHs(SV* sv)
12105 "XPUSHu"
12107 Push an unsigned integer onto the stack, extending the stack if
12108 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
12109 "dXSTARG" should be called to declare it. Do not call multiple
12110 "TARG"-oriented macros to return lists from XSUB's - see "mXPUSHu"
12111 instead. See also "PUSHu" and "mPUSHu".
12112 void XPUSHu(UV uv)
12114 "XS_APIVERSION_BOOTCHECK"
12116 Macro to verify that the perl api version an XS module has been
12117 compiled against matches the api version of the perl interpreter
12118 it's being loaded into.
12119 XS_APIVERSION_BOOTCHECK;
12121 "XSRETURN"
12123 Return from XSUB, indicating number of items on the stack. This is
12124 usually handled by "xsubpp".
12125 void XSRETURN(int nitems)
12127 "XSRETURN_EMPTY"
12129 Return an empty list from an XSUB immediately.
12130 XSRETURN_EMPTY;
12132 "XSRETURN_IV"
12134 Return an integer from an XSUB immediately. Uses "XST_mIV".
12135 void XSRETURN_IV(IV iv)
12137 "XSRETURN_NO"
12139 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
12140 XSRETURN_NO;
12142 "XSRETURN_NV"
12144 Return a double from an XSUB immediately. Uses "XST_mNV".
12145 void XSRETURN_NV(NV nv)
12147 "XSRETURN_PV"
12149 Return a copy of a string from an XSUB immediately. Uses
12150 "XST_mPV".
12151 void XSRETURN_PV(char* str)
12153 "XSRETURN_UNDEF"
12155 Return &PL_sv_undef from an XSUB immediately. Uses "XST_mUNDEF".
12156 XSRETURN_UNDEF;
12158 "XSRETURN_UV"
12160 Return an integer from an XSUB immediately. Uses "XST_mUV".
12161 void XSRETURN_UV(IV uv)
12163 "XSRETURN_YES"
12165 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
12166 XSRETURN_YES;
12168 "XST_mIV"
12170 Place an integer into the specified position "pos" on the stack.
12171 The value is stored in a new mortal SV.
12172 void XST_mIV(int pos, IV iv)
12174 "XST_mNO"
12176 Place &PL_sv_no into the specified position "pos" on the stack.
12177 void XST_mNO(int pos)
12179 "XST_mNV"
12181 Place a double into the specified position "pos" on the stack. The
12182 value is stored in a new mortal SV.
12183 void XST_mNV(int pos, NV nv)
12185 "XST_mPV"
12187 Place a copy of a string into the specified position "pos" on the
12188 stack. The value is stored in a new mortal SV.
12189 void XST_mPV(int pos, char* str)
12191 "XST_mUNDEF"
12193 Place &PL_sv_undef into the specified position "pos" on the stack.
12194 void XST_mUNDEF(int pos)
12196 "XST_mUV"
12198 Place an unsigned integer into the specified position "pos" on the
12199 stack. The value is stored in a new mortal SV.
12200 void XST_mUV(int pos, UV uv)
12202 "XST_mYES"
12204 Place &PL_sv_yes into the specified position "pos" on the stack.
12205 void XST_mYES(int pos)
12207 "XS_VERSION"
12209 The version identifier for an XS module. This is usually handled
12210 automatically by "ExtUtils::MakeMaker". See
12211 "XS_VERSION_BOOTCHECK".
12212 "XS_VERSION_BOOTCHECK"
12214 Macro to verify that a PM module's $VERSION variable matches the XS
12215 module's "XS_VERSION" variable. This is usually handled
12216 automatically by "xsubpp". See "The VERSIONCHECK: Keyword" in
12217 perlxs.
12218 XS_VERSION_BOOTCHECK;
12220
12222 See also "Unicode Support".
12223 "CAT2"
12225 This macro concatenates 2 tokens together.
12226 token CAT2(token x, token y)
12228 "Copy"
12230 "CopyD"
12231 The XSUB-writer's interface to the C "memcpy" function. The "src"
12232 is the source, "dest" is the destination, "nitems" is the number of
12233 items, and "type" is the type. May fail on overlapping copies.
12234 See also "Move".
12235 "CopyD" is like "Copy" but returns "dest". Useful for encouraging
12237 compilers to tail-call optimise.
12238 void Copy (void* src, void* dest, int nitems, type)
12240 void * CopyD(void* src, void* dest, int nitems, type)
12241 "delimcpy"
12243 Copy a source buffer to a destination buffer, stopping at (but not
12244 including) the first occurrence in the source of an unescaped
12245 (defined below) delimiter byte, "delim". The source is the bytes
12246 between "from" and "from_end" - 1. Similarly, the dest is "to" up
12247 to "to_end".
12248 The number of bytes copied is written to *retlen.
12250 Returns the position of the first uncopied "delim" in the "from"
12252 buffer, but if there is no such occurrence before "from_end", then
12253 "from_end" is returned, and the entire buffer
12254 "from" .. "from_end" - 1 is copied.
12255 If there is room in the destination available after the copy, an
12257 extra terminating safety "NUL" byte is appended (not included in
12258 the returned length).
12259 The error case is if the destination buffer is not large enough to
12261 accommodate everything that should be copied. In this situation, a
12262 value larger than "to_end" - "to" is written to *retlen, and as
12263 much of the source as fits will be written to the destination. Not
12264 having room for the safety "NUL" is not considered an error.
12265 In the following examples, let "x" be the delimiter, and 0
12267 represent a "NUL" byte (NOT the digit 0). Then we would have
12268 Source Destination
12270 abcxdef abc0
12271 provided the destination buffer is at least 4 bytes long.
12273 An escaped delimiter is one which is immediately preceded by a
12275 single backslash. Escaped delimiters are copied, and the copy
12276 continues past the delimiter; the backslash is not copied:
12277 Source Destination
12279 abc\xdef abcxdef0
12280 (provided the destination buffer is at least 8 bytes long).
12282 It's actually somewhat more complicated than that. A sequence of
12284 any odd number of backslashes escapes the following delimiter, and
12285 the copy continues with exactly one of the backslashes stripped.
12286 Source Destination
12288 abc\xdef abcxdef0
12289 abc\\\xdef abc\\xdef0
12290 abc\\\\\xdef abc\\\\xdef0
12291 (as always, if the destination is large enough)
12293 An even number of preceding backslashes does not escape the
12295 delimiter, so that the copy stops just before it, and includes all
12296 the backslashes (no stripping; zero is considered even):
12297 Source Destination
12299 abcxdef abc0
12300 abc\\xdef abc\\0
12301 abc\\\\xdef abc\\\\0
12302 char * delimcpy(char *to, const char *to_end, const char *from,
12304 const char *from_end, const int delim,
12305 I32 *retlen)
12306 "do_join"
12308 This performs a Perl "join", placing the joined output into "sv".
12309 The elements to join are in SVs, stored in a C array of pointers to
12311 SVs, from **mark to "**sp - 1". Hence *mark is a reference to the
12312 first SV. Each SV will be coerced into a PV if not one already.
12313 "delim" contains the string (or coerced into a string) that is to
12315 separate each of the joined elements.
12316 If any component is in UTF-8, the result will be as well, and all
12318 non-UTF-8 components will be converted to UTF-8 as necessary.
12319 Magic and tainting are handled.
12321 void do_join(SV *sv, SV *delim, SV **mark, SV **sp)
12323 "do_sprintf"
12325 This performs a Perl "sprintf" placing the string output into "sv".
12326 The elements to format are in SVs, stored in a C array of pointers
12328 to SVs of length "len"> and beginning at **sarg. The element
12329 referenced by *sarg is the format.
12330 Magic and tainting are handled.
12332 void do_sprintf(SV *sv, SSize_t len, SV **sarg)
12334 "fbm_compile"
12336 Analyzes the string in order to make fast searches on it using
12337 fbm_instr() -- the Boyer-Moore algorithm.
12338 void fbm_compile(SV *sv, U32 flags)
12340 "fbm_instr"
12342 Returns the location of the SV in the string delimited by "big" and
12343 "bigend" ("bigend") is the char following the last char). It
12344 returns "NULL" if the string can't be found. The "sv" does not
12345 have to be "fbm_compiled", but the search will not be as fast then.
12346 char * fbm_instr(unsigned char *big, unsigned char *bigend,
12348 SV *littlestr, U32 flags)
12349 "foldEQ"
12351 Returns true if the leading "len" bytes of the strings "s1" and
12352 "s2" are the same case-insensitively; false otherwise. Uppercase
12353 and lowercase ASCII range bytes match themselves and their opposite
12354 case counterparts. Non-cased and non-ASCII range bytes match only
12355 themselves.
12356 I32 foldEQ(const char *a, const char *b, I32 len)
12358 "ibcmp"
12360 This is a synonym for "(! foldEQ())"
12361 I32 ibcmp(const char *a, const char *b, I32 len)
12363 "ibcmp_locale"
12365 This is a synonym for "(! foldEQ_locale())"
12366 I32 ibcmp_locale(const char *a, const char *b, I32 len)
12368 "ibcmp_utf8"
12370 This is a synonym for "(! foldEQ_utf8())"
12371 I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1,
12373 const char *s2, char **pe2, UV l2, bool u2)
12374 "instr"
12376 Same as strstr(3), which finds and returns a pointer to the first
12377 occurrence of the NUL-terminated substring "little" in the NUL-
12378 terminated string "big", returning NULL if not found. The
12379 terminating NUL bytes are not compared.
12380 char * instr(const char *big, const char *little)
12382 "memCHRs"
12384 Returns the position of the first occurrence of the byte "c" in the
12385 literal string "list", or NULL if "c" doesn't appear in "list".
12386 All bytes are treated as unsigned char. Thus this macro can be
12387 used to determine if "c" is in a set of particular characters.
12388 Unlike strchr(3), it works even if "c" is "NUL" (and the set
12389 doesn't include "NUL").
12390 bool memCHRs("list", char c)
12392 "memEQ"
12394 Test two buffers (which may contain embedded "NUL" characters, to
12395 see if they are equal. The "len" parameter indicates the number of
12396 bytes to compare. Returns true or false. It is undefined behavior
12397 if either of the buffers doesn't contain at least "len" bytes.
12398 bool memEQ(char* s1, char* s2, STRLEN len)
12400 "memEQs"
12402 Like "memEQ", but the second string is a literal enclosed in double
12403 quotes, "l1" gives the number of bytes in "s1". Returns true or
12404 false.
12405 bool memEQs(char* s1, STRLEN l1, "s2")
12407 "memNE"
12409 Test two buffers (which may contain embedded "NUL" characters, to
12410 see if they are not equal. The "len" parameter indicates the
12411 number of bytes to compare. Returns true or false. It is
12412 undefined behavior if either of the buffers doesn't contain at
12413 least "len" bytes.
12414 bool memNE(char* s1, char* s2, STRLEN len)
12416 "memNEs"
12418 Like "memNE", but the second string is a literal enclosed in double
12419 quotes, "l1" gives the number of bytes in "s1". Returns true or
12420 false.
12421 bool memNEs(char* s1, STRLEN l1, "s2")
12423 "Move"
12425 "MoveD"
12426 The XSUB-writer's interface to the C "memmove" function. The "src"
12427 is the source, "dest" is the destination, "nitems" is the number of
12428 items, and "type" is the type. Can do overlapping moves. See also
12429 "Copy".
12430 "MoveD" is like "Move" but returns "dest". Useful for encouraging
12432 compilers to tail-call optimise.
12433 void Move (void* src, void* dest, int nitems, type)
12435 void * MoveD(void* src, void* dest, int nitems, type)
12436 "my_snprintf"
12438 The C library "snprintf" functionality, if available and standards-
12439 compliant (uses "vsnprintf", actually). However, if the
12440 "vsnprintf" is not available, will unfortunately use the unsafe
12441 "vsprintf" which can overrun the buffer (there is an overrun check,
12442 but that may be too late). Consider using "sv_vcatpvf" instead, or
12443 getting "vsnprintf".
12444 int my_snprintf(char *buffer, const Size_t len,
12446 const char *format, ...)
12447 "my_sprintf"
12449 "DEPRECATED!" It is planned to remove "my_sprintf" from a future
12450 release of Perl. Do not use it for new code; remove it from
12451 existing code.
12452 Do NOT use this due to the possibility of overflowing "buffer".
12454 Instead use my_snprintf()
12455 int my_sprintf(NN char *buffer, NN const char *pat, ...)
12457 "my_strnlen"
12459 The C library "strnlen" if available, or a Perl implementation of
12460 it.
12461 my_strnlen() computes the length of the string, up to "maxlen"
12463 characters. It will never attempt to address more than "maxlen"
12464 characters, making it suitable for use with strings that are not
12465 guaranteed to be NUL-terminated.
12466 Size_t my_strnlen(const char *str, Size_t maxlen)
12468 "my_vsnprintf"
12470 The C library "vsnprintf" if available and standards-compliant.
12471 However, if the "vsnprintf" is not available, will unfortunately
12472 use the unsafe "vsprintf" which can overrun the buffer (there is an
12473 overrun check, but that may be too late). Consider using
12474 "sv_vcatpvf" instead, or getting "vsnprintf".
12475 int my_vsnprintf(char *buffer, const Size_t len,
12477 const char *format, va_list ap)
12478 "NewCopy"
12480 Combines Newx() and Copy() into a single macro. Dest will be
12481 allocated using Newx() and then src will be copied into it.
12482 void NewCopy(void* src, void* dest, int nitems, type)
12484 "ninstr"
12486 Find the first (leftmost) occurrence of a sequence of bytes within
12487 another sequence. This is the Perl version of strstr(), extended
12488 to handle arbitrary sequences, potentially containing embedded
12489 "NUL" characters ("NUL" is what the initial "n" in the function
12490 name stands for; some systems have an equivalent, memmem(), but
12491 with a somewhat different API).
12492 Another way of thinking about this function is finding a needle in
12494 a haystack. "big" points to the first byte in the haystack.
12495 "big_end" points to one byte beyond the final byte in the haystack.
12496 "little" points to the first byte in the needle. "little_end"
12497 points to one byte beyond the final byte in the needle. All the
12498 parameters must be non-"NULL".
12499 The function returns "NULL" if there is no occurrence of "little"
12501 within "big". If "little" is the empty string, "big" is returned.
12502 Because this function operates at the byte level, and because of
12504 the inherent characteristics of UTF-8 (or UTF-EBCDIC), it will work
12505 properly if both the needle and the haystack are strings with the
12506 same UTF-8ness, but not if the UTF-8ness differs.
12507 char * ninstr(const char *big, const char *bigend,
12509 const char *little, const char *lend)
12510 "Nullch"
12512 Null character pointer. (No longer available when "PERL_CORE" is
12513 defined.)
12514 "PL_na"
12516 A scratch pad variable in which to store a "STRLEN" value. If
12517 would have been better named something like "PL_temp_strlen".
12518 It is is typically used with "SvPV" when one is actually planning
12520 to discard the returned length, (hence the length is "Not
12521 Applicable", which is how this variable got its name).
12522 BUT BEWARE, if this is used in a situation where something that is
12524 using it is in a call stack with something else that is using it,
12525 this variable would get zapped, leading to hard-to-diagnose errors.
12526 It is usually more efficient to either declare a local variable and
12528 use that instead, or to use the "SvPV_nolen" macro.
12529 STRLEN PL_na
12531 "rninstr"
12533 Like "ninstr", but instead finds the final (rightmost) occurrence
12534 of a sequence of bytes within another sequence, returning "NULL" if
12535 there is no such occurrence.
12536 char * rninstr(const char *big, const char *bigend,
12538 const char *little, const char *lend)
12539 "savepv"
12541 Perl's version of strdup(). Returns a pointer to a newly allocated
12542 string which is a duplicate of "pv". The size of the string is
12543 determined by strlen(), which means it may not contain embedded
12544 "NUL" characters and must have a trailing "NUL". To prevent memory
12545 leaks, the memory allocated for the new string needs to be freed
12546 when no longer needed. This can be done with the "Safefree"
12547 function, or "SAVEFREEPV".
12548 On some platforms, Windows for example, all allocated memory owned
12550 by a thread is deallocated when that thread ends. So if you need
12551 that not to happen, you need to use the shared memory functions,
12552 such as "savesharedpv".
12553 char * savepv(const char *pv)
12555 "savepvn"
12557 Perl's version of what strndup() would be if it existed. Returns a
12558 pointer to a newly allocated string which is a duplicate of the
12559 first "len" bytes from "pv", plus a trailing "NUL" byte. The
12560 memory allocated for the new string can be freed with the
12561 Safefree() function.
12562 On some platforms, Windows for example, all allocated memory owned
12564 by a thread is deallocated when that thread ends. So if you need
12565 that not to happen, you need to use the shared memory functions,
12566 such as "savesharedpvn".
12567 char * savepvn(const char *pv, Size_t len)
12569 "savepvs"
12571 Like "savepvn", but takes a literal string instead of a
12572 string/length pair.
12573 char* savepvs("literal string")
12575 "savesharedpv"
12577 A version of savepv() which allocates the duplicate string in
12578 memory which is shared between threads.
12579 char * savesharedpv(const char *pv)
12581 "savesharedpvn"
12583 A version of savepvn() which allocates the duplicate string in
12584 memory which is shared between threads. (With the specific
12585 difference that a "NULL" pointer is not acceptable)
12586 char * savesharedpvn(const char * const pv, const STRLEN len)
12588 "savesharedpvs"
12590 A version of savepvs() which allocates the duplicate string in
12591 memory which is shared between threads.
12592 char* savesharedpvs("literal string")
12594 "savesharedsvpv"
12596 A version of savesharedpv() which allocates the duplicate string in
12597 memory which is shared between threads.
12598 char * savesharedsvpv(SV *sv)
12600 "savesvpv"
12602 A version of savepv()/savepvn() which gets the string to duplicate
12603 from the passed in SV using SvPV()
12604 On some platforms, Windows for example, all allocated memory owned
12606 by a thread is deallocated when that thread ends. So if you need
12607 that not to happen, you need to use the shared memory functions,
12608 such as "savesharedsvpv".
12609 char * savesvpv(SV *sv)
12611 "strEQ"
12613 Test two "NUL"-terminated strings to see if they are equal.
12614 Returns true or false.
12615 bool strEQ(char* s1, char* s2)
12617 "strGE"
12619 Test two "NUL"-terminated strings to see if the first, "s1", is
12620 greater than or equal to the second, "s2". Returns true or false.
12621 bool strGE(char* s1, char* s2)
12623 "strGT"
12625 Test two "NUL"-terminated strings to see if the first, "s1", is
12626 greater than the second, "s2". Returns true or false.
12627 bool strGT(char* s1, char* s2)
12629 "STRINGIFY"
12631 This macro surrounds its token with double quotes.
12632 string STRINGIFY(token x)
12634 "strLE"
12636 Test two "NUL"-terminated strings to see if the first, "s1", is
12637 less than or equal to the second, "s2". Returns true or false.
12638 bool strLE(char* s1, char* s2)
12640 "STRLEN"
12642 Described in perlguts.
12643 "strLT"
12645 Test two "NUL"-terminated strings to see if the first, "s1", is
12646 less than the second, "s2". Returns true or false.
12647 bool strLT(char* s1, char* s2)
12649 "strNE"
12651 Test two "NUL"-terminated strings to see if they are different.
12652 Returns true or false.
12653 bool strNE(char* s1, char* s2)
12655 "strnEQ"
12657 Test two "NUL"-terminated strings to see if they are equal. The
12658 "len" parameter indicates the number of bytes to compare. Returns
12659 true or false. (A wrapper for "strncmp").
12660 bool strnEQ(char* s1, char* s2, STRLEN len)
12662 "strnNE"
12664 Test two "NUL"-terminated strings to see if they are different.
12665 The "len" parameter indicates the number of bytes to compare.
12666 Returns true or false. (A wrapper for "strncmp").
12667 bool strnNE(char* s1, char* s2, STRLEN len)
12669 "STR_WITH_LEN"
12671 Returns two comma separated tokens of the input literal string, and
12672 its length. This is convenience macro which helps out in some API
12673 calls. Note that it can't be used as an argument to macros or
12674 functions that under some configurations might be macros, which
12675 means that it requires the full Perl_xxx(aTHX_ ...) form for any
12676 API calls where it's used.
12677 pair STR_WITH_LEN("literal string")
12679 "Zero"
12681 "ZeroD"
12682 The XSUB-writer's interface to the C "memzero" function. The
12683 "dest" is the destination, "nitems" is the number of items, and
12684 "type" is the type.
12685 "ZeroD" is like "Zero" but returns "dest". Useful for encouraging
12687 compilers to tail-call optimise.
12688 void Zero (void* dest, int nitems, type)
12690 void * ZeroD(void* dest, int nitems, type)
12691
12693 "SVt_IV"
12694 Type flag for scalars. See "svtype".
12695 "SVt_NULL"
12697 Type flag for scalars. See "svtype".
12698 "SVt_NV"
12700 Type flag for scalars. See "svtype".
12701 "SVt_PV"
12703 Type flag for scalars. See "svtype".
12704 "SVt_PVAV"
12706 Type flag for arrays. See "svtype".
12707 "SVt_PVCV"
12709 Type flag for subroutines. See "svtype".
12710 "SVt_PVFM"
12712 Type flag for formats. See "svtype".
12713 "SVt_PVGV"
12715 Type flag for typeglobs. See "svtype".
12716 "SVt_PVHV"
12718 Type flag for hashes. See "svtype".
12719 "SVt_PVIO"
12721 Type flag for I/O objects. See "svtype".
12722 "SVt_PVIV"
12724 Type flag for scalars. See "svtype".
12725 "SVt_PVLV"
12727 Type flag for scalars. See "svtype".
12728 "SVt_PVMG"
12730 Type flag for scalars. See "svtype".
12731 "SVt_PVNV"
12733 Type flag for scalars. See "svtype".
12734 "SVt_PVOBJ"
12736 NOTE: "SVt_PVOBJ" is experimental and may change or be removed
12737 without notice.
12738 Type flag for object instances. See "svtype".
12740 "SVt_REGEXP"
12742 Type flag for regular expressions. See "svtype".
12743 "svtype"
12745 An enum of flags for Perl types. These are found in the file sv.h
12746 in the "svtype" enum. Test these flags with the "SvTYPE" macro.
12747 The types are:
12749 SVt_NULL
12751 SVt_IV
12752 SVt_NV
12753 SVt_RV
12754 SVt_PV
12755 SVt_PVIV
12756 SVt_PVNV
12757 SVt_PVMG
12758 SVt_INVLIST
12759 SVt_REGEXP
12760 SVt_PVGV
12761 SVt_PVLV
12762 SVt_PVAV
12763 SVt_PVHV
12764 SVt_PVCV
12765 SVt_PVFM
12766 SVt_PVIO
12767 SVt_PVOBJ
12768 These are most easily explained from the bottom up.
12770 "SVt_PVOBJ" is for object instances of the new `use feature
12772 'class'` kind. "SVt_PVIO" is for I/O objects, "SVt_PVFM" for
12773 formats, "SVt_PVCV" for subroutines, "SVt_PVHV" for hashes and
12774 "SVt_PVAV" for arrays.
12775 All the others are scalar types, that is, things that can be bound
12777 to a "$" variable. For these, the internal types are mostly
12778 orthogonal to types in the Perl language.
12779 Hence, checking "SvTYPE(sv) < SVt_PVAV" is the best way to see
12781 whether something is a scalar.
12782 "SVt_PVGV" represents a typeglob. If "!SvFAKE(sv)", then it is a
12784 real, incoercible typeglob. If SvFAKE(sv), then it is a scalar to
12785 which a typeglob has been assigned. Assigning to it again will
12786 stop it from being a typeglob. "SVt_PVLV" represents a scalar that
12787 delegates to another scalar behind the scenes. It is used, e.g.,
12788 for the return value of "substr" and for tied hash and array
12789 elements. It can hold any scalar value, including a typeglob.
12790 "SVt_REGEXP" is for regular expressions. "SVt_INVLIST" is for Perl
12791 core internal use only.
12792 "SVt_PVMG" represents a "normal" scalar (not a typeglob, regular
12794 expression, or delegate). Since most scalars do not need all the
12795 internal fields of a PVMG, we save memory by allocating smaller
12796 structs when possible. All the other types are just simpler forms
12797 of "SVt_PVMG", with fewer internal fields. "SVt_NULL" can only
12798 hold undef. "SVt_IV" can hold undef, an integer, or a reference.
12799 ("SVt_RV" is an alias for "SVt_IV", which exists for backward
12800 compatibility.) "SVt_NV" can hold undef or a double. (In builds
12801 that support headless NVs, these could also hold a reference via a
12802 suitable offset, in the same way that SVt_IV does, but this is not
12803 currently supported and seems to be a rare use case.) "SVt_PV" can
12804 hold "undef", a string, or a reference. "SVt_PVIV" is a superset
12805 of "SVt_PV" and "SVt_IV". "SVt_PVNV" is a superset of "SVt_PV" and
12806 "SVt_NV". "SVt_PVMG" can hold anything "SVt_PVNV" can hold, but it
12807 may also be blessed or magical.
12808
12810 "AV_FROM_REF"
12811 "CV_FROM_REF"
12812 "HV_FROM_REF"
12813 The "*V_FROM_REF" macros extract the SvRV() from a given reference
12814 SV and return a suitably-cast to pointer to the referenced SV. When
12815 running under "-DDEBUGGING", assertions are also applied that check
12816 that ref is definitely a reference SV that refers to an SV of the
12817 right type.
12818 AV * AV_FROM_REF(SV * ref)
12820 CV * CV_FROM_REF(SV * ref)
12821 HV * HV_FROM_REF(SV * ref)
12822 "BOOL_INTERNALS_sv_isbool"
12824 Checks if a SvBoolFlagsOK() sv is a bool. Note that it is the
12825 caller's responsibility to ensure that the sv is SvBoolFlagsOK()
12826 before calling this. This is only useful in specialized logic like
12827 serialization code where performance is critical and the flags have
12828 already been checked to be correct. Almost always you should be
12829 using sv_isbool(sv) instead.
12830 bool BOOL_INTERNALS_sv_isbool(SV* sv)
12832 "BOOL_INTERNALS_sv_isbool_false"
12834 Checks if a SvBoolFlagsOK() sv is a false bool. Note that it is the
12835 caller's responsibility to ensure that the sv is SvBoolFlagsOK()
12836 before calling this. This is only useful in specialized logic like
12837 serialization code where performance is critical and the flags have
12838 already been checked to be correct. This is NOT what you should use
12839 to check if an SV is "false", for that you should be using
12840 "!SvTRUE(sv)" instead.
12841 bool BOOL_INTERNALS_sv_isbool_false(SV* sv)
12843 "BOOL_INTERNALS_sv_isbool_true"
12845 Checks if a SvBoolFlagsOK() sv is a true bool. Note that it is the
12846 caller's responsibility to ensure that the sv is SvBoolFlagsOK()
12847 before calling this. This is only useful in specialized logic like
12848 serialization code where performance is critical and the flags have
12849 already been checked to be correct. This is NOT what you should use
12850 to check if an SV is "true", for that you should be using
12851 SvTRUE(sv) instead.
12852 bool BOOL_INTERNALS_sv_isbool_true(SV* sv)
12854 "boolSV"
12856 Returns a true SV if "b" is a true value, or a false SV if "b" is
12857 0.
12858 See also "PL_sv_yes" and "PL_sv_no".
12860 SV * boolSV(bool b)
12862 "croak_xs_usage"
12864 A specialised variant of croak() for emitting the usage message for
12865 xsubs
12866 croak_xs_usage(cv, "eee_yow");
12868 works out the package name and subroutine name from "cv", and then
12870 calls croak(). Hence if "cv" is &ouch::awk, it would call "croak"
12871 as:
12872 Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
12874 "eee_yow");
12875 void croak_xs_usage(const CV * const cv,
12877 const char * const params)
12878 "DEFSV"
12880 Returns the SV associated with $_
12881 SV * DEFSV
12883 "DEFSV_set"
12885 Associate "sv" with $_
12886 void DEFSV_set(SV * sv)
12888 "get_sv"
12890 Returns the SV of the specified Perl scalar. "flags" are passed to
12891 ""gv_fetchpv"". If "GV_ADD" is set and the Perl variable does not
12892 exist then it will be created. If "flags" is zero and the variable
12893 does not exist then NULL is returned.
12894 NOTE: the perl_get_sv() form is deprecated.
12896 SV * get_sv(const char *name, I32 flags)
12898 "isGV_with_GP"
12900 Returns a boolean as to whether or not "sv" is a GV with a pointer
12901 to a GP (glob pointer).
12902 bool isGV_with_GP(SV * sv)
12904 "looks_like_number"
12906 Test if the content of an SV looks like a number (or is a number).
12907 "Inf" and "Infinity" are treated as numbers (so will not issue a
12908 non-numeric warning), even if your atof() doesn't grok them. Get-
12909 magic is ignored.
12910 I32 looks_like_number(SV * const sv)
12912 "MUTABLE_AV"
12914 "MUTABLE_CV"
12915 "MUTABLE_GV"
12916 "MUTABLE_HV"
12917 "MUTABLE_IO"
12918 "MUTABLE_PTR"
12919 "MUTABLE_SV"
12920 The "MUTABLE_*"() macros cast pointers to the types shown, in such
12921 a way (compiler permitting) that casting away const-ness will give
12922 a warning; e.g.:
12923 const SV *sv = ...;
12925 AV *av1 = (AV*)sv; <== BAD: the const has been silently
12926 cast away
12927 AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
12928 "MUTABLE_PTR" is the base macro used to derive new casts. The
12930 other already-built-in ones return pointers to what their names
12931 indicate.
12932 AV * MUTABLE_AV (AV * p)
12934 CV * MUTABLE_CV (CV * p)
12935 GV * MUTABLE_GV (GV * p)
12936 HV * MUTABLE_HV (HV * p)
12937 IO * MUTABLE_IO (IO * p)
12938 void * MUTABLE_PTR(void * p)
12939 SV * MUTABLE_SV (SV * p)
12940 "newRV"
12942 "newRV_inc"
12943 These are identical. They create an RV wrapper for an SV. The
12944 reference count for the original SV is incremented.
12945 SV * newRV(SV * const sv)
12947 "newRV_noinc"
12949 Creates an RV wrapper for an SV. The reference count for the
12950 original SV is not incremented.
12951 SV * newRV_noinc(SV * const tmpRef)
12953 "newSV"
12955 Creates a new SV. A non-zero "len" parameter indicates the number
12956 of bytes of preallocated string space the SV should have. An extra
12957 byte for a trailing "NUL" is also reserved. ("SvPOK" is not set
12958 for the SV even if string space is allocated.) The reference count
12959 for the new SV is set to 1.
12960 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the
12962 first parameter, x, a debug aid which allowed callers to identify
12963 themselves. This aid has been superseded by a new build option,
12964 "PERL_MEM_LOG" (see "PERL_MEM_LOG" in perlhacktips). The older API
12965 is still there for use in XS modules supporting older perls.
12966 SV * newSV(const STRLEN len)
12968 "newSVbool"
12970 Creates a new SV boolean.
12971 SV * newSVbool(const bool bool_val)
12973 "newSV_false"
12975 Creates a new SV that is a boolean false.
12976 SV * newSV_false()
12978 "newSVhek"
12980 Creates a new SV from the hash key structure. It will generate
12981 scalars that point to the shared string table where possible.
12982 Returns a new (undefined) SV if "hek" is NULL.
12983 SV * newSVhek(const HEK * const hek)
12985 "newSVhek_mortal"
12987 Creates a new mortal SV from the hash key structure. It will
12988 generate scalars that point to the shared string table where
12989 possible. Returns a new (undefined) SV if "hek" is NULL.
12990 This is more efficient than using sv_2mortal(newSVhek( ... ))
12992 SV * newSVhek_mortal(const HEK * const hek)
12994 "newSViv"
12996 Creates a new SV and copies an integer into it. The reference
12997 count for the SV is set to 1.
12998 SV * newSViv(const IV i)
13000 "newSVnv"
13002 Creates a new SV and copies a floating point value into it. The
13003 reference count for the SV is set to 1.
13004 SV * newSVnv(const NV n)
13006 "newSVpadname"
13008 NOTE: "newSVpadname" is experimental and may change or be removed
13009 without notice.
13010 Creates a new SV containing the pad name.
13012 SV* newSVpadname(PADNAME *pn)
13014 "newSVpv"
13016 Creates a new SV and copies a string (which may contain "NUL"
13017 ("\0") characters) into it. The reference count for the SV is set
13018 to 1. If "len" is zero, Perl will compute the length using
13019 strlen(), (which means if you use this option, that "s" can't have
13020 embedded "NUL" characters and has to have a terminating "NUL"
13021 byte).
13022 This function can cause reliability issues if you are likely to
13024 pass in empty strings that are not null terminated, because it will
13025 run strlen on the string and potentially run past valid memory.
13026 Using "newSVpvn" is a safer alternative for non "NUL" terminated
13028 strings. For string literals use "newSVpvs" instead. This
13029 function will work fine for "NUL" terminated strings, but if you
13030 want to avoid the if statement on whether to call "strlen" use
13031 "newSVpvn" instead (calling "strlen" yourself).
13032 SV * newSVpv(const char * const s, const STRLEN len)
13034 "newSVpvf"
13036 Creates a new SV and initializes it with the string formatted like
13037 "sv_catpvf".
13038 NOTE: "newSVpvf" must be explicitly called as "Perl_newSVpvf" with
13040 an "aTHX_" parameter.
13041 SV * Perl_newSVpvf(pTHX_ const char * const pat, ...)
13043 "newSVpvf_nocontext"
13045 Like "newSVpvf" but does not take a thread context ("aTHX")
13046 parameter, so is used in situations where the caller doesn't
13047 already have the thread context.
13048 SV * newSVpvf_nocontext(const char * const pat, ...)
13050 "newSVpvn"
13052 Creates a new SV and copies a string into it, which may contain
13053 "NUL" characters ("\0") and other binary data. The reference count
13054 for the SV is set to 1. Note that if "len" is zero, Perl will
13055 create a zero length (Perl) string. You are responsible for
13056 ensuring that the source buffer is at least "len" bytes long. If
13057 the "buffer" argument is NULL the new SV will be undefined.
13058 SV * newSVpvn(const char * const buffer, const STRLEN len)
13060 "newSVpvn_flags"
13062 Creates a new SV and copies a string (which may contain "NUL"
13063 ("\0") characters) into it. The reference count for the SV is set
13064 to 1. Note that if "len" is zero, Perl will create a zero length
13065 string. You are responsible for ensuring that the source string is
13066 at least "len" bytes long. If the "s" argument is NULL the new SV
13067 will be undefined. Currently the only flag bits accepted are
13068 "SVf_UTF8" and "SVs_TEMP". If "SVs_TEMP" is set, then sv_2mortal()
13069 is called on the result before returning. If "SVf_UTF8" is set,
13070 "s" is considered to be in UTF-8 and the "SVf_UTF8" flag will be
13071 set on the new SV. newSVpvn_utf8() is a convenience wrapper for
13072 this function, defined as
13073 #define newSVpvn_utf8(s, len, u) \
13075 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
13076 SV * newSVpvn_flags(const char * const s, const STRLEN len,
13078 const U32 flags)
13079 "newSVpvn_share"
13081 Creates a new SV with its "SvPVX_const" pointing to a shared string
13082 in the string table. If the string does not already exist in the
13083 table, it is created first. Turns on the "SvIsCOW" flag (or
13084 "READONLY" and "FAKE" in 5.16 and earlier). If the "hash"
13085 parameter is non-zero, that value is used; otherwise the hash is
13086 computed. The string's hash can later be retrieved from the SV
13087 with the "SvSHARED_HASH" macro. The idea here is that as the
13088 string table is used for shared hash keys these strings will have
13089 "SvPVX_const == HeKEY" and hash lookup will avoid string compare.
13090 SV * newSVpvn_share(const char *s, I32 len, U32 hash)
13092 "newSVpvn_utf8"
13094 Creates a new SV and copies a string (which may contain "NUL"
13095 ("\0") characters) into it. If "utf8" is true, calls "SvUTF8_on"
13096 on the new SV. Implemented as a wrapper around "newSVpvn_flags".
13097 SV* newSVpvn_utf8(const char* s, STRLEN len, U32 utf8)
13099 "newSVpvs"
13101 Like "newSVpvn", but takes a literal string instead of a
13102 string/length pair.
13103 SV* newSVpvs("literal string")
13105 "newSVpvs_flags"
13107 Like "newSVpvn_flags", but takes a literal string instead of a
13108 string/length pair.
13109 SV* newSVpvs_flags("literal string", U32 flags)
13111 "newSVpv_share"
13113 Like "newSVpvn_share", but takes a "NUL"-terminated string instead
13114 of a string/length pair.
13115 SV * newSVpv_share(const char *s, U32 hash)
13117 "newSVpvs_share"
13119 Like "newSVpvn_share", but takes a literal string instead of a
13120 string/length pair and omits the hash parameter.
13121 SV* newSVpvs_share("literal string")
13123 "newSVrv"
13125 Creates a new SV for the existing RV, "rv", to point to. If "rv"
13126 is not an RV then it will be upgraded to one. If "classname" is
13127 non-null then the new SV will be blessed in the specified package.
13128 The new SV is returned and its reference count is 1. The reference
13129 count 1 is owned by "rv". See also newRV_inc() and newRV_noinc()
13130 for creating a new RV properly.
13131 SV * newSVrv(SV * const rv, const char * const classname)
13133 "newSVsv"
13135 "newSVsv_flags"
13136 "newSVsv_nomg"
13137 These create a new SV which is an exact duplicate of the original
13138 SV (using "sv_setsv".)
13139 They differ only in that "newSVsv" performs 'get' magic;
13141 "newSVsv_nomg" skips any magic; and "newSVsv_flags" allows you to
13142 explicitly set a "flags" parameter.
13143 SV * newSVsv (SV * const old)
13145 SV * newSVsv_flags(SV * const old, I32 flags)
13146 SV * newSVsv_nomg (SV * const old)
13147 "newSV_true"
13149 Creates a new SV that is a boolean true.
13150 SV * newSV_true()
13152 "newSV_type"
13154 Creates a new SV, of the type specified. The reference count for
13155 the new SV is set to 1.
13156 SV * newSV_type(const svtype type)
13158 "newSV_type_mortal"
13160 Creates a new mortal SV, of the type specified. The reference
13161 count for the new SV is set to 1.
13162 This is equivalent to
13164 SV* sv = sv_2mortal(newSV_type(<some type>)) and
13165 SV* sv = sv_newmortal();
13166 sv_upgrade(sv, <some_type>) but should be more efficient than
13167 both of them. (Unless sv_2mortal is inlined at some point in the
13168 future.)
13169 SV * newSV_type_mortal(const svtype type)
13171 "newSVuv"
13173 Creates a new SV and copies an unsigned integer into it. The
13174 reference count for the SV is set to 1.
13175 SV * newSVuv(const UV u)
13177 "Nullsv"
13179 Null SV pointer. (No longer available when "PERL_CORE" is
13180 defined.)
13181 "PL_sv_no"
13183 This is the "false" SV. It is readonly. See "PL_sv_yes". Always
13184 refer to this as &PL_sv_no.
13185 SV PL_sv_no
13187 "PL_sv_undef"
13189 This is the "undef" SV. It is readonly. Always refer to this as
13190 &PL_sv_undef.
13191 SV PL_sv_undef
13193 "PL_sv_yes"
13195 This is the "true" SV. It is readonly. See "PL_sv_no". Always
13196 refer to this as &PL_sv_yes.
13197 SV PL_sv_yes
13199 "PL_sv_zero"
13201 This readonly SV has a zero numeric value and a "0" string value.
13202 It's similar to "PL_sv_no" except for its string value. Can be used
13203 as a cheap alternative to mXPUSHi(0) for example. Always refer to
13204 this as &PL_sv_zero. Introduced in 5.28.
13205 SV PL_sv_zero
13207 "SAVE_DEFSV"
13209 Localize $_. See "Localizing changes" in perlguts.
13210 void SAVE_DEFSV
13212 "sortsv"
13214 In-place sort an array of SV pointers with the given comparison
13215 routine.
13216 Currently this always uses mergesort. See "sortsv_flags" for a
13218 more flexible routine.
13219 void sortsv(SV **array, size_t num_elts, SVCOMPARE_t cmp)
13221 "sortsv_flags"
13223 In-place sort an array of SV pointers with the given comparison
13224 routine, with various SORTf_* flag options.
13225 void sortsv_flags(SV **array, size_t num_elts, SVCOMPARE_t cmp,
13227 U32 flags)
13228 "SV"
13230 Described in perlguts.
13231 "SvAMAGIC"
13233 Returns a boolean as to whether "sv" has overloading (active magic)
13234 enabled or not.
13235 bool SvAMAGIC(SV * sv)
13237 "SvAMAGIC_off"
13239 Indicate that "sv" has overloading (active magic) disabled.
13240 void SvAMAGIC_off(SV *sv)
13242 "SvAMAGIC_on"
13244 Indicate that "sv" has overloading (active magic) enabled.
13245 void SvAMAGIC_on(SV *sv)
13247 "sv_backoff"
13249 Remove any string offset. You should normally use the "SvOOK_off"
13250 macro wrapper instead.
13251 void sv_backoff(SV * const sv)
13253 "sv_bless"
13255 Blesses an SV into a specified package. The SV must be an RV. The
13256 package must be designated by its stash (see "gv_stashpv"). The
13257 reference count of the SV is unaffected.
13258 SV * sv_bless(SV * const sv, HV * const stash)
13260 "SvBoolFlagsOK"
13262 Returns a bool indicating whether the SV has the right flags set
13263 such that it is safe to call BOOL_INTERNALS_sv_isbool() or
13264 BOOL_INTERNALS_sv_isbool_true() or
13265 BOOL_INTERNALS_sv_isbool_false(). Currently equivalent to
13266 SvIandPOK(sv) or "SvIOK(sv) && SvPOK(sv)". Serialization may want
13267 to unroll this check. If so you are strongly recommended to add
13268 code like "assert(SvBoolFlagsOK(sv));" before calling using any of
13269 the BOOL_INTERNALS macros.
13270 U32 SvBoolFlagsOK(SV* sv)
13272 "sv_catpv"
13274 "sv_catpv_flags"
13275 "sv_catpv_mg"
13276 "sv_catpv_nomg"
13277 These concatenate the "NUL"-terminated string "sstr" onto the end
13278 of the string which is in the SV. If the SV has the UTF-8 status
13279 set, then the bytes appended should be valid UTF-8.
13280 They differ only in how they handle magic:
13282 "sv_catpv_mg" performs both 'get' and 'set' magic.
13284 "sv_catpv" performs only 'get' magic.
13286 "sv_catpv_nomg" skips all magic.
13288 "sv_catpv_flags" has an extra "flags" parameter which allows you to
13290 specify any combination of magic handling (using "SV_GMAGIC" and/or
13291 "SV_SMAGIC"), and to also override the UTF-8 handling. By
13292 supplying the "SV_CATUTF8" flag, the appended string is forced to
13293 be interpreted as UTF-8; by supplying instead the "SV_CATBYTES"
13294 flag, it will be interpreted as just bytes. Either the SV or the
13295 string appended will be upgraded to UTF-8 if necessary.
13296 void sv_catpv (SV * const dsv, const char *sstr)
13298 void sv_catpv_flags(SV *dsv, const char *sstr, const I32 flags)
13299 void sv_catpv_mg (SV * const dsv, const char * const sstr)
13300 void sv_catpv_nomg (SV * const dsv, const char *sstr)
13301 "sv_catpvf"
13303 "sv_catpvf_mg"
13304 "sv_catpvf_mg_nocontext"
13305 "sv_catpvf_nocontext"
13306 These process their arguments like "sprintf", and append the
13307 formatted output to an SV. As with "sv_vcatpvfn", argument
13308 reordering is not supporte when called with a non-null C-style
13309 variable argument list.
13310 If the appended data contains "wide" characters (including, but not
13312 limited to, SVs with a UTF-8 PV formatted with %s, and characters
13313 >255 formatted with %c), the original SV might get upgraded to
13314 UTF-8.
13315 If the original SV was UTF-8, the pattern should be valid UTF-8; if
13317 the original SV was bytes, the pattern should be too.
13318 All perform 'get' magic, but only "sv_catpvf_mg" and
13320 "sv_catpvf_mg_nocontext" perform 'set' magic.
13321 "sv_catpvf_nocontext" and "sv_catpvf_mg_nocontext" do not take a
13323 thread context ("aTHX") parameter, so are used in situations where
13324 the caller doesn't already have the thread context.
13325 NOTE: "sv_catpvf" must be explicitly called as "Perl_sv_catpvf"
13327 with an "aTHX_" parameter.
13328 NOTE: "sv_catpvf_mg" must be explicitly called as
13330 "Perl_sv_catpvf_mg" with an "aTHX_" parameter.
13331 void Perl_sv_catpvf (pTHX_ SV * const sv,
13333 const char * const pat, ...)
13334 void Perl_sv_catpvf_mg (pTHX_ SV * const sv,
13335 const char * const pat, ...)
13336 void sv_catpvf_mg_nocontext(SV * const sv,
13337 const char * const pat, ...)
13338 void sv_catpvf_nocontext (SV * const sv,
13339 const char * const pat, ...)
13340 "sv_catpvn"
13342 "sv_catpvn_flags"
13343 "sv_catpvn_mg"
13344 "sv_catpvn_nomg"
13345 These concatenate the "len" bytes of the string beginning at "ptr"
13346 onto the end of the string which is in "dsv". The caller must make
13347 sure "ptr" contains at least "len" bytes.
13348 For all but "sv_catpvn_flags", the string appended is assumed to be
13350 valid UTF-8 if the SV has the UTF-8 status set, and a string of
13351 bytes otherwise.
13352 They differ in that:
13354 "sv_catpvn_mg" performs both 'get' and 'set' magic on "dsv".
13356 "sv_catpvn" performs only 'get' magic.
13358 "sv_catpvn_nomg" skips all magic.
13360 "sv_catpvn_flags" has an extra "flags" parameter which allows you
13362 to specify any combination of magic handling (using "SV_GMAGIC"
13363 and/or "SV_SMAGIC") and to also override the UTF-8 handling. By
13364 supplying the "SV_CATBYTES" flag, the appended string is
13365 interpreted as plain bytes; by supplying instead the "SV_CATUTF8"
13366 flag, it will be interpreted as UTF-8, and the "dsv" will be
13367 upgraded to UTF-8 if necessary.
13368 "sv_catpvn", "sv_catpvn_mg", and "sv_catpvn_nomg" are implemented
13370 in terms of "sv_catpvn_flags".
13371 void sv_catpvn (SV *dsv, const char *sstr, STRLEN len)
13373 void sv_catpvn_flags(SV * const dsv, const char *sstr,
13374 const STRLEN len, const I32 flags)
13375 void sv_catpvn_mg (SV *dsv, const char *sstr, STRLEN len)
13376 void sv_catpvn_nomg (SV *dsv, const char *sstr, STRLEN len)
13377 "sv_catpvs"
13379 Like "sv_catpvn", but takes a literal string instead of a
13380 string/length pair.
13381 void sv_catpvs(SV* sv, "literal string")
13383 "sv_catpvs_flags"
13385 Like "sv_catpvn_flags", but takes a literal string instead of a
13386 string/length pair.
13387 void sv_catpvs_flags(SV* sv, "literal string", I32 flags)
13389 "sv_catpvs_mg"
13391 Like "sv_catpvn_mg", but takes a literal string instead of a
13392 string/length pair.
13393 void sv_catpvs_mg(SV* sv, "literal string")
13395 "sv_catpvs_nomg"
13397 Like "sv_catpvn_nomg", but takes a literal string instead of a
13398 string/length pair.
13399 void sv_catpvs_nomg(SV* sv, "literal string")
13401 "sv_catsv"
13403 "sv_catsv_flags"
13404 "sv_catsv_mg"
13405 "sv_catsv_nomg"
13406 These concatenate the string from SV "sstr" onto the end of the
13407 string in SV "dsv". If "sstr" is null, these are no-ops; otherwise
13408 only "dsv" is modified.
13409 They differ only in what magic they perform:
13411 "sv_catsv_mg" performs 'get' magic on both SVs before the copy, and
13413 'set' magic on "dsv" afterwards.
13414 "sv_catsv" performs just 'get' magic, on both SVs.
13416 "sv_catsv_nomg" skips all magic.
13418 "sv_catsv_flags" has an extra "flags" parameter which allows you to
13420 use "SV_GMAGIC" and/or "SV_SMAGIC" to specify any combination of
13421 magic handling (although either both or neither SV will have 'get'
13422 magic applied to it.)
13423 "sv_catsv", "sv_catsv_mg", and "sv_catsv_nomg" are implemented in
13425 terms of "sv_catsv_flags".
13426 void sv_catsv (SV *dsv, SV *sstr)
13428 void sv_catsv_flags(SV * const dsv, SV * const sstr,
13429 const I32 flags)
13430 void sv_catsv_mg (SV *dsv, SV *sstr)
13431 void sv_catsv_nomg (SV *dsv, SV *sstr)
13432 "SV_CHECK_THINKFIRST"
13434 Remove any encumbrances from "sv", that need to be taken care of
13435 before it is modifiable. For example if it is Copy on Write (COW),
13436 now is the time to make that copy.
13437 If you know that you are about to change the PV value of "sv",
13439 instead use ""SV_CHECK_THINKFIRST_COW_DROP"" to avoid the write
13440 that would be immediately written again.
13441 void SV_CHECK_THINKFIRST(SV * sv)
13443 "SV_CHECK_THINKFIRST_COW_DROP"
13445 Call this when you are about to replace the PV value in "sv", which
13446 is potentially copy-on-write. It stops any sharing with other SVs,
13447 so that no Copy on Write (COW) actually happens. This COW would be
13448 useless, as it would immediately get changed to something else.
13449 This function also removes any other encumbrances that would be
13450 problematic when changing "sv".
13451 void SV_CHECK_THINKFIRST_COW_DROP(SV * sv)
13453 "sv_chop"
13455 Efficient removal of characters from the beginning of the string
13456 buffer. SvPOK(sv), or at least SvPOKp(sv), must be true and "ptr"
13457 must be a pointer to somewhere inside the string buffer. "ptr"
13458 becomes the first character of the adjusted string. Uses the "OOK"
13459 hack. On return, only SvPOK(sv) and SvPOKp(sv) among the "OK"
13460 flags will be true.
13461 Beware: after this function returns, "ptr" and SvPVX_const(sv) may
13463 no longer refer to the same chunk of data.
13464 The unfortunate similarity of this function's name to that of
13466 Perl's "chop" operator is strictly coincidental. This function
13467 works from the left; "chop" works from the right.
13468 void sv_chop(SV * const sv, const char * const ptr)
13470 "sv_clear"
13472 Clear an SV: call any destructors, free up any memory used by the
13473 body, and free the body itself. The SV's head is not freed,
13474 although its type is set to all 1's so that it won't inadvertently
13475 be assumed to be live during global destruction etc. This function
13476 should only be called when "REFCNT" is zero. Most of the time
13477 you'll want to call "SvREFCNT_dec" instead.
13478 void sv_clear(SV * const orig_sv)
13480 "sv_cmp"
13482 Compares the strings in two SVs. Returns -1, 0, or 1 indicating
13483 whether the string in "sv1" is less than, equal to, or greater than
13484 the string in "sv2". Is UTF-8 and 'use bytes' aware, handles get
13485 magic, and will coerce its args to strings if necessary. See also
13486 "sv_cmp_locale".
13487 I32 sv_cmp(SV * const sv1, SV * const sv2)
13489 "sv_cmp_flags"
13491 Compares the strings in two SVs. Returns -1, 0, or 1 indicating
13492 whether the string in "sv1" is less than, equal to, or greater than
13493 the string in "sv2". Is UTF-8 and 'use bytes' aware and will
13494 coerce its args to strings if necessary. If the flags has the
13495 "SV_GMAGIC" bit set, it handles get magic. See also
13496 "sv_cmp_locale_flags".
13497 I32 sv_cmp_flags(SV * const sv1, SV * const sv2, const U32 flags)
13499 "sv_cmp_locale"
13501 Compares the strings in two SVs in a locale-aware manner. Is UTF-8
13502 and 'use bytes' aware, handles get magic, and will coerce its args
13503 to strings if necessary. See also "sv_cmp".
13504 I32 sv_cmp_locale(SV * const sv1, SV * const sv2)
13506 "sv_cmp_locale_flags"
13508 Compares the strings in two SVs in a locale-aware manner. Is UTF-8
13509 and 'use bytes' aware and will coerce its args to strings if
13510 necessary. If the flags contain "SV_GMAGIC", it handles get magic.
13511 See also "sv_cmp_flags".
13512 I32 sv_cmp_locale_flags(SV * const sv1, SV * const sv2,
13514 const U32 flags)
13515 "sv_collxfrm"
13517 This calls "sv_collxfrm_flags" with the SV_GMAGIC flag. See
13518 "sv_collxfrm_flags".
13519 char * sv_collxfrm(SV * const sv, STRLEN * const nxp)
13521 "sv_collxfrm_flags"
13523 Add Collate Transform magic to an SV if it doesn't already have it.
13524 If the flags contain "SV_GMAGIC", it handles get-magic.
13525 Any scalar variable may carry "PERL_MAGIC_collxfrm" magic that
13527 contains the scalar data of the variable, but transformed to such a
13528 format that a normal memory comparison can be used to compare the
13529 data according to the locale settings.
13530 char * sv_collxfrm_flags(SV * const sv, STRLEN * const nxp,
13532 I32 const flags)
13533 "sv_copypv"
13535 "sv_copypv_flags"
13536 "sv_copypv_nomg"
13537 These copy a stringified representation of the source SV into the
13538 destination SV. They automatically perform coercion of numeric
13539 values into strings. Guaranteed to preserve the "UTF8" flag even
13540 from overloaded objects. Similar in nature to "sv_2pv[_flags]" but
13541 they operate directly on an SV instead of just the string. Mostly
13542 they use ""sv_2pv_flags"" to do the work, except when that would
13543 lose the UTF-8'ness of the PV.
13544 The three forms differ only in whether or not they perform 'get
13546 magic' on "sv". "sv_copypv_nomg" skips 'get magic'; "sv_copypv"
13547 performs it; and "sv_copypv_flags" either performs it (if the
13548 "SV_GMAGIC" bit is set in "flags") or doesn't (if that bit is
13549 cleared).
13550 void sv_copypv (SV * const dsv, SV * const ssv)
13552 void sv_copypv_flags(SV * const dsv, SV * const ssv,
13553 const I32 flags)
13554 void sv_copypv_nomg (SV * const dsv, SV * const ssv)
13555 "SvCUR"
13557 Returns the length, in bytes, of the PV inside the SV. Note that
13558 this may not match Perl's "length"; for that, use sv_len_utf8(sv).
13559 See "SvLEN" also.
13560 STRLEN SvCUR(SV* sv)
13562 "SvCUR_set"
13564 Sets the current length, in bytes, of the C string which is in the
13565 SV. See "SvCUR" and "SvIV_set">.
13566 void SvCUR_set(SV* sv, STRLEN len)
13568 "sv_2cv"
13570 Using various gambits, try to get a CV from an SV; in addition, try
13571 if possible to set *st and *gvp to the stash and GV associated with
13572 it. The flags in "lref" are passed to "gv_fetchsv".
13573 CV * sv_2cv(SV *sv, HV ** const st, GV ** const gvp,
13575 const I32 lref)
13576 "sv_dec"
13578 "sv_dec_nomg"
13579 These auto-decrement the value in the SV, doing string to numeric
13580 conversion if necessary. They both handle operator overloading.
13581 They differ only in that:
13583 "sv_dec" handles 'get' magic; "sv_dec_nomg" skips 'get' magic.
13585 void sv_dec(SV * const sv)
13587 "sv_derived_from"
13589 Exactly like "sv_derived_from_pv", but doesn't take a "flags"
13590 parameter.
13591 bool sv_derived_from(SV *sv, const char * const name)
13593 "sv_derived_from_hv"
13595 Exactly like "sv_derived_from_pvn", but takes the name string as
13596 the "HvNAME" of the given HV (which would presumably represent a
13597 stash).
13598 bool sv_derived_from_hv(SV *sv, HV *hv)
13600 "sv_derived_from_pv"
13602 Exactly like "sv_derived_from_pvn", but takes a nul-terminated
13603 string instead of a string/length pair.
13604 bool sv_derived_from_pv(SV *sv, const char * const name,
13606 U32 flags)
13607 "sv_derived_from_pvn"
13609 Returns a boolean indicating whether the SV is derived from the
13610 specified class at the C level. To check derivation at the Perl
13611 level, call isa() as a normal Perl method.
13612 Currently, the only significant value for "flags" is SVf_UTF8.
13614 bool sv_derived_from_pvn(SV *sv, const char * const name,
13616 const STRLEN len, U32 flags)
13617 "sv_derived_from_sv"
13619 Exactly like "sv_derived_from_pvn", but takes the name string in
13620 the form of an SV instead of a string/length pair. This is the
13621 advised form.
13622 bool sv_derived_from_sv(SV *sv, SV *namesv, U32 flags)
13624 "sv_does"
13626 Like "sv_does_pv", but doesn't take a "flags" parameter.
13627 bool sv_does(SV *sv, const char * const name)
13629 "sv_does_pv"
13631 Like "sv_does_sv", but takes a nul-terminated string instead of an
13632 SV.
13633 bool sv_does_pv(SV *sv, const char * const name, U32 flags)
13635 "sv_does_pvn"
13637 Like "sv_does_sv", but takes a string/length pair instead of an SV.
13638 bool sv_does_pvn(SV *sv, const char * const name,
13640 const STRLEN len, U32 flags)
13641 "sv_does_sv"
13643 Returns a boolean indicating whether the SV performs a specific,
13644 named role. The SV can be a Perl object or the name of a Perl
13645 class.
13646 bool sv_does_sv(SV *sv, SV *namesv, U32 flags)
13648 "SvEND"
13650 Returns a pointer to the spot just after the last character in the
13651 string which is in the SV, where there is usually a trailing "NUL"
13652 character (even though Perl scalars do not strictly require it).
13653 See "SvCUR". Access the character as "*(SvEND(sv))".
13654 Warning: If "SvCUR" is equal to "SvLEN", then "SvEND" points to
13656 unallocated memory.
13657 char* SvEND(SV* sv)
13659 "sv_eq"
13661 Returns a boolean indicating whether the strings in the two SVs are
13662 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and
13663 will coerce its args to strings if necessary.
13664 This function does not handle operator overloading. For a version
13666 that does, see instead "sv_streq".
13667 I32 sv_eq(SV *sv1, SV *sv2)
13669 "sv_eq_flags"
13671 Returns a boolean indicating whether the strings in the two SVs are
13672 identical. Is UTF-8 and 'use bytes' aware and coerces its args to
13673 strings if necessary. If the flags has the "SV_GMAGIC" bit set, it
13674 handles get-magic, too.
13675 This function does not handle operator overloading. For a version
13677 that does, see instead "sv_streq_flags".
13678 I32 sv_eq_flags(SV *sv1, SV *sv2, const U32 flags)
13680 "sv_force_normal"
13682 Undo various types of fakery on an SV: if the PV is a shared
13683 string, make a private copy; if we're a ref, stop refing; if we're
13684 a glob, downgrade to an "xpvmg". See also "sv_force_normal_flags".
13685 void sv_force_normal(SV *sv)
13687 "sv_force_normal_flags"
13689 Undo various types of fakery on an SV, where fakery means "more
13690 than" a string: if the PV is a shared string, make a private copy;
13691 if we're a ref, stop refing; if we're a glob, downgrade to an
13692 "xpvmg"; if we're a copy-on-write scalar, this is the on-write time
13693 when we do the copy, and is also used locally; if this is a
13694 vstring, drop the vstring magic. If "SV_COW_DROP_PV" is set then a
13695 copy-on-write scalar drops its PV buffer (if any) and becomes
13696 "SvPOK_off" rather than making a copy. (Used where this scalar is
13697 about to be set to some other value.) In addition, the "flags"
13698 parameter gets passed to sv_unref_flags() when unreffing.
13699 "sv_force_normal" calls this function with flags set to 0.
13700 This function is expected to be used to signal to perl that this SV
13702 is about to be written to, and any extra book-keeping needs to be
13703 taken care of. Hence, it croaks on read-only values.
13704 void sv_force_normal_flags(SV * const sv, const U32 flags)
13706 "sv_free"
13708 Decrement an SV's reference count, and if it drops to zero, call
13709 "sv_clear" to invoke destructors and free up any memory used by the
13710 body; finally, deallocating the SV's head itself. Normally called
13711 via a wrapper macro "SvREFCNT_dec".
13712 void sv_free(SV * const sv)
13714 "SvGAMAGIC"
13716 Returns true if the SV has get magic or overloading. If either is
13717 true then the scalar is active data, and has the potential to
13718 return a new value every time it is accessed. Hence you must be
13719 careful to only read it once per user logical operation and work
13720 with that returned value. If neither is true then the scalar's
13721 value cannot change unless written to.
13722 U32 SvGAMAGIC(SV* sv)
13724 "sv_get_backrefs"
13726 NOTE: "sv_get_backrefs" is experimental and may change or be
13727 removed without notice.
13728 If "sv" is the target of a weak reference then it returns the back
13730 references structure associated with the sv; otherwise return
13731 "NULL".
13732 When returning a non-null result the type of the return is
13734 relevant. If it is an AV then the elements of the AV are the weak
13735 reference RVs which point at this item. If it is any other type
13736 then the item itself is the weak reference.
13737 See also Perl_sv_add_backref(), Perl_sv_del_backref(),
13739 Perl_sv_kill_backrefs()
13740 SV * sv_get_backrefs(SV * const sv)
13742 "SvGETMAGIC"
13744 Invokes "mg_get" on an SV if it has 'get' magic. For example, this
13745 will call "FETCH" on a tied variable. As of 5.37.1, this function
13746 is guaranteed to evaluate its argument exactly once.
13747 void SvGETMAGIC(SV *sv)
13749 "sv_gets"
13751 Get a line from the filehandle and store it into the SV, optionally
13752 appending to the currently-stored string. If "append" is not 0,
13753 the line is appended to the SV instead of overwriting it. "append"
13754 should be set to the byte offset that the appended string should
13755 start at in the SV (typically, SvCUR(sv) is a suitable choice).
13756 char * sv_gets(SV * const sv, PerlIO * const fp, I32 append)
13758 "SvGROW"
13760 Expands the character buffer in the SV so that it has room for the
13761 indicated number of bytes (remember to reserve space for an extra
13762 trailing "NUL" character). Calls "sv_grow" to perform the
13763 expansion if necessary. Returns a pointer to the character buffer.
13764 SV must be of type >= "SVt_PV". One alternative is to call
13765 "sv_grow" if you are not sure of the type of SV.
13766 You might mistakenly think that "len" is the number of bytes to add
13768 to the existing size, but instead it is the total size "sv" should
13769 be.
13770 char * SvGROW(SV* sv, STRLEN len)
13772 "SvIandPOK"
13774 Returns a bool indicating whether the SV is both SvPOK() and
13775 SvIOK() at the same time. Equivalent to "SvIOK(sv) && SvPOK(sv)"
13776 but more efficient.
13777 U32 SvIandPOK(SV* sv)
13779 "SvIandPOK_off"
13781 Unsets the PV and IV status of an SV in one operation. Equivalent
13782 to "SvIOK_off(sv); SvPK_off(v);" but more efficient.
13783 void SvIandPOK_off(SV* sv)
13785 "SvIandPOK_on"
13787 Tells an SV that is a string and a number in one operation.
13788 Equivalent to "SvIOK_on(sv); SvPOK_on(sv);" but more efficient.
13789 void SvIandPOK_on(SV* sv)
13791 "sv_inc"
13793 "sv_inc_nomg"
13794 These auto-increment the value in the SV, doing string to numeric
13795 conversion if necessary. They both handle operator overloading.
13796 They differ only in that "sv_inc" performs 'get' magic;
13798 "sv_inc_nomg" skips any magic.
13799 void sv_inc(SV * const sv)
13801 "sv_insert"
13803 Inserts and/or replaces a string at the specified offset/length
13804 within the SV. Similar to the Perl substr() function, with
13805 "littlelen" bytes starting at "little" replacing "len" bytes of the
13806 string in "bigstr" starting at "offset". Handles get magic.
13807 void sv_insert(SV * const bigstr, const STRLEN offset,
13809 const STRLEN len, const char * const little,
13810 const STRLEN littlelen)
13811 "sv_insert_flags"
13813 Same as "sv_insert", but the extra "flags" are passed to the
13814 "SvPV_force_flags" that applies to "bigstr".
13815 void sv_insert_flags(SV * const bigstr, const STRLEN offset,
13817 const STRLEN len, const char *little,
13818 const STRLEN littlelen, const U32 flags)
13819 "sv_2io"
13821 Using various gambits, try to get an IO from an SV: the IO slot if
13822 its a GV; or the recursive result if we're an RV; or the IO slot of
13823 the symbol named after the PV if we're a string.
13824 'Get' magic is ignored on the "sv" passed in, but will be called on
13826 SvRV(sv) if "sv" is an RV.
13827 IO * sv_2io(SV * const sv)
13829 "SvIOK"
13831 Returns a U32 value indicating whether the SV contains an integer.
13832 U32 SvIOK(SV* sv)
13834 "SvIOK_notUV"
13836 Returns a boolean indicating whether the SV contains a signed
13837 integer.
13838 bool SvIOK_notUV(SV* sv)
13840 "SvIOK_off"
13842 Unsets the IV status of an SV.
13843 void SvIOK_off(SV* sv)
13845 "SvIOK_on"
13847 Tells an SV that it is an integer.
13848 void SvIOK_on(SV* sv)
13850 "SvIOK_only"
13852 Tells an SV that it is an integer and disables all other "OK" bits.
13853 void SvIOK_only(SV* sv)
13855 "SvIOK_only_UV"
13857 Tells an SV that it is an unsigned integer and disables all other
13858 "OK" bits.
13859 void SvIOK_only_UV(SV* sv)
13861 "SvIOKp"
13863 Returns a U32 value indicating whether the SV contains an integer.
13864 Checks the private setting. Use "SvIOK" instead.
13865 U32 SvIOKp(SV* sv)
13867 "SvIOK_UV"
13869 Returns a boolean indicating whether the SV contains an integer
13870 that must be interpreted as unsigned. A non-negative integer whose
13871 value is within the range of both an IV and a UV may be flagged as
13872 either "SvUOK" or "SvIOK".
13873 bool SvIOK_UV(SV* sv)
13875 "sv_isa"
13877 Returns a boolean indicating whether the SV is blessed into the
13878 specified class.
13879 This does not check for subtypes or method overloading. Use
13881 "sv_isa_sv" to verify an inheritance relationship in the same way
13882 as the "isa" operator by respecting any isa() method overloading;
13883 or "sv_derived_from_sv" to test directly on the actual object type.
13884 int sv_isa(SV *sv, const char * const name)
13886 "sv_isa_sv"
13888 NOTE: "sv_isa_sv" is experimental and may change or be removed
13889 without notice.
13890 Returns a boolean indicating whether the SV is an object reference
13892 and is derived from the specified class, respecting any isa()
13893 method overloading it may have. Returns false if "sv" is not a
13894 reference to an object, or is not derived from the specified class.
13895 This is the function used to implement the behaviour of the "isa"
13897 operator.
13898 Does not invoke magic on "sv".
13900 Not to be confused with the older "sv_isa" function, which does not
13902 use an overloaded isa() method, nor will check subclassing.
13903 bool sv_isa_sv(SV *sv, SV *namesv)
13905 "SvIsBOOL"
13907 Returns true if the SV is one of the special boolean constants
13908 (PL_sv_yes or PL_sv_no), or is a regular SV whose last assignment
13909 stored a copy of one.
13910 bool SvIsBOOL(SV* sv)
13912 "SvIsCOW"
13914 Returns a U32 value indicating whether the SV is Copy-On-Write
13915 (either shared hash key scalars, or full Copy On Write scalars if
13916 5.9.0 is configured for COW).
13917 U32 SvIsCOW(SV* sv)
13919 "SvIsCOW_shared_hash"
13921 Returns a boolean indicating whether the SV is Copy-On-Write shared
13922 hash key scalar.
13923 bool SvIsCOW_shared_hash(SV* sv)
13925 "sv_isobject"
13927 Returns a boolean indicating whether the SV is an RV pointing to a
13928 blessed object. If the SV is not an RV, or if the object is not
13929 blessed, then this will return false.
13930 int sv_isobject(SV *sv)
13932 "SvIV"
13934 "SvIV_nomg"
13935 "SvIVx"
13936 These each coerce the given SV to IV and return it. The returned
13937 value in many circumstances will get stored in "sv"'s IV slot, but
13938 not in all cases. (Use "sv_setiv" to make sure it does).
13939 As of 5.37.1, all are guaranteed to evaluate "sv" only once.
13941 "SvIVx" is now identical to "SvIV", but prior to 5.37.1, it was the
13943 only form guaranteed to evaluate "sv" only once.
13944 "SvIV_nomg" is the same as "SvIV", but does not perform 'get'
13946 magic.
13947 IV SvIV(SV *sv)
13949 "sv_2iv_flags"
13951 Return the integer value of an SV, doing any necessary string
13952 conversion. If "flags" has the "SV_GMAGIC" bit set, does an
13953 mg_get() first. Normally used via the SvIV(sv) and SvIVx(sv)
13954 macros.
13955 IV sv_2iv_flags(SV * const sv, const I32 flags)
13957 "SvIV_set"
13959 Set the value of the IV pointer in sv to val. It is possible to
13960 perform the same function of this macro with an lvalue assignment
13961 to "SvIVX". With future Perls, however, it will be more efficient
13962 to use "SvIV_set" instead of the lvalue assignment to "SvIVX".
13963 void SvIV_set(SV* sv, IV val)
13965 "SvIVX"
13967 Returns the raw value in the SV's IV slot, without checks or
13968 conversions. Only use when you are sure "SvIOK" is true. See also
13969 "SvIV".
13970 IV SvIVX(SV* sv)
13972 "SvLEN"
13974 Returns the size of the string buffer in the SV, not including any
13975 part attributable to "SvOOK". See "SvCUR".
13976 STRLEN SvLEN(SV* sv)
13978 "sv_len"
13980 Returns the length of the string in the SV. Handles magic and type
13981 coercion and sets the UTF8 flag appropriately. See also "SvCUR",
13982 which gives raw access to the "xpv_cur" slot.
13983 STRLEN sv_len(SV * const sv)
13985 "SvLEN_set"
13987 Set the size of the string buffer for the SV. See "SvLEN".
13988 void SvLEN_set(SV* sv, STRLEN len)
13990 "sv_len_utf8"
13992 "sv_len_utf8_nomg"
13993 These return the number of characters in the string in an SV,
13994 counting wide UTF-8 bytes as a single character. Both handle type
13995 coercion. They differ only in that "sv_len_utf8" performs 'get'
13996 magic; "sv_len_utf8_nomg" skips any magic.
13997 STRLEN sv_len_utf8(SV * const sv)
13999 "SvLOCK"
14001 Arranges for a mutual exclusion lock to be obtained on "sv" if a
14002 suitable module has been loaded.
14003 void SvLOCK(SV* sv)
14005 "sv_magic"
14007 Adds magic to an SV. First upgrades "sv" to type "SVt_PVMG" if
14008 necessary, then adds a new magic item of type "how" to the head of
14009 the magic list.
14010 See "sv_magicext" (which "sv_magic" now calls) for a description of
14012 the handling of the "name" and "namlen" arguments.
14013 You need to use "sv_magicext" to add magic to "SvREADONLY" SVs and
14015 also to add more than one instance of the same "how".
14016 void sv_magic(SV * const sv, SV * const obj, const int how,
14018 const char * const name, const I32 namlen)
14019 "sv_magicext"
14021 Adds magic to an SV, upgrading it if necessary. Applies the
14022 supplied "vtable" and returns a pointer to the magic added.
14023 Note that "sv_magicext" will allow things that "sv_magic" will not.
14025 In particular, you can add magic to "SvREADONLY" SVs, and add more
14026 than one instance of the same "how".
14027 If "namlen" is greater than zero then a "savepvn" copy of "name" is
14029 stored, if "namlen" is zero then "name" is stored as-is and - as
14030 another special case - if "(name && namlen == HEf_SVKEY)" then
14031 "name" is assumed to contain an SV* and is stored as-is with its
14032 "REFCNT" incremented.
14033 (This is now used as a subroutine by "sv_magic".)
14035 MAGIC * sv_magicext(SV * const sv, SV * const obj, const int how,
14037 const MGVTBL * const vtbl,
14038 const char * const name, const I32 namlen)
14039 "SvMAGIC_set"
14041 Set the value of the MAGIC pointer in "sv" to val. See "SvIV_set".
14042 void SvMAGIC_set(SV* sv, MAGIC* val)
14044 "sv_2mortal"
14046 Marks an existing SV as mortal. The SV will be destroyed "soon",
14047 either by an explicit call to "FREETMPS", or by an implicit call at
14048 places such as statement boundaries. SvTEMP() is turned on which
14049 means that the SV's string buffer can be "stolen" if this SV is
14050 copied. See also "sv_newmortal" and "sv_mortalcopy".
14051 SV * sv_2mortal(SV * const sv)
14053 "sv_mortalcopy"
14055 Creates a new SV which is a copy of the original SV (using
14056 "sv_setsv"). The new SV is marked as mortal. It will be destroyed
14057 "soon", either by an explicit call to "FREETMPS", or by an implicit
14058 call at places such as statement boundaries. See also
14059 "sv_newmortal" and "sv_2mortal".
14060 SV * sv_mortalcopy(SV * const oldsv)
14062 "sv_mortalcopy_flags"
14064 Like "sv_mortalcopy", but the extra "flags" are passed to the
14065 "sv_setsv_flags".
14066 SV * sv_mortalcopy_flags(SV * const oldsv, U32 flags)
14068 "sv_newmortal"
14070 Creates a new null SV which is mortal. The reference count of the
14071 SV is set to 1. It will be destroyed "soon", either by an explicit
14072 call to "FREETMPS", or by an implicit call at places such as
14073 statement boundaries. See also "sv_mortalcopy" and "sv_2mortal".
14074 SV * sv_newmortal()
14076 "SvNIOK"
14078 Returns a U32 value indicating whether the SV contains a number,
14079 integer or double.
14080 U32 SvNIOK(SV* sv)
14082 "SvNIOK_off"
14084 Unsets the NV/IV status of an SV.
14085 void SvNIOK_off(SV* sv)
14087 "SvNIOKp"
14089 Returns a U32 value indicating whether the SV contains a number,
14090 integer or double. Checks the private setting. Use "SvNIOK"
14091 instead.
14092 U32 SvNIOKp(SV* sv)
14094 "SvNOK"
14096 Returns a U32 value indicating whether the SV contains a double.
14097 U32 SvNOK(SV* sv)
14099 "SvNOK_off"
14101 Unsets the NV status of an SV.
14102 void SvNOK_off(SV* sv)
14104 "SvNOK_on"
14106 Tells an SV that it is a double.
14107 void SvNOK_on(SV* sv)
14109 "SvNOK_only"
14111 Tells an SV that it is a double and disables all other OK bits.
14112 void SvNOK_only(SV* sv)
14114 "SvNOKp"
14116 Returns a U32 value indicating whether the SV contains a double.
14117 Checks the private setting. Use "SvNOK" instead.
14118 U32 SvNOKp(SV* sv)
14120 "sv_nolocking"
14122 "DEPRECATED!" It is planned to remove "sv_nolocking" from a future
14123 release of Perl. Do not use it for new code; remove it from
14124 existing code.
14125 Dummy routine which "locks" an SV when there is no locking module
14127 present. Exists to avoid test for a "NULL" function pointer and
14128 because it could potentially warn under some level of strict-ness.
14129 "Superseded" by sv_nosharing().
14131 void sv_nolocking(SV *sv)
14133 "sv_nounlocking"
14135 "DEPRECATED!" It is planned to remove "sv_nounlocking" from a
14136 future release of Perl. Do not use it for new code; remove it from
14137 existing code.
14138 Dummy routine which "unlocks" an SV when there is no locking module
14140 present. Exists to avoid test for a "NULL" function pointer and
14141 because it could potentially warn under some level of strict-ness.
14142 "Superseded" by sv_nosharing().
14144 void sv_nounlocking(SV *sv)
14146 "sv_numeq"
14148 A convenient shortcut for calling "sv_numeq_flags" with the
14149 "SV_GMAGIC" flag. This function basically behaves like the Perl
14150 code "$sv1 == $sv2".
14151 bool sv_numeq(SV *sv1, SV *sv2)
14153 "sv_numeq_flags"
14155 Returns a boolean indicating whether the numbers in the two SVs are
14156 identical. If the flags argument has the "SV_GMAGIC" bit set, it
14157 handles get-magic too. Will coerce its args to numbers if
14158 necessary. Treats "NULL" as undef.
14159 If flags does not have the "SV_SKIP_OVERLOAD" bit set, an attempt
14161 to use "==" overloading will be made. If such overloading does not
14162 exist or the flag is set, then regular numerical comparison will be
14163 used instead.
14164 bool sv_numeq_flags(SV *sv1, SV *sv2, const U32 flags)
14166 "SvNV"
14168 "SvNV_nomg"
14169 "SvNVx"
14170 These each coerce the given SV to NV and return it. The returned
14171 value in many circumstances will get stored in "sv"'s NV slot, but
14172 not in all cases. (Use "sv_setnv" to make sure it does).
14173 As of 5.37.1, all are guaranteed to evaluate "sv" only once.
14175 "SvNVx" is now identical to "SvNV", but prior to 5.37.1, it was the
14177 only form guaranteed to evaluate "sv" only once.
14178 "SvNV_nomg" is the same as "SvNV", but does not perform 'get'
14180 magic.
14181 NV SvNV(SV *sv)
14183 "sv_2nv_flags"
14185 Return the num value of an SV, doing any necessary string or
14186 integer conversion. If "flags" has the "SV_GMAGIC" bit set, does
14187 an mg_get() first. Normally used via the SvNV(sv) and SvNVx(sv)
14188 macros.
14189 NV sv_2nv_flags(SV * const sv, const I32 flags)
14191 "SvNV_set"
14193 Set the value of the NV pointer in "sv" to val. See "SvIV_set".
14194 void SvNV_set(SV* sv, NV val)
14196 "SvNVX"
14198 Returns the raw value in the SV's NV slot, without checks or
14199 conversions. Only use when you are sure "SvNOK" is true. See also
14200 "SvNV".
14201 NV SvNVX(SV* sv)
14203 "SvOK"
14205 Returns a U32 value indicating whether the value is defined. This
14206 is only meaningful for scalars.
14207 U32 SvOK(SV* sv)
14209 "SvOOK"
14211 Returns a U32 indicating whether the pointer to the string buffer
14212 is offset. This hack is used internally to speed up removal of
14213 characters from the beginning of a "SvPV". When "SvOOK" is true,
14214 then the start of the allocated string buffer is actually
14215 SvOOK_offset() bytes before "SvPVX". This offset used to be stored
14216 in "SvIVX", but is now stored within the spare part of the buffer.
14217 U32 SvOOK(SV* sv)
14219 "SvOOK_off"
14221 Remove any string offset.
14222 void SvOOK_off(SV * sv)
14224 "SvOOK_offset"
14226 Reads into "len" the offset from "SvPVX" back to the true start of
14227 the allocated buffer, which will be non-zero if "sv_chop" has been
14228 used to efficiently remove characters from start of the buffer.
14229 Implemented as a macro, which takes the address of "len", which
14230 must be of type "STRLEN". Evaluates "sv" more than once. Sets
14231 "len" to 0 if SvOOK(sv) is false.
14232 void SvOOK_offset(SV*sv, STRLEN len)
14234 "SvPOK"
14236 Returns a U32 value indicating whether the SV contains a character
14237 string.
14238 U32 SvPOK(SV* sv)
14240 "SvPOK_off"
14242 Unsets the PV status of an SV.
14243 void SvPOK_off(SV* sv)
14245 "SvPOK_on"
14247 Tells an SV that it is a string.
14248 void SvPOK_on(SV* sv)
14250 "SvPOK_only"
14252 Tells an SV that it is a string and disables all other "OK" bits.
14253 Will also turn off the UTF-8 status.
14254 void SvPOK_only(SV* sv)
14256 "SvPOK_only_UTF8"
14258 Tells an SV that it is a string and disables all other "OK" bits,
14259 and leaves the UTF-8 status as it was.
14260 void SvPOK_only_UTF8(SV* sv)
14262 "SvPOKp"
14264 Returns a U32 value indicating whether the SV contains a character
14265 string. Checks the private setting. Use "SvPOK" instead.
14266 U32 SvPOKp(SV* sv)
14268 "sv_pos_b2u"
14270 Converts the value pointed to by "offsetp" from a count of bytes
14271 from the start of the string, to a count of the equivalent number
14272 of UTF-8 chars. Handles magic and type coercion.
14273 Use "sv_pos_b2u_flags" in preference, which correctly handles
14275 strings longer than 2Gb.
14276 void sv_pos_b2u(SV * const sv, I32 * const offsetp)
14278 "sv_pos_b2u_flags"
14280 Converts "offset" from a count of bytes from the start of the
14281 string, to a count of the equivalent number of UTF-8 chars.
14282 Handles type coercion. "flags" is passed to "SvPV_flags", and
14283 usually should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
14284 STRLEN sv_pos_b2u_flags(SV * const sv, STRLEN const offset,
14286 U32 flags)
14287 "sv_pos_u2b"
14289 Converts the value pointed to by "offsetp" from a count of UTF-8
14290 chars from the start of the string, to a count of the equivalent
14291 number of bytes; if "lenp" is non-zero, it does the same to "lenp",
14292 but this time starting from the offset, rather than from the start
14293 of the string. Handles magic and type coercion.
14294 Use "sv_pos_u2b_flags" in preference, which correctly handles
14296 strings longer than 2Gb.
14297 void sv_pos_u2b(SV * const sv, I32 * const offsetp,
14299 I32 * const lenp)
14300 "sv_pos_u2b_flags"
14302 Converts the offset from a count of UTF-8 chars from the start of
14303 the string, to a count of the equivalent number of bytes; if "lenp"
14304 is non-zero, it does the same to "lenp", but this time starting
14305 from "offset", rather than from the start of the string. Handles
14306 type coercion. "flags" is passed to "SvPV_flags", and usually
14307 should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
14308 STRLEN sv_pos_u2b_flags(SV * const sv, STRLEN uoffset,
14310 STRLEN * const lenp, U32 flags)
14311 "SvPV"
14313 "SvPV_const"
14314 "SvPV_flags"
14315 "SvPV_flags_const"
14316 "SvPV_flags_mutable"
14317 "SvPV_mutable"
14318 "SvPV_nolen"
14319 "SvPV_nolen_const"
14320 "SvPV_nomg"
14321 "SvPV_nomg_const"
14322 "SvPV_nomg_const_nolen"
14323 "SvPV_nomg_nolen"
14324 "SvPVbyte"
14325 "SvPVbyte_nolen"
14326 "SvPVbyte_nomg"
14327 "SvPVbyte_or_null"
14328 "SvPVbyte_or_null_nomg"
14329 "SvPVbytex"
14330 "SvPVbytex_nolen"
14331 "SvPVutf8"
14332 "SvPVutf8_nolen"
14333 "SvPVutf8_nomg"
14334 "SvPVutf8_or_null"
14335 "SvPVutf8_or_null_nomg"
14336 "SvPVutf8x"
14337 "SvPVx"
14338 "SvPVx_const"
14339 "SvPVx_nolen"
14340 "SvPVx_nolen_const"
14341 These each return a pointer to the string in "sv", or a stringified
14342 form of "sv" if it does not contain a string. The SV may cache the
14343 stringified version becoming "SvPOK".
14344 This is a very basic and common operation, so there are lots of
14346 slightly different versions of it.
14347 Note that there is no guarantee that the return value of SvPV(sv),
14349 for example, is equal to SvPVX(sv), or that SvPVX(sv) contains
14350 valid data, or that successive calls to SvPV(sv) (or another of
14351 these forms) will return the same pointer value each time. This is
14352 due to the way that things like overloading and Copy-On-Write are
14353 handled. In these cases, the return value may point to a temporary
14354 buffer or similar. If you absolutely need the "SvPVX" field to be
14355 valid (for example, if you intend to write to it), then see
14356 "SvPV_force".
14357 The differences between the forms are:
14359 The forms with neither "byte" nor "utf8" in their names (e.g.,
14361 "SvPV" or "SvPV_nolen") can expose the SV's internal string buffer.
14362 If that buffer consists entirely of bytes 0-255 and includes any
14363 bytes above 127, then you MUST consult "SvUTF8" to determine the
14364 actual code points the string is meant to contain. Generally
14365 speaking, it is probably safer to prefer "SvPVbyte", "SvPVutf8",
14366 and the like. See "How do I pass a Perl string to a C library?" in
14367 perlguts for more details.
14368 The forms with "flags" in their names allow you to use the "flags"
14370 parameter to specify to process 'get' magic (by setting the
14371 "SV_GMAGIC" flag) or to skip 'get' magic (by clearing it). The
14372 other forms process 'get' magic, except for the ones with "nomg" in
14373 their names, which skip 'get' magic.
14374 The forms that take a "len" parameter will set that variable to the
14376 byte length of the resultant string (these are macros, so don't use
14377 &len).
14378 The forms with "nolen" in their names indicate they don't have a
14380 "len" parameter. They should be used only when it is known that
14381 the PV is a C string, terminated by a NUL byte, and without
14382 intermediate NUL characters; or when you don't care about its
14383 length.
14384 The forms with "const" in their names return "const char *" so that
14386 the compiler will hopefully complain if you were to try to modify
14387 the contents of the string (unless you cast away const yourself).
14388 The other forms return a mutable pointer so that the string is
14390 modifiable by the caller; this is emphasized for the ones with
14391 "mutable" in their names.
14392 As of 5.38, all forms are guaranteed to evaluate "sv" exactly once.
14394 For earlier Perls, use a form whose name ends with "x" for single
14395 evaluation.
14396 "SvPVutf8" is like "SvPV", but converts "sv" to UTF-8 first if not
14398 already UTF-8. Similarly, the other forms with "utf8" in their
14399 names correspond to their respective forms without.
14400 "SvPVutf8_or_null" and "SvPVutf8_or_null_nomg" don't have
14402 corresponding non-"utf8" forms. Instead they are like
14403 "SvPVutf8_nomg", but when "sv" is undef, they return "NULL".
14404 "SvPVbyte" is like "SvPV", but converts "sv" to byte representation
14406 first if currently encoded as UTF-8. If "sv" cannot be downgraded
14407 from UTF-8, it croaks. Similarly, the other forms with "byte" in
14408 their names correspond to their respective forms without.
14409 "SvPVbyte_or_null" doesn't have a corresponding non-"byte" form.
14411 Instead it is like "SvPVbyte", but when "sv" is undef, it returns
14412 "NULL".
14413 char* SvPV (SV* sv, STRLEN len)
14415 const char* SvPV_const (SV* sv, STRLEN len)
14416 char* SvPV_flags (SV* sv, STRLEN len, U32 flags)
14417 const char* SvPV_flags_const (SV* sv, STRLEN len, U32 flags)
14418 char* SvPV_flags_mutable (SV* sv, STRLEN len, U32 flags)
14419 char* SvPV_mutable (SV* sv, STRLEN len)
14420 char* SvPV_nolen (SV* sv)
14421 const char* SvPV_nolen_const (SV* sv)
14422 char* SvPV_nomg (SV* sv, STRLEN len)
14423 const char* SvPV_nomg_const (SV* sv, STRLEN len)
14424 const char* SvPV_nomg_const_nolen(SV* sv)
14425 char* SvPV_nomg_nolen (SV* sv)
14426 char* SvPVbyte (SV* sv, STRLEN len)
14427 char* SvPVbyte_nolen (SV* sv)
14428 char* SvPVbyte_nomg (SV* sv, STRLEN len)
14429 char* SvPVbyte_or_null (SV* sv, STRLEN len)
14430 char* SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
14431 char* SvPVbytex (SV* sv, STRLEN len)
14432 char* SvPVbytex_nolen (SV* sv)
14433 char* SvPVutf8 (SV* sv, STRLEN len)
14434 char* SvPVutf8_nolen (SV* sv)
14435 char* SvPVutf8_nomg (SV* sv, STRLEN len)
14436 char* SvPVutf8_or_null (SV* sv, STRLEN len)
14437 char* SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
14438 char* SvPVutf8x (SV* sv, STRLEN len)
14439 char* SvPVx (SV* sv, STRLEN len)
14440 const char* SvPVx_const (SV* sv, STRLEN len)
14441 char* SvPVx_nolen (SV* sv)
14442 const char* SvPVx_nolen_const (SV* sv)
14443 "sv_2pv"
14445 "sv_2pv_flags"
14446 These implement the various forms of the ""SvPV"" in perlapi
14447 macros. The macros are the preferred interface.
14448 These return a pointer to the string value of an SV (coercing it to
14450 a string if necessary), and set *lp to its length in bytes.
14451 The forms differ in that plain "sv_2pvbyte" always processes 'get'
14453 magic; and "sv_2pvbyte_flags" processes 'get' magic if and only if
14454 "flags" contains "SV_GMAGIC".
14455 char * sv_2pv (SV *sv, STRLEN *lp)
14457 char * sv_2pv_flags(SV * const sv, STRLEN * const lp,
14458 const U32 flags)
14459 "sv_2pvbyte"
14461 "sv_2pvbyte_flags"
14462 These implement the various forms of the ""SvPVbyte"" in perlapi
14463 macros. The macros are the preferred interface.
14464 These return a pointer to the byte-encoded representation of the
14466 SV, and set *lp to its length. If the SV is marked as being
14467 encoded as UTF-8, it will be downgraded, if possible, to a byte
14468 string. If the SV cannot be downgraded, they croak.
14469 The forms differ in that plain "sv_2pvbyte" always processes 'get'
14471 magic; and "sv_2pvbyte_flags" processes 'get' magic if and only if
14472 "flags" contains "SV_GMAGIC".
14473 char * sv_2pvbyte (SV *sv, STRLEN * const lp)
14475 char * sv_2pvbyte_flags(SV *sv, STRLEN * const lp,
14476 const U32 flags)
14477 "SvPVCLEAR"
14479 Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is
14480 properly null terminated. Equivalent to sv_setpvs(""), but more
14481 efficient.
14482 char * SvPVCLEAR(SV* sv)
14484 "SvPVCLEAR_FRESH"
14486 Like SvPVCLEAR, but optimized for newly-minted
14487 SVt_PV/PVIV/PVNV/PVMG that already have a PV buffer allocated, but
14488 no SvTHINKFIRST.
14489 char * SvPVCLEAR_FRESH(SV* sv)
14491 "SvPV_force"
14493 "SvPV_force_flags"
14494 "SvPV_force_flags_mutable"
14495 "SvPV_force_flags_nolen"
14496 "SvPV_force_mutable"
14497 "SvPV_force_nolen"
14498 "SvPV_force_nomg"
14499 "SvPV_force_nomg_nolen"
14500 "SvPVbyte_force"
14501 "SvPVbytex_force"
14502 "SvPVutf8_force"
14503 "SvPVutf8x_force"
14504 "SvPVx_force"
14505 These are like "SvPV", returning the string in the SV, but will
14506 force the SV into containing a string ("SvPOK"), and only a string
14507 ("SvPOK_only"), by hook or by crook. You need to use one of these
14508 "force" routines if you are going to update the "SvPVX" directly.
14509 Note that coercing an arbitrary scalar into a plain PV will
14511 potentially strip useful data from it. For example if the SV was
14512 "SvROK", then the referent will have its reference count
14513 decremented, and the SV itself may be converted to an "SvPOK"
14514 scalar with a string buffer containing a value such as
14515 "ARRAY(0x1234)".
14516 The differences between the forms are:
14518 The forms with "flags" in their names allow you to use the "flags"
14520 parameter to specify to perform 'get' magic (by setting the
14521 "SV_GMAGIC" flag) or to skip 'get' magic (by clearing it). The
14522 other forms do perform 'get' magic, except for the ones with "nomg"
14523 in their names, which skip 'get' magic.
14524 The forms that take a "len" parameter will set that variable to the
14526 byte length of the resultant string (these are macros, so don't use
14527 &len).
14528 The forms with "nolen" in their names indicate they don't have a
14530 "len" parameter. They should be used only when it is known that
14531 the PV is a C string, terminated by a NUL byte, and without
14532 intermediate NUL characters; or when you don't care about its
14533 length.
14534 The forms with "mutable" in their names are effectively the same as
14536 those without, but the name emphasizes that the string is
14537 modifiable by the caller, which it is in all the forms.
14538 "SvPVutf8_force" is like "SvPV_force", but converts "sv" to UTF-8
14540 first if not already UTF-8.
14541 "SvPVutf8x_force" is like "SvPVutf8_force", but guarantees to
14543 evaluate "sv" only once; use the more efficient "SvPVutf8_force"
14544 otherwise.
14545 "SvPVbyte_force" is like "SvPV_force", but converts "sv" to byte
14547 representation first if currently encoded as UTF-8. If the SV
14548 cannot be downgraded from UTF-8, this croaks.
14549 "SvPVbytex_force" is like "SvPVbyte_force", but guarantees to
14551 evaluate "sv" only once; use the more efficient "SvPVbyte_force"
14552 otherwise.
14553 char* SvPV_force (SV* sv, STRLEN len)
14555 char* SvPV_force_flags (SV * sv, STRLEN len, U32 flags)
14556 char* SvPV_force_flags_mutable(SV * sv, STRLEN len, U32 flags)
14557 char* SvPV_force_flags_nolen (SV * sv, U32 flags)
14558 char* SvPV_force_mutable (SV * sv, STRLEN len)
14559 char* SvPV_force_nolen (SV* sv)
14560 char* SvPV_force_nomg (SV* sv, STRLEN len)
14561 char* SvPV_force_nomg_nolen (SV * sv)
14562 char* SvPVbyte_force (SV * sv, STRLEN len)
14563 char* SvPVbytex_force (SV * sv, STRLEN len)
14564 char* SvPVutf8_force (SV * sv, STRLEN len)
14565 char* SvPVutf8x_force (SV * sv, STRLEN len)
14566 char* SvPVx_force (SV* sv, STRLEN len)
14567 "SvPV_free"
14569 Frees the PV buffer in "sv", leaving things in a precarious state,
14570 so should only be used as part of a larger operation
14571 void SvPV_free(SV * sv)
14573 "sv_pvn_force_flags"
14575 Get a sensible string out of the SV somehow. If "flags" has the
14576 "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate, else
14577 not. "sv_pvn_force" and "sv_pvn_force_nomg" are implemented in
14578 terms of this function. You normally want to use the various
14579 wrapper macros instead: see "SvPV_force" and "SvPV_force_nomg".
14580 char * sv_pvn_force_flags(SV * const sv, STRLEN * const lp,
14582 const U32 flags)
14583 "SvPV_renew"
14585 Low level micro optimization of "SvGROW". It is generally better
14586 to use "SvGROW" instead. This is because "SvPV_renew" ignores
14587 potential issues that "SvGROW" handles. "sv" needs to have a real
14588 "PV" that is unencumbered by things like COW. Using
14589 "SV_CHECK_THINKFIRST" or "SV_CHECK_THINKFIRST_COW_DROP" before
14590 calling this should clean it up, but why not just use "SvGROW" if
14591 you're not sure about the provenance?
14592 void SvPV_renew(SV* sv, STRLEN len)
14594 "SvPV_set"
14596 This is probably not what you want to use, you probably wanted
14597 "sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
14598 Set the value of the PV pointer in "sv" to the Perl allocated
14600 "NUL"-terminated string "val". See also "SvIV_set".
14601 Remember to free the previous PV buffer. There are many things to
14603 check. Beware that the existing pointer may be involved in copy-
14604 on-write or other mischief, so do SvOOK_off(sv) and use
14605 "sv_force_normal" or "SvPV_force" (or check the "SvIsCOW" flag)
14606 first to make sure this modification is safe. Then finally, if it
14607 is not a COW, call "SvPV_free" to free the previous PV buffer.
14608 void SvPV_set(SV* sv, char* val)
14610 "SvPV_shrink_to_cur"
14612 Trim any trailing unused memory in the PV of "sv", which needs to
14613 have a real "PV" that is unencumbered by things like COW. Think
14614 first before using this functionality. Is the space saving really
14615 worth giving up COW? Will the needed size of "sv" stay the same?
14616 If the answers are both yes, then use ""SV_CHECK_THINKFIRST"" or
14618 ""SV_CHECK_THINKFIRST_COW_DROP"" before calling this.
14619 void SvPV_shrink_to_cur(SV* sv)
14621 "sv_2pvutf8"
14623 "sv_2pvutf8_flags"
14624 These implement the various forms of the ""SvPVutf8"" in perlapi
14625 macros. The macros are the preferred interface.
14626 These return a pointer to the UTF-8-encoded representation of the
14628 SV, and set *lp to its length in bytes. They may cause the SV to
14629 be upgraded to UTF-8 as a side-effect.
14630 The forms differ in that plain "sv_2pvutf8" always processes 'get'
14632 magic; and "sv_2pvutf8_flags" processes 'get' magic if and only if
14633 "flags" contains "SV_GMAGIC".
14634 char * sv_2pvutf8 (SV *sv, STRLEN * const lp)
14636 char * sv_2pvutf8_flags(SV *sv, STRLEN * const lp,
14637 const U32 flags)
14638 "SvPVX"
14640 "SvPVX_const"
14641 "SvPVX_mutable"
14642 "SvPVXx"
14643 These return a pointer to the physical string in the SV. The SV
14644 must contain a string. Prior to 5.9.3 it is not safe to execute
14645 these unless the SV's type >= "SVt_PV".
14646 These are also used to store the name of an autoloaded subroutine
14648 in an XS AUTOLOAD routine. See "Autoloading with XSUBs" in
14649 perlguts.
14650 "SvPVXx" is identical to "SvPVX".
14652 "SvPVX_mutable" is merely a synonym for "SvPVX", but its name
14654 emphasizes that the string is modifiable by the caller.
14655 "SvPVX_const" differs in that the return value has been cast so
14657 that the compiler will complain if you were to try to modify the
14658 contents of the string, (unless you cast away const yourself).
14659 char* SvPVX (SV* sv)
14661 const char* SvPVX_const (SV* sv)
14662 char* SvPVX_mutable(SV* sv)
14663 char* SvPVXx (SV* sv)
14664 "SvPVXtrue"
14666 Returns a boolean as to whether or not "sv" contains a PV that is
14667 considered TRUE. FALSE is returned if "sv" doesn't contain a PV,
14668 or if the PV it does contain is zero length, or consists of just
14669 the single character '0'. Every other PV value is considered TRUE.
14670 As of Perl v5.37.1, "sv" is evaluated exactly once; in earlier
14672 releases, it could be evaluated more than once.
14673 bool SvPVXtrue(SV *sv)
14675 "SvREADONLY"
14677 Returns true if the argument is readonly, otherwise returns false.
14678 Exposed to perl code via Internals::SvREADONLY().
14679 U32 SvREADONLY(SV* sv)
14681 "SvREADONLY_off"
14683 Mark an object as not-readonly. Exactly what this mean depends on
14684 the object type. Exposed to perl code via Internals::SvREADONLY().
14685 U32 SvREADONLY_off(SV* sv)
14687 "SvREADONLY_on"
14689 Mark an object as readonly. Exactly what this means depends on the
14690 object type. Exposed to perl code via Internals::SvREADONLY().
14691 U32 SvREADONLY_on(SV* sv)
14693 "sv_ref"
14695 Returns a SV describing what the SV passed in is a reference to.
14696 dst can be a SV to be set to the description or NULL, in which case
14698 a mortal SV is returned.
14699 If ob is true and the SV is blessed, the description is the class
14701 name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
14702 SV * sv_ref(SV *dst, const SV * const sv, const int ob)
14704 "SvREFCNT"
14706 Returns the value of the object's reference count. Exposed to perl
14707 code via Internals::SvREFCNT().
14708 U32 SvREFCNT(SV* sv)
14710 "SvREFCNT_dec"
14712 "SvREFCNT_dec_set_NULL"
14713 "SvREFCNT_dec_ret_NULL"
14714 "SvREFCNT_dec_NN"
14715 These decrement the reference count of the given SV.
14716 "SvREFCNT_dec_NN" may only be used when "sv" is known to not be
14718 "NULL".
14719 The function SvREFCNT_dec_ret_NULL() is identical to the
14721 SvREFCNT_dec() except it returns a NULL "SV *". It is used by
14722 SvREFCNT_dec_set_NULL() which is a macro which will, when passed a
14723 non-NULL argument, decrement the reference count of its argument
14724 and then set it to NULL. You can replace code of the following
14725 form:
14726 if (sv) {
14728 SvREFCNT_dec_NN(sv);
14729 sv = NULL;
14730 }
14731 with
14733 SvREFCNT_dec_set_NULL(sv);
14735 void SvREFCNT_dec (SV *sv)
14737 void SvREFCNT_dec_set_NULL(SV *sv)
14738 SV * SvREFCNT_dec_ret_NULL(SV *sv)
14739 void SvREFCNT_dec_NN (SV *sv)
14740 "SvREFCNT_inc"
14742 "SvREFCNT_inc_NN"
14743 "SvREFCNT_inc_simple"
14744 "SvREFCNT_inc_simple_NN"
14745 "SvREFCNT_inc_simple_void"
14746 "SvREFCNT_inc_simple_void_NN"
14747 "SvREFCNT_inc_void"
14748 "SvREFCNT_inc_void_NN"
14749 These all increment the reference count of the given SV. The ones
14750 without "void" in their names return the SV.
14751 "SvREFCNT_inc" is the base operation; the rest are optimizations if
14753 various input constraints are known to be true; hence, all can be
14754 replaced with "SvREFCNT_inc".
14755 "SvREFCNT_inc_NN" can only be used if you know "sv" is not "NULL".
14757 Since we don't have to check the NULLness, it's faster and smaller.
14758 "SvREFCNT_inc_void" can only be used if you don't need the return
14760 value. The macro doesn't need to return a meaningful value.
14761 "SvREFCNT_inc_void_NN" can only be used if you both don't need the
14763 return value, and you know that "sv" is not "NULL". The macro
14764 doesn't need to return a meaningful value, or check for NULLness,
14765 so it's smaller and faster.
14766 "SvREFCNT_inc_simple" can only be used with expressions without
14768 side effects. Since we don't have to store a temporary value, it's
14769 faster.
14770 "SvREFCNT_inc_simple_NN" can only be used with expressions without
14772 side effects and you know "sv" is not "NULL". Since we don't have
14773 to store a temporary value, nor check for NULLness, it's faster and
14774 smaller.
14775 "SvREFCNT_inc_simple_void" can only be used with expressions
14777 without side effects and you don't need the return value.
14778 "SvREFCNT_inc_simple_void_NN" can only be used with expressions
14780 without side effects, you don't need the return value, and you know
14781 "sv" is not "NULL".
14782 SV * SvREFCNT_inc (SV *sv)
14784 SV * SvREFCNT_inc_NN (SV *sv)
14785 SV* SvREFCNT_inc_simple (SV* sv)
14786 SV* SvREFCNT_inc_simple_NN (SV* sv)
14787 void SvREFCNT_inc_simple_void (SV* sv)
14788 void SvREFCNT_inc_simple_void_NN(SV* sv)
14789 void SvREFCNT_inc_void (SV *sv)
14790 void SvREFCNT_inc_void_NN (SV* sv)
14791 "sv_reftype"
14793 Returns a string describing what the SV is a reference to.
14794 If ob is true and the SV is blessed, the string is the class name,
14796 otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
14797 const char * sv_reftype(const SV * const sv, const int ob)
14799 "sv_replace"
14801 Make the first argument a copy of the second, then delete the
14802 original. The target SV physically takes over ownership of the
14803 body of the source SV and inherits its flags; however, the target
14804 keeps any magic it owns, and any magic in the source is discarded.
14805 Note that this is a rather specialist SV copying operation; most of
14806 the time you'll want to use "sv_setsv" or one of its many macro
14807 front-ends.
14808 void sv_replace(SV * const sv, SV * const nsv)
14810 "sv_report_used"
14812 Dump the contents of all SVs not yet freed (debugging aid).
14813 void sv_report_used()
14815 "sv_reset"
14817 Underlying implementation for the "reset" Perl function. Note that
14818 the perl-level function is vaguely deprecated.
14819 void sv_reset(const char *s, HV * const stash)
14821 "SvROK"
14823 Tests if the SV is an RV.
14824 U32 SvROK(SV* sv)
14826 "SvROK_off"
14828 Unsets the RV status of an SV.
14829 void SvROK_off(SV* sv)
14831 "SvROK_on"
14833 Tells an SV that it is an RV.
14834 void SvROK_on(SV* sv)
14836 "SvRV"
14838 Dereferences an RV to return the SV.
14839 SV* SvRV(SV* sv)
14841 "SvRV_set"
14843 Set the value of the RV pointer in "sv" to val. See "SvIV_set".
14844 void SvRV_set(SV* sv, SV* val)
14846 "sv_rvunweaken"
14848 Unweaken a reference: Clear the "SvWEAKREF" flag on this RV; remove
14849 the backreference to this RV from the array of backreferences
14850 associated with the target SV, increment the refcount of the
14851 target. Silently ignores "undef" and warns on non-weak references.
14852 SV * sv_rvunweaken(SV * const sv)
14854 "sv_rvweaken"
14856 Weaken a reference: set the "SvWEAKREF" flag on this RV; give the
14857 referred-to SV "PERL_MAGIC_backref" magic if it hasn't already; and
14858 push a back-reference to this RV onto the array of backreferences
14859 associated with that magic. If the RV is magical, set magic will
14860 be called after the RV is cleared. Silently ignores "undef" and
14861 warns on already-weak references.
14862 SV * sv_rvweaken(SV * const sv)
14864 "sv_setbool"
14866 "sv_setbool_mg"
14867 These set an SV to a true or false boolean value, upgrading first
14868 if necessary.
14869 They differ only in that "sv_setbool_mg" handles 'set' magic;
14871 "sv_setbool" does not.
14872 void sv_setbool(SV *sv, bool b)
14874 "sv_set_bool"
14876 Equivalent to "sv_setsv(sv, bool_val ? &Pl_sv_yes : &PL_sv_no)",
14877 but may be made more efficient in the future. Doesn't handle set
14878 magic.
14879 The perl equivalent is "$sv = !!$expr;".
14881 Introduced in perl 5.35.11.
14883 void sv_set_bool(SV *sv, const bool bool_val)
14885 "sv_set_false"
14887 Equivalent to "sv_setsv(sv, &PL_sv_no)", but may be made more
14888 efficient in the future. Doesn't handle set magic.
14889 The perl equivalent is "$sv = !1;".
14891 Introduced in perl 5.35.11.
14893 void sv_set_false(SV *sv)
14895 "sv_setiv"
14897 "sv_setiv_mg"
14898 These copy an integer into the given SV, upgrading first if
14899 necessary.
14900 They differ only in that "sv_setiv_mg" handles 'set' magic;
14902 "sv_setiv" does not.
14903 void sv_setiv (SV * const sv, const IV num)
14905 void sv_setiv_mg(SV * const sv, const IV i)
14906 "SvSETMAGIC"
14908 Invokes "mg_set" on an SV if it has 'set' magic. This is necessary
14909 after modifying a scalar, in case it is a magical variable like $|
14910 or a tied variable (it calls "STORE"). This macro evaluates its
14911 argument more than once.
14912 void SvSETMAGIC(SV* sv)
14914 "SvSetMagicSV"
14916 "SvSetMagicSV_nosteal"
14917 "SvSetSV"
14918 "SvSetSV_nosteal"
14919 if "dsv" is the same as "ssv", these do nothing. Otherwise they
14920 all call some form of "sv_setsv". They may evaluate their
14921 arguments more than once.
14922 The only differences are:
14924 "SvSetMagicSV" and "SvSetMagicSV_nosteal" perform any required
14926 'set' magic afterwards on the destination SV; "SvSetSV" and
14927 "SvSetSV_nosteal" do not.
14928 "SvSetSV_nosteal" "SvSetMagicSV_nosteal" call a non-destructive
14930 version of "sv_setsv".
14931 void SvSetMagicSV(SV* dsv, SV* ssv)
14933 "sv_setnv"
14935 "sv_setnv_mg"
14936 These copy a double into the given SV, upgrading first if
14937 necessary.
14938 They differ only in that "sv_setnv_mg" handles 'set' magic;
14940 "sv_setnv" does not.
14941 void sv_setnv(SV * const sv, const NV num)
14943 "sv_setpv"
14945 "sv_setpv_mg"
14946 "sv_setpvn"
14947 "sv_setpvn_fresh"
14948 "sv_setpvn_mg"
14949 "sv_setpvs"
14950 "sv_setpvs_mg"
14951 These copy a string into the SV "sv", making sure it is
14952 "SvPOK_only".
14953 In the "pvs" forms, the string must be a C literal string, enclosed
14955 in double quotes.
14956 In the "pvn" forms, the first byte of the string is pointed to by
14958 "ptr", and "len" indicates the number of bytes to be copied,
14959 potentially including embedded "NUL" characters.
14960 In the plain "pv" forms, "ptr" points to a NUL-terminated C string.
14962 That is, it points to the first byte of the string, and the copy
14963 proceeds up through the first encountered "NUL" byte.
14964 In the forms that take a "ptr" argument, if it is NULL, the SV will
14966 become undefined.
14967 The UTF-8 flag is not changed by these functions. A terminating
14969 NUL byte is guaranteed in the result.
14970 The "_mg" forms handle 'set' magic; the other forms skip all magic.
14972 "sv_setpvn_fresh" is a cut-down alternative to "sv_setpvn",
14974 intended ONLY to be used with a fresh sv that has been upgraded to
14975 a SVt_PV, SVt_PVIV, SVt_PVNV, or SVt_PVMG.
14976 void sv_setpv (SV * const sv, const char * const ptr)
14978 void sv_setpv_mg (SV * const sv, const char * const ptr)
14979 void sv_setpvn (SV * const sv, const char * const ptr,
14980 const STRLEN len)
14981 void sv_setpvn_fresh(SV * const sv, const char * const ptr,
14982 const STRLEN len)
14983 void sv_setpvn_mg (SV * const sv, const char * const ptr,
14984 const STRLEN len)
14985 void sv_setpvs (SV* sv, "literal string")
14986 void sv_setpvs_mg (SV* sv, "literal string")
14987 "sv_setpv_bufsize"
14989 Sets the SV to be a string of cur bytes length, with at least len
14990 bytes available. Ensures that there is a null byte at SvEND.
14991 Returns a char * pointer to the SvPV buffer.
14992 char * sv_setpv_bufsize(SV * const sv, const STRLEN cur,
14994 const STRLEN len)
14995 "sv_setpvf"
14997 "sv_setpvf_mg"
14998 "sv_setpvf_mg_nocontext"
14999 "sv_setpvf_nocontext"
15000 These work like "sv_catpvf" but copy the text into the SV instead
15001 of appending it.
15002 The differences between these are:
15004 "sv_setpvf_mg" and "sv_setpvf_mg_nocontext" perform 'set' magic;
15006 "sv_setpvf" and "sv_setpvf_nocontext" skip all magic.
15007 "sv_setpvf_nocontext" and "sv_setpvf_mg_nocontext" do not take a
15009 thread context ("aTHX") parameter, so are used in situations where
15010 the caller doesn't already have the thread context.
15011 NOTE: "sv_setpvf" must be explicitly called as "Perl_sv_setpvf"
15013 with an "aTHX_" parameter.
15014 NOTE: "sv_setpvf_mg" must be explicitly called as
15016 "Perl_sv_setpvf_mg" with an "aTHX_" parameter.
15017 void Perl_sv_setpvf (pTHX_ SV * const sv,
15019 const char * const pat, ...)
15020 void Perl_sv_setpvf_mg (pTHX_ SV * const sv,
15021 const char * const pat, ...)
15022 void sv_setpvf_mg_nocontext(SV * const sv,
15023 const char * const pat, ...)
15024 void sv_setpvf_nocontext (SV * const sv,
15025 const char * const pat, ...)
15026 "sv_setref_iv"
15028 Copies an integer into a new SV, optionally blessing the SV. The
15029 "rv" argument will be upgraded to an RV. That RV will be modified
15030 to point to the new SV. The "classname" argument indicates the
15031 package for the blessing. Set "classname" to "NULL" to avoid the
15032 blessing. The new SV will have a reference count of 1, and the RV
15033 will be returned.
15034 SV * sv_setref_iv(SV * const rv, const char * const classname,
15036 const IV iv)
15037 "sv_setref_nv"
15039 Copies a double into a new SV, optionally blessing the SV. The
15040 "rv" argument will be upgraded to an RV. That RV will be modified
15041 to point to the new SV. The "classname" argument indicates the
15042 package for the blessing. Set "classname" to "NULL" to avoid the
15043 blessing. The new SV will have a reference count of 1, and the RV
15044 will be returned.
15045 SV * sv_setref_nv(SV * const rv, const char * const classname,
15047 const NV nv)
15048 "sv_setref_pv"
15050 Copies a pointer into a new SV, optionally blessing the SV. The
15051 "rv" argument will be upgraded to an RV. That RV will be modified
15052 to point to the new SV. If the "pv" argument is "NULL", then
15053 "PL_sv_undef" will be placed into the SV. The "classname" argument
15054 indicates the package for the blessing. Set "classname" to "NULL"
15055 to avoid the blessing. The new SV will have a reference count of
15056 1, and the RV will be returned.
15057 Do not use with other Perl types such as HV, AV, SV, CV, because
15059 those objects will become corrupted by the pointer copy process.
15060 Note that "sv_setref_pvn" copies the string while this copies the
15062 pointer.
15063 SV * sv_setref_pv(SV * const rv, const char * const classname,
15065 void * const pv)
15066 "sv_setref_pvn"
15068 Copies a string into a new SV, optionally blessing the SV. The
15069 length of the string must be specified with "n". The "rv" argument
15070 will be upgraded to an RV. That RV will be modified to point to
15071 the new SV. The "classname" argument indicates the package for the
15072 blessing. Set "classname" to "NULL" to avoid the blessing. The
15073 new SV will have a reference count of 1, and the RV will be
15074 returned.
15075 Note that "sv_setref_pv" copies the pointer while this copies the
15077 string.
15078 SV * sv_setref_pvn(SV * const rv, const char * const classname,
15080 const char * const pv, const STRLEN n)
15081 "sv_setref_pvs"
15083 Like "sv_setref_pvn", but takes a literal string instead of a
15084 string/length pair.
15085 SV * sv_setref_pvs(SV *const rv, const char *const classname,
15087 "literal string")
15088 "sv_setref_uv"
15090 Copies an unsigned integer into a new SV, optionally blessing the
15091 SV. The "rv" argument will be upgraded to an RV. That RV will be
15092 modified to point to the new SV. The "classname" argument
15093 indicates the package for the blessing. Set "classname" to "NULL"
15094 to avoid the blessing. The new SV will have a reference count of
15095 1, and the RV will be returned.
15096 SV * sv_setref_uv(SV * const rv, const char * const classname,
15098 const UV uv)
15099 "sv_setrv_inc"
15101 "sv_setrv_inc_mg"
15102 As "sv_setrv_noinc" but increments the reference count of ref.
15103 "sv_setrv_inc_mg" will invoke 'set' magic on the SV; "sv_setrv_inc"
15105 will not.
15106 void sv_setrv_inc(SV * const sv, SV * const ref)
15108 "sv_setrv_noinc"
15110 "sv_setrv_noinc_mg"
15111 Copies an SV pointer into the given SV as an SV reference,
15112 upgrading it if necessary. After this, SvRV(sv) is equal to ref.
15113 This does not adjust the reference count of ref. The reference ref
15114 must not be NULL.
15115 "sv_setrv_noinc_mg" will invoke 'set' magic on the SV;
15117 "sv_setrv_noinc" will not.
15118 void sv_setrv_noinc(SV * const sv, SV * const ref)
15120 "sv_setsv"
15122 "sv_setsv_flags"
15123 "sv_setsv_mg"
15124 "sv_setsv_nomg"
15125 These copy the contents of the source SV "ssv" into the destination
15126 SV "dsv". "ssv" may be destroyed if it is mortal, so don't use
15127 these functions if the source SV needs to be reused. Loosely
15128 speaking, they perform a copy-by-value, obliterating any previous
15129 content of the destination.
15130 They differ only in that:
15132 "sv_setsv" calls 'get' magic on "ssv", but skips 'set' magic on
15134 "dsv".
15135 "sv_setsv_mg" calls both 'get' magic on "ssv" and 'set' magic on
15137 "dsv".
15138 "sv_setsv_nomg" skips all magic.
15140 "sv_setsv_flags" has a "flags" parameter which you can use to
15142 specify any combination of magic handling, and also you can specify
15143 "SV_NOSTEAL" so that the buffers of temps will not be stolen.
15144 You probably want to instead use one of the assortment of wrappers,
15146 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
15147 "SvSetMagicSV_nosteal".
15148 "sv_setsv_flags" is the primary function for copying scalars, and
15150 most other copy-ish functions and macros use it underneath.
15151 void sv_setsv (SV *dsv, SV *ssv)
15153 void sv_setsv_flags(SV *dsv, SV *ssv, const I32 flags)
15154 void sv_setsv_mg (SV * const dsv, SV * const ssv)
15155 void sv_setsv_nomg (SV *dsv, SV *ssv)
15156 "sv_set_true"
15158 Equivalent to "sv_setsv(sv, &PL_sv_yes)", but may be made more
15159 efficient in the future. Doesn't handle set magic.
15160 The perl equivalent is "$sv = !0;".
15162 Introduced in perl 5.35.11.
15164 void sv_set_true(SV *sv)
15166 "sv_set_undef"
15168 Equivalent to "sv_setsv(sv, &PL_sv_undef)", but more efficient.
15169 Doesn't handle set magic.
15170 The perl equivalent is "$sv = undef;". Note that it doesn't free
15172 any string buffer, unlike "undef $sv".
15173 Introduced in perl 5.25.12.
15175 void sv_set_undef(SV *sv)
15177 "sv_setuv"
15179 "sv_setuv_mg"
15180 These copy an unsigned integer into the given SV, upgrading first
15181 if necessary.
15182 They differ only in that "sv_setuv_mg" handles 'set' magic;
15184 "sv_setuv" does not.
15185 void sv_setuv (SV * const sv, const UV num)
15187 void sv_setuv_mg(SV * const sv, const UV u)
15188 "SvSHARE"
15190 Arranges for "sv" to be shared between threads if a suitable module
15191 has been loaded.
15192 void SvSHARE(SV* sv)
15194 "SvSHARED_HASH"
15196 Returns the hash for "sv" created by "newSVpvn_share".
15197 struct hek* SvSHARED_HASH(SV * sv)
15199 "SvSTASH"
15201 Returns the stash of the SV.
15202 HV* SvSTASH(SV* sv)
15204 "SvSTASH_set"
15206 Set the value of the STASH pointer in "sv" to val. See "SvIV_set".
15207 void SvSTASH_set(SV* sv, HV* val)
15209 "sv_streq"
15211 A convenient shortcut for calling "sv_streq_flags" with the
15212 "SV_GMAGIC" flag. This function basically behaves like the Perl
15213 code "$sv1 eq $sv2".
15214 bool sv_streq(SV *sv1, SV *sv2)
15216 "sv_streq_flags"
15218 Returns a boolean indicating whether the strings in the two SVs are
15219 identical. If the flags argument has the "SV_GMAGIC" bit set, it
15220 handles get-magic too. Will coerce its args to strings if
15221 necessary. Treats "NULL" as undef. Correctly handles the UTF8 flag.
15222 If flags does not have the "SV_SKIP_OVERLOAD" bit set, an attempt
15224 to use "eq" overloading will be made. If such overloading does not
15225 exist or the flag is set, then regular string comparison will be
15226 used instead.
15227 bool sv_streq_flags(SV *sv1, SV *sv2, const U32 flags)
15229 "SvTRUE"
15231 "SvTRUE_NN"
15232 "SvTRUE_nomg"
15233 "SvTRUE_nomg_NN"
15234 "SvTRUEx"
15235 These return a boolean indicating whether Perl would evaluate the
15236 SV as true or false. See "SvOK" for a defined/undefined test.
15237 As of Perl 5.32, all are guaranteed to evaluate "sv" only once.
15239 Prior to that release, only "SvTRUEx" guaranteed single evaluation;
15240 now "SvTRUEx" is identical to "SvTRUE".
15241 "SvTRUE_nomg" and "TRUE_nomg_NN" do not perform 'get' magic; the
15243 others do unless the scalar is already "SvPOK", "SvIOK", or "SvNOK"
15244 (the public, not the private flags).
15245 "SvTRUE_NN" is like "SvTRUE", but "sv" is assumed to be non-null
15247 (NN). If there is a possibility that it is NULL, use plain
15248 "SvTRUE".
15249 "SvTRUE_nomg_NN" is like "SvTRUE_nomg", but "sv" is assumed to be
15251 non-null (NN). If there is a possibility that it is NULL, use
15252 plain "SvTRUE_nomg".
15253 bool SvTRUE(SV *sv)
15255 "SvTYPE"
15257 Returns the type of the SV. See "svtype".
15258 svtype SvTYPE(SV* sv)
15260 "SvUNLOCK"
15262 Releases a mutual exclusion lock on "sv" if a suitable module has
15263 been loaded.
15264 void SvUNLOCK(SV* sv)
15266 "sv_unmagic"
15268 Removes all magic of type "type" from an SV.
15269 int sv_unmagic(SV * const sv, const int type)
15271 "sv_unmagicext"
15273 Removes all magic of type "type" with the specified "vtbl" from an
15274 SV.
15275 int sv_unmagicext(SV * const sv, const int type,
15277 const MGVTBL *vtbl)
15278 "sv_unref"
15280 Unsets the RV status of the SV, and decrements the reference count
15281 of whatever was being referenced by the RV. This can almost be
15282 thought of as a reversal of "newSVrv". This is "sv_unref_flags"
15283 with the "flag" being zero. See "SvROK_off".
15284 void sv_unref(SV *sv)
15286 "sv_unref_flags"
15288 Unsets the RV status of the SV, and decrements the reference count
15289 of whatever was being referenced by the RV. This can almost be
15290 thought of as a reversal of "newSVrv". The "cflags" argument can
15291 contain "SV_IMMEDIATE_UNREF" to force the reference count to be
15292 decremented (otherwise the decrementing is conditional on the
15293 reference count being different from one or the reference being a
15294 readonly SV). See "SvROK_off".
15295 void sv_unref_flags(SV * const ref, const U32 flags)
15297 "SvUOK"
15299 Returns a boolean indicating whether the SV contains an integer
15300 that must be interpreted as unsigned. A non-negative integer whose
15301 value is within the range of both an IV and a UV may be flagged as
15302 either "SvUOK" or "SvIOK".
15303 bool SvUOK(SV* sv)
15305 "SvUPGRADE"
15307 Used to upgrade an SV to a more complex form. Uses "sv_upgrade" to
15308 perform the upgrade if necessary. See "svtype".
15309 void SvUPGRADE(SV* sv, svtype type)
15311 "sv_upgrade"
15313 Upgrade an SV to a more complex form. Generally adds a new body
15314 type to the SV, then copies across as much information as possible
15315 from the old body. It croaks if the SV is already in a more
15316 complex form than requested. You generally want to use the
15317 "SvUPGRADE" macro wrapper, which checks the type before calling
15318 "sv_upgrade", and hence does not croak. See also "svtype".
15319 void sv_upgrade(SV * const sv, svtype new_type)
15321 "sv_usepvn"
15323 "sv_usepvn_flags"
15324 "sv_usepvn_mg"
15325 These tell an SV to use "ptr" for its string value. Normally SVs
15326 have their string stored inside the SV, but these tell the SV to
15327 use an external string instead.
15328 "ptr" should point to memory that was allocated by ""Newx"". It
15330 must be the start of a "Newx"-ed block of memory, and not a pointer
15331 to the middle of it (beware of "OOK" and copy-on-write), and not be
15332 from a non-"Newx" memory allocator like "malloc". The string
15333 length, "len", must be supplied. By default this function will
15334 ""Renew"" (i.e. realloc, move) the memory pointed to by "ptr", so
15335 that the pointer should not be freed or used by the programmer
15336 after giving it to "sv_usepvn", and neither should any pointers
15337 from "behind" that pointer (e.g., "ptr" + 1) be used.
15338 In the "sv_usepvn_flags" form, if "flags & SV_SMAGIC" is true,
15340 "SvSETMAGIC" is called before returning. And if
15341 "flags & SV_HAS_TRAILING_NUL" is true, then "ptr[len]" must be
15342 "NUL", and the realloc will be skipped (i.e., the buffer is
15343 actually at least 1 byte longer than "len", and already meets the
15344 requirements for storing in "SvPVX").
15345 "sv_usepvn" is merely "sv_usepvn_flags" with "flags" set to 0, so
15347 'set' magic is skipped.
15348 "sv_usepvn_mg" is merely "sv_usepvn_flags" with "flags" set to
15350 "SV_SMAGIC", so 'set' magic is performed.
15351 void sv_usepvn (SV *sv, char *ptr, STRLEN len)
15353 void sv_usepvn_flags(SV * const sv, char *ptr, const STRLEN len,
15354 const U32 flags)
15355 void sv_usepvn_mg (SV *sv, char *ptr, STRLEN len)
15356 "sv_utf8_decode"
15358 If the PV of the SV is an octet sequence in Perl's extended UTF-8
15359 and contains a multiple-byte character, the "SvUTF8" flag is turned
15360 on so that it looks like a character. If the PV contains only
15361 single-byte characters, the "SvUTF8" flag stays off. Scans PV for
15362 validity and returns FALSE if the PV is invalid UTF-8.
15363 bool sv_utf8_decode(SV * const sv)
15365 "sv_utf8_downgrade"
15367 "sv_utf8_downgrade_flags"
15368 "sv_utf8_downgrade_nomg"
15369 These attempt to convert the PV of an SV from characters to bytes.
15370 If the PV contains a character that cannot fit in a byte, this
15371 conversion will fail; in this case, "FALSE" is returned if
15372 "fail_ok" is true; otherwise they croak.
15373 They are not a general purpose Unicode to byte encoding interface:
15375 use the "Encode" extension for that.
15376 They differ only in that:
15378 "sv_utf8_downgrade" processes 'get' magic on "sv".
15380 "sv_utf8_downgrade_nomg" does not.
15382 "sv_utf8_downgrade_flags" has an additional "flags" parameter in
15384 which you can specify "SV_GMAGIC" to process 'get' magic, or leave
15385 it cleared to not process 'get' magic.
15386 bool sv_utf8_downgrade (SV * const sv, const bool fail_ok)
15388 bool sv_utf8_downgrade_flags(SV * const sv, const bool fail_ok,
15389 const U32 flags)
15390 bool sv_utf8_downgrade_nomg (SV * const sv, const bool fail_ok)
15391 "sv_utf8_encode"
15393 Converts the PV of an SV to UTF-8, but then turns the "SvUTF8" flag
15394 off so that it looks like octets again.
15395 void sv_utf8_encode(SV * const sv)
15397 "SvUTF8_off"
15399 Unsets the UTF-8 status of an SV (the data is not changed, just the
15400 flag). Do not use frivolously.
15401 void SvUTF8_off(SV *sv)
15403 "SvUTF8_on"
15405 Turn on the UTF-8 status of an SV (the data is not changed, just
15406 the flag). Do not use frivolously.
15407 void SvUTF8_on(SV *sv)
15409 "sv_utf8_upgrade"
15411 "sv_utf8_upgrade_flags"
15412 "sv_utf8_upgrade_flags_grow"
15413 "sv_utf8_upgrade_nomg"
15414 These convert the PV of an SV to its UTF-8-encoded form. The SV is
15415 forced to string form if it is not already. They always set the
15416 "SvUTF8" flag to avoid future validity checks even if the whole
15417 string is the same in UTF-8 as not. They return the number of
15418 bytes in the converted string
15419 The forms differ in just two ways. The main difference is whether
15421 or not they perform 'get magic' on "sv". "sv_utf8_upgrade_nomg"
15422 skips 'get magic'; "sv_utf8_upgrade" performs it; and
15423 "sv_utf8_upgrade_flags" and "sv_utf8_upgrade_flags_grow" either
15424 perform it (if the "SV_GMAGIC" bit is set in "flags") or don't (if
15425 that bit is cleared).
15426 The other difference is that "sv_utf8_upgrade_flags_grow" has an
15428 additional parameter, "extra", which allows the caller to specify
15429 an amount of space to be reserved as spare beyond what is needed
15430 for the actual conversion. This is used when the caller knows it
15431 will soon be needing yet more space, and it is more efficient to
15432 request space from the system in a single call. This form is
15433 otherwise identical to "sv_utf8_upgrade_flags".
15434 These are not a general purpose byte encoding to Unicode interface:
15436 use the Encode extension for that.
15437 The "SV_FORCE_UTF8_UPGRADE" flag is now ignored.
15439 STRLEN sv_utf8_upgrade (SV *sv)
15441 STRLEN sv_utf8_upgrade_flags (SV * const sv, const I32 flags)
15442 STRLEN sv_utf8_upgrade_flags_grow(SV * const sv, const I32 flags,
15443 STRLEN extra)
15444 STRLEN sv_utf8_upgrade_nomg (SV *sv)
15445 "SvUTF8"
15447 Returns a U32 value indicating the UTF-8 status of an SV. If
15448 things are set-up properly, this indicates whether or not the SV
15449 contains UTF-8 encoded data. You should use this after a call to
15450 "SvPV" or one of its variants, in case any call to string
15451 overloading updates the internal flag.
15452 If you want to take into account the bytes pragma, use "DO_UTF8"
15454 instead.
15455 U32 SvUTF8(SV* sv)
15457 "SvUV"
15459 "SvUV_nomg"
15460 "SvUVx"
15461 These each coerce the given SV to UV and return it. The returned
15462 value in many circumstances will get stored in "sv"'s UV slot, but
15463 not in all cases. (Use "sv_setuv" to make sure it does).
15464 As of 5.37.1, all are guaranteed to evaluate "sv" only once.
15466 "SvUVx" is now identical to "SvUV", but prior to 5.37.1, it was the
15468 only form guaranteed to evaluate "sv" only once.
15469 UV SvUV(SV *sv)
15471 "sv_2uv_flags"
15473 Return the unsigned integer value of an SV, doing any necessary
15474 string conversion. If "flags" has the "SV_GMAGIC" bit set, does an
15475 mg_get() first. Normally used via the SvUV(sv) and SvUVx(sv)
15476 macros.
15477 UV sv_2uv_flags(SV * const sv, const I32 flags)
15479 "SvUV_set"
15481 Set the value of the UV pointer in "sv" to val. See "SvIV_set".
15482 void SvUV_set(SV* sv, UV val)
15484 "SvUVX"
15486 Returns the raw value in the SV's UV slot, without checks or
15487 conversions. Only use when you are sure "SvIOK" is true. See also
15488 "SvUV".
15489 UV SvUVX(SV* sv)
15491 "SvUVXx"
15493 "DEPRECATED!" It is planned to remove "SvUVXx" from a future
15494 release of Perl. Do not use it for new code; remove it from
15495 existing code.
15496 This is an unnecessary synonym for "SvUVX"
15498 UV SvUVXx(SV* sv)
15500 "sv_vcatpvf"
15502 "sv_vcatpvf_mg"
15503 These process their arguments like "sv_vcatpvfn" called with a non-
15504 null C-style variable argument list, and append the formatted
15505 output to "sv".
15506 They differ only in that "sv_vcatpvf_mg" performs 'set' magic;
15508 "sv_vcatpvf" skips 'set' magic.
15509 Both perform 'get' magic.
15511 They are usually accessed via their frontends "sv_catpvf" and
15513 "sv_catpvf_mg".
15514 void sv_vcatpvf(SV * const sv, const char * const pat,
15516 va_list * const args)
15517 "sv_vcatpvfn"
15519 "sv_vcatpvfn_flags"
15520 These process their arguments like vsprintf(3) and append the
15521 formatted output to an SV. They use an array of SVs if the C-style
15522 variable argument list is missing ("NULL"). Argument reordering
15523 (using format specifiers like "%2$d" or "%*2$d") is supported only
15524 when using an array of SVs; using a C-style "va_list" argument list
15525 with a format string that uses argument reordering will yield an
15526 exception.
15527 When running with taint checks enabled, they indicate via
15529 "maybe_tainted" if results are untrustworthy (often due to the use
15530 of locales).
15531 They assume that "pat" has the same utf8-ness as "sv". It's the
15533 caller's responsibility to ensure that this is so.
15534 They differ in that "sv_vcatpvfn_flags" has a "flags" parameter in
15536 which you can set or clear the "SV_GMAGIC" and/or SV_SMAGIC flags,
15537 to specify which magic to handle or not handle; whereas plain
15538 "sv_vcatpvfn" always specifies both 'get' and 'set' magic.
15539 They are usually used via one of the frontends ""sv_vcatpvf"" and
15541 ""sv_vcatpvf_mg"".
15542 void sv_vcatpvfn (SV * const sv, const char * const pat,
15544 const STRLEN patlen, va_list * const args,
15545 SV ** const svargs, const Size_t sv_count,
15546 bool * const maybe_tainted)
15547 void sv_vcatpvfn_flags(SV * const sv, const char * const pat,
15548 const STRLEN patlen, va_list * const args,
15549 SV ** const svargs, const Size_t sv_count,
15550 bool * const maybe_tainted,
15551 const U32 flags)
15552 "SvVOK"
15554 Returns a boolean indicating whether the SV contains a v-string.
15555 bool SvVOK(SV* sv)
15557 "sv_vsetpvf"
15559 "sv_vsetpvf_mg"
15560 These work like "sv_vcatpvf" but copy the text into the SV instead
15561 of appending it.
15562 They differ only in that "sv_vsetpvf_mg" performs 'set' magic;
15564 "sv_vsetpvf" skips all magic.
15565 They are usually used via their frontends, "sv_setpvf" and
15567 "sv_setpvf_mg".
15568 void sv_vsetpvf(SV * const sv, const char * const pat,
15570 va_list * const args)
15571 "sv_vsetpvfn"
15573 Works like "sv_vcatpvfn" but copies the text into the SV instead of
15574 appending it.
15575 Usually used via one of its frontends ""sv_vsetpvf"" and
15577 ""sv_vsetpvf_mg"".
15578 void sv_vsetpvfn(SV * const sv, const char * const pat,
15580 const STRLEN patlen, va_list * const args,
15581 SV ** const svargs, const Size_t sv_count,
15582 bool * const maybe_tainted)
15583 "SvVSTRING_mg"
15585 Returns the vstring magic, or NULL if none
15586 MAGIC* SvVSTRING_mg(SV * sv)
15588 "vnewSVpvf"
15590 Like "newSVpvf" but the arguments are an encapsulated argument
15591 list.
15592 SV * vnewSVpvf(const char * const pat, va_list * const args)
15594
15596 "SvTAINT"
15597 Taints an SV if tainting is enabled, and if some input to the
15598 current expression is tainted--usually a variable, but possibly
15599 also implicit inputs such as locale settings. "SvTAINT" propagates
15600 that taintedness to the outputs of an expression in a pessimistic
15601 fashion; i.e., without paying attention to precisely which outputs
15602 are influenced by which inputs.
15603 void SvTAINT(SV* sv)
15605 "SvTAINTED"
15607 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
15608 not.
15609 bool SvTAINTED(SV* sv)
15611 "SvTAINTED_off"
15613 Untaints an SV. Be very careful with this routine, as it short-
15614 circuits some of Perl's fundamental security features. XS module
15615 authors should not use this function unless they fully understand
15616 all the implications of unconditionally untainting the value.
15617 Untainting should be done in the standard perl fashion, via a
15618 carefully crafted regexp, rather than directly untainting
15619 variables.
15620 void SvTAINTED_off(SV* sv)
15622 "SvTAINTED_on"
15624 Marks an SV as tainted if tainting is enabled.
15625 void SvTAINTED_on(SV* sv)
15627
15629 "ASCTIME_R_PROTO"
15630 This symbol encodes the prototype of "asctime_r". It is zero if
15631 "d_asctime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
15632 macros of reentr.h if "d_asctime_r" is defined.
15633 "CTIME_R_PROTO"
15635 This symbol encodes the prototype of "ctime_r". It is zero if
15636 "d_ctime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC" macros
15637 of reentr.h if "d_ctime_r" is defined.
15638 "GMTIME_MAX"
15640 This symbol contains the maximum value for the "time_t" offset that
15641 the system function gmtime () accepts, and defaults to 0
15642 "GMTIME_MIN"
15644 This symbol contains the minimum value for the "time_t" offset that
15645 the system function gmtime () accepts, and defaults to 0
15646 "GMTIME_R_PROTO"
15648 This symbol encodes the prototype of "gmtime_r". It is zero if
15649 "d_gmtime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
15650 macros of reentr.h if "d_gmtime_r" is defined.
15651 "HAS_ASCTIME_R"
15653 This symbol, if defined, indicates that the "asctime_r" routine is
15654 available to asctime re-entrantly.
15655 "HAS_ASCTIME64"
15657 This symbol, if defined, indicates that the "asctime64" () routine
15658 is available to do the 64bit variant of asctime ()
15659 "HAS_CTIME_R"
15661 This symbol, if defined, indicates that the "ctime_r" routine is
15662 available to ctime re-entrantly.
15663 "HAS_CTIME64"
15665 This symbol, if defined, indicates that the "ctime64" () routine is
15666 available to do the 64bit variant of ctime ()
15667 "HAS_DIFFTIME"
15669 This symbol, if defined, indicates that the "difftime" routine is
15670 available.
15671 "HAS_DIFFTIME64"
15673 This symbol, if defined, indicates that the "difftime64" () routine
15674 is available to do the 64bit variant of difftime ()
15675 "HAS_FUTIMES"
15677 This symbol, if defined, indicates that the "futimes" routine is
15678 available to change file descriptor time stamps with "struct
15679 timevals".
15680 "HAS_GETITIMER"
15682 This symbol, if defined, indicates that the "getitimer" routine is
15683 available to return interval timers.
15684 "HAS_GETTIMEOFDAY"
15686 This symbol, if defined, indicates that the gettimeofday() system
15687 call is available for a sub-second accuracy clock. Usually, the
15688 file sys/resource.h needs to be included (see "I_SYS_RESOURCE").
15689 The type "Timeval" should be used to refer to ""struct timeval"".
15690 "HAS_GMTIME_R"
15692 This symbol, if defined, indicates that the "gmtime_r" routine is
15693 available to gmtime re-entrantly.
15694 "HAS_GMTIME64"
15696 This symbol, if defined, indicates that the "gmtime64" () routine
15697 is available to do the 64bit variant of gmtime ()
15698 "HAS_LOCALTIME_R"
15700 This symbol, if defined, indicates that the "localtime_r" routine
15701 is available to localtime re-entrantly.
15702 "HAS_LOCALTIME64"
15704 This symbol, if defined, indicates that the "localtime64" ()
15705 routine is available to do the 64bit variant of localtime ()
15706 "HAS_MKTIME"
15708 This symbol, if defined, indicates that the "mktime" routine is
15709 available.
15710 "HAS_MKTIME64"
15712 This symbol, if defined, indicates that the "mktime64" () routine
15713 is available to do the 64bit variant of mktime ()
15714 "HAS_NANOSLEEP"
15716 This symbol, if defined, indicates that the "nanosleep" system call
15717 is available to sleep with 1E-9 sec accuracy.
15718 "HAS_SETITIMER"
15720 This symbol, if defined, indicates that the "setitimer" routine is
15721 available to set interval timers.
15722 "HAS_STRFTIME"
15724 This symbol, if defined, indicates that the "strftime" routine is
15725 available to do time formatting.
15726 "HAS_TIME"
15728 This symbol, if defined, indicates that the time() routine exists.
15729 "HAS_TIMEGM"
15731 This symbol, if defined, indicates that the "timegm" routine is
15732 available to do the opposite of gmtime ()
15733 "HAS_TIMES"
15735 This symbol, if defined, indicates that the times() routine exists.
15736 Note that this became obsolete on some systems ("SUNOS"), which now
15737 use getrusage(). It may be necessary to include sys/times.h.
15738 "HAS_TM_TM_GMTOFF"
15740 This symbol, if defined, indicates to the C program that the
15741 "struct tm" has a "tm_gmtoff" field.
15742 "HAS_TM_TM_ZONE"
15744 This symbol, if defined, indicates to the C program that the
15745 "struct tm" has a "tm_zone" field.
15746 "HAS_TZNAME"
15748 This symbol, if defined, indicates that the "tzname[]" array is
15749 available to access timezone names.
15750 "HAS_USLEEP"
15752 This symbol, if defined, indicates that the "usleep" routine is
15753 available to let the process sleep on a sub-second accuracy.
15754 "HAS_USLEEP_PROTO"
15756 This symbol, if defined, indicates that the system provides a
15757 prototype for the usleep() function. Otherwise, it is up to the
15758 program to supply one. A good guess is
15759 extern int usleep(useconds_t);
15761 "I_TIME"
15763 This symbol is always defined, and indicates to the C program that
15764 it should include time.h.
15765 #ifdef I_TIME
15767 #include <time.h>
15768 #endif
15769 "I_UTIME"
15771 This symbol, if defined, indicates to the C program that it should
15772 include utime.h.
15773 #ifdef I_UTIME
15775 #include <utime.h>
15776 #endif
15777 "LOCALTIME_MAX"
15779 This symbol contains the maximum value for the "time_t" offset that
15780 the system function localtime () accepts, and defaults to 0
15781 "LOCALTIME_MIN"
15783 This symbol contains the minimum value for the "time_t" offset that
15784 the system function localtime () accepts, and defaults to 0
15785 "LOCALTIME_R_NEEDS_TZSET"
15787 Many libc's "localtime_r" implementations do not call tzset, making
15788 them differ from localtime(), and making timezone changes using
15789 $"ENV"{TZ} without explicitly calling tzset impossible. This symbol
15790 makes us call tzset before "localtime_r"
15791 "LOCALTIME_R_PROTO"
15793 This symbol encodes the prototype of "localtime_r". It is zero if
15794 "d_localtime_r" is undef, and one of the "REENTRANT_PROTO_T_ABC"
15795 macros of reentr.h if "d_localtime_r" is defined.
15796 "L_R_TZSET"
15798 If localtime_r() needs tzset, it is defined in this define
15799 "mini_mktime"
15801 normalise "struct tm" values without the localtime() semantics (and
15802 overhead) of mktime().
15803 void mini_mktime(struct tm *ptm)
15805 "my_strftime"
15807 strftime(), but with a different API so that the return value is a
15808 pointer to the formatted result (which MUST be arranged to be FREED
15809 BY THE CALLER). This allows this function to increase the buffer
15810 size as needed, so that the caller doesn't have to worry about
15811 that.
15812 On failure it returns NULL.
15814 Note that yday and wday effectively are ignored by this function,
15816 as mini_mktime() overwrites them.
15817 Also note that it is always executed in the underlying "LC_TIME"
15819 locale of the program, giving results based on that locale.
15820 char * my_strftime(const char *fmt, int sec, int min, int hour,
15822 int mday, int mon, int year, int wday,
15823 int yday, int isdst)
15824 "switch_to_global_locale"
15826 This function copies the locale state of the calling thread into
15827 the program's global locale, and converts the thread to use that
15828 global locale.
15829 It is intended so that Perl can safely be used with C libraries
15831 that access the global locale and which can't be converted to not
15832 access it. Effectively, this means libraries that call
15833 setlocale(3) on non-Windows systems. (For portability, it is a
15834 good idea to use it on Windows as well.)
15835 A downside of using it is that it disables the services that Perl
15837 provides to hide locale gotchas from your code. The service you
15838 most likely will miss regards the radix character (decimal point)
15839 in floating point numbers. Code executed after this function is
15840 called can no longer just assume that this character is correct for
15841 the current circumstances.
15842 To return to Perl control, and restart the gotcha prevention
15844 services, call "sync_locale". Behavior is undefined for any pure
15845 Perl code that executes while the switch is in effect.
15846 The global locale and the per-thread locales are independent. As
15848 long as just one thread converts to the global locale, everything
15849 works smoothly. But if more than one does, they can easily
15850 interfere with each other, and races are likely. On Windows
15851 systems prior to Visual Studio 15 (at which point Microsoft fixed a
15852 bug), races can occur (even if only one thread has been converted
15853 to the global locale), but only if you use the following
15854 operations:
15855 POSIX::localeconv
15857 I18N::Langinfo, items "CRNCYSTR" and "THOUSEP"
15858 "Perl_langinfo" in perlapi, items "CRNCYSTR" and "THOUSEP"
15859 The first item is not fixable (except by upgrading to a later
15861 Visual Studio release), but it would be possible to work around the
15862 latter two items by having Perl change its algorithm for
15863 calculating these to use Windows API functions (likely
15864 "GetNumberFormat" and "GetCurrencyFormat"); patches welcome.
15865 XS code should never call plain "setlocale", but should instead be
15867 converted to either call "Perl_setlocale" (which is a drop-in for
15868 the system "setlocale") or use the methods given in perlcall to
15869 call "POSIX::setlocale". Either one will transparently properly
15870 handle all cases of single- vs multi-thread, POSIX 2008-supported
15871 or not.
15872 void switch_to_global_locale()
15874 "sync_locale"
15876 This function copies the state of the program global locale into
15877 the calling thread, and converts that thread to using per-thread
15878 locales, if it wasn't already, and the platform supports them. The
15879 LC_NUMERIC locale is toggled into the standard state (using the C
15880 locale's conventions), if not within the lexical scope of
15881 "use locale".
15882 Perl will now consider itself to have control of the locale.
15884 Since unthreaded perls have only a global locale, this function is
15886 a no-op without threads.
15887 This function is intended for use with C libraries that do locale
15889 manipulation. It allows Perl to accommodate the use of them. Call
15890 this function before transferring back to Perl space so that it
15891 knows what state the C code has left things in.
15892 XS code should not manipulate the locale on its own. Instead,
15894 "Perl_setlocale" can be used at any time to query or change the
15895 locale (though changing the locale is antisocial and dangerous on
15896 multi-threaded systems that don't have multi-thread safe locale
15897 operations. (See "Multi-threaded operation" in perllocale).
15898 Using the libc setlocale(3) function should be avoided.
15900 Nevertheless, certain non-Perl libraries called from XS, do call
15901 it, and their behavior may not be able to be changed. This
15902 function, along with "switch_to_global_locale", can be used to get
15903 seamless behavior in these circumstances, as long as only one
15904 thread is involved.
15905 If the library has an option to turn off its locale manipulation,
15907 doing that is preferable to using this mechanism. "Gtk" is such a
15908 library.
15909 The return value is a boolean: TRUE if the global locale at the
15911 time of call was in effect for the caller; and FALSE if a per-
15912 thread locale was in effect.
15913 bool sync_locale()
15915
15917 "DB_Hash_t"
15918 This symbol contains the type of the prefix structure element in
15919 the db.h header file. In older versions of DB, it was int, while
15920 in newer ones it is "size_t".
15921 "DB_Prefix_t"
15923 This symbol contains the type of the prefix structure element in
15924 the db.h header file. In older versions of DB, it was int, while
15925 in newer ones it is "u_int32_t".
15926 "Direntry_t"
15928 This symbol is set to '"struct direct"' or '"struct dirent"'
15929 depending on whether dirent is available or not. You should use
15930 this pseudo type to portably declare your directory entries.
15931 "Fpos_t"
15933 This symbol holds the type used to declare file positions in libc.
15934 It can be "fpos_t", long, uint, etc... It may be necessary to
15935 include sys/types.h to get any typedef'ed information.
15936 "Free_t"
15938 This variable contains the return type of free(). It is usually
15939 void, but occasionally int.
15940 "Gid_t"
15942 This symbol holds the return type of getgid() and the type of
15943 argument to setrgid() and related functions. Typically, it is the
15944 type of group ids in the kernel. It can be int, ushort, "gid_t",
15945 etc... It may be necessary to include sys/types.h to get any
15946 typedef'ed information.
15947 "Gid_t_f"
15949 This symbol defines the format string used for printing a "Gid_t".
15950 "Gid_t_sign"
15952 This symbol holds the signedness of a "Gid_t". 1 for unsigned, -1
15953 for signed.
15954 "Gid_t_size"
15956 This symbol holds the size of a "Gid_t" in bytes.
15957 "Groups_t"
15959 This symbol holds the type used for the second argument to
15960 getgroups() and setgroups(). Usually, this is the same as gidtype
15961 ("gid_t") , but sometimes it isn't. It can be int, ushort,
15962 "gid_t", etc... It may be necessary to include sys/types.h to get
15963 any typedef'ed information. This is only required if you have
15964 getgroups() or setgroups()..
15965 "Malloc_t"
15967 This symbol is the type of pointer returned by malloc and realloc.
15968 "Mmap_t"
15970 This symbol holds the return type of the mmap() system call (and
15971 simultaneously the type of the first argument). Usually set to
15972 'void *' or '"caddr_t"'.
15973 "Mode_t"
15975 This symbol holds the type used to declare file modes for systems
15976 calls. It is usually "mode_t", but may be int or unsigned short.
15977 It may be necessary to include sys/types.h to get any typedef'ed
15978 information.
15979 "Netdb_hlen_t"
15981 This symbol holds the type used for the 2nd argument to
15982 gethostbyaddr().
15983 "Netdb_host_t"
15985 This symbol holds the type used for the 1st argument to
15986 gethostbyaddr().
15987 "Netdb_name_t"
15989 This symbol holds the type used for the argument to
15990 gethostbyname().
15991 "Netdb_net_t"
15993 This symbol holds the type used for the 1st argument to
15994 getnetbyaddr().
15995 "Off_t"
15997 This symbol holds the type used to declare offsets in the kernel.
15998 It can be int, long, "off_t", etc... It may be necessary to include
15999 sys/types.h to get any typedef'ed information.
16000 "Off_t_size"
16002 This symbol holds the number of bytes used by the "Off_t".
16003 "Pid_t"
16005 This symbol holds the type used to declare process ids in the
16006 kernel. It can be int, uint, "pid_t", etc... It may be necessary
16007 to include sys/types.h to get any typedef'ed information.
16008 "Rand_seed_t"
16010 This symbol defines the type of the argument of the random seed
16011 function.
16012 "Select_fd_set_t"
16014 This symbol holds the type used for the 2nd, 3rd, and 4th arguments
16015 to select. Usually, this is '"fd_set" *', if "HAS_FD_SET" is
16016 defined, and 'int *' otherwise. This is only useful if you have
16017 select(), of course.
16018 "Shmat_t"
16020 This symbol holds the return type of the shmat() system call.
16021 Usually set to 'void *' or 'char *'.
16022 "Signal_t"
16024 This symbol's value is either "void" or "int", corresponding to the
16025 appropriate return type of a signal handler. Thus, you can declare
16026 a signal handler using ""Signal_t" (*handler)()", and define the
16027 handler using ""Signal_t" handler(sig)".
16028 "Size_t"
16030 This symbol holds the type used to declare length parameters for
16031 string functions. It is usually "size_t", but may be unsigned
16032 long, int, etc. It may be necessary to include sys/types.h to get
16033 any typedef'ed information.
16034 "Size_t_size"
16036 This symbol holds the size of a "Size_t" in bytes.
16037 "Sock_size_t"
16039 This symbol holds the type used for the size argument of various
16040 socket calls (just the base type, not the pointer-to).
16041 "SSize_t"
16043 This symbol holds the type used by functions that return a count of
16044 bytes or an error condition. It must be a signed type. It is
16045 usually "ssize_t", but may be long or int, etc. It may be
16046 necessary to include sys/types.h or unistd.h to get any typedef'ed
16047 information. We will pick a type such that sizeof(SSize_t) ==
16048 sizeof(Size_t).
16049 "Time_t"
16051 This symbol holds the type returned by time(). It can be long, or
16052 "time_t" on "BSD" sites (in which case sys/types.h should be
16053 included).
16054 "Uid_t"
16056 This symbol holds the type used to declare user ids in the kernel.
16057 It can be int, ushort, "uid_t", etc... It may be necessary to
16058 include sys/types.h to get any typedef'ed information.
16059 "Uid_t_f"
16061 This symbol defines the format string used for printing a "Uid_t".
16062 "Uid_t_sign"
16064 This symbol holds the signedness of a "Uid_t". 1 for unsigned, -1
16065 for signed.
16066 "Uid_t_size"
16068 This symbol holds the size of a "Uid_t" in bytes.
16069
16071 "Unicode Support" in perlguts has an introduction to this API.
16072 See also "Character classification", "Character case changing", and
16074 "String Handling". Various functions outside this section also work
16075 specially with Unicode. Search for the string "utf8" in this document.
16076 "BOM_UTF8"
16078 This is a macro that evaluates to a string constant of the UTF-8
16079 bytes that define the Unicode BYTE ORDER MARK (U+FEFF) for the
16080 platform that perl is compiled on. This allows code to use a
16081 mnemonic for this character that works on both ASCII and EBCDIC
16082 platforms. "sizeof(BOM_UTF8) - 1" can be used to get its length in
16083 bytes.
16084 "bytes_cmp_utf8"
16086 Compares the sequence of characters (stored as octets) in "b",
16087 "blen" with the sequence of characters (stored as UTF-8) in "u",
16088 "ulen". Returns 0 if they are equal, -1 or -2 if the first string
16089 is less than the second string, +1 or +2 if the first string is
16090 greater than the second string.
16091 -1 or +1 is returned if the shorter string was identical to the
16093 start of the longer string. -2 or +2 is returned if there was a
16094 difference between characters within the strings.
16095 int bytes_cmp_utf8(const U8 *b, STRLEN blen, const U8 *u,
16097 STRLEN ulen)
16098 "bytes_from_utf8"
16100 NOTE: "bytes_from_utf8" is experimental and may change or be
16101 removed without notice.
16102 Converts a potentially UTF-8 encoded string "s" of length *lenp
16104 into native byte encoding. On input, the boolean *is_utf8p gives
16105 whether or not "s" is actually encoded in UTF-8.
16106 Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-
16108 destructive of the input string.
16109 Do nothing if *is_utf8p is 0, or if there are code points in the
16111 string not expressible in native byte encoding. In these cases,
16112 *is_utf8p and *lenp are unchanged, and the return value is the
16113 original "s".
16114 Otherwise, *is_utf8p is set to 0, and the return value is a pointer
16116 to a newly created string containing a downgraded copy of "s", and
16117 whose length is returned in *lenp, updated. The new string is
16118 "NUL"-terminated. The caller is responsible for arranging for the
16119 memory used by this string to get freed.
16120 Upon successful return, the number of variants in the string can be
16122 computed by having saved the value of *lenp before the call, and
16123 subtracting the after-call value of *lenp from it.
16124 U8 * bytes_from_utf8(const U8 *s, STRLEN *lenp, bool *is_utf8p)
16126 "bytes_to_utf8"
16128 NOTE: "bytes_to_utf8" is experimental and may change or be removed
16129 without notice.
16130 Converts a string "s" of length *lenp bytes from the native
16132 encoding into UTF-8. Returns a pointer to the newly-created
16133 string, and sets *lenp to reflect the new length in bytes. The
16134 caller is responsible for arranging for the memory used by this
16135 string to get freed.
16136 Upon successful return, the number of variants in the string can be
16138 computed by having saved the value of *lenp before the call, and
16139 subtracting it from the after-call value of *lenp.
16140 A "NUL" character will be written after the end of the string.
16142 If you want to convert to UTF-8 from encodings other than the
16144 native (Latin1 or EBCDIC), see "sv_recode_to_utf8"().
16145 U8 * bytes_to_utf8(const U8 *s, STRLEN *lenp)
16147 "DO_UTF8"
16149 Returns a bool giving whether or not the PV in "sv" is to be
16150 treated as being encoded in UTF-8.
16151 You should use this after a call to SvPV() or one of its variants,
16153 in case any call to string overloading updates the internal UTF-8
16154 encoding flag.
16155 bool DO_UTF8(SV* sv)
16157 "foldEQ_utf8"
16159 Returns true if the leading portions of the strings "s1" and "s2"
16160 (either or both of which may be in UTF-8) are the same case-
16161 insensitively; false otherwise. How far into the strings to
16162 compare is determined by other input parameters.
16163 If "u1" is true, the string "s1" is assumed to be in UTF-8-encoded
16165 Unicode; otherwise it is assumed to be in native 8-bit encoding.
16166 Correspondingly for "u2" with respect to "s2".
16167 If the byte length "l1" is non-zero, it says how far into "s1" to
16169 check for fold equality. In other words, "s1"+"l1" will be used as
16170 a goal to reach. The scan will not be considered to be a match
16171 unless the goal is reached, and scanning won't continue past that
16172 goal. Correspondingly for "l2" with respect to "s2".
16173 If "pe1" is non-"NULL" and the pointer it points to is not "NULL",
16175 that pointer is considered an end pointer to the position 1 byte
16176 past the maximum point in "s1" beyond which scanning will not
16177 continue under any circumstances. (This routine assumes that UTF-8
16178 encoded input strings are not malformed; malformed input can cause
16179 it to read past "pe1"). This means that if both "l1" and "pe1" are
16180 specified, and "pe1" is less than "s1"+"l1", the match will never
16181 be successful because it can never get as far as its goal (and in
16182 fact is asserted against). Correspondingly for "pe2" with respect
16183 to "s2".
16184 At least one of "s1" and "s2" must have a goal (at least one of
16186 "l1" and "l2" must be non-zero), and if both do, both have to be
16187 reached for a successful match. Also, if the fold of a character
16188 is multiple characters, all of them must be matched (see tr21
16189 reference below for 'folding').
16190 Upon a successful match, if "pe1" is non-"NULL", it will be set to
16192 point to the beginning of the next character of "s1" beyond what
16193 was matched. Correspondingly for "pe2" and "s2".
16194 For case-insensitiveness, the "casefolding" of Unicode is used
16196 instead of upper/lowercasing both the characters, see
16197 <https://www.unicode.org/reports/tr21/> (Case Mappings).
16198 I32 foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1,
16200 const char *s2, char **pe2, UV l2, bool u2)
16201 "is_ascii_string"
16203 This is a misleadingly-named synonym for
16204 "is_utf8_invariant_string". On ASCII-ish platforms, the name isn't
16205 misleading: the ASCII-range characters are exactly the UTF-8
16206 invariants. But EBCDIC machines have more invariants than just the
16207 ASCII characters, so "is_utf8_invariant_string" is preferred.
16208 bool is_ascii_string(const U8 * const s, STRLEN len)
16210 "isC9_STRICT_UTF8_CHAR"
16212 Evaluates to non-zero if the first few bytes of the string starting
16213 at "s" and looking no further than "e - 1" are well-formed UTF-8
16214 that represents some Unicode non-surrogate code point; otherwise it
16215 evaluates to 0. If non-zero, the value gives how many bytes
16216 starting at "s" comprise the code point's representation. Any
16217 bytes remaining before "e", but beyond the ones needed to form the
16218 first code point in "s", are not examined.
16219 The largest acceptable code point is the Unicode maximum 0x10FFFF.
16221 This differs from "isSTRICT_UTF8_CHAR" only in that it accepts non-
16222 character code points. This corresponds to Unicode Corrigendum #9
16223 <http://www.unicode.org/versions/corrigendum9.html>. which said
16224 that non-character code points are merely discouraged rather than
16225 completely forbidden in open interchange. See "Noncharacter code
16226 points" in perlunicode.
16227 Use "isUTF8_CHAR" to check for Perl's extended UTF-8; and
16229 "isUTF8_CHAR_flags" for a more customized definition.
16230 Use "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
16232 "is_c9strict_utf8_string_loclen" to check entire strings.
16233 Size_t isC9_STRICT_UTF8_CHAR(const U8 * const s0,
16235 const U8 * const e)
16236 "is_c9strict_utf8_string"
16238 Returns TRUE if the first "len" bytes of string "s" form a valid
16239 UTF-8-encoded string that conforms to Unicode Corrigendum #9
16240 <http://www.unicode.org/versions/corrigendum9.html>; otherwise it
16241 returns FALSE. If "len" is 0, it will be calculated using
16242 strlen(s) (which means if you use this option, that "s" can't have
16243 embedded "NUL" characters and has to have a terminating "NUL"
16244 byte). Note that all characters being ASCII constitute 'a valid
16245 UTF-8 string'.
16246 This function returns FALSE for strings containing any code points
16248 above the Unicode max of 0x10FFFF or surrogate code points, but
16249 accepts non-character code points per Corrigendum #9
16250 <http://www.unicode.org/versions/corrigendum9.html>.
16251 See also "is_utf8_invariant_string",
16253 "is_utf8_invariant_string_loc", "is_utf8_string",
16254 "is_utf8_string_flags", "is_utf8_string_loc",
16255 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
16256 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
16257 "is_utf8_fixed_width_buf_loc_flags",
16258 "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
16259 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
16260 "is_c9strict_utf8_string_loc", and
16261 "is_c9strict_utf8_string_loclen".
16262 bool is_c9strict_utf8_string(const U8 *s, STRLEN len)
16264 "is_c9strict_utf8_string_loc"
16266 Like "is_c9strict_utf8_string" but stores the location of the
16267 failure (in the case of "utf8ness failure") or the location
16268 "s"+"len" (in the case of "utf8ness success") in the "ep" pointer.
16269 See also "is_c9strict_utf8_string_loclen".
16271 bool is_c9strict_utf8_string_loc(const U8 *s, STRLEN len,
16273 const U8 **ep)
16274 "is_c9strict_utf8_string_loclen"
16276 Like "is_c9strict_utf8_string" but stores the location of the
16277 failure (in the case of "utf8ness failure") or the location
16278 "s"+"len" (in the case of "utf8ness success") in the "ep" pointer,
16279 and the number of UTF-8 encoded characters in the "el" pointer.
16280 See also "is_c9strict_utf8_string_loc".
16282 bool is_c9strict_utf8_string_loclen(const U8 *s, STRLEN len,
16284 const U8 **ep, STRLEN *el)
16285 "is_invariant_string"
16287 This is a somewhat misleadingly-named synonym for
16288 "is_utf8_invariant_string". "is_utf8_invariant_string" is
16289 preferred, as it indicates under what conditions the string is
16290 invariant.
16291 bool is_invariant_string(const U8 * const s, STRLEN len)
16293 "isSTRICT_UTF8_CHAR"
16295 Evaluates to non-zero if the first few bytes of the string starting
16296 at "s" and looking no further than "e - 1" are well-formed UTF-8
16297 that represents some Unicode code point completely acceptable for
16298 open interchange between all applications; otherwise it evaluates
16299 to 0. If non-zero, the value gives how many bytes starting at "s"
16300 comprise the code point's representation. Any bytes remaining
16301 before "e", but beyond the ones needed to form the first code point
16302 in "s", are not examined.
16303 The largest acceptable code point is the Unicode maximum 0x10FFFF,
16305 and must not be a surrogate nor a non-character code point. Thus
16306 this excludes any code point from Perl's extended UTF-8.
16307 This is used to efficiently decide if the next few bytes in "s" is
16309 legal Unicode-acceptable UTF-8 for a single character.
16310 Use "isC9_STRICT_UTF8_CHAR" to use the Unicode Corrigendum #9
16312 <http://www.unicode.org/versions/corrigendum9.html> definition of
16313 allowable code points; "isUTF8_CHAR" to check for Perl's extended
16314 UTF-8; and "isUTF8_CHAR_flags" for a more customized definition.
16315 Use "is_strict_utf8_string", "is_strict_utf8_string_loc", and
16317 "is_strict_utf8_string_loclen" to check entire strings.
16318 Size_t isSTRICT_UTF8_CHAR(const U8 * const s0,
16320 const U8 * const e)
16321 "is_strict_utf8_string"
16323 Returns TRUE if the first "len" bytes of string "s" form a valid
16324 UTF-8-encoded string that is fully interchangeable by any
16325 application using Unicode rules; otherwise it returns FALSE. If
16326 "len" is 0, it will be calculated using strlen(s) (which means if
16327 you use this option, that "s" can't have embedded "NUL" characters
16328 and has to have a terminating "NUL" byte). Note that all
16329 characters being ASCII constitute 'a valid UTF-8 string'.
16330 This function returns FALSE for strings containing any code points
16332 above the Unicode max of 0x10FFFF, surrogate code points, or non-
16333 character code points.
16334 See also "is_utf8_invariant_string",
16336 "is_utf8_invariant_string_loc", "is_utf8_string",
16337 "is_utf8_string_flags", "is_utf8_string_loc",
16338 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
16339 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
16340 "is_utf8_fixed_width_buf_loc_flags",
16341 "is_utf8_fixed_width_buf_loclen_flags",
16342 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
16343 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
16344 "is_c9strict_utf8_string_loclen".
16345 bool is_strict_utf8_string(const U8 *s, STRLEN len)
16347 "is_strict_utf8_string_loc"
16349 Like "is_strict_utf8_string" but stores the location of the failure
16350 (in the case of "utf8ness failure") or the location "s"+"len" (in
16351 the case of "utf8ness success") in the "ep" pointer.
16352 See also "is_strict_utf8_string_loclen".
16354 bool is_strict_utf8_string_loc(const U8 *s, STRLEN len,
16356 const U8 **ep)
16357 "is_strict_utf8_string_loclen"
16359 Like "is_strict_utf8_string" but stores the location of the failure
16360 (in the case of "utf8ness failure") or the location "s"+"len" (in
16361 the case of "utf8ness success") in the "ep" pointer, and the number
16362 of UTF-8 encoded characters in the "el" pointer.
16363 See also "is_strict_utf8_string_loc".
16365 bool is_strict_utf8_string_loclen(const U8 *s, STRLEN len,
16367 const U8 **ep, STRLEN *el)
16368 "isUTF8_CHAR"
16370 Evaluates to non-zero if the first few bytes of the string starting
16371 at "s" and looking no further than "e - 1" are well-formed UTF-8,
16372 as extended by Perl, that represents some code point; otherwise it
16373 evaluates to 0. If non-zero, the value gives how many bytes
16374 starting at "s" comprise the code point's representation. Any
16375 bytes remaining before "e", but beyond the ones needed to form the
16376 first code point in "s", are not examined.
16377 The code point can be any that will fit in an IV on this machine,
16379 using Perl's extension to official UTF-8 to represent those higher
16380 than the Unicode maximum of 0x10FFFF. That means that this macro
16381 is used to efficiently decide if the next few bytes in "s" is legal
16382 UTF-8 for a single character.
16383 Use "isSTRICT_UTF8_CHAR" to restrict the acceptable code points to
16385 those defined by Unicode to be fully interchangeable across
16386 applications; "isC9_STRICT_UTF8_CHAR" to use the Unicode
16387 Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>
16388 definition of allowable code points; and "isUTF8_CHAR_flags" for a
16389 more customized definition.
16390 Use "is_utf8_string", "is_utf8_string_loc", and
16392 "is_utf8_string_loclen" to check entire strings.
16393 Note also that a UTF-8 "invariant" character (i.e. ASCII on non-
16395 EBCDIC machines) is a valid UTF-8 character.
16396 Size_t isUTF8_CHAR(const U8 * const s0, const U8 * const e)
16398 "is_utf8_char_buf"
16400 This is identical to the macro "isUTF8_CHAR" in perlapi.
16401 STRLEN is_utf8_char_buf(const U8 *buf, const U8 *buf_end)
16403 "isUTF8_CHAR_flags"
16405 Evaluates to non-zero if the first few bytes of the string starting
16406 at "s" and looking no further than "e - 1" are well-formed UTF-8,
16407 as extended by Perl, that represents some code point, subject to
16408 the restrictions given by "flags"; otherwise it evaluates to 0. If
16409 non-zero, the value gives how many bytes starting at "s" comprise
16410 the code point's representation. Any bytes remaining before "e",
16411 but beyond the ones needed to form the first code point in "s", are
16412 not examined.
16413 If "flags" is 0, this gives the same results as "isUTF8_CHAR"; if
16415 "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the same
16416 results as "isSTRICT_UTF8_CHAR"; and if "flags" is
16417 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same results
16418 as "isC9_STRICT_UTF8_CHAR". Otherwise "flags" may be any
16419 combination of the "UTF8_DISALLOW_foo" flags understood by
16420 "utf8n_to_uvchr", with the same meanings.
16421 The three alternative macros are for the most commonly needed
16423 validations; they are likely to run somewhat faster than this more
16424 general one, as they can be inlined into your code.
16425 Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
16427 "is_utf8_string_loclen_flags" to check entire strings.
16428 Size_t isUTF8_CHAR_flags(const U8 * const s0, const U8 * const e,
16430 const U32 flags)
16431 "is_utf8_fixed_width_buf_flags"
16433 Returns TRUE if the fixed-width buffer starting at "s" with length
16434 "len" is entirely valid UTF-8, subject to the restrictions given by
16435 "flags"; otherwise it returns FALSE.
16436 If "flags" is 0, any well-formed UTF-8, as extended by Perl, is
16438 accepted without restriction. If the final few bytes of the buffer
16439 do not form a complete code point, this will return TRUE anyway,
16440 provided that "is_utf8_valid_partial_char_flags" returns TRUE for
16441 them.
16442 If "flags" in non-zero, it can be any combination of the
16444 "UTF8_DISALLOW_foo" flags accepted by "utf8n_to_uvchr", and with
16445 the same meanings.
16446 This function differs from "is_utf8_string_flags" only in that the
16448 latter returns FALSE if the final few bytes of the string don't
16449 form a complete code point.
16450 bool is_utf8_fixed_width_buf_flags(const U8 * const s,
16452 STRLEN len, const U32 flags)
16453 "is_utf8_fixed_width_buf_loc_flags"
16455 Like "is_utf8_fixed_width_buf_flags" but stores the location of the
16456 failure in the "ep" pointer. If the function returns TRUE, *ep
16457 will point to the beginning of any partial character at the end of
16458 the buffer; if there is no partial character *ep will contain
16459 "s"+"len".
16460 See also "is_utf8_fixed_width_buf_loclen_flags".
16462 bool is_utf8_fixed_width_buf_loc_flags(const U8 * const s,
16464 STRLEN len, const U8 **ep,
16465 const U32 flags)
16466 "is_utf8_fixed_width_buf_loclen_flags"
16468 Like "is_utf8_fixed_width_buf_loc_flags" but stores the number of
16469 complete, valid characters found in the "el" pointer.
16470 bool is_utf8_fixed_width_buf_loclen_flags(const U8 * const s,
16472 STRLEN len,
16473 const U8 **ep,
16474 STRLEN *el,
16475 const U32 flags)
16476 "is_utf8_invariant_string"
16478 Returns TRUE if the first "len" bytes of the string "s" are the
16479 same regardless of the UTF-8 encoding of the string (or UTF-EBCDIC
16480 encoding on EBCDIC machines); otherwise it returns FALSE. That is,
16481 it returns TRUE if they are UTF-8 invariant. On ASCII-ish
16482 machines, all the ASCII characters and only the ASCII characters
16483 fit this definition. On EBCDIC machines, the ASCII-range
16484 characters are invariant, but so also are the C1 controls.
16485 If "len" is 0, it will be calculated using strlen(s), (which means
16487 if you use this option, that "s" can't have embedded "NUL"
16488 characters and has to have a terminating "NUL" byte).
16489 See also "is_utf8_string", "is_utf8_string_flags",
16491 "is_utf8_string_loc", "is_utf8_string_loc_flags",
16492 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
16493 "is_utf8_fixed_width_buf_flags",
16494 "is_utf8_fixed_width_buf_loc_flags",
16495 "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
16496 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
16497 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
16498 "is_c9strict_utf8_string_loclen".
16499 bool is_utf8_invariant_string(const U8 * const s, STRLEN len)
16501 "is_utf8_invariant_string_loc"
16503 Like "is_utf8_invariant_string" but upon failure, stores the
16504 location of the first UTF-8 variant character in the "ep" pointer;
16505 if all characters are UTF-8 invariant, this function does not
16506 change the contents of *ep.
16507 bool is_utf8_invariant_string_loc(const U8 * const s, STRLEN len,
16509 const U8 **ep)
16510 "is_utf8_string"
16512 Returns TRUE if the first "len" bytes of string "s" form a valid
16513 Perl-extended-UTF-8 string; returns FALSE otherwise. If "len" is
16514 0, it will be calculated using strlen(s) (which means if you use
16515 this option, that "s" can't have embedded "NUL" characters and has
16516 to have a terminating "NUL" byte). Note that all characters being
16517 ASCII constitute 'a valid UTF-8 string'.
16518 This function considers Perl's extended UTF-8 to be valid. That
16520 means that code points above Unicode, surrogates, and non-character
16521 code points are considered valid by this function. Use
16522 "is_strict_utf8_string", "is_c9strict_utf8_string", or
16523 "is_utf8_string_flags" to restrict what code points are considered
16524 valid.
16525 See also "is_utf8_invariant_string",
16527 "is_utf8_invariant_string_loc", "is_utf8_string_loc",
16528 "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags",
16529 "is_utf8_fixed_width_buf_loc_flags",
16530 "is_utf8_fixed_width_buf_loclen_flags",
16531 bool is_utf8_string(const U8 *s, STRLEN len)
16533 "is_utf8_string_flags"
16535 Returns TRUE if the first "len" bytes of string "s" form a valid
16536 UTF-8 string, subject to the restrictions imposed by "flags";
16537 returns FALSE otherwise. If "len" is 0, it will be calculated
16538 using strlen(s) (which means if you use this option, that "s" can't
16539 have embedded "NUL" characters and has to have a terminating "NUL"
16540 byte). Note that all characters being ASCII constitute 'a valid
16541 UTF-8 string'.
16542 If "flags" is 0, this gives the same results as "is_utf8_string";
16544 if "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the
16545 same results as "is_strict_utf8_string"; and if "flags" is
16546 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same results
16547 as "is_c9strict_utf8_string". Otherwise "flags" may be any
16548 combination of the "UTF8_DISALLOW_foo" flags understood by
16549 "utf8n_to_uvchr", with the same meanings.
16550 See also "is_utf8_invariant_string",
16552 "is_utf8_invariant_string_loc", "is_utf8_string",
16553 "is_utf8_string_loc", "is_utf8_string_loc_flags",
16554 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
16555 "is_utf8_fixed_width_buf_flags",
16556 "is_utf8_fixed_width_buf_loc_flags",
16557 "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string",
16558 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
16559 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
16560 "is_c9strict_utf8_string_loclen".
16561 bool is_utf8_string_flags(const U8 *s, STRLEN len,
16563 const U32 flags)
16564 "is_utf8_string_loc"
16566 Like "is_utf8_string" but stores the location of the failure (in
16567 the case of "utf8ness failure") or the location "s"+"len" (in the
16568 case of "utf8ness success") in the "ep" pointer.
16569 See also "is_utf8_string_loclen".
16571 bool is_utf8_string_loc(const U8 *s, const STRLEN len,
16573 const U8 **ep)
16574 "is_utf8_string_loc_flags"
16576 Like "is_utf8_string_flags" but stores the location of the failure
16577 (in the case of "utf8ness failure") or the location "s"+"len" (in
16578 the case of "utf8ness success") in the "ep" pointer.
16579 See also "is_utf8_string_loclen_flags".
16581 bool is_utf8_string_loc_flags(const U8 *s, STRLEN len,
16583 const U8 **ep, const U32 flags)
16584 "is_utf8_string_loclen"
16586 Like "is_utf8_string" but stores the location of the failure (in
16587 the case of "utf8ness failure") or the location "s"+"len" (in the
16588 case of "utf8ness success") in the "ep" pointer, and the number of
16589 UTF-8 encoded characters in the "el" pointer.
16590 See also "is_utf8_string_loc".
16592 bool is_utf8_string_loclen(const U8 *s, STRLEN len,
16594 const U8 **ep, STRLEN *el)
16595 "is_utf8_string_loclen_flags"
16597 Like "is_utf8_string_flags" but stores the location of the failure
16598 (in the case of "utf8ness failure") or the location "s"+"len" (in
16599 the case of "utf8ness success") in the "ep" pointer, and the number
16600 of UTF-8 encoded characters in the "el" pointer.
16601 See also "is_utf8_string_loc_flags".
16603 bool is_utf8_string_loclen_flags(const U8 *s, STRLEN len,
16605 const U8 **ep, STRLEN *el,
16606 const U32 flags)
16607 "is_utf8_valid_partial_char"
16609 Returns 0 if the sequence of bytes starting at "s" and looking no
16610 further than "e - 1" is the UTF-8 encoding, as extended by Perl,
16611 for one or more code points. Otherwise, it returns 1 if there
16612 exists at least one non-empty sequence of bytes that when appended
16613 to sequence "s", starting at position "e" causes the entire
16614 sequence to be the well-formed UTF-8 of some code point; otherwise
16615 returns 0.
16616 In other words this returns TRUE if "s" points to a partial
16618 UTF-8-encoded code point.
16619 This is useful when a fixed-length buffer is being tested for being
16621 well-formed UTF-8, but the final few bytes in it don't comprise a
16622 full character; that is, it is split somewhere in the middle of the
16623 final code point's UTF-8 representation. (Presumably when the
16624 buffer is refreshed with the next chunk of data, the new first
16625 bytes will complete the partial code point.) This function is
16626 used to verify that the final bytes in the current buffer are in
16627 fact the legal beginning of some code point, so that if they
16628 aren't, the failure can be signalled without having to wait for the
16629 next read.
16630 bool is_utf8_valid_partial_char(const U8 * const s0,
16632 const U8 * const e)
16633 "is_utf8_valid_partial_char_flags"
16635 Like "is_utf8_valid_partial_char", it returns a boolean giving
16636 whether or not the input is a valid UTF-8 encoded partial
16637 character, but it takes an extra parameter, "flags", which can
16638 further restrict which code points are considered valid.
16639 If "flags" is 0, this behaves identically to
16641 "is_utf8_valid_partial_char". Otherwise "flags" can be any
16642 combination of the "UTF8_DISALLOW_foo" flags accepted by
16643 "utf8n_to_uvchr". If there is any sequence of bytes that can
16644 complete the input partial character in such a way that a non-
16645 prohibited character is formed, the function returns TRUE;
16646 otherwise FALSE. Non character code points cannot be determined
16647 based on partial character input. But many of the other possible
16648 excluded types can be determined from just the first one or two
16649 bytes.
16650 bool is_utf8_valid_partial_char_flags(const U8 * const s0,
16652 const U8 * const e,
16653 const U32 flags)
16654 "LATIN1_TO_NATIVE"
16656 Returns the native equivalent of the input Latin-1 code point
16657 (including ASCII and control characters) given by "ch". Thus,
16658 LATIN1_TO_NATIVE(66) on EBCDIC platforms returns 194. These each
16659 represent the character "B" on their respective platforms. On
16660 ASCII platforms no conversion is needed, so this macro expands to
16661 just its input, adding no time nor space requirements to the
16662 implementation.
16663 For conversion of code points potentially larger than will fit in a
16665 character, use "UNI_TO_NATIVE".
16666 U8 LATIN1_TO_NATIVE(U8 ch)
16668 "NATIVE_TO_LATIN1"
16670 Returns the Latin-1 (including ASCII and control characters)
16671 equivalent of the input native code point given by "ch". Thus,
16672 NATIVE_TO_LATIN1(193) on EBCDIC platforms returns 65. These each
16673 represent the character "A" on their respective platforms. On
16674 ASCII platforms no conversion is needed, so this macro expands to
16675 just its input, adding no time nor space requirements to the
16676 implementation.
16677 For conversion of code points potentially larger than will fit in a
16679 character, use "NATIVE_TO_UNI".
16680 U8 NATIVE_TO_LATIN1(U8 ch)
16682 "NATIVE_TO_UNI"
16684 Returns the Unicode equivalent of the input native code point
16685 given by "ch". Thus, NATIVE_TO_UNI(195) on EBCDIC platforms
16686 returns 67. These each represent the character "C" on their
16687 respective platforms. On ASCII platforms no conversion is needed,
16688 so this macro expands to just its input, adding no time nor space
16689 requirements to the implementation.
16690 UV NATIVE_TO_UNI(UV ch)
16692 "pv_uni_display"
16694 Build to the scalar "dsv" a displayable version of the UTF-8
16695 encoded string "spv", length "len", the displayable version being
16696 at most "pvlim" bytes long (if longer, the rest is truncated and
16697 "..." will be appended).
16698 The "flags" argument can have "UNI_DISPLAY_ISPRINT" set to display
16700 isPRINT()able characters as themselves, "UNI_DISPLAY_BACKSLASH" to
16701 display the "\\[nrfta\\]" as the backslashed versions (like "\n")
16702 ("UNI_DISPLAY_BACKSLASH" is preferred over "UNI_DISPLAY_ISPRINT"
16703 for "\\"). "UNI_DISPLAY_QQ" (and its alias "UNI_DISPLAY_REGEX")
16704 have both "UNI_DISPLAY_BACKSLASH" and "UNI_DISPLAY_ISPRINT" turned
16705 on.
16706 Additionally, there is now "UNI_DISPLAY_BACKSPACE" which allows
16708 "\b" for a backspace, but only when "UNI_DISPLAY_BACKSLASH" also is
16709 set.
16710 The pointer to the PV of the "dsv" is returned.
16712 See also "sv_uni_display".
16714 char * pv_uni_display(SV *dsv, const U8 *spv, STRLEN len,
16716 STRLEN pvlim, UV flags)
16717 "REPLACEMENT_CHARACTER_UTF8"
16719 This is a macro that evaluates to a string constant of the UTF-8
16720 bytes that define the Unicode REPLACEMENT CHARACTER (U+FFFD) for
16721 the platform that perl is compiled on. This allows code to use a
16722 mnemonic for this character that works on both ASCII and EBCDIC
16723 platforms. "sizeof(REPLACEMENT_CHARACTER_UTF8) - 1" can be used to
16724 get its length in bytes.
16725 "sv_cat_decode"
16727 "encoding" is assumed to be an "Encode" object, the PV of "ssv" is
16728 assumed to be octets in that encoding and decoding the input starts
16729 from the position which "(PV + *offset)" pointed to. "dsv" will be
16730 concatenated with the decoded UTF-8 string from "ssv". Decoding
16731 will terminate when the string "tstr" appears in decoding output or
16732 the input ends on the PV of "ssv". The value which "offset" points
16733 will be modified to the last input position on "ssv".
16734 Returns TRUE if the terminator was found, else returns FALSE.
16736 bool sv_cat_decode(SV *dsv, SV *encoding, SV *ssv, int *offset,
16738 char *tstr, int tlen)
16739 "sv_recode_to_utf8"
16741 "encoding" is assumed to be an "Encode" object, on entry the PV of
16742 "sv" is assumed to be octets in that encoding, and "sv" will be
16743 converted into Unicode (and UTF-8).
16744 If "sv" already is UTF-8 (or if it is not "POK"), or if "encoding"
16746 is not a reference, nothing is done to "sv". If "encoding" is not
16747 an "Encode::XS" Encoding object, bad things will happen. (See
16748 encoding and Encode.)
16749 The PV of "sv" is returned.
16751 char * sv_recode_to_utf8(SV *sv, SV *encoding)
16753 "sv_uni_display"
16755 Build to the scalar "dsv" a displayable version of the scalar "sv",
16756 the displayable version being at most "pvlim" bytes long (if
16757 longer, the rest is truncated and "..." will be appended).
16758 The "flags" argument is as in "pv_uni_display"().
16760 The pointer to the PV of the "dsv" is returned.
16762 char * sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
16764 "UNICODE_IS_NONCHAR"
16766 Returns a boolean as to whether or not "uv" is one of the Unicode
16767 non-character code points
16768 bool UNICODE_IS_NONCHAR(const UV uv)
16770 "UNICODE_IS_REPLACEMENT"
16772 Returns a boolean as to whether or not "uv" is the Unicode
16773 REPLACEMENT CHARACTER
16774 bool UNICODE_IS_REPLACEMENT(const UV uv)
16776 "UNICODE_IS_SUPER"
16778 Returns a boolean as to whether or not "uv" is above the maximum
16779 legal Unicode code point of U+10FFFF.
16780 bool UNICODE_IS_SUPER(const UV uv)
16782 "UNICODE_IS_SURROGATE"
16784 Returns a boolean as to whether or not "uv" is one of the Unicode
16785 surrogate code points
16786 bool UNICODE_IS_SURROGATE(const UV uv)
16788 "UNICODE_REPLACEMENT"
16790 Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT
16791 CHARACTER
16792 "UNI_TO_NATIVE"
16794 Returns the native equivalent of the input Unicode code point
16795 given by "ch". Thus, UNI_TO_NATIVE(68) on EBCDIC platforms returns
16796 196. These each represent the character "D" on their respective
16797 platforms. On ASCII platforms no conversion is needed, so this
16798 macro expands to just its input, adding no time nor space
16799 requirements to the implementation.
16800 UV UNI_TO_NATIVE(UV ch)
16802 "UTF8_CHK_SKIP"
16804 This is a safer version of "UTF8SKIP", but still not as safe as
16805 "UTF8_SAFE_SKIP". This version doesn't blindly assume that the
16806 input string pointed to by "s" is well-formed, but verifies that
16807 there isn't a NUL terminating character before the expected end of
16808 the next character in "s". The length "UTF8_CHK_SKIP" returns
16809 stops just before any such NUL.
16810 Perl tends to add NULs, as an insurance policy, after the end of
16812 strings in SV's, so it is likely that using this macro will prevent
16813 inadvertent reading beyond the end of the input buffer, even if it
16814 is malformed UTF-8.
16815 This macro is intended to be used by XS modules where the inputs
16817 could be malformed, and it isn't feasible to restructure to use the
16818 safer "UTF8_SAFE_SKIP", for example when interfacing with a C
16819 library.
16820 STRLEN UTF8_CHK_SKIP(char* s)
16822 "utf8_distance"
16824 Returns the number of UTF-8 characters between the UTF-8 pointers
16825 "a" and "b".
16826 WARNING: use only if you *know* that the pointers point inside the
16828 same UTF-8 buffer.
16829 IV utf8_distance(const U8 *a, const U8 *b)
16831 "utf8_hop"
16833 Return the UTF-8 pointer "s" displaced by "off" characters, either
16834 forward (if "off" is positive) or backward (if negative). "s" does
16835 not need to be pointing to the starting byte of a character. If it
16836 isn't, one count of "off" will be used up to get to the start of
16837 the next character for forward hops, and to the start of the
16838 current character for negative ones.
16839 WARNING: Prefer "utf8_hop_safe" to this one.
16841 Do NOT use this function unless you know "off" is within the UTF-8
16843 data pointed to by "s" and that on entry "s" is aligned on the
16844 first byte of a character or just after the last byte of a
16845 character.
16846 U8 * utf8_hop(const U8 *s, SSize_t off)
16848 "utf8_hop_back"
16850 Return the UTF-8 pointer "s" displaced by up to "off" characters,
16851 backward. "s" does not need to be pointing to the starting byte of
16852 a character. If it isn't, one count of "off" will be used up to
16853 get to that start.
16854 "off" must be non-positive.
16856 "s" must be after or equal to "start".
16858 When moving backward it will not move before "start".
16860 Will not exceed this limit even if the string is not valid "UTF-8".
16862 U8 * utf8_hop_back(const U8 *s, SSize_t off, const U8 *start)
16864 "utf8_hop_forward"
16866 Return the UTF-8 pointer "s" displaced by up to "off" characters,
16867 forward. "s" does not need to be pointing to the starting byte of
16868 a character. If it isn't, one count of "off" will be used up to
16869 get to the start of the next character.
16870 "off" must be non-negative.
16872 "s" must be before or equal to "end".
16874 When moving forward it will not move beyond "end".
16876 Will not exceed this limit even if the string is not valid "UTF-8".
16878 U8 * utf8_hop_forward(const U8 *s, SSize_t off, const U8 *end)
16880 "utf8_hop_safe"
16882 Return the UTF-8 pointer "s" displaced by up to "off" characters,
16883 either forward or backward. "s" does not need to be pointing to
16884 the starting byte of a character. If it isn't, one count of "off"
16885 will be used up to get to the start of the next character for
16886 forward hops, and to the start of the current character for
16887 negative ones.
16888 When moving backward it will not move before "start".
16890 When moving forward it will not move beyond "end".
16892 Will not exceed those limits even if the string is not valid
16894 "UTF-8".
16895 U8 * utf8_hop_safe(const U8 *s, SSize_t off, const U8 *start,
16897 const U8 *end)
16898 "UTF8_IS_INVARIANT"
16900 Evaluates to 1 if the byte "c" represents the same character when
16901 encoded in UTF-8 as when not; otherwise evaluates to 0. UTF-8
16902 invariant characters can be copied as-is when converting to/from
16903 UTF-8, saving time.
16904 In spite of the name, this macro gives the correct result if the
16906 input string from which "c" comes is not encoded in UTF-8.
16907 See "UVCHR_IS_INVARIANT" for checking if a UV is invariant.
16909 bool UTF8_IS_INVARIANT(char c)
16911 "UTF8_IS_NONCHAR"
16913 Evaluates to non-zero if the first few bytes of the string starting
16914 at "s" and looking no further than "e - 1" are well-formed UTF-8
16915 that represents one of the Unicode non-character code points;
16916 otherwise it evaluates to 0. If non-zero, the value gives how many
16917 bytes starting at "s" comprise the code point's representation.
16918 bool UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
16920 "UTF8_IS_REPLACEMENT"
16922 Evaluates to non-zero if the first few bytes of the string starting
16923 at "s" and looking no further than "e - 1" are well-formed UTF-8
16924 that represents the Unicode REPLACEMENT CHARACTER; otherwise it
16925 evaluates to 0. If non-zero, the value gives how many bytes
16926 starting at "s" comprise the code point's representation.
16927 bool UTF8_IS_REPLACEMENT(const U8 *s, const U8 *e)
16929 "UTF8_IS_SUPER"
16931 Recall that Perl recognizes an extension to UTF-8 that can encode
16932 code points larger than the ones defined by Unicode, which are
16933 0..0x10FFFF.
16934 This macro evaluates to non-zero if the first few bytes of the
16936 string starting at "s" and looking no further than "e - 1" are from
16937 this UTF-8 extension; otherwise it evaluates to 0. If non-zero,
16938 the return is how many bytes starting at "s" comprise the code
16939 point's representation.
16940 0 is returned if the bytes are not well-formed extended UTF-8, or
16942 if they represent a code point that cannot fit in a UV on the
16943 current platform. Hence this macro can give different results when
16944 run on a 64-bit word machine than on one with a 32-bit word size.
16945 Note that it is illegal in Perl to have code points that are larger
16947 than what can fit in an IV on the current machine; and illegal in
16948 Unicode to have any that this macro matches
16949 bool UTF8_IS_SUPER(const U8 *s, const U8 *e)
16951 "UTF8_IS_SURROGATE"
16953 Evaluates to non-zero if the first few bytes of the string starting
16954 at "s" and looking no further than "e - 1" are well-formed UTF-8
16955 that represents one of the Unicode surrogate code points; otherwise
16956 it evaluates to 0. If non-zero, the value gives how many bytes
16957 starting at "s" comprise the code point's representation.
16958 bool UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
16960 "utf8_length"
16962 Returns the number of characters in the sequence of UTF-8-encoded
16963 bytes starting at "s" and ending at the byte just before "e". If
16964 <s> and <e> point to the same place, it returns 0 with no warning
16965 raised.
16966 If "e < s" or if the scan would end up past "e", it raises a UTF8
16968 warning and returns the number of valid characters.
16969 STRLEN utf8_length(const U8 *s0, const U8 *e)
16971 "UTF8_MAXBYTES"
16973 The maximum width of a single UTF-8 encoded character, in bytes.
16974 NOTE: Strictly speaking Perl's UTF-8 should not be called UTF-8
16976 since UTF-8 is an encoding of Unicode, and Unicode's upper limit,
16977 0x10FFFF, can be expressed with 4 bytes. However, Perl thinks of
16978 UTF-8 as a way to encode non-negative integers in a binary format,
16979 even those above Unicode.
16980 "UTF8_MAXBYTES_CASE"
16982 The maximum number of UTF-8 bytes a single Unicode character can
16983 uppercase/lowercase/titlecase/fold into.
16984 "utf8ness_t"
16986 This typedef is used by several core functions that return PV
16987 strings, to indicate the UTF-8ness of those strings.
16988 (If you write a new function, you probably should instead return
16990 the PV in an SV with the UTF-8 flag of the SV properly set, rather
16991 than use this mechanism.)
16992 The possible values this can be are:
16994 "UTF8NESS_YES"
16996 This means the string definitely should be treated as a
16997 sequence of UTF-8-encoded characters.
16998 Most code that needs to handle this typedef should be of the
17000 form:
17001 if (utf8ness_flag == UTF8NESS_YES) {
17003 treat as utf8; // like turning on an SV UTF-8 flag
17004 }
17005 "UTF8NESS_NO"
17007 This means the string definitely should be treated as a
17008 sequence of bytes, not encoded as UTF-8.
17009 "UTF8NESS_IMMATERIAL"
17011 This means it is equally valid to treat the string as bytes, or
17012 as UTF-8 characters; use whichever way you want. This happens
17013 when the string consists entirely of characters which have the
17014 same representation whether encoded in UTF-8 or not.
17015 "UTF8NESS_UNKNOWN"
17017 This means it is unknown how the string should be treated. No
17018 core function will ever return this value to a non-core caller.
17019 Instead, it is used by the caller to initialize a variable to a
17020 non-legal value. A typical call will look like:
17021 utf8ness_t string_is_utf8 = UTF8NESS_UNKNOWN
17023 const char * string = foo(arg1, arg2, ..., &string_is_utf8);
17024 if (string_is_utf8 == UTF8NESS_YES) {
17025 do something for UTF-8;
17026 }
17027 The following relationships hold between the enum values:
17029 "0 <= enum value <= UTF8NESS_IMMATERIAL"
17031 the string may be treated in code as non-UTF8
17032 "UTF8NESS_IMMATERIAL <= <enum value"
17034 the string may be treated in code as encoded in UTF-8
17035 "utf8n_to_uvchr"
17037 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
17038 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"() rather
17039 than call this directly.
17040 Bottom level UTF-8 decode routine. Returns the native code point
17042 value of the first character in the string "s", which is assumed to
17043 be in UTF-8 (or UTF-EBCDIC) encoding, and no longer than "curlen"
17044 bytes; *retlen (if "retlen" isn't NULL) will be set to the length,
17045 in bytes, of that character.
17046 The value of "flags" determines the behavior when "s" does not
17048 point to a well-formed UTF-8 character. If "flags" is 0,
17049 encountering a malformation causes zero to be returned and *retlen
17050 is set so that ("s" + *retlen) is the next possible position in "s"
17051 that could begin a non-malformed character. Also, if UTF-8
17052 warnings haven't been lexically disabled, a warning is raised.
17053 Some UTF-8 input sequences may contain multiple malformations.
17054 This function tries to find every possible one in each call, so
17055 multiple warnings can be raised for the same sequence.
17056 Various ALLOW flags can be set in "flags" to allow (and not warn
17058 on) individual types of malformations, such as the sequence being
17059 overlong (that is, when there is a shorter sequence that can
17060 express the same code point; overlong sequences are expressly
17061 forbidden in the UTF-8 standard due to potential security issues).
17062 Another malformation example is the first byte of a character not
17063 being a legal first byte. See utf8.h for the list of such flags.
17064 Even if allowed, this function generally returns the Unicode
17065 REPLACEMENT CHARACTER when it encounters a malformation. There are
17066 flags in utf8.h to override this behavior for the overlong
17067 malformations, but don't do that except for very specialized
17068 purposes.
17069 The "UTF8_CHECK_ONLY" flag overrides the behavior when a non-
17071 allowed (by other flags) malformation is found. If this flag is
17072 set, the routine assumes that the caller will raise a warning, and
17073 this function will silently just set "retlen" to -1 (cast to
17074 "STRLEN") and return zero.
17075 Note that this API requires disambiguation between successful
17077 decoding a "NUL" character, and an error return (unless the
17078 "UTF8_CHECK_ONLY" flag is set), as in both cases, 0 is returned,
17079 and, depending on the malformation, "retlen" may be set to 1. To
17080 disambiguate, upon a zero return, see if the first byte of "s" is 0
17081 as well. If so, the input was a "NUL"; if not, the input had an
17082 error. Or you can use "utf8n_to_uvchr_error".
17083 Certain code points are considered problematic. These are Unicode
17085 surrogates, Unicode non-characters, and code points above the
17086 Unicode maximum of 0x10FFFF. By default these are considered
17087 regular code points, but certain situations warrant special
17088 handling for them, which can be specified using the "flags"
17089 parameter. If "flags" contains
17090 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", all three classes are treated
17091 as malformations and handled as such. The flags
17092 "UTF8_DISALLOW_SURROGATE", "UTF8_DISALLOW_NONCHAR", and
17093 "UTF8_DISALLOW_SUPER" (meaning above the legal Unicode maximum) can
17094 be set to disallow these categories individually.
17095 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed inputs to
17096 the strict UTF-8 traditionally defined by Unicode. Use
17097 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE" to use the strictness
17098 definition given by Unicode Corrigendum #9
17099 <https://www.unicode.org/versions/corrigendum9.html>. The
17100 difference between traditional strictness and C9 strictness is that
17101 the latter does not forbid non-character code points. (They are
17102 still discouraged, however.) For more discussion see "Noncharacter
17103 code points" in perlunicode.
17104 The flags "UTF8_WARN_ILLEGAL_INTERCHANGE",
17106 "UTF8_WARN_ILLEGAL_C9_INTERCHANGE", "UTF8_WARN_SURROGATE",
17107 "UTF8_WARN_NONCHAR", and "UTF8_WARN_SUPER" will cause warning
17108 messages to be raised for their respective categories, but
17109 otherwise the code points are considered valid (not malformations).
17110 To get a category to both be treated as a malformation and raise a
17111 warning, specify both the WARN and DISALLOW flags. (But note that
17112 warnings are not raised if lexically disabled nor if
17113 "UTF8_CHECK_ONLY" is also specified.)
17114 Extremely high code points were never specified in any standard,
17116 and require an extension to UTF-8 to express, which Perl does. It
17117 is likely that programs written in something other than Perl would
17118 not be able to read files that contain these; nor would Perl
17119 understand files written by something that uses a different
17120 extension. For these reasons, there is a separate set of flags
17121 that can warn and/or disallow these extremely high code points,
17122 even if other above-Unicode ones are accepted. They are the
17123 "UTF8_WARN_PERL_EXTENDED" and "UTF8_DISALLOW_PERL_EXTENDED" flags.
17124 For more information see "UTF8_GOT_PERL_EXTENDED". Of course
17125 "UTF8_DISALLOW_SUPER" will treat all above-Unicode code points,
17126 including these, as malformations. (Note that the Unicode standard
17127 considers anything above 0x10FFFF to be illegal, but there are
17128 standards predating it that allow up to 0x7FFF_FFFF (2**31 -1))
17129 A somewhat misleadingly named synonym for "UTF8_WARN_PERL_EXTENDED"
17131 is retained for backward compatibility: "UTF8_WARN_ABOVE_31_BIT".
17132 Similarly, "UTF8_DISALLOW_ABOVE_31_BIT" is usable instead of the
17133 more accurately named "UTF8_DISALLOW_PERL_EXTENDED". The names are
17134 misleading because these flags can apply to code points that
17135 actually do fit in 31 bits. This happens on EBCDIC platforms, and
17136 sometimes when the overlong malformation is also present. The new
17137 names accurately describe the situation in all cases.
17138 All other code points corresponding to Unicode characters,
17140 including private use and those yet to be assigned, are never
17141 considered malformed and never warn.
17142 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen,
17144 const U32 flags)
17145 "utf8n_to_uvchr_error"
17147 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
17148 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"() rather
17149 than call this directly.
17150 This function is for code that needs to know what the precise
17152 malformation(s) are when an error is found. If you also need to
17153 know the generated warning messages, use "utf8n_to_uvchr_msgs"()
17154 instead.
17155 It is like "utf8n_to_uvchr" but it takes an extra parameter placed
17157 after all the others, "errors". If this parameter is 0, this
17158 function behaves identically to "utf8n_to_uvchr". Otherwise,
17159 "errors" should be a pointer to a "U32" variable, which this
17160 function sets to indicate any errors found. Upon return, if
17161 *errors is 0, there were no errors found. Otherwise, *errors is
17162 the bit-wise "OR" of the bits described in the list below. Some of
17163 these bits will be set if a malformation is found, even if the
17164 input "flags" parameter indicates that the given malformation is
17165 allowed; those exceptions are noted:
17166 "UTF8_GOT_PERL_EXTENDED"
17168 The input sequence is not standard UTF-8, but a Perl extension.
17169 This bit is set only if the input "flags" parameter contains
17170 either the "UTF8_DISALLOW_PERL_EXTENDED" or the
17171 "UTF8_WARN_PERL_EXTENDED" flags.
17172 Code points above 0x7FFF_FFFF (2**31 - 1) were never specified
17174 in any standard, and so some extension must be used to express
17175 them. Perl uses a natural extension to UTF-8 to represent the
17176 ones up to 2**36-1, and invented a further extension to
17177 represent even higher ones, so that any code point that fits in
17178 a 64-bit word can be represented. Text using these extensions
17179 is not likely to be portable to non-Perl code. We lump both of
17180 these extensions together and refer to them as Perl extended
17181 UTF-8. There exist other extensions that people have invented,
17182 incompatible with Perl's.
17183 On EBCDIC platforms starting in Perl v5.24, the Perl extension
17185 for representing extremely high code points kicks in at
17186 0x3FFF_FFFF (2**30 -1), which is lower than on ASCII. Prior to
17187 that, code points 2**31 and higher were simply unrepresentable,
17188 and a different, incompatible method was used to represent code
17189 points between 2**30 and 2**31 - 1.
17190 On both platforms, ASCII and EBCDIC, "UTF8_GOT_PERL_EXTENDED"
17192 is set if Perl extended UTF-8 is used.
17193 In earlier Perls, this bit was named "UTF8_GOT_ABOVE_31_BIT",
17195 which you still may use for backward compatibility. That name
17196 is misleading, as this flag may be set when the code point
17197 actually does fit in 31 bits. This happens on EBCDIC
17198 platforms, and sometimes when the overlong malformation is also
17199 present. The new name accurately describes the situation in
17200 all cases.
17201 "UTF8_GOT_CONTINUATION"
17203 The input sequence was malformed in that the first byte was a
17204 UTF-8 continuation byte.
17205 "UTF8_GOT_EMPTY"
17207 The input "curlen" parameter was 0.
17208 "UTF8_GOT_LONG"
17210 The input sequence was malformed in that there is some other
17211 sequence that evaluates to the same code point, but that
17212 sequence is shorter than this one.
17213 Until Unicode 3.1, it was legal for programs to accept this
17215 malformation, but it was discovered that this created security
17216 issues.
17217 "UTF8_GOT_NONCHAR"
17219 The code point represented by the input UTF-8 sequence is for a
17220 Unicode non-character code point. This bit is set only if the
17221 input "flags" parameter contains either the
17222 "UTF8_DISALLOW_NONCHAR" or the "UTF8_WARN_NONCHAR" flags.
17223 "UTF8_GOT_NON_CONTINUATION"
17225 The input sequence was malformed in that a non-continuation
17226 type byte was found in a position where only a continuation
17227 type one should be. See also "UTF8_GOT_SHORT".
17228 "UTF8_GOT_OVERFLOW"
17230 The input sequence was malformed in that it is for a code point
17231 that is not representable in the number of bits available in an
17232 IV on the current platform.
17233 "UTF8_GOT_SHORT"
17235 The input sequence was malformed in that "curlen" is smaller
17236 than required for a complete sequence. In other words, the
17237 input is for a partial character sequence.
17238 "UTF8_GOT_SHORT" and "UTF8_GOT_NON_CONTINUATION" both indicate
17240 a too short sequence. The difference is that
17241 "UTF8_GOT_NON_CONTINUATION" indicates always that there is an
17242 error, while "UTF8_GOT_SHORT" means that an incomplete sequence
17243 was looked at. If no other flags are present, it means that
17244 the sequence was valid as far as it went. Depending on the
17245 application, this could mean one of three things:
17246 • The "curlen" length parameter passed in was too small, and
17248 the function was prevented from examining all the necessary
17249 bytes.
17250 • The buffer being looked at is based on reading data, and
17252 the data received so far stopped in the middle of a
17253 character, so that the next read will read the remainder of
17254 this character. (It is up to the caller to deal with the
17255 split bytes somehow.)
17256 • This is a real error, and the partial sequence is all we're
17258 going to get.
17259 "UTF8_GOT_SUPER"
17261 The input sequence was malformed in that it is for a non-
17262 Unicode code point; that is, one above the legal Unicode
17263 maximum. This bit is set only if the input "flags" parameter
17264 contains either the "UTF8_DISALLOW_SUPER" or the
17265 "UTF8_WARN_SUPER" flags.
17266 "UTF8_GOT_SURROGATE"
17268 The input sequence was malformed in that it is for a -Unicode
17269 UTF-16 surrogate code point. This bit is set only if the input
17270 "flags" parameter contains either the "UTF8_DISALLOW_SURROGATE"
17271 or the "UTF8_WARN_SURROGATE" flags.
17272 To do your own error handling, call this function with the
17274 "UTF8_CHECK_ONLY" flag to suppress any warnings, and then examine
17275 the *errors return.
17276 UV utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
17278 STRLEN *retlen, const U32 flags,
17279 U32 *errors)
17280 "utf8n_to_uvchr_msgs"
17282 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
17283 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"() rather
17284 than call this directly.
17285 This function is for code that needs to know what the precise
17287 malformation(s) are when an error is found, and wants the
17288 corresponding warning and/or error messages to be returned to the
17289 caller rather than be displayed. All messages that would have been
17290 displayed if all lexical warnings are enabled will be returned.
17291 It is just like "utf8n_to_uvchr_error" but it takes an extra
17293 parameter placed after all the others, "msgs". If this parameter
17294 is 0, this function behaves identically to "utf8n_to_uvchr_error".
17295 Otherwise, "msgs" should be a pointer to an "AV *" variable, in
17296 which this function creates a new AV to contain any appropriate
17297 messages. The elements of the array are ordered so that the first
17298 message that would have been displayed is in the 0th element, and
17299 so on. Each element is a hash with three key-value pairs, as
17300 follows:
17301 "text"
17303 The text of the message as a "SVpv".
17304 "warn_categories"
17306 The warning category (or categories) packed into a "SVuv".
17307 "flag"
17309 A single flag bit associated with this message, in a "SVuv".
17310 The bit corresponds to some bit in the *errors return value,
17311 such as "UTF8_GOT_LONG".
17312 It's important to note that specifying this parameter as non-null
17314 will cause any warnings this function would otherwise generate to
17315 be suppressed, and instead be placed in *msgs. The caller can
17316 check the lexical warnings state (or not) when choosing what to do
17317 with the returned messages.
17318 If the flag "UTF8_CHECK_ONLY" is passed, no warnings are generated,
17320 and hence no AV is created.
17321 The caller, of course, is responsible for freeing any returned AV.
17323 UV utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
17325 STRLEN *retlen, const U32 flags,
17326 U32 *errors, AV **msgs)
17327 "UTF8_SAFE_SKIP"
17329 returns 0 if "s >= e"; otherwise returns the number of bytes in the
17330 UTF-8 encoded character whose first byte is pointed to by "s".
17331 But it never returns beyond "e". On DEBUGGING builds, it asserts
17332 that "s <= e".
17333 STRLEN UTF8_SAFE_SKIP(char* s, char* e)
17335 "UTF8SKIP"
17337 returns the number of bytes a non-malformed UTF-8 encoded character
17338 whose first (perhaps only) byte is pointed to by "s".
17339 If there is a possibility of malformed input, use instead:
17341 "UTF8_SAFE_SKIP" if you know the maximum ending pointer in the
17343 buffer pointed to by "s"; or
17344 "UTF8_CHK_SKIP" if you don't know it.
17345 It is better to restructure your code so the end pointer is passed
17347 down so that you know what it actually is at the point of this
17348 call, but if that isn't possible, "UTF8_CHK_SKIP" can minimize the
17349 chance of accessing beyond the end of the input buffer.
17350 STRLEN UTF8SKIP(char* s)
17352 "UTF8_SKIP"
17354 This is a synonym for "UTF8SKIP"
17355 STRLEN UTF8_SKIP(char* s)
17357 "utf8_to_bytes"
17359 NOTE: "utf8_to_bytes" is experimental and may change or be removed
17360 without notice.
17361 Converts a string "s" of length *lenp from UTF-8 into native byte
17363 encoding. Unlike "bytes_to_utf8", this over-writes the original
17364 string, and updates *lenp to contain the new length. Returns zero
17365 on failure (leaving "s" unchanged) setting *lenp to -1.
17366 Upon successful return, the number of variants in the string can be
17368 computed by having saved the value of *lenp before the call, and
17369 subtracting the after-call value of *lenp from it.
17370 If you need a copy of the string, see "bytes_from_utf8".
17372 U8 * utf8_to_bytes(U8 *s, STRLEN *lenp)
17374 "utf8_to_uvchr"
17376 "DEPRECATED!" It is planned to remove "utf8_to_uvchr" from a
17377 future release of Perl. Do not use it for new code; remove it from
17378 existing code.
17379 Returns the native code point of the first character in the string
17381 "s" which is assumed to be in UTF-8 encoding; "retlen" will be set
17382 to the length, in bytes, of that character.
17383 Some, but not all, UTF-8 malformations are detected, and in fact,
17385 some malformed input could cause reading beyond the end of the
17386 input buffer, which is why this function is deprecated. Use
17387 "utf8_to_uvchr_buf" instead.
17388 If "s" points to one of the detected malformations, and UTF8
17390 warnings are enabled, zero is returned and *retlen is set (if
17391 "retlen" isn't "NULL") to -1. If those warnings are off, the
17392 computed value if well-defined (or the Unicode REPLACEMENT
17393 CHARACTER, if not) is silently returned, and *retlen is set (if
17394 "retlen" isn't NULL) so that ("s" + *retlen) is the next possible
17395 position in "s" that could begin a non-malformed character. See
17396 "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is
17397 returned.
17398 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
17400 "utf8_to_uvchr_buf"
17402 Returns the native code point of the first character in the string
17403 "s" which is assumed to be in UTF-8 encoding; "send" points to 1
17404 beyond the end of "s". *retlen will be set to the length, in
17405 bytes, of that character.
17406 If "s" does not point to a well-formed UTF-8 character and UTF8
17408 warnings are enabled, zero is returned and *retlen is set (if
17409 "retlen" isn't "NULL") to -1. If those warnings are off, the
17410 computed value, if well-defined (or the Unicode REPLACEMENT
17411 CHARACTER if not), is silently returned, and *retlen is set (if
17412 "retlen" isn't "NULL") so that ("s" + *retlen) is the next possible
17413 position in "s" that could begin a non-malformed character. See
17414 "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is
17415 returned.
17416 UV utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen)
17418 "UVCHR_IS_INVARIANT"
17420 Evaluates to 1 if the representation of code point "cp" is the same
17421 whether or not it is encoded in UTF-8; otherwise evaluates to 0.
17422 UTF-8 invariant characters can be copied as-is when converting
17423 to/from UTF-8, saving time. "cp" is Unicode if above 255;
17424 otherwise is platform-native.
17425 bool UVCHR_IS_INVARIANT(UV cp)
17427 "UVCHR_SKIP"
17429 returns the number of bytes required to represent the code point
17430 "cp" when encoded as UTF-8. "cp" is a native (ASCII or EBCDIC)
17431 code point if less than 255; a Unicode code point otherwise.
17432 STRLEN UVCHR_SKIP(UV cp)
17434 "uvchr_to_utf8_flags"
17436 Adds the UTF-8 representation of the native code point "uv" to the
17437 end of the string "d"; "d" should have at least "UVCHR_SKIP(uv)+1"
17438 (up to "UTF8_MAXBYTES+1") free bytes available. The return value
17439 is the pointer to the byte after the end of the new character. In
17440 other words,
17441 d = uvchr_to_utf8_flags(d, uv, flags);
17443 or, in most cases,
17445 d = uvchr_to_utf8_flags(d, uv, 0);
17447 This is the Unicode-aware way of saying
17449 *(d++) = uv;
17451 If "flags" is 0, this function accepts any code point from
17453 0.."IV_MAX" as input. "IV_MAX" is typically 0x7FFF_FFFF in a
17454 32-bit word.
17455 Specifying "flags" can further restrict what is allowed and not
17457 warned on, as follows:
17458 If "uv" is a Unicode surrogate code point and
17460 "UNICODE_WARN_SURROGATE" is set, the function will raise a warning,
17461 provided UTF8 warnings are enabled. If instead
17462 "UNICODE_DISALLOW_SURROGATE" is set, the function will fail and
17463 return NULL. If both flags are set, the function will both warn
17464 and return NULL.
17465 Similarly, the "UNICODE_WARN_NONCHAR" and
17467 "UNICODE_DISALLOW_NONCHAR" flags affect how the function handles a
17468 Unicode non-character.
17469 And likewise, the "UNICODE_WARN_SUPER" and "UNICODE_DISALLOW_SUPER"
17471 flags affect the handling of code points that are above the Unicode
17472 maximum of 0x10FFFF. Languages other than Perl may not be able to
17473 accept files that contain these.
17474 The flag "UNICODE_WARN_ILLEGAL_INTERCHANGE" selects all three of
17476 the above WARN flags; and "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE"
17477 selects all three DISALLOW flags.
17478 "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed inputs
17479 to the strict UTF-8 traditionally defined by Unicode. Similarly,
17480 "UNICODE_WARN_ILLEGAL_C9_INTERCHANGE" and
17481 "UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE" are shortcuts to select
17482 the above-Unicode and surrogate flags, but not the non-character
17483 ones, as defined in Unicode Corrigendum #9
17484 <https://www.unicode.org/versions/corrigendum9.html>. See
17485 "Noncharacter code points" in perlunicode.
17486 Extremely high code points were never specified in any standard,
17488 and require an extension to UTF-8 to express, which Perl does. It
17489 is likely that programs written in something other than Perl would
17490 not be able to read files that contain these; nor would Perl
17491 understand files written by something that uses a different
17492 extension. For these reasons, there is a separate set of flags
17493 that can warn and/or disallow these extremely high code points,
17494 even if other above-Unicode ones are accepted. They are the
17495 "UNICODE_WARN_PERL_EXTENDED" and "UNICODE_DISALLOW_PERL_EXTENDED"
17496 flags. For more information see "UTF8_GOT_PERL_EXTENDED". Of
17497 course "UNICODE_DISALLOW_SUPER" will treat all above-Unicode code
17498 points, including these, as malformations. (Note that the Unicode
17499 standard considers anything above 0x10FFFF to be illegal, but there
17500 are standards predating it that allow up to 0x7FFF_FFFF (2**31 -1))
17501 A somewhat misleadingly named synonym for
17503 "UNICODE_WARN_PERL_EXTENDED" is retained for backward
17504 compatibility: "UNICODE_WARN_ABOVE_31_BIT". Similarly,
17505 "UNICODE_DISALLOW_ABOVE_31_BIT" is usable instead of the more
17506 accurately named "UNICODE_DISALLOW_PERL_EXTENDED". The names are
17507 misleading because on EBCDIC platforms,these flags can apply to
17508 code points that actually do fit in 31 bits. The new names
17509 accurately describe the situation in all cases.
17510 U8 * uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
17512 "uvchr_to_utf8_flags_msgs"
17514 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
17515 CIRCUMSTANCES.
17516 Most code should use ""uvchr_to_utf8_flags"()" rather than call
17518 this directly.
17519 This function is for code that wants any warning and/or error
17521 messages to be returned to the caller rather than be displayed.
17522 All messages that would have been displayed if all lexical warnings
17523 are enabled will be returned.
17524 It is just like "uvchr_to_utf8_flags" but it takes an extra
17526 parameter placed after all the others, "msgs". If this parameter
17527 is 0, this function behaves identically to "uvchr_to_utf8_flags".
17528 Otherwise, "msgs" should be a pointer to an "HV *" variable, in
17529 which this function creates a new HV to contain any appropriate
17530 messages. The hash has three key-value pairs, as follows:
17531 "text"
17533 The text of the message as a "SVpv".
17534 "warn_categories"
17536 The warning category (or categories) packed into a "SVuv".
17537 "flag"
17539 A single flag bit associated with this message, in a "SVuv".
17540 The bit corresponds to some bit in the *errors return value,
17541 such as "UNICODE_GOT_SURROGATE".
17542 It's important to note that specifying this parameter as non-null
17544 will cause any warnings this function would otherwise generate to
17545 be suppressed, and instead be placed in *msgs. The caller can
17546 check the lexical warnings state (or not) when choosing what to do
17547 with the returned messages.
17548 The caller, of course, is responsible for freeing any returned HV.
17550 U8 * uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags, HV **msgs)
17552 "uvchr_to_utf8"
17554 Adds the UTF-8 representation of the native code point "uv" to the
17555 end of the string "d"; "d" should have at least "UVCHR_SKIP(uv)+1"
17556 (up to "UTF8_MAXBYTES+1") free bytes available. The return value
17557 is the pointer to the byte after the end of the new character. In
17558 other words,
17559 d = uvchr_to_utf8(d, uv);
17561 is the recommended wide native character-aware way of saying
17563 *(d++) = uv;
17565 This function accepts any code point from 0.."IV_MAX" as input.
17567 "IV_MAX" is typically 0x7FFF_FFFF in a 32-bit word.
17568 It is possible to forbid or warn on non-Unicode code points, or
17570 those that may be problematic by using "uvchr_to_utf8_flags".
17571 U8 * uvchr_to_utf8(U8 *d, UV uv)
17573
17575 "C_ARRAY_END"
17576 Returns a pointer to one element past the final element of the
17577 input C array.
17578 void * C_ARRAY_END(void *a)
17580 "C_ARRAY_LENGTH"
17582 Returns the number of elements in the input C array (so you want
17583 your zero-based indices to be less than but not equal to).
17584 STRLEN C_ARRAY_LENGTH(void *a)
17586 "getcwd_sv"
17588 Fill "sv" with current working directory
17589 int getcwd_sv(SV *sv)
17591 "IN_PERL_COMPILETIME"
17593 Returns 1 if this macro is being called during the compilation
17594 phase of the program; otherwise 0;
17595 bool IN_PERL_COMPILETIME
17597 "IN_PERL_RUNTIME"
17599 Returns 1 if this macro is being called during the execution phase
17600 of the program; otherwise 0;
17601 bool IN_PERL_RUNTIME
17603 "IS_SAFE_SYSCALL"
17605 Same as "is_safe_syscall".
17606 bool IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
17608 NN const char *what, NN const char *op_name)
17609 "is_safe_syscall"
17611 Test that the given "pv" (with length "len") doesn't contain any
17612 internal "NUL" characters. If it does, set "errno" to "ENOENT",
17613 optionally warn using the "syscalls" category, and return FALSE.
17614 Return TRUE if the name is safe.
17616 "what" and "op_name" are used in any warning.
17618 Used by the IS_SAFE_SYSCALL() macro.
17620 bool is_safe_syscall(const char *pv, STRLEN len,
17622 const char *what, const char *op_name)
17623 "my_setenv"
17625 A wrapper for the C library setenv(3). Don't use the latter, as
17626 the perl version has desirable safeguards
17627 void my_setenv(const char *nam, const char *val)
17629 "newPADxVOP"
17631 Constructs, checks and returns an op containing a pad offset.
17632 "type" is the opcode, which should be one of "OP_PADSV",
17633 "OP_PADAV", "OP_PADHV" or "OP_PADCV". The returned op will have
17634 the "op_targ" field set by the "padix" argument.
17635 This is convenient when constructing a large optree in nested
17637 function calls, as it avoids needing to store the pad op directly
17638 to set the "op_targ" field as a side-effect. For example
17639 o = op_append_elem(OP_LINESEQ, o,
17641 newPADxVOP(OP_PADSV, 0, padix));
17642 OP * newPADxVOP(I32 type, I32 flags, PADOFFSET padix)
17644 "phase_name"
17646 Returns the given phase's name as a NUL-terminated string.
17647 For example, to print a stack trace that includes the current
17649 interpreter phase you might do:
17650 const char* phase_name = phase_name(PL_phase);
17652 mess("This is weird. (Perl phase: %s)", phase_name);
17653 const char * const phase_name(enum perl_phase)
17655 "Poison"
17657 PoisonWith(0xEF) for catching access to freed memory.
17658 void Poison(void* dest, int nitems, type)
17660 "PoisonFree"
17662 PoisonWith(0xEF) for catching access to freed memory.
17663 void PoisonFree(void* dest, int nitems, type)
17665 "PoisonNew"
17667 PoisonWith(0xAB) for catching access to allocated but uninitialized
17668 memory.
17669 void PoisonNew(void* dest, int nitems, type)
17671 "PoisonWith"
17673 Fill up memory with a byte pattern (a byte repeated over and over
17674 again) that hopefully catches attempts to access uninitialized
17675 memory.
17676 void PoisonWith(void* dest, int nitems, type, U8 byte)
17678 "StructCopy"
17680 This is an architecture-independent macro to copy one structure to
17681 another.
17682 void StructCopy(type *src, type *dest, type)
17684 "sv_destroyable"
17686 Dummy routine which reports that object can be destroyed when there
17687 is no sharing module present. It ignores its single SV argument,
17688 and returns 'true'. Exists to avoid test for a "NULL" function
17689 pointer and because it could potentially warn under some level of
17690 strict-ness.
17691 bool sv_destroyable(SV *sv)
17693 "sv_nosharing"
17695 Dummy routine which "shares" an SV when there is no sharing module
17696 present. Or "locks" it. Or "unlocks" it. In other words, ignores
17697 its single SV argument. Exists to avoid test for a "NULL" function
17698 pointer and because it could potentially warn under some level of
17699 strict-ness.
17700 void sv_nosharing(SV *sv)
17702
17704 "new_version"
17705 Returns a new version object based on the passed in SV:
17706 SV *sv = new_version(SV *ver);
17708 Does not alter the passed in ver SV. See "upg_version" if you want
17710 to upgrade the SV.
17711 SV * new_version(SV *ver)
17713 "PERL_REVISION"
17715 "DEPRECATED!" It is planned to remove "PERL_REVISION" from a
17716 future release of Perl. Do not use it for new code; remove it from
17717 existing code.
17718 The major number component of the perl interpreter currently being
17720 compiled or executing. This has been 5 from 1993 into 2020.
17721 Instead use one of the version comparison macros. See
17723 "PERL_VERSION_EQ".
17724 "PERL_SUBVERSION"
17726 "DEPRECATED!" It is planned to remove "PERL_SUBVERSION" from a
17727 future release of Perl. Do not use it for new code; remove it from
17728 existing code.
17729 The micro number component of the perl interpreter currently being
17731 compiled or executing. In stable releases this gives the dot
17732 release number for maintenance updates. In development releases
17733 this gives a tag for a snapshot of the status at various points in
17734 the development cycle.
17735 Instead use one of the version comparison macros. See
17737 "PERL_VERSION_EQ".
17738 "PERL_VERSION"
17740 "DEPRECATED!" It is planned to remove "PERL_VERSION" from a future
17741 release of Perl. Do not use it for new code; remove it from
17742 existing code.
17743 The minor number component of the perl interpreter currently being
17745 compiled or executing. Between 1993 into 2020, this has ranged
17746 from 0 to 33.
17747 Instead use one of the version comparison macros. See
17749 "PERL_VERSION_EQ".
17750 "PERL_VERSION_EQ"
17752 "PERL_VERSION_GE"
17753 "PERL_VERSION_GT"
17754 "PERL_VERSION_LE"
17755 "PERL_VERSION_LT"
17756 "PERL_VERSION_NE"
17757 Returns whether or not the perl currently being compiled has the
17758 specified relationship to the perl given by the parameters. For
17759 example,
17760 #if PERL_VERSION_GT(5,24,2)
17762 code that will only be compiled on perls after v5.24.2
17763 #else
17764 fallback code
17765 #endif
17766 Note that this is usable in making compile-time decisions
17768 You may use the special value '*' for the final number to mean ALL
17770 possible values for it. Thus,
17771 #if PERL_VERSION_EQ(5,31,'*')
17773 means all perls in the 5.31 series. And
17775 #if PERL_VERSION_NE(5,24,'*')
17777 means all perls EXCEPT 5.24 ones. And
17779 #if PERL_VERSION_LE(5,9,'*')
17781 is effectively
17783 #if PERL_VERSION_LT(5,10,0)
17785 This means you don't have to think so much when converting from the
17787 existing deprecated "PERL_VERSION" to using this macro:
17788 #if PERL_VERSION <= 9
17790 becomes
17792 #if PERL_VERSION_LE(5,9,'*')
17794 bool PERL_VERSION_EQ(const U8 major, const U8 minor,
17796 const U8 patch)
17797 "prescan_version"
17799 Validate that a given string can be parsed as a version object, but
17800 doesn't actually perform the parsing. Can use either strict or lax
17801 validation rules. Can optionally set a number of hint variables to
17802 save the parsing code some time when tokenizing.
17803 const char * prescan_version(const char *s, bool strict,
17805 const char **errstr, bool *sqv,
17806 int *ssaw_decimal, int *swidth,
17807 bool *salpha)
17808 "scan_version"
17810 Returns a pointer to the next character after the parsed version
17811 string, as well as upgrading the passed in SV to an RV.
17812 Function must be called with an already existing SV like
17814 sv = newSV(0);
17816 s = scan_version(s, SV *sv, bool qv);
17817 Performs some preprocessing to the string to ensure that it has the
17819 correct characteristics of a version. Flags the object if it
17820 contains an underscore (which denotes this is an alpha version).
17821 The boolean qv denotes that the version should be interpreted as if
17822 it had multiple decimals, even if it doesn't.
17823 const char * scan_version(const char *s, SV *rv, bool qv)
17825 "upg_version"
17827 In-place upgrade of the supplied SV to a version object.
17828 SV *sv = upg_version(SV *sv, bool qv);
17830 Returns a pointer to the upgraded SV. Set the boolean qv if you
17832 want to force this SV to be interpreted as an "extended" version.
17833 SV * upg_version(SV *ver, bool qv)
17835 "vcmp"
17837 Version object aware cmp. Both operands must already have been
17838 converted into version objects.
17839 int vcmp(SV *lhv, SV *rhv)
17841 "vnormal"
17843 Accepts a version object and returns the normalized string
17844 representation. Call like:
17845 sv = vnormal(rv);
17847 NOTE: you can pass either the object directly or the SV contained
17849 within the RV.
17850 The SV returned has a refcount of 1.
17852 SV * vnormal(SV *vs)
17854 "vnumify"
17856 Accepts a version object and returns the normalized floating point
17857 representation. Call like:
17858 sv = vnumify(rv);
17860 NOTE: you can pass either the object directly or the SV contained
17862 within the RV.
17863 The SV returned has a refcount of 1.
17865 SV * vnumify(SV *vs)
17867 "vstringify"
17869 In order to maintain maximum compatibility with earlier versions of
17870 Perl, this function will return either the floating point notation
17871 or the multiple dotted notation, depending on whether the original
17872 version contained 1 or more dots, respectively.
17873 The SV returned has a refcount of 1.
17875 SV * vstringify(SV *vs)
17877 "vverify"
17879 Validates that the SV contains valid internal structure for a
17880 version object. It may be passed either the version object (RV) or
17881 the hash itself (HV). If the structure is valid, it returns the
17882 HV. If the structure is invalid, it returns NULL.
17883 SV *hv = vverify(sv);
17885 Note that it only confirms the bare minimum structure (so as not to
17887 get confused by derived classes which may contain additional hash
17888 entries):
17889 • The SV is an HV or a reference to an HV
17891 • The hash contains a "version" key
17893 • The "version" key has a reference to an AV as its value
17895 SV * vverify(SV *vs)
17897
17899 In all these calls, the "U32 wn" parameters are warning category
17900 constants. You can see the ones currently available in "Category
17901 Hierarchy" in warnings, just capitalize all letters in the names and
17902 prefix them by "WARN_". So, for example, the category "void" used in a
17903 perl program becomes "WARN_VOID" when used in XS code and passed to one
17904 of the calls below.
17905 "ckWARN"
17907 "ckWARN2"
17908 "ckWARN3"
17909 "ckWARN4"
17910 These return a boolean as to whether or not warnings are enabled
17911 for any of the warning category(ies) parameters: "w", "w1", ....
17912 Should any of the categories by default be enabled even if not
17914 within the scope of "use warnings", instead use the "ckWARN_d"
17915 macros.
17916 The categories must be completely independent, one may not be
17918 subclassed from the other.
17919 bool ckWARN (U32 w)
17921 bool ckWARN2(U32 w1, U32 w2)
17922 bool ckWARN3(U32 w1, U32 w2, U32 w3)
17923 bool ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
17924 "ckWARN_d"
17926 "ckWARN2_d"
17927 "ckWARN3_d"
17928 "ckWARN4_d"
17929 Like "ckWARN", but for use if and only if the warning category(ies)
17930 is by default enabled even if not within the scope of
17931 "use warnings".
17932 bool ckWARN_d (U32 w)
17934 bool ckWARN2_d(U32 w1, U32 w2)
17935 bool ckWARN3_d(U32 w1, U32 w2, U32 w3)
17936 bool ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
17937 "ck_warner"
17939 "ck_warner_d"
17940 If none of the warning categories given by "err" are enabled, do
17941 nothing; otherwise call "warner" or "warner_nocontext" with the
17942 passed-in parameters;.
17943 "err" must be one of the "packWARN", "packWARN2", "packWARN3",
17945 "packWARN4" macros populated with the appropriate number of warning
17946 categories.
17947 The two forms differ only in that "ck_warner_d" should be used if
17949 warnings for any of the categories are by default enabled.
17950 NOTE: "ck_warner" must be explicitly called as "Perl_ck_warner"
17952 with an "aTHX_" parameter.
17953 NOTE: "ck_warner_d" must be explicitly called as "Perl_ck_warner_d"
17955 with an "aTHX_" parameter.
17956 void Perl_ck_warner(pTHX_ U32 err, const char *pat, ...)
17958 "CLEAR_ERRSV"
17960 Clear the contents of $@, setting it to the empty string.
17961 This replaces any read-only SV with a fresh SV and removes any
17963 magic.
17964 void CLEAR_ERRSV()
17966 "croak"
17968 "croak_nocontext"
17969 These are XS interfaces to Perl's "die" function.
17970 They take a sprintf-style format pattern and argument list, which
17972 are used to generate a string message. If the message does not end
17973 with a newline, then it will be extended with some indication of
17974 the current location in the code, as described for "mess_sv".
17975 The error message will be used as an exception, by default
17977 returning control to the nearest enclosing "eval", but subject to
17978 modification by a $SIG{__DIE__} handler. In any case, these croak
17979 functions never return normally.
17980 For historical reasons, if "pat" is null then the contents of
17982 "ERRSV" ($@) will be used as an error message or object instead of
17983 building an error message from arguments. If you want to throw a
17984 non-string object, or build an error message in an SV yourself, it
17985 is preferable to use the "croak_sv" function, which does not
17986 involve clobbering "ERRSV".
17987 The two forms differ only in that "croak_nocontext" does not take a
17989 thread context ("aTHX") parameter. It is usually preferred as it
17990 takes up fewer bytes of code than plain "Perl_croak", and time is
17991 rarely a critical resource when you are about to throw an
17992 exception.
17993 NOTE: "croak" must be explicitly called as "Perl_croak" with an
17995 "aTHX_" parameter.
17996 void Perl_croak (pTHX_ const char *pat, ...)
17998 void croak_nocontext(const char *pat, ...)
17999 "croak_no_modify"
18001 This encapsulates a common reason for dying, generating terser
18002 object code than using the generic "Perl_croak". It is exactly
18003 equivalent to "Perl_croak(aTHX_ "%s", PL_no_modify)" (which expands
18004 to something like "Modification of a read-only value attempted").
18005 Less code used on exception code paths reduces CPU cache pressure.
18007 void croak_no_modify()
18009 "croak_sv"
18011 This is an XS interface to Perl's "die" function.
18012 "baseex" is the error message or object. If it is a reference, it
18014 will be used as-is. Otherwise it is used as a string, and if it
18015 does not end with a newline then it will be extended with some
18016 indication of the current location in the code, as described for
18017 "mess_sv".
18018 The error message or object will be used as an exception, by
18020 default returning control to the nearest enclosing "eval", but
18021 subject to modification by a $SIG{__DIE__} handler. In any case,
18022 the "croak_sv" function never returns normally.
18023 To die with a simple string message, the "croak" function may be
18025 more convenient.
18026 void croak_sv(SV *baseex)
18028 "die"
18030 "die_nocontext"
18031 These behave the same as "croak", except for the return type. They
18032 should be used only where the "OP *" return type is required. They
18033 never actually return.
18034 The two forms differ only in that "die_nocontext" does not take a
18036 thread context ("aTHX") parameter, so is used in situations where
18037 the caller doesn't already have the thread context.
18038 NOTE: "die" must be explicitly called as "Perl_die" with an "aTHX_"
18040 parameter.
18041 OP * Perl_die (pTHX_ const char *pat, ...)
18043 OP * die_nocontext(const char *pat, ...)
18044 "die_sv"
18046 This behaves the same as "croak_sv", except for the return type.
18047 It should be used only where the "OP *" return type is required.
18048 The function never actually returns.
18049 OP * die_sv(SV *baseex)
18051 "ERRSV"
18053 Returns the SV for $@, creating it if needed.
18054 SV * ERRSV
18056 "packWARN"
18058 "packWARN2"
18059 "packWARN3"
18060 "packWARN4"
18061 These macros are used to pack warning categories into a single U32
18062 to pass to macros and functions that take a warning category
18063 parameter. The number of categories to pack is given by the name,
18064 with a corresponding number of category parameters passed.
18065 U32 packWARN (U32 w1)
18067 U32 packWARN2(U32 w1, U32 w2)
18068 U32 packWARN3(U32 w1, U32 w2, U32 w3)
18069 U32 packWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
18070 "SANE_ERRSV"
18072 Clean up ERRSV so we can safely set it.
18073 This replaces any read-only SV with a fresh writable copy and
18075 removes any magic.
18076 void SANE_ERRSV()
18078 "vcroak"
18080 This is an XS interface to Perl's "die" function.
18081 "pat" and "args" are a sprintf-style format pattern and
18083 encapsulated argument list. These are used to generate a string
18084 message. If the message does not end with a newline, then it will
18085 be extended with some indication of the current location in the
18086 code, as described for "mess_sv".
18087 The error message will be used as an exception, by default
18089 returning control to the nearest enclosing "eval", but subject to
18090 modification by a $SIG{__DIE__} handler. In any case, the "croak"
18091 function never returns normally.
18092 For historical reasons, if "pat" is null then the contents of
18094 "ERRSV" ($@) will be used as an error message or object instead of
18095 building an error message from arguments. If you want to throw a
18096 non-string object, or build an error message in an SV yourself, it
18097 is preferable to use the "croak_sv" function, which does not
18098 involve clobbering "ERRSV".
18099 void vcroak(const char *pat, va_list *args)
18101 "vwarn"
18103 This is an XS interface to Perl's "warn" function.
18104 This is like "warn", but "args" are an encapsulated argument list.
18106 Unlike with "vcroak", "pat" is not permitted to be null.
18108 void vwarn(const char *pat, va_list *args)
18110 "vwarner"
18112 This is like "warner", but "args" are an encapsulated argument
18113 list.
18114 void vwarner(U32 err, const char *pat, va_list *args)
18116 "warn"
18118 "warn_nocontext"
18119 These are XS interfaces to Perl's "warn" function.
18120 They take a sprintf-style format pattern and argument list, which
18122 are used to generate a string message. If the message does not end
18123 with a newline, then it will be extended with some indication of
18124 the current location in the code, as described for "mess_sv".
18125 The error message or object will by default be written to standard
18127 error, but this is subject to modification by a $SIG{__WARN__}
18128 handler.
18129 Unlike with "croak", "pat" is not permitted to be null.
18131 The two forms differ only in that "warn_nocontext" does not take a
18133 thread context ("aTHX") parameter, so is used in situations where
18134 the caller doesn't already have the thread context.
18135 NOTE: "warn" must be explicitly called as "Perl_warn" with an
18137 "aTHX_" parameter.
18138 void Perl_warn (pTHX_ const char *pat, ...)
18140 void warn_nocontext(const char *pat, ...)
18141 "warner"
18143 "warner_nocontext"
18144 These output a warning of the specified category (or categories)
18145 given by "err", using the sprintf-style format pattern "pat", and
18146 argument list.
18147 "err" must be one of the "packWARN", "packWARN2", "packWARN3",
18149 "packWARN4" macros populated with the appropriate number of warning
18150 categories. If any of the warning categories they specify is
18151 fatal, a fatal exception is thrown.
18152 In any event a message is generated by the pattern and arguments.
18154 If the message does not end with a newline, then it will be
18155 extended with some indication of the current location in the code,
18156 as described for "mess_sv".
18157 The error message or object will by default be written to standard
18159 error, but this is subject to modification by a $SIG{__WARN__}
18160 handler.
18161 "pat" is not permitted to be null.
18163 The two forms differ only in that "warner_nocontext" does not take
18165 a thread context ("aTHX") parameter, so is used in situations where
18166 the caller doesn't already have the thread context.
18167 These functions differ from the similarly named "warn" functions,
18169 in that the latter are for XS code to unconditionally display a
18170 warning, whereas these are for code that may be compiling a perl
18171 program, and does extra checking to see if the warning should be
18172 fatal.
18173 NOTE: "warner" must be explicitly called as "Perl_warner" with an
18175 "aTHX_" parameter.
18176 void Perl_warner (pTHX_ U32 err, const char *pat, ...)
18178 void warner_nocontext(U32 err, const char *pat, ...)
18179 "warn_sv"
18181 This is an XS interface to Perl's "warn" function.
18182 "baseex" is the error message or object. If it is a reference, it
18184 will be used as-is. Otherwise it is used as a string, and if it
18185 does not end with a newline then it will be extended with some
18186 indication of the current location in the code, as described for
18187 "mess_sv".
18188 The error message or object will by default be written to standard
18190 error, but this is subject to modification by a $SIG{__WARN__}
18191 handler.
18192 To warn with a simple string message, the "warn" function may be
18194 more convenient.
18195 void warn_sv(SV *baseex)
18197
18199 xsubpp compiles XS code into C. See "xsubpp" in perlutil.
18200 "aMY_CXT"
18202 Described in perlxs.
18203 "_aMY_CXT"
18205 Described in perlxs.
18206 "aMY_CXT_"
18208 Described in perlxs.
18209 "ax"
18211 Variable which is setup by "xsubpp" to indicate the stack base
18212 offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros. The
18213 "dMARK" macro must be called prior to setup the "MARK" variable.
18214 I32 ax
18216 "CLASS"
18218 Variable which is setup by "xsubpp" to indicate the class name for
18219 a C++ XS constructor. This is always a "char*". See "THIS".
18220 char* CLASS
18222 "dAX"
18224 Sets up the "ax" variable. This is usually handled automatically
18225 by "xsubpp" by calling "dXSARGS".
18226 dAX;
18228 "dAXMARK"
18230 Sets up the "ax" variable and stack marker variable "mark". This
18231 is usually handled automatically by "xsubpp" by calling "dXSARGS".
18232 dAXMARK;
18234 "dITEMS"
18236 Sets up the "items" variable. This is usually handled
18237 automatically by "xsubpp" by calling "dXSARGS".
18238 dITEMS;
18240 "dMY_CXT"
18242 Described in perlxs.
18243 "dMY_CXT_SV"
18245 Now a placeholder that declares nothing
18246 dMY_CXT_SV;
18248 "dUNDERBAR"
18250 Sets up any variable needed by the "UNDERBAR" macro. It used to
18251 define "padoff_du", but it is currently a noop. However, it is
18252 strongly advised to still use it for ensuring past and future
18253 compatibility.
18254 dUNDERBAR;
18256 "dXSARGS"
18258 Sets up stack and mark pointers for an XSUB, calling "dSP" and
18259 "dMARK". Sets up the "ax" and "items" variables by calling "dAX"
18260 and "dITEMS". This is usually handled automatically by "xsubpp".
18261 dXSARGS;
18263 "dXSI32"
18265 Sets up the "ix" variable for an XSUB which has aliases. This is
18266 usually handled automatically by "xsubpp".
18267 dXSI32;
18269 "items"
18271 Variable which is setup by "xsubpp" to indicate the number of items
18272 on the stack. See "Variable-length Parameter Lists" in perlxs.
18273 I32 items
18275 "ix"
18277 Variable which is setup by "xsubpp" to indicate which of an XSUB's
18278 aliases was used to invoke it. See "The ALIAS: Keyword" in perlxs.
18279 I32 ix
18281 "MY_CXT"
18283 Described in perlxs.
18284 "MY_CXT_CLONE"
18286 Described in perlxs.
18287 "MY_CXT_INIT"
18289 Described in perlxs.
18290 "pMY_CXT"
18292 Described in perlxs.
18293 "_pMY_CXT"
18295 Described in perlxs.
18296 "pMY_CXT_"
18298 Described in perlxs.
18299 "RETVAL"
18301 Variable which is setup by "xsubpp" to hold the return value for an
18302 XSUB. This is always the proper type for the XSUB. See "The
18303 RETVAL Variable" in perlxs.
18304 type RETVAL
18306 "ST"
18308 Used to access elements on the XSUB's stack.
18309 SV* ST(int ix)
18311 "START_MY_CXT"
18313 Described in perlxs.
18314 "THIS"
18316 Variable which is setup by "xsubpp" to designate the object in a
18317 C++ XSUB. This is always the proper type for the C++ object. See
18318 "CLASS" and "Using XS With C++" in perlxs.
18319 type THIS
18321 "UNDERBAR"
18323 The SV* corresponding to the $_ variable. Works even if there is a
18324 lexical $_ in scope.
18325 "XS"
18327 Macro to declare an XSUB and its C parameter list. This is handled
18328 by "xsubpp". It is the same as using the more explicit
18329 "XS_EXTERNAL" macro; the latter is preferred.
18330 "XS_EXTERNAL"
18332 Macro to declare an XSUB and its C parameter list explicitly
18333 exporting the symbols.
18334 "XS_INTERNAL"
18336 Macro to declare an XSUB and its C parameter list without exporting
18337 the symbols. This is handled by "xsubpp" and generally preferable
18338 over exporting the XSUB symbols unnecessarily.
18339 "XSPROTO"
18341 Macro used by "XS_INTERNAL" and "XS_EXTERNAL" to declare a function
18342 prototype. You probably shouldn't be using this directly yourself.
18343
18345 The following functions have been flagged as part of the public API,
18346 but are currently undocumented. Use them at your own risk, as the
18347 interfaces are subject to change. Functions that are not listed in
18348 this document are not intended for public use, and should NOT be used
18349 under any circumstances.
18350 If you feel you need to use one of these functions, first send email to
18352 perl5-porters@perl.org <mailto:perl5-porters@perl.org>. It may be that
18353 there is a good reason for the function not being documented, and it
18354 should be removed from this list; or it may just be that no one has
18355 gotten around to documenting it. In the latter case, you will be asked
18356 to submit a patch to document the function. Once your patch is
18357 accepted, it will indicate that the interface is stable (unless it is
18358 explicitly marked otherwise) and usable by you.
18359 clone_params_del newANONATTRSUB newAVREF newSVREF
18361 clone_params_new newANONHASH newCVREF resume_compcv
18362 do_open newANONLIST newGVREF sv_dup
18363 do_openn newANONSUB newHVREF sv_dup_inc
18364 Next are the API-flagged elements that are considered experimental.
18366 Using one of these is even more risky than plain undocumented ones.
18367 They are listed here because they should be listed somewhere (so their
18368 existence doesn't get lost) and this is the best place for them.
18369 apply_attrs_string hv_store_flags thread_locale_init
18371 gv_fetchmethod_pv_flags leave_adjust_stacks thread_locale_term
18372 gv_fetchmethod_pvn_flags newXS_flags
18373 gv_fetchmethod_sv_flags savetmps
18374 Finally are deprecated undocumented API elements. Do not use any for
18376 new code; remove all occurrences of all of these from existing code.
18377 There are currently no items of this type
18379
18381 Until May 1997, this document was maintained by Jeff Okamoto
18382 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
18383 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
18385 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
18386 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
18387 Stephen McCamant, and Gurusamy Sarathy.
18388 API Listing originally by Dean Roehrich <roehrich@cray.com>.
18390 Updated to be autogenerated from comments in the source by Benjamin
18392 Stuhl.
18393
18395 config.h, perlapio, perlcall, perlclib, perlembed, perlfilter,
18396 perlguts, perlhacktips, perlintern, perlinterp, perliol, perlmroapi,
18397 perlreapi, perlreguts, perlxs
18398perl v5.38.2 2023-11-30 PERLAPI(1)