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 Some specialized items are instead documented in config.h, perlapio,
13 perlcall, perlclib, perlfilter, perlguts, perlmroapi, perlxs,
14 perlxstut, and warnings.
15 At the end is a list of functions which have yet to be documented.
17 Patches welcome! The interfaces of these are subject to change without
18 notice.
19 Anything not listed here is not part of the public API, and should not
21 be used by extension writers at all. For these reasons, blindly using
22 functions listed in proto.h is to be avoided when writing extensions.
23 In Perl, unlike C, a string of characters may generally contain
25 embedded "NUL" characters. Sometimes in the documentation a Perl
26 string is referred to as a "buffer" to distinguish it from a C string,
27 but sometimes they are both just referred to as strings.
28 Note that all Perl API global variables must be referenced with the
30 "PL_" prefix. Again, those not listed here are not to be used by
31 extension writers, and can be changed or removed without notice; same
32 with macros. Some macros are provided for compatibility with the
33 older, unadorned names, but this support may be disabled in a future
34 release.
35 Perl was originally written to handle US-ASCII only (that is characters
37 whose ordinal numbers are in the range 0 - 127). And documentation and
38 comments may still use the term ASCII, when sometimes in fact the
39 entire range from 0 - 255 is meant.
40 The non-ASCII characters below 256 can have various meanings, depending
42 on various things. (See, most notably, perllocale.) But usually the
43 whole range can be referred to as ISO-8859-1. Often, the term
44 "Latin-1" (or "Latin1") is used as an equivalent for ISO-8859-1. But
45 some people treat "Latin1" as referring just to the characters in the
46 range 128 through 255, or somethimes from 160 through 255. This
47 documentation uses "Latin1" and "Latin-1" to refer to all 256
48 characters.
49 Note that Perl can be compiled and run under either ASCII or EBCDIC
51 (See perlebcdic). Most of the documentation (and even comments in the
52 code) ignore the EBCDIC possibility. For almost all purposes the
53 differences are transparent. As an example, under EBCDIC, instead of
54 UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so whenever
55 this documentation refers to "utf8" (and variants of that name,
56 including in function names), it also (essentially transparently) means
57 "UTF-EBCDIC". But the ordinals of characters differ between ASCII,
58 EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may
59 occupy a different number of bytes than in UTF-8.
60 The listing below is alphabetical, case insensitive.
62
64 av_clear
65 Frees the all the elements of an array, leaving it empty. The
66 XS equivalent of "@array = ()". See also "av_undef".
67 Note that it is possible that the actions of a destructor
69 called directly or indirectly by freeing an element of the
70 array could cause the reference count of the array itself to be
71 reduced (e.g. by deleting an entry in the symbol table). So it
72 is a possibility that the AV could have been freed (or even
73 reallocated) on return from the call unless you hold a
74 reference to it.
75 void av_clear(AV *av)
77 av_create_and_push
79 NOTE: this function is experimental and may change or be
80 removed without notice.
81 Push an SV onto the end of the array, creating the array if
83 necessary. A small internal helper function to remove a
84 commonly duplicated idiom.
85 NOTE: this function must be explicitly called as
87 Perl_av_create_and_push with an aTHX_ parameter.
88 void Perl_av_create_and_push(pTHX_ AV **const avp,
90 SV *const val)
91 av_create_and_unshift_one
93 NOTE: this function is experimental and may change or be
94 removed without notice.
95 Unshifts an SV onto the beginning of the array, creating the
97 array if necessary. A small internal helper function to remove
98 a commonly duplicated idiom.
99 NOTE: this function must be explicitly called as
101 Perl_av_create_and_unshift_one with an aTHX_ parameter.
102 SV** Perl_av_create_and_unshift_one(pTHX_
104 AV **const avp,
105 SV *const val)
106 av_delete
108 Deletes the element indexed by "key" from the array, makes the
109 element mortal, and returns it. If "flags" equals "G_DISCARD",
110 the element is freed and NULL is returned. NULL is also
111 returned if "key" is out of range.
112 Perl equivalent: "splice(@myarray, $key, 1, undef)" (with the
114 "splice" in void context if "G_DISCARD" is present).
115 SV* av_delete(AV *av, SSize_t key, I32 flags)
117 av_exists
119 Returns true if the element indexed by "key" has been
120 initialized.
121 This relies on the fact that uninitialized array elements are
123 set to "NULL".
124 Perl equivalent: "exists($myarray[$key])".
126 bool av_exists(AV *av, SSize_t key)
128 av_extend
130 Pre-extend an array so that it is capable of storing values at
131 indexes "0..key". Thus "av_extend(av,99)" guarantees that the
132 array can store 100 elements, i.e. that "av_store(av, 0, sv)"
133 through "av_store(av, 99, sv)" on a plain array will work
134 without any further memory allocation.
135 If the av argument is a tied array then will call the "EXTEND"
137 tied array method with an argument of "(key+1)".
138 void av_extend(AV *av, SSize_t key)
140 av_fetch
142 Returns the SV at the specified index in the array. The "key"
143 is the index. If lval is true, you are guaranteed to get a
144 real SV back (in case it wasn't real before), which you can
145 then modify. Check that the return value is non-null before
146 dereferencing it to a "SV*".
147 See "Understanding the Magic of Tied Hashes and Arrays" in
149 perlguts for more information on how to use this function on
150 tied arrays.
151 The rough perl equivalent is $myarray[$key].
153 SV** av_fetch(AV *av, SSize_t key, I32 lval)
155 AvFILL Same as "av_top_index()" or "av_tindex()".
157 int AvFILL(AV* av)
159 av_fill Set the highest index in the array to the given number,
161 equivalent to Perl's "$#array = $fill;".
162 The number of elements in the array will be "fill + 1" after
164 "av_fill()" returns. If the array was previously shorter, then
165 the additional elements appended are set to NULL. If the array
166 was longer, then the excess elements are freed.
167 "av_fill(av, -1)" is the same as "av_clear(av)".
168 void av_fill(AV *av, SSize_t fill)
170 av_len Same as "av_top_index". Note that, unlike what the name
172 implies, it returns the highest index in the array. This is
173 unlike "sv_len", which returns what you would expect.
174 To get the true number of elements in the array, instead use
176 "av_count".
177 SSize_t av_len(AV *av)
179 av_make Creates a new AV and populates it with a list of SVs. The SVs
181 are copied into the array, so they may be freed after the call
182 to "av_make". The new AV will have a reference count of 1.
183 Perl equivalent: "my @new_array = ($scalar1, $scalar2,
185 $scalar3...);"
186 AV* av_make(SSize_t size, SV **strp)
188 av_pop Removes one SV from the end of the array, reducing its size by
190 one and returning the SV (transferring control of one reference
191 count) to the caller. Returns &PL_sv_undef if the array is
192 empty.
193 Perl equivalent: "pop(@myarray);"
195 SV* av_pop(AV *av)
197 av_push Pushes an SV (transferring control of one reference count) onto
199 the end of the array. The array will grow automatically to
200 accommodate the addition.
201 Perl equivalent: "push @myarray, $val;".
203 void av_push(AV *av, SV *val)
205 av_shift
207 Removes one SV from the start of the array, reducing its size
208 by one and returning the SV (transferring control of one
209 reference count) to the caller. Returns &PL_sv_undef if the
210 array is empty.
211 Perl equivalent: "shift(@myarray);"
213 SV* av_shift(AV *av)
215 av_store
217 Stores an SV in an array. The array index is specified as
218 "key". The return value will be "NULL" if the operation failed
219 or if the value did not need to be actually stored within the
220 array (as in the case of tied arrays). Otherwise, it can be
221 dereferenced to get the "SV*" that was stored there (= "val")).
222 Note that the caller is responsible for suitably incrementing
224 the reference count of "val" before the call, and decrementing
225 it if the function returned "NULL".
226 Approximate Perl equivalent: "splice(@myarray, $key, 1, $val)".
228 See "Understanding the Magic of Tied Hashes and Arrays" in
230 perlguts for more information on how to use this function on
231 tied arrays.
232 SV** av_store(AV *av, SSize_t key, SV *val)
234 av_tindex
236 Same as "av_top_index()".
237 SSize_t av_tindex(AV *av)
239 av_top_index
241 Returns the highest index in the array. The number of elements
242 in the array is "av_top_index(av) + 1". Returns -1 if the
243 array is empty.
244 The Perl equivalent for this is $#myarray.
246 (A slightly shorter form is "av_tindex".)
248 SSize_t av_top_index(AV *av)
250 av_undef
252 Undefines the array. The XS equivalent of "undef(@array)".
253 As well as freeing all the elements of the array (like
255 "av_clear()"), this also frees the memory used by the av to
256 store its list of scalars.
257 See "av_clear" for a note about the array possibly being
259 invalid on return.
260 void av_undef(AV *av)
262 av_unshift
264 Unshift the given number of "undef" values onto the beginning
265 of the array. The array will grow automatically to accommodate
266 the addition.
267 Perl equivalent: "unshift @myarray, ((undef) x $num);"
269 void av_unshift(AV *av, SSize_t num)
271 get_av Returns the AV of the specified Perl global or package array
273 with the given name (so it won't work on lexical variables).
274 "flags" are passed to "gv_fetchpv". If "GV_ADD" is set and the
275 Perl variable does not exist then it will be created. If
276 "flags" is zero and the variable does not exist then NULL is
277 returned.
278 Perl equivalent: "@{"$name"}".
280 NOTE: the perl_ form of this function is deprecated.
282 AV* get_av(const char *name, I32 flags)
284 newAV Creates a new AV. The reference count is set to 1.
286 Perl equivalent: "my @array;".
288 AV* newAV()
290 sortsv In-place sort an array of SV pointers with the given comparison
292 routine.
293 Currently this always uses mergesort. See "sortsv_flags" for a
295 more flexible routine.
296 void sortsv(SV** array, size_t num_elts,
298 SVCOMPARE_t cmp)
299
301 call_argv
302 Performs a callback to the specified named and package-scoped
303 Perl subroutine with "argv" (a "NULL"-terminated array of
304 strings) as arguments. See perlcall.
305 Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
307 NOTE: the perl_ form of this function is deprecated.
309 I32 call_argv(const char* sub_name, I32 flags,
311 char** argv)
312 call_method
314 Performs a callback to the specified Perl method. The blessed
315 object must be on the stack. See perlcall.
316 NOTE: the perl_ form of this function is deprecated.
318 I32 call_method(const char* methname, I32 flags)
320 call_pv Performs a callback to the specified Perl sub. See perlcall.
322 NOTE: the perl_ form of this function is deprecated.
324 I32 call_pv(const char* sub_name, I32 flags)
326 call_sv Performs a callback to the Perl sub specified by the SV.
328 If neither the "G_METHOD" nor "G_METHOD_NAMED" flag is
330 supplied, the SV may be any of a CV, a GV, a reference to a CV,
331 a reference to a GV or "SvPV(sv)" will be used as the name of
332 the sub to call.
333 If the "G_METHOD" flag is supplied, the SV may be a reference
335 to a CV or "SvPV(sv)" will be used as the name of the method to
336 call.
337 If the "G_METHOD_NAMED" flag is supplied, "SvPV(sv)" will be
339 used as the name of the method to call.
340 Some other values are treated specially for internal use and
342 should not be depended on.
343 See perlcall.
345 NOTE: the perl_ form of this function is deprecated.
347 I32 call_sv(SV* sv, volatile I32 flags)
349 ENTER Opening bracket on a callback. See "LEAVE" and perlcall.
351 ENTER;
353 ENTER_with_name
355 Same as "ENTER", but when debugging is enabled it also
356 associates the given literal string with the new scope.
357 ENTER_with_name("name");
359 eval_pv Tells Perl to "eval" the given string in scalar context and
361 return an SV* result.
362 NOTE: the perl_ form of this function is deprecated.
364 SV* eval_pv(const char* p, I32 croak_on_error)
366 eval_sv Tells Perl to "eval" the string in the SV. It supports the
368 same flags as "call_sv", with the obvious exception of
369 "G_EVAL". See perlcall.
370 The "G_RETHROW" flag can be used if you only need eval_sv() to
372 execute code specified by a string, but not catch any errors.
373 NOTE: the perl_ form of this function is deprecated.
375 I32 eval_sv(SV* sv, I32 flags)
377 FREETMPS
379 Closing bracket for temporaries on a callback. See "SAVETMPS"
380 and perlcall.
381 FREETMPS;
383 LEAVE Closing bracket on a callback. See "ENTER" and perlcall.
385 LEAVE;
387 LEAVE_with_name
389 Same as "LEAVE", but when debugging is enabled it first checks
390 that the scope has the given name. "name" must be a literal
391 string.
392 LEAVE_with_name("name");
394 SAVETMPS
396 Opening bracket for temporaries on a callback. See "FREETMPS"
397 and perlcall.
398 SAVETMPS;
400
402 Perl uses "full" Unicode case mappings. This means that converting a
403 single character to another case may result in a sequence of more than
404 one character. For example, the uppercase of "ss" (LATIN SMALL LETTER
405 SHARP S) is the two character sequence "SS". This presents some
406 complications The lowercase of all characters in the range 0..255 is
407 a single character, and thus "toLOWER_L1" is furnished. But,
408 "toUPPER_L1" can't exist, as it couldn't return a valid result for all
409 legal inputs. Instead "toUPPER_uvchr" has an API that does allow every
410 possible legal result to be returned.) Likewise no other function that
411 is crippled by not being able to give the correct results for the full
412 range of possible inputs has been implemented here.
413 toFOLD Converts the specified character to foldcase. If the input is
415 anything but an ASCII uppercase character, that input character
416 itself is returned. Variant "toFOLD_A" is equivalent. (There
417 is no equivalent "to_FOLD_L1" for the full Latin1 range, as the
418 full generality of "toFOLD_uvchr" is needed there.)
419 U8 toFOLD(U8 ch)
421 toFOLD_utf8
423 Converts the first UTF-8 encoded character in the sequence
424 starting at "p" and extending no further than "e - 1" to its
425 foldcase version, and stores that in UTF-8 in "s", and its
426 length in bytes in "lenp". Note that the buffer pointed to by
427 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
428 foldcase version may be longer than the original character.
429 The first code point of the foldcased version is returned (but
431 note, as explained at the top of this section, that there may
432 be more).
433 It will not attempt to read beyond "e - 1", provided that the
435 constraint "s < e" is true (this is asserted for in
436 "-DDEBUGGING" builds). If the UTF-8 for the input character is
437 malformed in some way, the program may croak, or the function
438 may return the REPLACEMENT CHARACTER, at the discretion of the
439 implementation, and subject to change in future releases.
440 UV toFOLD_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
442 toFOLD_utf8_safe
444 Same as "toFOLD_utf8".
445 UV toFOLD_utf8_safe(U8* p, U8* e, U8* s,
447 STRLEN* lenp)
448 toFOLD_uvchr
450 Converts the code point "cp" to its foldcase version, and
451 stores that in UTF-8 in "s", and its length in bytes in "lenp".
452 The code point is interpreted as native if less than 256;
453 otherwise as Unicode. Note that the buffer pointed to by "s"
454 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
455 foldcase version may be longer than the original character.
456 The first code point of the foldcased version is returned (but
458 note, as explained at the top of this section, that there may
459 be more).
460 UV toFOLD_uvchr(UV cp, U8* s, STRLEN* lenp)
462 toLOWER Converts the specified character to lowercase. If the input is
464 anything but an ASCII uppercase character, that input character
465 itself is returned. Variant "toLOWER_A" is equivalent.
466 U8 toLOWER(U8 ch)
468 toLOWER_L1
470 Converts the specified Latin1 character to lowercase. The
471 results are undefined if the input doesn't fit in a byte.
472 U8 toLOWER_L1(U8 ch)
474 toLOWER_LC
476 Converts the specified character to lowercase using the current
477 locale's rules, if possible; otherwise returns the input
478 character itself.
479 U8 toLOWER_LC(U8 ch)
481 toLOWER_utf8
483 Converts the first UTF-8 encoded character in the sequence
484 starting at "p" and extending no further than "e - 1" to its
485 lowercase version, and stores that in UTF-8 in "s", and its
486 length in bytes in "lenp". Note that the buffer pointed to by
487 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
488 lowercase version may be longer than the original character.
489 The first code point of the lowercased version is returned (but
491 note, as explained at the top of this section, that there may
492 be more). It will not attempt to read beyond "e - 1", provided
493 that the constraint "s < e" is true (this is asserted for in
494 "-DDEBUGGING" builds). If the UTF-8 for the input character is
495 malformed in some way, the program may croak, or the function
496 may return the REPLACEMENT CHARACTER, at the discretion of the
497 implementation, and subject to change in future releases.
498 UV toLOWER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
500 toLOWER_utf8_safe
502 Same as "toLOWER_utf8".
503 UV toLOWER_utf8_safe(U8* p, U8* e, U8* s,
505 STRLEN* lenp)
506 toLOWER_uvchr
508 Converts the code point "cp" to its lowercase version, and
509 stores that in UTF-8 in "s", and its length in bytes in "lenp".
510 The code point is interpreted as native if less than 256;
511 otherwise as Unicode. Note that the buffer pointed to by "s"
512 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
513 lowercase version may be longer than the original character.
514 The first code point of the lowercased version is returned (but
516 note, as explained at the top of this section, that there may
517 be more).
518 UV toLOWER_uvchr(UV cp, U8* s, STRLEN* lenp)
520 toTITLE Converts the specified character to titlecase. If the input is
522 anything but an ASCII lowercase character, that input character
523 itself is returned. Variant "toTITLE_A" is equivalent. (There
524 is no "toTITLE_L1" for the full Latin1 range, as the full
525 generality of "toTITLE_uvchr" is needed there. Titlecase is
526 not a concept used in locale handling, so there is no
527 functionality for that.)
528 U8 toTITLE(U8 ch)
530 toTITLE_utf8
532 Converts the first UTF-8 encoded character in the sequence
533 starting at "p" and extending no further than "e - 1" to its
534 titlecase version, and stores that in UTF-8 in "s", and its
535 length in bytes in "lenp". Note that the buffer pointed to by
536 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
537 titlecase version may be longer than the original character.
538 The first code point of the titlecased version is returned (but
540 note, as explained at the top of this section, that there may
541 be more).
542 It will not attempt to read beyond "e - 1", provided that the
544 constraint "s < e" is true (this is asserted for in
545 "-DDEBUGGING" builds). If the UTF-8 for the input character is
546 malformed in some way, the program may croak, or the function
547 may return the REPLACEMENT CHARACTER, at the discretion of the
548 implementation, and subject to change in future releases.
549 UV toTITLE_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
551 toTITLE_utf8_safe
553 Same as "toTITLE_utf8".
554 UV toTITLE_utf8_safe(U8* p, U8* e, U8* s,
556 STRLEN* lenp)
557 toTITLE_uvchr
559 Converts the code point "cp" to its titlecase version, and
560 stores that in UTF-8 in "s", and its length in bytes in "lenp".
561 The code point is interpreted as native if less than 256;
562 otherwise as Unicode. Note that the buffer pointed to by "s"
563 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
564 titlecase version may be longer than the original character.
565 The first code point of the titlecased version is returned (but
567 note, as explained at the top of this section, that there may
568 be more).
569 UV toTITLE_uvchr(UV cp, U8* s, STRLEN* lenp)
571 toUPPER Converts the specified character to uppercase. If the input is
573 anything but an ASCII lowercase character, that input character
574 itself is returned. Variant "toUPPER_A" is equivalent.
575 U8 toUPPER(int ch)
577 toUPPER_utf8
579 Converts the first UTF-8 encoded character in the sequence
580 starting at "p" and extending no further than "e - 1" to its
581 uppercase version, and stores that in UTF-8 in "s", and its
582 length in bytes in "lenp". Note that the buffer pointed to by
583 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
584 uppercase version may be longer than the original character.
585 The first code point of the uppercased version is returned (but
587 note, as explained at the top of this section, that there may
588 be more).
589 It will not attempt to read beyond "e - 1", provided that the
591 constraint "s < e" is true (this is asserted for in
592 "-DDEBUGGING" builds). If the UTF-8 for the input character is
593 malformed in some way, the program may croak, or the function
594 may return the REPLACEMENT CHARACTER, at the discretion of the
595 implementation, and subject to change in future releases.
596 UV toUPPER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
598 toUPPER_utf8_safe
600 Same as "toUPPER_utf8".
601 UV toUPPER_utf8_safe(U8* p, U8* e, U8* s,
603 STRLEN* lenp)
604 toUPPER_uvchr
606 Converts the code point "cp" to its uppercase version, and
607 stores that in UTF-8 in "s", and its length in bytes in "lenp".
608 The code point is interpreted as native if less than 256;
609 otherwise as Unicode. Note that the buffer pointed to by "s"
610 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
611 uppercase version may be longer than the original character.
612 The first code point of the uppercased version is returned (but
614 note, as explained at the top of this section, that there may
615 be more.)
616 UV toUPPER_uvchr(UV cp, U8* s, STRLEN* lenp)
618 WIDEST_UTYPE
620 Yields the widest unsigned integer type on the platform,
621 currently either "U32" or 64. This can be used in declarations
622 such as
623 WIDEST_UTYPE my_uv;
625 or casts
627 my_uv = (WIDEST_UTYPE) val;
629
631 This section is about functions (really macros) that classify
632 characters into types, such as punctuation versus alphabetic, etc.
633 Most of these are analogous to regular expression character classes.
634 (See "POSIX Character Classes" in perlrecharclass.) There are several
635 variants for each class. (Not all macros have all variants; each item
636 below lists the ones valid for it.) None are affected by "use bytes",
637 and only the ones with "LC" in the name are affected by the current
638 locale.
639 The base function, e.g., "isALPHA()", takes any signed or unsigned
641 value, treating it as a code point, and returns a boolean as to whether
642 or not the character represented by it is (or on non-ASCII platforms,
643 corresponds to) an ASCII character in the named class based on
644 platform, Unicode, and Perl rules. If the input is a number that
645 doesn't fit in an octet, FALSE is returned.
646 Variant "isFOO_A" (e.g., "isALPHA_A()") is identical to the base
648 function with no suffix "_A". This variant is used to emphasize by its
649 name that only ASCII-range characters can return TRUE.
650 Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivalent) character
652 set onto the platform. That is, the code points that are ASCII are
653 unaffected, since ASCII is a subset of Latin-1. But the non-ASCII code
654 points are treated as if they are Latin-1 characters. For example,
655 "isWORDCHAR_L1()" will return true when called with the code point
656 0xDF, which is a word character in both ASCII and EBCDIC (though it
657 represents different characters in each). If the input is a number
658 that doesn't fit in an octet, FALSE is returned. (Perl's documentation
659 uses a colloquial definition of Latin-1, to include all code points
660 below 256.)
661 Variant "isFOO_uvchr" is exactly like the "isFOO_L1" variant, for
663 inputs below 256, but if the code point is larger than 255, Unicode
664 rules are used to determine if it is in the character class. For
665 example, "isWORDCHAR_uvchr(0x100)" returns TRUE, since 0x100 is LATIN
666 CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.
667 Variants "isFOO_utf8" and "isFOO_utf8_safe" are like "isFOO_uvchr", but
669 are used for UTF-8 encoded strings. The two forms are different names
670 for the same thing. Each call to one of these classifies the first
671 character of the string starting at "p". The second parameter, "e",
672 points to anywhere in the string beyond the first character, up to one
673 byte past the end of the entire string. Although both variants are
674 identical, the suffix "_safe" in one name emphasizes that it will not
675 attempt to read beyond "e - 1", provided that the constraint "s < e" is
676 true (this is asserted for in "-DDEBUGGING" builds). If the UTF-8 for
677 the input character is malformed in some way, the program may croak, or
678 the function may return FALSE, at the discretion of the implementation,
679 and subject to change in future releases.
680 Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but
682 the result is based on the current locale, which is what "LC" in the
683 name stands for. If Perl can determine that the current locale is a
684 UTF-8 locale, it uses the published Unicode rules; otherwise, it uses
685 the C library function that gives the named classification. For
686 example, "isDIGIT_LC()" when not in a UTF-8 locale returns the result
687 of calling "isdigit()". FALSE is always returned if the input won't
688 fit into an octet. On some platforms where the C library function is
689 known to be defective, Perl changes its result to follow the POSIX
690 standard's rules.
691 Variant "isFOO_LC_uvchr" acts exactly like "isFOO_LC" for inputs less
693 than 256, but for larger ones it returns the Unicode classification of
694 the code point.
695 Variants "isFOO_LC_utf8" and "isFOO_LC_utf8_safe" are like
697 "isFOO_LC_uvchr", but are used for UTF-8 encoded strings. The two
698 forms are different names for the same thing. Each call to one of
699 these classifies the first character of the string starting at "p".
700 The second parameter, "e", points to anywhere in the string beyond the
701 first character, up to one byte past the end of the entire string.
702 Although both variants are identical, the suffix "_safe" in one name
703 emphasizes that it will not attempt to read beyond "e - 1", provided
704 that the constraint "s < e" is true (this is asserted for in
705 "-DDEBUGGING" builds). If the UTF-8 for the input character is
706 malformed in some way, the program may croak, or the function may
707 return FALSE, at the discretion of the implementation, and subject to
708 change in future releases.
709 isALPHA Returns a boolean indicating whether the specified input is one
711 of "[A-Za-z]", analogous to "m/[[:alpha:]]/". See the top of
712 this section for an explanation of variants "isALPHA_A",
713 "isALPHA_L1", "isALPHA_uvchr", "isALPHA_utf8",
714 "isALPHA_utf8_safe", "isALPHA_LC", "isALPHA_LC_uvchr",
715 "isALPHA_LC_utf8", and "isALPHA_LC_utf8_safe".
716 bool isALPHA(int ch)
718 isALPHANUMERIC
720 Returns a boolean indicating whether the specified character is
721 one of "[A-Za-z0-9]", analogous to "m/[[:alnum:]]/". See the
722 top of this section for an explanation of variants
723 "isALPHANUMERIC_A", "isALPHANUMERIC_L1",
724 "isALPHANUMERIC_uvchr", "isALPHANUMERIC_utf8",
725 "isALPHANUMERIC_utf8_safe", "isALPHANUMERIC_LC",
726 "isALPHANUMERIC_LC_uvchr", "isALPHANUMERIC_LC_utf8", and
727 "isALPHANUMERIC_LC_utf8_safe".
728 A (discouraged from use) synonym is "isALNUMC" (where the "C"
730 suffix means this corresponds to the C language alphanumeric
731 definition). Also there are the variants "isALNUMC_A",
732 "isALNUMC_L1" "isALNUMC_LC", and "isALNUMC_LC_uvchr".
733 bool isALPHANUMERIC(int ch)
735 isASCII Returns a boolean indicating whether the specified character is
737 one of the 128 characters in the ASCII character set, analogous
738 to "m/[[:ascii:]]/". On non-ASCII platforms, it returns TRUE
739 iff this character corresponds to an ASCII character. Variants
740 "isASCII_A()" and "isASCII_L1()" are identical to "isASCII()".
741 See the top of this section for an explanation of variants
742 "isASCII_uvchr", "isASCII_utf8", "isASCII_utf8_safe",
743 "isASCII_LC", "isASCII_LC_uvchr", "isASCII_LC_utf8", and
744 "isASCII_LC_utf8_safe". Note, however, that some platforms do
745 not have the C library routine "isascii()". In these cases,
746 the variants whose names contain "LC" are the same as the
747 corresponding ones without.
748 bool isASCII(int ch)
750 isBLANK Returns a boolean indicating whether the specified character is
752 a character considered to be a blank, analogous to
753 "m/[[:blank:]]/". See the top of this section for an
754 explanation of variants "isBLANK_A", "isBLANK_L1",
755 "isBLANK_uvchr", "isBLANK_utf8", "isBLANK_utf8_safe",
756 "isBLANK_LC", "isBLANK_LC_uvchr", "isBLANK_LC_utf8", and
757 "isBLANK_LC_utf8_safe". Note, however, that some platforms do
758 not have the C library routine "isblank()". In these cases,
759 the variants whose names contain "LC" are the same as the
760 corresponding ones without.
761 bool isBLANK(char ch)
763 isCNTRL Returns a boolean indicating whether the specified character is
765 a control character, analogous to "m/[[:cntrl:]]/". See the
766 top of this section for an explanation of variants "isCNTRL_A",
767 "isCNTRL_L1", "isCNTRL_uvchr", "isCNTRL_utf8",
768 "isCNTRL_utf8_safe", "isCNTRL_LC", "isCNTRL_LC_uvchr",
769 "isCNTRL_LC_utf8" and "isCNTRL_LC_utf8_safe". On EBCDIC
770 platforms, you almost always want to use the "isCNTRL_L1"
771 variant.
772 bool isCNTRL(char ch)
774 isDIGIT Returns a boolean indicating whether the specified character is
776 a digit, analogous to "m/[[:digit:]]/". Variants "isDIGIT_A"
777 and "isDIGIT_L1" are identical to "isDIGIT". See the top of
778 this section for an explanation of variants "isDIGIT_uvchr",
779 "isDIGIT_utf8", "isDIGIT_utf8_safe", "isDIGIT_LC",
780 "isDIGIT_LC_uvchr", "isDIGIT_LC_utf8", and
781 "isDIGIT_LC_utf8_safe".
782 bool isDIGIT(char ch)
784 isGRAPH Returns a boolean indicating whether the specified character is
786 a graphic character, analogous to "m/[[:graph:]]/". See the
787 top of this section for an explanation of variants "isGRAPH_A",
788 "isGRAPH_L1", "isGRAPH_uvchr", "isGRAPH_utf8",
789 "isGRAPH_utf8_safe", "isGRAPH_LC", "isGRAPH_LC_uvchr",
790 "isGRAPH_LC_utf8_safe", and "isGRAPH_LC_utf8_safe".
791 bool isGRAPH(char ch)
793 isIDCONT
795 Returns a boolean indicating whether the specified character
796 can be the second or succeeding character of an identifier.
797 This is very close to, but not quite the same as the official
798 Unicode property "XID_Continue". The difference is that this
799 returns true only if the input character also matches
800 "isWORDCHAR". See the top of this section for an explanation
801 of variants "isIDCONT_A", "isIDCONT_L1", "isIDCONT_uvchr",
802 "isIDCONT_utf8", "isIDCONT_utf8_safe", "isIDCONT_LC",
803 "isIDCONT_LC_uvchr", "isIDCONT_LC_utf8", and
804 "isIDCONT_LC_utf8_safe".
805 bool isIDCONT(char ch)
807 isIDFIRST
809 Returns a boolean indicating whether the specified character
810 can be the first character of an identifier. This is very
811 close to, but not quite the same as the official Unicode
812 property "XID_Start". The difference is that this returns true
813 only if the input character also matches "isWORDCHAR". See the
814 top of this section for an explanation of variants
815 "isIDFIRST_A", "isIDFIRST_L1", "isIDFIRST_uvchr",
816 "isIDFIRST_utf8", "isIDFIRST_utf8_safe", "isIDFIRST_LC",
817 "isIDFIRST_LC_uvchr", "isIDFIRST_LC_utf8", and
818 "isIDFIRST_LC_utf8_safe".
819 bool isIDFIRST(char ch)
821 isLOWER Returns a boolean indicating whether the specified character is
823 a lowercase character, analogous to "m/[[:lower:]]/". See the
824 top of this section for an explanation of variants "isLOWER_A",
825 "isLOWER_L1", "isLOWER_uvchr", "isLOWER_utf8",
826 "isLOWER_utf8_safe", "isLOWER_LC", "isLOWER_LC_uvchr",
827 "isLOWER_LC_utf8", and "isLOWER_LC_utf8_safe".
828 bool isLOWER(char ch)
830 isOCTAL Returns a boolean indicating whether the specified character is
832 an octal digit, [0-7]. The only two variants are "isOCTAL_A"
833 and "isOCTAL_L1"; each is identical to "isOCTAL".
834 bool isOCTAL(char ch)
836 isPRINT Returns a boolean indicating whether the specified character is
838 a printable character, analogous to "m/[[:print:]]/". See the
839 top of this section for an explanation of variants "isPRINT_A",
840 "isPRINT_L1", "isPRINT_uvchr", "isPRINT_utf8",
841 "isPRINT_utf8_safe", "isPRINT_LC", "isPRINT_LC_uvchr",
842 "isPRINT_LC_utf8", and "isPRINT_LC_utf8_safe".
843 bool isPRINT(char ch)
845 isPSXSPC
847 (short for Posix Space) Starting in 5.18, this is identical in
848 all its forms to the corresponding "isSPACE()" macros. The
849 locale forms of this macro are identical to their corresponding
850 "isSPACE()" forms in all Perl releases. In releases prior to
851 5.18, the non-locale forms differ from their "isSPACE()" forms
852 only in that the "isSPACE()" forms don't match a Vertical Tab,
853 and the "isPSXSPC()" forms do. Otherwise they are identical.
854 Thus this macro is analogous to what "m/[[:space:]]/" matches
855 in a regular expression. See the top of this section for an
856 explanation of variants "isPSXSPC_A", "isPSXSPC_L1",
857 "isPSXSPC_uvchr", "isPSXSPC_utf8", "isPSXSPC_utf8_safe",
858 "isPSXSPC_LC", "isPSXSPC_LC_uvchr", "isPSXSPC_LC_utf8", and
859 "isPSXSPC_LC_utf8_safe".
860 bool isPSXSPC(char ch)
862 isPUNCT Returns a boolean indicating whether the specified character is
864 a punctuation character, analogous to "m/[[:punct:]]/". Note
865 that the definition of what is punctuation isn't as
866 straightforward as one might desire. See "POSIX Character
867 Classes" in perlrecharclass for details. See the top of this
868 section for an explanation of variants "isPUNCT_A",
869 "isPUNCT_L1", "isPUNCT_uvchr", "isPUNCT_utf8",
870 "isPUNCT_utf8_safe", "isPUNCT_LC", "isPUNCT_LC_uvchr",
871 "isPUNCT_LC_utf8", and "isPUNCT_LC_utf8_safe".
872 bool isPUNCT(char ch)
874 isSPACE Returns a boolean indicating whether the specified character is
876 a whitespace character. This is analogous to what "m/\s/"
877 matches in a regular expression. Starting in Perl 5.18 this
878 also matches what "m/[[:space:]]/" does. Prior to 5.18, only
879 the locale forms of this macro (the ones with "LC" in their
880 names) matched precisely what "m/[[:space:]]/" does. In those
881 releases, the only difference, in the non-locale variants, was
882 that "isSPACE()" did not match a vertical tab. (See "isPSXSPC"
883 for a macro that matches a vertical tab in all releases.) See
884 the top of this section for an explanation of variants
885 "isSPACE_A", "isSPACE_L1", "isSPACE_uvchr", "isSPACE_utf8",
886 "isSPACE_utf8_safe", "isSPACE_LC", "isSPACE_LC_uvchr",
887 "isSPACE_LC_utf8", and "isSPACE_LC_utf8_safe".
888 bool isSPACE(char ch)
890 isUPPER Returns a boolean indicating whether the specified character is
892 an uppercase character, analogous to "m/[[:upper:]]/". See the
893 top of this section for an explanation of variants "isUPPER_A",
894 "isUPPER_L1", "isUPPER_uvchr", "isUPPER_utf8",
895 "isUPPER_utf8_safe", "isUPPER_LC", "isUPPER_LC_uvchr",
896 "isUPPER_LC_utf8", and "isUPPER_LC_utf8_safe".
897 bool isUPPER(char ch)
899 isWORDCHAR
901 Returns a boolean indicating whether the specified character is
902 a character that is a word character, analogous to what "m/\w/"
903 and "m/[[:word:]]/" match in a regular expression. A word
904 character is an alphabetic character, a decimal digit, a
905 connecting punctuation character (such as an underscore), or a
906 "mark" character that attaches to one of those (like some sort
907 of accent). "isALNUM()" is a synonym provided for backward
908 compatibility, even though a word character includes more than
909 the standard C language meaning of alphanumeric. See the top
910 of this section for an explanation of variants "isWORDCHAR_A",
911 "isWORDCHAR_L1", "isWORDCHAR_uvchr", "isWORDCHAR_utf8", and
912 "isWORDCHAR_utf8_safe". "isWORDCHAR_LC",
913 "isWORDCHAR_LC_uvchr", "isWORDCHAR_LC_utf8", and
914 "isWORDCHAR_LC_utf8_safe" are also as described there, but
915 additionally include the platform's native underscore.
916 bool isWORDCHAR(char ch)
918 isXDIGIT
920 Returns a boolean indicating whether the specified character is
921 a hexadecimal digit. In the ASCII range these are
922 "[0-9A-Fa-f]". Variants "isXDIGIT_A()" and "isXDIGIT_L1()" are
923 identical to "isXDIGIT()". See the top of this section for an
924 explanation of variants "isXDIGIT_uvchr", "isXDIGIT_utf8",
925 "isXDIGIT_utf8_safe", "isXDIGIT_LC", "isXDIGIT_LC_uvchr",
926 "isXDIGIT_LC_utf8", and "isXDIGIT_LC_utf8_safe".
927 bool isXDIGIT(char ch)
929
931 perl_clone
932 Create and return a new interpreter by cloning the current one.
933 "perl_clone" takes these flags as parameters:
935 "CLONEf_COPY_STACKS" - is used to, well, copy the stacks also,
937 without it we only clone the data and zero the stacks, with it
938 we copy the stacks and the new perl interpreter is ready to run
939 at the exact same point as the previous one. The pseudo-fork
940 code uses "COPY_STACKS" while the threads->create doesn't.
941 "CLONEf_KEEP_PTR_TABLE" - "perl_clone" keeps a ptr_table with
943 the pointer of the old variable as a key and the new variable
944 as a value, this allows it to check if something has been
945 cloned and not clone it again, but rather just use the value
946 and increase the refcount. If "KEEP_PTR_TABLE" is not set then
947 "perl_clone" will kill the ptr_table using the function
948 "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;". A reason
949 to keep it around is if you want to dup some of your own
950 variables which are outside the graph that perl scans.
951 "CLONEf_CLONE_HOST" - This is a win32 thing, it is ignored on
953 unix, it tells perl's win32host code (which is c++) to clone
954 itself, this is needed on win32 if you want to run two threads
955 at the same time, if you just want to do some stuff in a
956 separate perl interpreter and then throw it away and return to
957 the original one, you don't need to do anything.
958 PerlInterpreter* perl_clone(
960 PerlInterpreter *proto_perl,
961 UV flags
962 )
963
965 BhkDISABLE
966 NOTE: this function is experimental and may change or be
967 removed without notice.
968 Temporarily disable an entry in this BHK structure, by clearing
970 the appropriate flag. "which" is a preprocessor token
971 indicating which entry to disable.
972 void BhkDISABLE(BHK *hk, which)
974 BhkENABLE
976 NOTE: this function is experimental and may change or be
977 removed without notice.
978 Re-enable an entry in this BHK structure, by setting the
980 appropriate flag. "which" is a preprocessor token indicating
981 which entry to enable. This will assert (under -DDEBUGGING) if
982 the entry doesn't contain a valid pointer.
983 void BhkENABLE(BHK *hk, which)
985 BhkENTRY_set
987 NOTE: this function is experimental and may change or be
988 removed without notice.
989 Set an entry in the BHK structure, and set the flags to
991 indicate it is valid. "which" is a preprocessing token
992 indicating which entry to set. The type of "ptr" depends on
993 the entry.
994 void BhkENTRY_set(BHK *hk, which, void *ptr)
996 blockhook_register
998 NOTE: this function is experimental and may change or be
999 removed without notice.
1000 Register a set of hooks to be called when the Perl lexical
1002 scope changes at compile time. See "Compile-time scope hooks"
1003 in perlguts.
1004 NOTE: this function must be explicitly called as
1006 Perl_blockhook_register with an aTHX_ parameter.
1007 void Perl_blockhook_register(pTHX_ BHK *hk)
1009
1011 cophh_2hv
1012 NOTE: this function is experimental and may change or be
1013 removed without notice.
1014 Generates and returns a standard Perl hash representing the
1016 full set of key/value pairs in the cop hints hash "cophh".
1017 "flags" is currently unused and must be zero.
1018 HV * cophh_2hv(const COPHH *cophh, U32 flags)
1020 cophh_copy
1022 NOTE: this function is experimental and may change or be
1023 removed without notice.
1024 Make and return a complete copy of the cop hints hash "cophh".
1026 COPHH * cophh_copy(COPHH *cophh)
1028 cophh_delete_pv
1030 NOTE: this function is experimental and may change or be
1031 removed without notice.
1032 Like "cophh_delete_pvn", but takes a nul-terminated string
1034 instead of a string/length pair.
1035 COPHH * cophh_delete_pv(const COPHH *cophh,
1037 const char *key, U32 hash,
1038 U32 flags)
1039 cophh_delete_pvn
1041 NOTE: this function is experimental and may change or be
1042 removed without notice.
1043 Delete a key and its associated value from the cop hints hash
1045 "cophh", and returns the modified hash. The returned hash
1046 pointer is in general not the same as the hash pointer that was
1047 passed in. The input hash is consumed by the function, and the
1048 pointer to it must not be subsequently used. Use "cophh_copy"
1049 if you need both hashes.
1050 The key is specified by "keypv" and "keylen". If "flags" has
1052 the "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1053 UTF-8, otherwise they are interpreted as Latin-1. "hash" is a
1054 precomputed hash of the key string, or zero if it has not been
1055 precomputed.
1056 COPHH * cophh_delete_pvn(COPHH *cophh,
1058 const char *keypv,
1059 STRLEN keylen, U32 hash,
1060 U32 flags)
1061 cophh_delete_pvs
1063 NOTE: this function is experimental and may change or be
1064 removed without notice.
1065 Like "cophh_delete_pvn", but takes a literal string instead of
1067 a string/length pair, and no precomputed hash.
1068 COPHH * cophh_delete_pvs(const COPHH *cophh, "key",
1070 U32 flags)
1071 cophh_delete_sv
1073 NOTE: this function is experimental and may change or be
1074 removed without notice.
1075 Like "cophh_delete_pvn", but takes a Perl scalar instead of a
1077 string/length pair.
1078 COPHH * cophh_delete_sv(const COPHH *cophh, SV *key,
1080 U32 hash, U32 flags)
1081 cophh_fetch_pv
1083 NOTE: this function is experimental and may change or be
1084 removed without notice.
1085 Like "cophh_fetch_pvn", but takes a nul-terminated string
1087 instead of a string/length pair.
1088 SV * cophh_fetch_pv(const COPHH *cophh,
1090 const char *key, U32 hash,
1091 U32 flags)
1092 cophh_fetch_pvn
1094 NOTE: this function is experimental and may change or be
1095 removed without notice.
1096 Look up the entry in the cop hints hash "cophh" with the key
1098 specified by "keypv" and "keylen". If "flags" has the
1099 "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1100 UTF-8, otherwise they are interpreted as Latin-1. "hash" is a
1101 precomputed hash of the key string, or zero if it has not been
1102 precomputed. Returns a mortal scalar copy of the value
1103 associated with the key, or &PL_sv_placeholder if there is no
1104 value associated with the key.
1105 SV * cophh_fetch_pvn(const COPHH *cophh,
1107 const char *keypv,
1108 STRLEN keylen, U32 hash,
1109 U32 flags)
1110 cophh_fetch_pvs
1112 NOTE: this function is experimental and may change or be
1113 removed without notice.
1114 Like "cophh_fetch_pvn", but takes a literal string instead of a
1116 string/length pair, and no precomputed hash.
1117 SV * cophh_fetch_pvs(const COPHH *cophh, "key",
1119 U32 flags)
1120 cophh_fetch_sv
1122 NOTE: this function is experimental and may change or be
1123 removed without notice.
1124 Like "cophh_fetch_pvn", but takes a Perl scalar instead of a
1126 string/length pair.
1127 SV * cophh_fetch_sv(const COPHH *cophh, SV *key,
1129 U32 hash, U32 flags)
1130 cophh_free
1132 NOTE: this function is experimental and may change or be
1133 removed without notice.
1134 Discard the cop hints hash "cophh", freeing all resources
1136 associated with it.
1137 void cophh_free(COPHH *cophh)
1139 cophh_new_empty
1141 NOTE: this function is experimental and may change or be
1142 removed without notice.
1143 Generate and return a fresh cop hints hash containing no
1145 entries.
1146 COPHH * cophh_new_empty()
1148 cophh_store_pv
1150 NOTE: this function is experimental and may change or be
1151 removed without notice.
1152 Like "cophh_store_pvn", but takes a nul-terminated string
1154 instead of a string/length pair.
1155 COPHH * cophh_store_pv(const COPHH *cophh,
1157 const char *key, U32 hash,
1158 SV *value, U32 flags)
1159 cophh_store_pvn
1161 NOTE: this function is experimental and may change or be
1162 removed without notice.
1163 Stores a value, associated with a key, in the cop hints hash
1165 "cophh", and returns the modified hash. The returned hash
1166 pointer is in general not the same as the hash pointer that was
1167 passed in. The input hash is consumed by the function, and the
1168 pointer to it must not be subsequently used. Use "cophh_copy"
1169 if you need both hashes.
1170 The key is specified by "keypv" and "keylen". If "flags" has
1172 the "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1173 UTF-8, otherwise they are interpreted as Latin-1. "hash" is a
1174 precomputed hash of the key string, or zero if it has not been
1175 precomputed.
1176 "value" is the scalar value to store for this key. "value" is
1178 copied by this function, which thus does not take ownership of
1179 any reference to it, and later changes to the scalar will not
1180 be reflected in the value visible in the cop hints hash.
1181 Complex types of scalar will not be stored with referential
1182 integrity, but will be coerced to strings.
1183 COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
1185 STRLEN keylen, U32 hash,
1186 SV *value, U32 flags)
1187 cophh_store_pvs
1189 NOTE: this function is experimental and may change or be
1190 removed without notice.
1191 Like "cophh_store_pvn", but takes a literal string instead of a
1193 string/length pair, and no precomputed hash.
1194 COPHH * cophh_store_pvs(const COPHH *cophh, "key",
1196 SV *value, U32 flags)
1197 cophh_store_sv
1199 NOTE: this function is experimental and may change or be
1200 removed without notice.
1201 Like "cophh_store_pvn", but takes a Perl scalar instead of a
1203 string/length pair.
1204 COPHH * cophh_store_sv(const COPHH *cophh, SV *key,
1206 U32 hash, SV *value, U32 flags)
1207
1209 cop_hints_2hv
1210 Generates and returns a standard Perl hash representing the
1211 full set of hint entries in the cop "cop". "flags" is
1212 currently unused and must be zero.
1213 HV * cop_hints_2hv(const COP *cop, U32 flags)
1215 cop_hints_fetch_pv
1217 Like "cop_hints_fetch_pvn", but takes a nul-terminated string
1218 instead of a string/length pair.
1219 SV * cop_hints_fetch_pv(const COP *cop,
1221 const char *key, U32 hash,
1222 U32 flags)
1223 cop_hints_fetch_pvn
1225 Look up the hint entry in the cop "cop" with the key specified
1226 by "keypv" and "keylen". If "flags" has the "COPHH_KEY_UTF8"
1227 bit set, the key octets are interpreted as UTF-8, otherwise
1228 they are interpreted as Latin-1. "hash" is a precomputed hash
1229 of the key string, or zero if it has not been precomputed.
1230 Returns a mortal scalar copy of the value associated with the
1231 key, or &PL_sv_placeholder if there is no value associated with
1232 the key.
1233 SV * cop_hints_fetch_pvn(const COP *cop,
1235 const char *keypv,
1236 STRLEN keylen, U32 hash,
1237 U32 flags)
1238 cop_hints_fetch_pvs
1240 Like "cop_hints_fetch_pvn", but takes a literal string instead
1241 of a string/length pair, and no precomputed hash.
1242 SV * cop_hints_fetch_pvs(const COP *cop, "key",
1244 U32 flags)
1245 cop_hints_fetch_sv
1247 Like "cop_hints_fetch_pvn", but takes a Perl scalar instead of
1248 a string/length pair.
1249 SV * cop_hints_fetch_sv(const COP *cop, SV *key,
1251 U32 hash, U32 flags)
1252 CopLABEL
1254 Returns the label attached to a cop.
1255 const char * CopLABEL(COP *const cop)
1257 CopLABEL_len
1259 Returns the label attached to a cop, and stores its length in
1260 bytes into *len.
1261 const char * CopLABEL_len(COP *const cop, STRLEN *len)
1263 CopLABEL_len_flags
1265 Returns the label attached to a cop, and stores its length in
1266 bytes into *len. Upon return, *flags will be set to either
1267 "SVf_UTF8" or 0.
1268 const char * CopLABEL_len_flags(COP *const cop,
1270 STRLEN *len, U32 *flags)
1271
1273 custom_op_register
1274 Register a custom op. See "Custom Operators" in perlguts.
1275 NOTE: this function must be explicitly called as
1277 Perl_custom_op_register with an aTHX_ parameter.
1278 void Perl_custom_op_register(pTHX_
1280 Perl_ppaddr_t ppaddr,
1281 const XOP *xop)
1282 Perl_custom_op_xop
1284 Return the XOP structure for a given custom op. This macro
1285 should be considered internal to "OP_NAME" and the other access
1286 macros: use them instead. This macro does call a function.
1287 Prior to 5.19.6, this was implemented as a function.
1288 const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
1290 XopDISABLE
1292 Temporarily disable a member of the XOP, by clearing the
1293 appropriate flag.
1294 void XopDISABLE(XOP *xop, which)
1296 XopENABLE
1298 Reenable a member of the XOP which has been disabled.
1299 void XopENABLE(XOP *xop, which)
1301 XopENTRY
1303 Return a member of the XOP structure. "which" is a cpp token
1304 indicating which entry to return. If the member is not set
1305 this will return a default value. The return type depends on
1306 "which". This macro evaluates its arguments more than once.
1307 If you are using "Perl_custom_op_xop" to retreive a "XOP *"
1308 from a "OP *", use the more efficient "XopENTRYCUSTOM" instead.
1309 XopENTRY(XOP *xop, which)
1311 XopENTRYCUSTOM
1313 Exactly like "XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o),
1314 which)" but more efficient. The "which" parameter is identical
1315 to "XopENTRY".
1316 XopENTRYCUSTOM(const OP *o, which)
1318 XopENTRY_set
1320 Set a member of the XOP structure. "which" is a cpp token
1321 indicating which entry to set. See "Custom Operators" in
1322 perlguts for details about the available members and how they
1323 are used. This macro evaluates its argument more than once.
1324 void XopENTRY_set(XOP *xop, which, value)
1326 XopFLAGS
1328 Return the XOP's flags.
1329 U32 XopFLAGS(XOP *xop)
1331
1333 This section documents functions to manipulate CVs which are code-
1334 values, or subroutines. For more information, see perlguts.
1335 caller_cx
1337 The XSUB-writer's equivalent of caller(). The returned
1338 "PERL_CONTEXT" structure can be interrogated to find all the
1339 information returned to Perl by "caller". Note that XSUBs
1340 don't get a stack frame, so "caller_cx(0, NULL)" will return
1341 information for the immediately-surrounding Perl code.
1342 This function skips over the automatic calls to &DB::sub made
1344 on the behalf of the debugger. If the stack frame requested
1345 was a sub called by "DB::sub", the return value will be the
1346 frame for the call to "DB::sub", since that has the correct
1347 line number/etc. for the call site. If dbcxp is non-"NULL", it
1348 will be set to a pointer to the frame for the sub call itself.
1349 const PERL_CONTEXT * caller_cx(
1351 I32 level,
1352 const PERL_CONTEXT **dbcxp
1353 )
1354 CvSTASH Returns the stash of the CV. A stash is the symbol table hash,
1356 containing the package-scoped variables in the package where
1357 the subroutine was defined. For more information, see
1358 perlguts.
1359 This also has a special use with XS AUTOLOAD subs. See
1361 "Autoloading with XSUBs" in perlguts.
1362 HV* CvSTASH(CV* cv)
1364 find_runcv
1366 Locate the CV corresponding to the currently executing sub or
1367 eval. If "db_seqp" is non_null, skip CVs that are in the DB
1368 package and populate *db_seqp with the cop sequence number at
1369 the point that the DB:: code was entered. (This allows
1370 debuggers to eval in the scope of the breakpoint rather than in
1371 the scope of the debugger itself.)
1372 CV* find_runcv(U32 *db_seqp)
1374 get_cv Uses "strlen" to get the length of "name", then calls
1376 "get_cvn_flags".
1377 NOTE: the perl_ form of this function is deprecated.
1379 CV* get_cv(const char* name, I32 flags)
1381 get_cvn_flags
1383 Returns the CV of the specified Perl subroutine. "flags" are
1384 passed to "gv_fetchpvn_flags". If "GV_ADD" is set and the Perl
1385 subroutine does not exist then it will be declared (which has
1386 the same effect as saying "sub name;"). If "GV_ADD" is not set
1387 and the subroutine does not exist then NULL is returned.
1388 CV* get_cvn_flags(const char* name, STRLEN len,
1390 I32 flags)
1391
1393 ax Variable which is setup by "xsubpp" to indicate the stack base
1394 offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros.
1395 The "dMARK" macro must be called prior to setup the "MARK"
1396 variable.
1397 I32 ax
1399 CLASS Variable which is setup by "xsubpp" to indicate the class name
1401 for a C++ XS constructor. This is always a "char*". See
1402 "THIS".
1403 char* CLASS
1405 dAX Sets up the "ax" variable. This is usually handled
1407 automatically by "xsubpp" by calling "dXSARGS".
1408 dAX;
1410 dAXMARK Sets up the "ax" variable and stack marker variable "mark".
1412 This is usually handled automatically by "xsubpp" by calling
1413 "dXSARGS".
1414 dAXMARK;
1416 dITEMS Sets up the "items" variable. This is usually handled
1418 automatically by "xsubpp" by calling "dXSARGS".
1419 dITEMS;
1421 dUNDERBAR
1423 Sets up any variable needed by the "UNDERBAR" macro. It used
1424 to define "padoff_du", but it is currently a noop. However, it
1425 is strongly advised to still use it for ensuring past and
1426 future compatibility.
1427 dUNDERBAR;
1429 dXSARGS Sets up stack and mark pointers for an XSUB, calling "dSP" and
1431 "dMARK". Sets up the "ax" and "items" variables by calling
1432 "dAX" and "dITEMS". This is usually handled automatically by
1433 "xsubpp".
1434 dXSARGS;
1436 dXSI32 Sets up the "ix" variable for an XSUB which has aliases. This
1438 is usually handled automatically by "xsubpp".
1439 dXSI32;
1441 items Variable which is setup by "xsubpp" to indicate the number of
1443 items on the stack. See "Variable-length Parameter Lists" in
1444 perlxs.
1445 I32 items
1447 ix Variable which is setup by "xsubpp" to indicate which of an
1449 XSUB's aliases was used to invoke it. See "The ALIAS: Keyword"
1450 in perlxs.
1451 I32 ix
1453 RETVAL Variable which is setup by "xsubpp" to hold the return value
1455 for an XSUB. This is always the proper type for the XSUB. See
1456 "The RETVAL Variable" in perlxs.
1457 (whatever) RETVAL
1459 ST Used to access elements on the XSUB's stack.
1461 SV* ST(int ix)
1463 THIS Variable which is setup by "xsubpp" to designate the object in
1465 a C++ XSUB. This is always the proper type for the C++ object.
1466 See "CLASS" and "Using XS With C++" in perlxs.
1467 (whatever) THIS
1469 UNDERBAR
1471 The SV* corresponding to the $_ variable. Works even if there
1472 is a lexical $_ in scope.
1473 XS Macro to declare an XSUB and its C parameter list. This is
1475 handled by "xsubpp". It is the same as using the more explicit
1476 "XS_EXTERNAL" macro.
1477 XS_EXTERNAL
1479 Macro to declare an XSUB and its C parameter list explicitly
1480 exporting the symbols.
1481 XS_INTERNAL
1483 Macro to declare an XSUB and its C parameter list without
1484 exporting the symbols. This is handled by "xsubpp" and
1485 generally preferable over exporting the XSUB symbols
1486 unnecessarily.
1487
1489 dump_all
1490 Dumps the entire optree of the current program starting at
1491 "PL_main_root" to "STDERR". Also dumps the optrees for all
1492 visible subroutines in "PL_defstash".
1493 void dump_all()
1495 dump_packsubs
1497 Dumps the optrees for all visible subroutines in "stash".
1498 void dump_packsubs(const HV* stash)
1500 op_class
1502 Given an op, determine what type of struct it has been
1503 allocated as. Returns one of the OPclass enums, such as
1504 OPclass_LISTOP.
1505 OPclass op_class(const OP *o)
1507 op_dump Dumps the optree starting at OP "o" to "STDERR".
1509 void op_dump(const OP *o)
1511 sv_dump Dumps the contents of an SV to the "STDERR" filehandle.
1513 For an example of its output, see Devel::Peek.
1515 void sv_dump(SV* sv)
1517
1519 pv_display
1520 Similar to
1521 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
1523 except that an additional "\0" will be appended to the string
1525 when len > cur and pv[cur] is "\0".
1526 Note that the final string may be up to 7 chars longer than
1528 pvlim.
1529 char* pv_display(SV *dsv, const char *pv, STRLEN cur,
1531 STRLEN len, STRLEN pvlim)
1532 pv_escape
1534 Escapes at most the first "count" chars of "pv" and puts the
1535 results into "dsv" such that the size of the escaped string
1536 will not exceed "max" chars and will not contain any incomplete
1537 escape sequences. The number of bytes escaped will be returned
1538 in the "STRLEN *escaped" parameter if it is not null. When the
1539 "dsv" parameter is null no escaping actually occurs, but the
1540 number of bytes that would be escaped were it not null will be
1541 calculated.
1542 If flags contains "PERL_PV_ESCAPE_QUOTE" then any double quotes
1544 in the string will also be escaped.
1545 Normally the SV will be cleared before the escaped string is
1547 prepared, but when "PERL_PV_ESCAPE_NOCLEAR" is set this will
1548 not occur.
1549 If "PERL_PV_ESCAPE_UNI" is set then the input string is treated
1551 as UTF-8 if "PERL_PV_ESCAPE_UNI_DETECT" is set then the input
1552 string is scanned using "is_utf8_string()" to determine if it
1553 is UTF-8.
1554 If "PERL_PV_ESCAPE_ALL" is set then all input chars will be
1556 output using "\x01F1" style escapes, otherwise if
1557 "PERL_PV_ESCAPE_NONASCII" is set, only non-ASCII chars will be
1558 escaped using this style; otherwise, only chars above 255 will
1559 be so escaped; other non printable chars will use octal or
1560 common escaped patterns like "\n". Otherwise, if
1561 "PERL_PV_ESCAPE_NOBACKSLASH" then all chars below 255 will be
1562 treated as printable and will be output as literals.
1563 If "PERL_PV_ESCAPE_FIRSTCHAR" is set then only the first char
1565 of the string will be escaped, regardless of max. If the
1566 output is to be in hex, then it will be returned as a plain hex
1567 sequence. Thus the output will either be a single char, an
1568 octal escape sequence, a special escape like "\n" or a hex
1569 value.
1570 If "PERL_PV_ESCAPE_RE" is set then the escape char used will be
1572 a "%" and not a "\\". This is because regexes very often
1573 contain backslashed sequences, whereas "%" is not a
1574 particularly common character in patterns.
1575 Returns a pointer to the escaped text as held by "dsv".
1577 char* pv_escape(SV *dsv, char const * const str,
1579 const STRLEN count, const STRLEN max,
1580 STRLEN * const escaped,
1581 const U32 flags)
1582 pv_pretty
1584 Converts a string into something presentable, handling escaping
1585 via "pv_escape()" and supporting quoting and ellipses.
1586 If the "PERL_PV_PRETTY_QUOTE" flag is set then the result will
1588 be double quoted with any double quotes in the string escaped.
1589 Otherwise if the "PERL_PV_PRETTY_LTGT" flag is set then the
1590 result be wrapped in angle brackets.
1591 If the "PERL_PV_PRETTY_ELLIPSES" flag is set and not all
1593 characters in string were output then an ellipsis "..." will be
1594 appended to the string. Note that this happens AFTER it has
1595 been quoted.
1596 If "start_color" is non-null then it will be inserted after the
1598 opening quote (if there is one) but before the escaped text.
1599 If "end_color" is non-null then it will be inserted after the
1600 escaped text but before any quotes or ellipses.
1601 Returns a pointer to the prettified text as held by "dsv".
1603 char* pv_pretty(SV *dsv, char const * const str,
1605 const STRLEN count, const STRLEN max,
1606 char const * const start_color,
1607 char const * const end_color,
1608 const U32 flags)
1609
1611 cv_clone
1612 Clone a CV, making a lexical closure. "proto" supplies the
1613 prototype of the function: its code, pad structure, and other
1614 attributes. The prototype is combined with a capture of outer
1615 lexicals to which the code refers, which are taken from the
1616 currently-executing instance of the immediately surrounding
1617 code.
1618 CV* cv_clone(CV* proto)
1620 cv_name Returns an SV containing the name of the CV, mainly for use in
1622 error reporting. The CV may actually be a GV instead, in which
1623 case the returned SV holds the GV's name. Anything other than
1624 a GV or CV is treated as a string already holding the sub name,
1625 but this could change in the future.
1626 An SV may be passed as a second argument. If so, the name will
1628 be assigned to it and it will be returned. Otherwise the
1629 returned SV will be a new mortal.
1630 If "flags" has the "CV_NAME_NOTQUAL" bit set, then the package
1632 name will not be included. If the first argument is neither a
1633 CV nor a GV, this flag is ignored (subject to change).
1634 SV * cv_name(CV *cv, SV *sv, U32 flags)
1636 cv_undef
1638 Clear out all the active components of a CV. This can happen
1639 either by an explicit "undef &foo", or by the reference count
1640 going to zero. In the former case, we keep the "CvOUTSIDE"
1641 pointer, so that any anonymous children can still follow the
1642 full lexical scope chain.
1643 void cv_undef(CV* cv)
1645 find_rundefsv
1647 Returns the global variable $_.
1648 SV* find_rundefsv()
1650 find_rundefsvoffset
1652 DEPRECATED! It is planned to remove this function from a
1653 future release of Perl. Do not use it for new code; remove it
1654 from existing code.
1655 Until the lexical $_ feature was removed, this function would
1657 find the position of the lexical $_ in the pad of the
1658 currently-executing function and return the offset in the
1659 current pad, or "NOT_IN_PAD".
1660 Now it always returns "NOT_IN_PAD".
1662 PADOFFSET find_rundefsvoffset()
1664 intro_my
1666 "Introduce" "my" variables to visible status. This is called
1667 during parsing at the end of each statement to make lexical
1668 variables visible to subsequent statements.
1669 U32 intro_my()
1671 load_module
1673 Loads the module whose name is pointed to by the string part of
1674 "name". Note that the actual module name, not its filename,
1675 should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver,
1676 if specified and not NULL, provides version semantics similar
1677 to "use Foo::Bar VERSION". The optional trailing arguments can
1678 be used to specify arguments to the module's "import()" method,
1679 similar to "use Foo::Bar VERSION LIST"; their precise handling
1680 depends on the flags. The flags argument is a bitwise-ORed
1681 collection of any of "PERL_LOADMOD_DENY",
1682 "PERL_LOADMOD_NOIMPORT", or "PERL_LOADMOD_IMPORT_OPS" (or 0 for
1683 no flags).
1684 If "PERL_LOADMOD_NOIMPORT" is set, the module is loaded as if
1686 with an empty import list, as in "use Foo::Bar ()"; this is the
1687 only circumstance in which the trailing optional arguments may
1688 be omitted entirely. Otherwise, if "PERL_LOADMOD_IMPORT_OPS" is
1689 set, the trailing arguments must consist of exactly one "OP*",
1690 containing the op tree that produces the relevant import
1691 arguments. Otherwise, the trailing arguments must all be "SV*"
1692 values that will be used as import arguments; and the list must
1693 be terminated with "(SV*) NULL". If neither
1694 "PERL_LOADMOD_NOIMPORT" nor "PERL_LOADMOD_IMPORT_OPS" is set,
1695 the trailing "NULL" pointer is needed even if no import
1696 arguments are desired. The reference count for each specified
1697 "SV*" argument is decremented. In addition, the "name" argument
1698 is modified.
1699 If "PERL_LOADMOD_DENY" is set, the module is loaded as if with
1701 "no" rather than "use".
1702 void load_module(U32 flags, SV* name, SV* ver, ...)
1704 my_exit A wrapper for the C library exit(3), honoring what
1706 "PL_exit_flags" in perlapi say to do.
1707 void my_exit(U32 status)
1709 newPADNAMELIST
1711 NOTE: this function is experimental and may change or be
1712 removed without notice.
1713 Creates a new pad name list. "max" is the highest index for
1715 which space is allocated.
1716 PADNAMELIST * newPADNAMELIST(size_t max)
1718 newPADNAMEouter
1720 NOTE: this function is experimental and may change or be
1721 removed without notice.
1722 Constructs and returns a new pad name. Only use this function
1724 for names that refer to outer lexicals. (See also
1725 "newPADNAMEpvn".) "outer" is the outer pad name that this one
1726 mirrors. The returned pad name has the "PADNAMEt_OUTER" flag
1727 already set.
1728 PADNAME * newPADNAMEouter(PADNAME *outer)
1730 newPADNAMEpvn
1732 NOTE: this function is experimental and may change or be
1733 removed without notice.
1734 Constructs and returns a new pad name. "s" must be a UTF-8
1736 string. Do not use this for pad names that point to outer
1737 lexicals. See "newPADNAMEouter".
1738 PADNAME * newPADNAMEpvn(const char *s, STRLEN len)
1740 nothreadhook
1742 Stub that provides thread hook for perl_destruct when there are
1743 no threads.
1744 int nothreadhook()
1746 pad_add_anon
1748 Allocates a place in the currently-compiling pad (via
1749 "pad_alloc") for an anonymous function that is lexically scoped
1750 inside the currently-compiling function. The function "func"
1751 is linked into the pad, and its "CvOUTSIDE" link to the outer
1752 scope is weakened to avoid a reference loop.
1753 One reference count is stolen, so you may need to do
1755 "SvREFCNT_inc(func)".
1756 "optype" should be an opcode indicating the type of operation
1758 that the pad entry is to support. This doesn't affect
1759 operational semantics, but is used for debugging.
1760 PADOFFSET pad_add_anon(CV* func, I32 optype)
1762 pad_add_name_pv
1764 Exactly like "pad_add_name_pvn", but takes a nul-terminated
1765 string instead of a string/length pair.
1766 PADOFFSET pad_add_name_pv(const char *name,
1768 const U32 flags,
1769 HV *typestash, HV *ourstash)
1770 pad_add_name_pvn
1772 Allocates a place in the currently-compiling pad for a named
1773 lexical variable. Stores the name and other metadata in the
1774 name part of the pad, and makes preparations to manage the
1775 variable's lexical scoping. Returns the offset of the
1776 allocated pad slot.
1777 "namepv"/"namelen" specify the variable's name, including
1779 leading sigil. If "typestash" is non-null, the name is for a
1780 typed lexical, and this identifies the type. If "ourstash" is
1781 non-null, it's a lexical reference to a package variable, and
1782 this identifies the package. The following flags can be OR'ed
1783 together:
1784 padadd_OUR redundantly specifies if it's a package var
1786 padadd_STATE variable will retain value persistently
1787 padadd_NO_DUP_CHECK skip check for lexical shadowing
1788 PADOFFSET pad_add_name_pvn(const char *namepv,
1790 STRLEN namelen, U32 flags,
1791 HV *typestash, HV *ourstash)
1792 pad_add_name_sv
1794 Exactly like "pad_add_name_pvn", but takes the name string in
1795 the form of an SV instead of a string/length pair.
1796 PADOFFSET pad_add_name_sv(SV *name, U32 flags,
1798 HV *typestash, HV *ourstash)
1799 pad_alloc
1801 NOTE: this function is experimental and may change or be
1802 removed without notice.
1803 Allocates a place in the currently-compiling pad, returning the
1805 offset of the allocated pad slot. No name is initially
1806 attached to the pad slot. "tmptype" is a set of flags
1807 indicating the kind of pad entry required, which will be set in
1808 the value SV for the allocated pad entry:
1809 SVs_PADMY named lexical variable ("my", "our", "state")
1811 SVs_PADTMP unnamed temporary store
1812 SVf_READONLY constant shared between recursion levels
1813 "SVf_READONLY" has been supported here only since perl 5.20.
1815 To work with earlier versions as well, use
1816 "SVf_READONLY|SVs_PADTMP". "SVf_READONLY" does not cause the
1817 SV in the pad slot to be marked read-only, but simply tells
1818 "pad_alloc" that it will be made read-only (by the caller), or
1819 at least should be treated as such.
1820 "optype" should be an opcode indicating the type of operation
1822 that the pad entry is to support. This doesn't affect
1823 operational semantics, but is used for debugging.
1824 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
1826 pad_findmy_pv
1828 Exactly like "pad_findmy_pvn", but takes a nul-terminated
1829 string instead of a string/length pair.
1830 PADOFFSET pad_findmy_pv(const char* name, U32 flags)
1832 pad_findmy_pvn
1834 Given the name of a lexical variable, find its position in the
1835 currently-compiling pad. "namepv"/"namelen" specify the
1836 variable's name, including leading sigil. "flags" is reserved
1837 and must be zero. If it is not in the current pad but appears
1838 in the pad of any lexically enclosing scope, then a pseudo-
1839 entry for it is added in the current pad. Returns the offset
1840 in the current pad, or "NOT_IN_PAD" if no such lexical is in
1841 scope.
1842 PADOFFSET pad_findmy_pvn(const char* namepv,
1844 STRLEN namelen, U32 flags)
1845 pad_findmy_sv
1847 Exactly like "pad_findmy_pvn", but takes the name string in the
1848 form of an SV instead of a string/length pair.
1849 PADOFFSET pad_findmy_sv(SV* name, U32 flags)
1851 padnamelist_fetch
1853 NOTE: this function is experimental and may change or be
1854 removed without notice.
1855 Fetches the pad name from the given index.
1857 PADNAME * padnamelist_fetch(PADNAMELIST *pnl,
1859 SSize_t key)
1860 padnamelist_store
1862 NOTE: this function is experimental and may change or be
1863 removed without notice.
1864 Stores the pad name (which may be null) at the given index,
1866 freeing any existing pad name in that slot.
1867 PADNAME ** padnamelist_store(PADNAMELIST *pnl,
1869 SSize_t key, PADNAME *val)
1870 pad_setsv
1872 Set the value at offset "po" in the current (compiling or
1873 executing) pad. Use the macro "PAD_SETSV()" rather than
1874 calling this function directly.
1875 void pad_setsv(PADOFFSET po, SV* sv)
1877 pad_sv Get the value at offset "po" in the current (compiling or
1879 executing) pad. Use macro "PAD_SV" instead of calling this
1880 function directly.
1881 SV* pad_sv(PADOFFSET po)
1883 pad_tidy
1885 NOTE: this function is experimental and may change or be
1886 removed without notice.
1887 Tidy up a pad at the end of compilation of the code to which it
1889 belongs. Jobs performed here are: remove most stuff from the
1890 pads of anonsub prototypes; give it a @_; mark temporaries as
1891 such. "type" indicates the kind of subroutine:
1892 padtidy_SUB ordinary subroutine
1894 padtidy_SUBCLONE prototype for lexical closure
1895 padtidy_FORMAT format
1896 void pad_tidy(padtidy_type type)
1898 perl_alloc
1900 Allocates a new Perl interpreter. See perlembed.
1901 PerlInterpreter* perl_alloc()
1903 perl_construct
1905 Initializes a new Perl interpreter. See perlembed.
1906 void perl_construct(PerlInterpreter *my_perl)
1908 perl_destruct
1910 Shuts down a Perl interpreter. See perlembed for a tutorial.
1911 "my_perl" points to the Perl interpreter. It must have been
1913 previously created through the use of "perl_alloc" and
1914 "perl_construct". It may have been initialised through
1915 "perl_parse", and may have been used through "perl_run" and
1916 other means. This function should be called for any Perl
1917 interpreter that has been constructed with "perl_construct",
1918 even if subsequent operations on it failed, for example if
1919 "perl_parse" returned a non-zero value.
1920 If the interpreter's "PL_exit_flags" word has the
1922 "PERL_EXIT_DESTRUCT_END" flag set, then this function will
1923 execute code in "END" blocks before performing the rest of
1924 destruction. If it is desired to make any use of the
1925 interpreter between "perl_parse" and "perl_destruct" other than
1926 just calling "perl_run", then this flag should be set early on.
1927 This matters if "perl_run" will not be called, or if anything
1928 else will be done in addition to calling "perl_run".
1929 Returns a value be a suitable value to pass to the C library
1931 function "exit" (or to return from "main"), to serve as an exit
1932 code indicating the nature of the way the interpreter
1933 terminated. This takes into account any failure of
1934 "perl_parse" and any early exit from "perl_run". The exit code
1935 is of the type required by the host operating system, so
1936 because of differing exit code conventions it is not portable
1937 to interpret specific numeric values as having specific
1938 meanings.
1939 int perl_destruct(PerlInterpreter *my_perl)
1941 perl_free
1943 Releases a Perl interpreter. See perlembed.
1944 void perl_free(PerlInterpreter *my_perl)
1946 perl_parse
1948 Tells a Perl interpreter to parse a Perl script. This performs
1949 most of the initialisation of a Perl interpreter. See
1950 perlembed for a tutorial.
1951 "my_perl" points to the Perl interpreter that is to parse the
1953 script. It must have been previously created through the use
1954 of "perl_alloc" and "perl_construct". "xsinit" points to a
1955 callback function that will be called to set up the ability for
1956 this Perl interpreter to load XS extensions, or may be null to
1957 perform no such setup.
1958 "argc" and "argv" supply a set of command-line arguments to the
1960 Perl interpreter, as would normally be passed to the "main"
1961 function of a C program. "argv[argc]" must be null. These
1962 arguments are where the script to parse is specified, either by
1963 naming a script file or by providing a script in a "-e" option.
1964 If $0 will be written to in the Perl interpreter, then the
1965 argument strings must be in writable memory, and so mustn't
1966 just be string constants.
1967 "env" specifies a set of environment variables that will be
1969 used by this Perl interpreter. If non-null, it must point to a
1970 null-terminated array of environment strings. If null, the
1971 Perl interpreter will use the environment supplied by the
1972 "environ" global variable.
1973 This function initialises the interpreter, and parses and
1975 compiles the script specified by the command-line arguments.
1976 This includes executing code in "BEGIN", "UNITCHECK", and
1977 "CHECK" blocks. It does not execute "INIT" blocks or the main
1978 program.
1979 Returns an integer of slightly tricky interpretation. The
1981 correct use of the return value is as a truth value indicating
1982 whether there was a failure in initialisation. If zero is
1983 returned, this indicates that initialisation was successful,
1984 and it is safe to proceed to call "perl_run" and make other use
1985 of it. If a non-zero value is returned, this indicates some
1986 problem that means the interpreter wants to terminate. The
1987 interpreter should not be just abandoned upon such failure; the
1988 caller should proceed to shut the interpreter down cleanly with
1989 "perl_destruct" and free it with "perl_free".
1990 For historical reasons, the non-zero return value also attempts
1992 to be a suitable value to pass to the C library function "exit"
1993 (or to return from "main"), to serve as an exit code indicating
1994 the nature of the way initialisation terminated. However, this
1995 isn't portable, due to differing exit code conventions. A
1996 historical bug is preserved for the time being: if the Perl
1997 built-in "exit" is called during this function's execution,
1998 with a type of exit entailing a zero exit code under the host
1999 operating system's conventions, then this function returns zero
2000 rather than a non-zero value. This bug, [perl #2754], leads to
2001 "perl_run" being called (and therefore "INIT" blocks and the
2002 main program running) despite a call to "exit". It has been
2003 preserved because a popular module-installing module has come
2004 to rely on it and needs time to be fixed. This issue is [perl
2005 #132577], and the original bug is due to be fixed in Perl 5.30.
2006 int perl_parse(PerlInterpreter *my_perl,
2008 XSINIT_t xsinit, int argc,
2009 char** argv, char** env)
2010 perl_run
2012 Tells a Perl interpreter to run its main program. See
2013 perlembed for a tutorial.
2014 "my_perl" points to the Perl interpreter. It must have been
2016 previously created through the use of "perl_alloc" and
2017 "perl_construct", and initialised through "perl_parse". This
2018 function should not be called if "perl_parse" returned a non-
2019 zero value, indicating a failure in initialisation or
2020 compilation.
2021 This function executes code in "INIT" blocks, and then executes
2023 the main program. The code to be executed is that established
2024 by the prior call to "perl_parse". If the interpreter's
2025 "PL_exit_flags" word does not have the "PERL_EXIT_DESTRUCT_END"
2026 flag set, then this function will also execute code in "END"
2027 blocks. If it is desired to make any further use of the
2028 interpreter after calling this function, then "END" blocks
2029 should be postponed to "perl_destruct" time by setting that
2030 flag.
2031 Returns an integer of slightly tricky interpretation. The
2033 correct use of the return value is as a truth value indicating
2034 whether the program terminated non-locally. If zero is
2035 returned, this indicates that the program ran to completion,
2036 and it is safe to make other use of the interpreter (provided
2037 that the "PERL_EXIT_DESTRUCT_END" flag was set as described
2038 above). If a non-zero value is returned, this indicates that
2039 the interpreter wants to terminate early. The interpreter
2040 should not be just abandoned because of this desire to
2041 terminate; the caller should proceed to shut the interpreter
2042 down cleanly with "perl_destruct" and free it with "perl_free".
2043 For historical reasons, the non-zero return value also attempts
2045 to be a suitable value to pass to the C library function "exit"
2046 (or to return from "main"), to serve as an exit code indicating
2047 the nature of the way the program terminated. However, this
2048 isn't portable, due to differing exit code conventions. An
2049 attempt is made to return an exit code of the type required by
2050 the host operating system, but because it is constrained to be
2051 non-zero, it is not necessarily possible to indicate every type
2052 of exit. It is only reliable on Unix, where a zero exit code
2053 can be augmented with a set bit that will be ignored. In any
2054 case, this function is not the correct place to acquire an exit
2055 code: one should get that from "perl_destruct".
2056 int perl_run(PerlInterpreter *my_perl)
2058 require_pv
2060 Tells Perl to "require" the file named by the string argument.
2061 It is analogous to the Perl code "eval "require '$file'"".
2062 It's even implemented that way; consider using load_module
2063 instead.
2064 NOTE: the perl_ form of this function is deprecated.
2066 void require_pv(const char* pv)
2068
2070 dXCPT Set up necessary local variables for exception handling. See
2071 "Exception Handling" in perlguts.
2072 dXCPT;
2074 XCPT_CATCH
2076 Introduces a catch block. See "Exception Handling" in
2077 perlguts.
2078 XCPT_RETHROW
2080 Rethrows a previously caught exception. See "Exception
2081 Handling" in perlguts.
2082 XCPT_RETHROW;
2084 XCPT_TRY_END
2086 Ends a try block. See "Exception Handling" in perlguts.
2087 XCPT_TRY_START
2089 Starts a try block. See "Exception Handling" in perlguts.
2090
2092 av_count
2093 Returns the number of elements in the array "av". This is the
2094 true length of the array, including any undefined elements. It
2095 is always the same as "av_top_index(av) + 1".
2096 Size_t av_count(AV *av)
2098
2100 new_version
2101 Returns a new version object based on the passed in SV:
2102 SV *sv = new_version(SV *ver);
2104 Does not alter the passed in ver SV. See "upg_version" if you
2106 want to upgrade the SV.
2107 SV* new_version(SV *ver)
2109 prescan_version
2111 Validate that a given string can be parsed as a version object,
2112 but doesn't actually perform the parsing. Can use either
2113 strict or lax validation rules. Can optionally set a number of
2114 hint variables to save the parsing code some time when
2115 tokenizing.
2116 const char* prescan_version(const char *s, bool strict,
2118 const char** errstr,
2119 bool *sqv,
2120 int *ssaw_decimal,
2121 int *swidth, bool *salpha)
2122 scan_version
2124 Returns a pointer to the next character after the parsed
2125 version string, as well as upgrading the passed in SV to an RV.
2126 Function must be called with an already existing SV like
2128 sv = newSV(0);
2130 s = scan_version(s, SV *sv, bool qv);
2131 Performs some preprocessing to the string to ensure that it has
2133 the correct characteristics of a version. Flags the object if
2134 it contains an underscore (which denotes this is an alpha
2135 version). The boolean qv denotes that the version should be
2136 interpreted as if it had multiple decimals, even if it doesn't.
2137 const char* scan_version(const char *s, SV *rv, bool qv)
2139 upg_version
2141 In-place upgrade of the supplied SV to a version object.
2142 SV *sv = upg_version(SV *sv, bool qv);
2144 Returns a pointer to the upgraded SV. Set the boolean qv if
2146 you want to force this SV to be interpreted as an "extended"
2147 version.
2148 SV* upg_version(SV *ver, bool qv)
2150 vcmp Version object aware cmp. Both operands must already have been
2152 converted into version objects.
2153 int vcmp(SV *lhv, SV *rhv)
2155 vnormal Accepts a version object and returns the normalized string
2157 representation. Call like:
2158 sv = vnormal(rv);
2160 NOTE: you can pass either the object directly or the SV
2162 contained within the RV.
2163 The SV returned has a refcount of 1.
2165 SV* vnormal(SV *vs)
2167 vnumify Accepts a version object and returns the normalized floating
2169 point representation. Call like:
2170 sv = vnumify(rv);
2172 NOTE: you can pass either the object directly or the SV
2174 contained within the RV.
2175 The SV returned has a refcount of 1.
2177 SV* vnumify(SV *vs)
2179 vstringify
2181 In order to maintain maximum compatibility with earlier
2182 versions of Perl, this function will return either the floating
2183 point notation or the multiple dotted notation, depending on
2184 whether the original version contained 1 or more dots,
2185 respectively.
2186 The SV returned has a refcount of 1.
2188 SV* vstringify(SV *vs)
2190 vverify Validates that the SV contains valid internal structure for a
2192 version object. It may be passed either the version object
2193 (RV) or the hash itself (HV). If the structure is valid, it
2194 returns the HV. If the structure is invalid, it returns NULL.
2195 SV *hv = vverify(sv);
2197 Note that it only confirms the bare minimum structure (so as
2199 not to get confused by derived classes which may contain
2200 additional hash entries):
2201 • The SV is an HV or a reference to an HV
2203 • The hash contains a "version" key
2205 • The "version" key has a reference to an AV as its value
2207 SV* vverify(SV *vs)
2209
2211 G_ARRAY Used to indicate list context. See "GIMME_V", "GIMME" and
2212 perlcall.
2213 G_DISCARD
2215 Indicates that arguments returned from a callback should be
2216 discarded. See perlcall.
2217 G_EVAL Used to force a Perl "eval" wrapper around a callback. See
2219 perlcall.
2220 GIMME A backward-compatible version of "GIMME_V" which can only
2222 return "G_SCALAR" or "G_ARRAY"; in a void context, it returns
2223 "G_SCALAR". Deprecated. Use "GIMME_V" instead.
2224 U32 GIMME
2226 GIMME_V The XSUB-writer's equivalent to Perl's "wantarray". Returns
2228 "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list
2229 context, respectively. See perlcall for a usage example.
2230 U32 GIMME_V
2232 G_NOARGS
2234 Indicates that no arguments are being sent to a callback. See
2235 perlcall.
2236 G_SCALAR
2238 Used to indicate scalar context. See "GIMME_V", "GIMME", and
2239 perlcall.
2240 G_VOID Used to indicate void context. See "GIMME_V" and perlcall.
2242
2244 These variables are global to an entire process. They are shared
2245 between all interpreters and all threads in a process. Any variables
2246 not documented here may be changed or removed without notice, so don't
2247 use them! If you feel you really do need to use an unlisted variable,
2248 first send email to perl5-porters@perl.org
2249 <mailto:perl5-porters@perl.org>. It may be that someone there will
2250 point out a way to accomplish what you need without using an internal
2251 variable. But if not, you should get a go-ahead to document and then
2252 use the variable.
2253 PL_check
2255 Array, indexed by opcode, of functions that will be called for
2256 the "check" phase of optree building during compilation of Perl
2257 code. For most (but not all) types of op, once the op has been
2258 initially built and populated with child ops it will be
2259 filtered through the check function referenced by the
2260 appropriate element of this array. The new op is passed in as
2261 the sole argument to the check function, and the check function
2262 returns the completed op. The check function may (as the name
2263 suggests) check the op for validity and signal errors. It may
2264 also initialise or modify parts of the ops, or perform more
2265 radical surgery such as adding or removing child ops, or even
2266 throw the op away and return a different op in its place.
2267 This array of function pointers is a convenient place to hook
2269 into the compilation process. An XS module can put its own
2270 custom check function in place of any of the standard ones, to
2271 influence the compilation of a particular type of op. However,
2272 a custom check function must never fully replace a standard
2273 check function (or even a custom check function from another
2274 module). A module modifying checking must instead wrap the
2275 preexisting check function. A custom check function must be
2276 selective about when to apply its custom behaviour. In the
2277 usual case where it decides not to do anything special with an
2278 op, it must chain the preexisting op function. Check functions
2279 are thus linked in a chain, with the core's base checker at the
2280 end.
2281 For thread safety, modules should not write directly to this
2283 array. Instead, use the function "wrap_op_checker".
2284 PL_keyword_plugin
2286 NOTE: this function is experimental and may change or be
2287 removed without notice.
2288 Function pointer, pointing at a function used to handle
2290 extended keywords. The function should be declared as
2291 int keyword_plugin_function(pTHX_
2293 char *keyword_ptr, STRLEN keyword_len,
2294 OP **op_ptr)
2295 The function is called from the tokeniser, whenever a possible
2297 keyword is seen. "keyword_ptr" points at the word in the
2298 parser's input buffer, and "keyword_len" gives its length; it
2299 is not null-terminated. The function is expected to examine
2300 the word, and possibly other state such as %^H, to decide
2301 whether it wants to handle it as an extended keyword. If it
2302 does not, the function should return "KEYWORD_PLUGIN_DECLINE",
2303 and the normal parser process will continue.
2304 If the function wants to handle the keyword, it first must
2306 parse anything following the keyword that is part of the syntax
2307 introduced by the keyword. See "Lexer interface" for details.
2308 When a keyword is being handled, the plugin function must build
2310 a tree of "OP" structures, representing the code that was
2311 parsed. The root of the tree must be stored in *op_ptr. The
2312 function then returns a constant indicating the syntactic role
2313 of the construct that it has parsed: "KEYWORD_PLUGIN_STMT" if
2314 it is a complete statement, or "KEYWORD_PLUGIN_EXPR" if it is
2315 an expression. Note that a statement construct cannot be used
2316 inside an expression (except via "do BLOCK" and similar), and
2317 an expression is not a complete statement (it requires at least
2318 a terminating semicolon).
2319 When a keyword is handled, the plugin function may also have
2321 (compile-time) side effects. It may modify "%^H", define
2322 functions, and so on. Typically, if side effects are the main
2323 purpose of a handler, it does not wish to generate any ops to
2324 be included in the normal compilation. In this case it is
2325 still required to supply an op tree, but it suffices to
2326 generate a single null op.
2327 That's how the *PL_keyword_plugin function needs to behave
2329 overall. Conventionally, however, one does not completely
2330 replace the existing handler function. Instead, take a copy of
2331 "PL_keyword_plugin" before assigning your own function pointer
2332 to it. Your handler function should look for keywords that it
2333 is interested in and handle those. Where it is not interested,
2334 it should call the saved plugin function, passing on the
2335 arguments it received. Thus "PL_keyword_plugin" actually
2336 points at a chain of handler functions, all of which have an
2337 opportunity to handle keywords, and only the last function in
2338 the chain (built into the Perl core) will normally return
2339 "KEYWORD_PLUGIN_DECLINE".
2340 For thread safety, modules should not set this variable
2342 directly. Instead, use the function "wrap_keyword_plugin".
2343 PL_phase
2345 A value that indicates the current Perl interpreter's phase.
2346 Possible values include "PERL_PHASE_CONSTRUCT",
2347 "PERL_PHASE_START", "PERL_PHASE_CHECK", "PERL_PHASE_INIT",
2348 "PERL_PHASE_RUN", "PERL_PHASE_END", and "PERL_PHASE_DESTRUCT".
2349 For example, the following determines whether the interpreter
2351 is in global destruction:
2352 if (PL_phase == PERL_PHASE_DESTRUCT) {
2354 // we are in global destruction
2355 }
2356 "PL_phase" was introduced in Perl 5.14; in prior perls you can
2358 use "PL_dirty" (boolean) to determine whether the interpreter
2359 is in global destruction. (Use of "PL_dirty" is discouraged
2360 since 5.14.)
2361 enum perl_phase PL_phase
2363
2365 A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
2366 It is a structure that holds a pointer to a scalar, an array, a hash
2367 etc, corresponding to $foo, @foo, %foo.
2368 GVs are usually found as values in stashes (symbol table hashes) where
2370 Perl stores its global variables.
2371 GvAV Return the AV from the GV.
2373 AV* GvAV(GV* gv)
2375 gv_const_sv
2377 If "gv" is a typeglob whose subroutine entry is a constant sub
2378 eligible for inlining, or "gv" is a placeholder reference that
2379 would be promoted to such a typeglob, then returns the value
2380 returned by the sub. Otherwise, returns "NULL".
2381 SV* gv_const_sv(GV* gv)
2383 GvCV Return the CV from the GV.
2385 CV* GvCV(GV* gv)
2387 gv_fetchmeth
2389 Like "gv_fetchmeth_pvn", but lacks a flags parameter.
2390 GV* gv_fetchmeth(HV* stash, const char* name,
2392 STRLEN len, I32 level)
2393 gv_fetchmethod_autoload
2395 Returns the glob which contains the subroutine to call to
2396 invoke the method on the "stash". In fact in the presence of
2397 autoloading this may be the glob for "AUTOLOAD". In this case
2398 the corresponding variable $AUTOLOAD is already setup.
2399 The third parameter of "gv_fetchmethod_autoload" determines
2401 whether AUTOLOAD lookup is performed if the given method is not
2402 present: non-zero means yes, look for AUTOLOAD; zero means no,
2403 don't look for AUTOLOAD. Calling "gv_fetchmethod" is
2404 equivalent to calling "gv_fetchmethod_autoload" with a non-zero
2405 "autoload" parameter.
2406 These functions grant "SUPER" token as a prefix of the method
2408 name. Note that if you want to keep the returned glob for a
2409 long time, you need to check for it being "AUTOLOAD", since at
2410 the later time the call may load a different subroutine due to
2411 $AUTOLOAD changing its value. Use the glob created as a side
2412 effect to do this.
2413 These functions have the same side-effects as "gv_fetchmeth"
2415 with "level==0". The warning against passing the GV returned
2416 by "gv_fetchmeth" to "call_sv" applies equally to these
2417 functions.
2418 GV* gv_fetchmethod_autoload(HV* stash,
2420 const char* name,
2421 I32 autoload)
2422 gv_fetchmeth_autoload
2424 This is the old form of "gv_fetchmeth_pvn_autoload", which has
2425 no flags parameter.
2426 GV* gv_fetchmeth_autoload(HV* stash,
2428 const char* name,
2429 STRLEN len, I32 level)
2430 gv_fetchmeth_pv
2432 Exactly like "gv_fetchmeth_pvn", but takes a nul-terminated
2433 string instead of a string/length pair.
2434 GV* gv_fetchmeth_pv(HV* stash, const char* name,
2436 I32 level, U32 flags)
2437 gv_fetchmeth_pvn
2439 Returns the glob with the given "name" and a defined subroutine
2440 or "NULL". The glob lives in the given "stash", or in the
2441 stashes accessible via @ISA and "UNIVERSAL::".
2442 The argument "level" should be either 0 or -1. If "level==0",
2444 as a side-effect creates a glob with the given "name" in the
2445 given "stash" which in the case of success contains an alias
2446 for the subroutine, and sets up caching info for this glob.
2447 The only significant values for "flags" are "GV_SUPER" and
2449 "SVf_UTF8".
2450 "GV_SUPER" indicates that we want to look up the method in the
2452 superclasses of the "stash".
2453 The GV returned from "gv_fetchmeth" may be a method cache
2455 entry, which is not visible to Perl code. So when calling
2456 "call_sv", you should not use the GV directly; instead, you
2457 should use the method's CV, which can be obtained from the GV
2458 with the "GvCV" macro.
2459 GV* gv_fetchmeth_pvn(HV* stash, const char* name,
2461 STRLEN len, I32 level,
2462 U32 flags)
2463 gv_fetchmeth_pvn_autoload
2465 Same as "gv_fetchmeth_pvn()", but looks for autoloaded
2466 subroutines too. Returns a glob for the subroutine.
2467 For an autoloaded subroutine without a GV, will create a GV
2469 even if "level < 0". For an autoloaded subroutine without a
2470 stub, "GvCV()" of the result may be zero.
2471 Currently, the only significant value for "flags" is
2473 "SVf_UTF8".
2474 GV* gv_fetchmeth_pvn_autoload(HV* stash,
2476 const char* name,
2477 STRLEN len, I32 level,
2478 U32 flags)
2479 gv_fetchmeth_pv_autoload
2481 Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-
2482 terminated string instead of a string/length pair.
2483 GV* gv_fetchmeth_pv_autoload(HV* stash,
2485 const char* name,
2486 I32 level, U32 flags)
2487 gv_fetchmeth_sv
2489 Exactly like "gv_fetchmeth_pvn", but takes the name string in
2490 the form of an SV instead of a string/length pair.
2491 GV* gv_fetchmeth_sv(HV* stash, SV* namesv,
2493 I32 level, U32 flags)
2494 gv_fetchmeth_sv_autoload
2496 Exactly like "gv_fetchmeth_pvn_autoload", but takes the name
2497 string in the form of an SV instead of a string/length pair.
2498 GV* gv_fetchmeth_sv_autoload(HV* stash, SV* namesv,
2500 I32 level, U32 flags)
2501 GvHV Return the HV from the GV.
2503 HV* GvHV(GV* gv)
2505 gv_init The old form of "gv_init_pvn()". It does not work with UTF-8
2507 strings, as it has no flags parameter. If the "multi"
2508 parameter is set, the "GV_ADDMULTI" flag will be passed to
2509 "gv_init_pvn()".
2510 void gv_init(GV* gv, HV* stash, const char* name,
2512 STRLEN len, int multi)
2513 gv_init_pv
2515 Same as "gv_init_pvn()", but takes a nul-terminated string for
2516 the name instead of separate char * and length parameters.
2517 void gv_init_pv(GV* gv, HV* stash, const char* name,
2519 U32 flags)
2520 gv_init_pvn
2522 Converts a scalar into a typeglob. This is an incoercible
2523 typeglob; assigning a reference to it will assign to one of its
2524 slots, instead of overwriting it as happens with typeglobs
2525 created by "SvSetSV". Converting any scalar that is "SvOK()"
2526 may produce unpredictable results and is reserved for perl's
2527 internal use.
2528 "gv" is the scalar to be converted.
2530 "stash" is the parent stash/package, if any.
2532 "name" and "len" give the name. The name must be unqualified;
2534 that is, it must not include the package name. If "gv" is a
2535 stash element, it is the caller's responsibility to ensure that
2536 the name passed to this function matches the name of the
2537 element. If it does not match, perl's internal bookkeeping
2538 will get out of sync.
2539 "flags" can be set to "SVf_UTF8" if "name" is a UTF-8 string,
2541 or the return value of SvUTF8(sv). It can also take the
2542 "GV_ADDMULTI" flag, which means to pretend that the GV has been
2543 seen before (i.e., suppress "Used once" warnings).
2544 void gv_init_pvn(GV* gv, HV* stash, const char* name,
2546 STRLEN len, U32 flags)
2547 gv_init_sv
2549 Same as "gv_init_pvn()", but takes an SV * for the name instead
2550 of separate char * and length parameters. "flags" is currently
2551 unused.
2552 void gv_init_sv(GV* gv, HV* stash, SV* namesv,
2554 U32 flags)
2555 gv_stashpv
2557 Returns a pointer to the stash for a specified package. Uses
2558 "strlen" to determine the length of "name", then calls
2559 "gv_stashpvn()".
2560 HV* gv_stashpv(const char* name, I32 flags)
2562 gv_stashpvn
2564 Returns a pointer to the stash for a specified package. The
2565 "namelen" parameter indicates the length of the "name", in
2566 bytes. "flags" is passed to "gv_fetchpvn_flags()", so if set
2567 to "GV_ADD" then the package will be created if it does not
2568 already exist. If the package does not exist and "flags" is 0
2569 (or any other setting that does not create packages) then
2570 "NULL" is returned.
2571 Flags may be one of:
2573 GV_ADD
2575 SVf_UTF8
2576 GV_NOADD_NOINIT
2577 GV_NOINIT
2578 GV_NOEXPAND
2579 GV_ADDMG
2580 The most important of which are probably "GV_ADD" and
2582 "SVf_UTF8".
2583 Note, use of "gv_stashsv" instead of "gv_stashpvn" where
2585 possible is strongly recommended for performance reasons.
2586 HV* gv_stashpvn(const char* name, U32 namelen,
2588 I32 flags)
2589 gv_stashpvs
2591 Like "gv_stashpvn", but takes a literal string instead of a
2592 string/length pair.
2593 HV* gv_stashpvs("name", I32 create)
2595 gv_stashsv
2597 Returns a pointer to the stash for a specified package. See
2598 "gv_stashpvn".
2599 Note this interface is strongly preferred over "gv_stashpvn"
2601 for performance reasons.
2602 HV* gv_stashsv(SV* sv, I32 flags)
2604 GvSV Return the SV from the GV.
2606 SV* GvSV(GV* gv)
2608 save_gp Saves the current GP of gv on the save stack to be restored on
2610 scope exit.
2611 If empty is true, replace the GP with a new GP.
2613 If empty is false, mark gv with GVf_INTRO so the next reference
2615 assigned is localized, which is how " local *foo = $someref; "
2616 works.
2617 void save_gp(GV* gv, I32 empty)
2619 setdefout
2621 Sets "PL_defoutgv", the default file handle for output, to the
2622 passed in typeglob. As "PL_defoutgv" "owns" a reference on its
2623 typeglob, the reference count of the passed in typeglob is
2624 increased by one, and the reference count of the typeglob that
2625 "PL_defoutgv" points to is decreased by one.
2626 void setdefout(GV* gv)
2628
2630 C_ARRAY_END
2631 Returns a pointer to one element past the final element of the
2632 input C array.
2633 void * C_ARRAY_END(void *a)
2635 C_ARRAY_LENGTH
2637 Returns the number of elements in the input C array (so you
2638 want your zero-based indices to be less than but not equal to).
2639 STRLEN C_ARRAY_LENGTH(void *a)
2641 cBOOL Cast-to-bool. A simple "(bool) expr" cast may not do the right
2643 thing: if "bool" is defined as "char", for example, then the
2644 cast from "int" is implementation-defined.
2645 "(bool)!!(cbool)" in a ternary triggers a bug in xlc on AIX
2647 bool cBOOL(bool expr)
2649 Nullav DEPRECATED! It is planned to remove this function from a
2651 future release of Perl. Do not use it for new code; remove it
2652 from existing code.
2653 Null AV pointer.
2655 (deprecated - use "(AV *)NULL" instead)
2657 Nullch Null character pointer. (No longer available when "PERL_CORE"
2659 is defined.)
2660 Nullcv DEPRECATED! It is planned to remove this function from a
2662 future release of Perl. Do not use it for new code; remove it
2663 from existing code.
2664 Null CV pointer.
2666 (deprecated - use "(CV *)NULL" instead)
2668 Nullhv DEPRECATED! It is planned to remove this function from a
2670 future release of Perl. Do not use it for new code; remove it
2671 from existing code.
2672 Null HV pointer.
2674 (deprecated - use "(HV *)NULL" instead)
2676 Nullsv Null SV pointer. (No longer available when "PERL_CORE" is
2678 defined.)
2679 STR_WITH_LEN
2681 Returns two comma separated tokens of the input literal string,
2682 and its length. This is convenience macro which helps out in
2683 some API calls. Note that it can't be used as an argument to
2684 macros or functions that under some configurations might be
2685 macros, which means that it requires the full Perl_xxx(aTHX_
2686 ...) form for any API calls where it's used.
2687 pair STR_WITH_LEN("literal string")
2689 __ASSERT_
2691 This is a helper macro to avoid preprocessor issues, replaced
2692 by nothing unless under DEBUGGING, where it expands to an
2693 assert of its argument, followed by a comma (hence the comma
2694 operator). If we just used a straight assert(), we would get a
2695 comma with nothing before it when not DEBUGGING.
2696 void __ASSERT_(bool expr)
2698
2700 A HV structure represents a Perl hash. It consists mainly of an array
2701 of pointers, each of which points to a linked list of HE structures.
2702 The array is indexed by the hash function of the key, so each linked
2703 list represents all the hash entries with the same hash value. Each HE
2704 contains a pointer to the actual value, plus a pointer to a HEK
2705 structure which holds the key and hash value.
2706 cop_fetch_label
2708 NOTE: this function is experimental and may change or be
2709 removed without notice.
2710 Returns the label attached to a cop, and stores its length in
2712 bytes into *len. Upon return, *flags will be set to either
2713 "SVf_UTF8" or 0.
2714 Alternatively, use the macro ""CopLABEL_len_flags""; or if you
2716 don't need to know if the label is UTF-8 or not, the macro
2717 ""CopLABEL_len""; or if you additionally dont need to know the
2718 length, ""CopLABEL"".
2719 const char * cop_fetch_label(COP *const cop,
2721 STRLEN *len, U32 *flags)
2722 cop_store_label
2724 NOTE: this function is experimental and may change or be
2725 removed without notice.
2726 Save a label into a "cop_hints_hash". You need to set flags to
2728 "SVf_UTF8" for a UTF-8 label. Any other flag is ignored.
2729 void cop_store_label(COP *const cop,
2731 const char *label, STRLEN len,
2732 U32 flags)
2733 get_hv Returns the HV of the specified Perl hash. "flags" are passed
2735 to "gv_fetchpv". If "GV_ADD" is set and the Perl variable does
2736 not exist then it will be created. If "flags" is zero and the
2737 variable does not exist then "NULL" is returned.
2738 NOTE: the perl_ form of this function is deprecated.
2740 HV* get_hv(const char *name, I32 flags)
2742 HEf_SVKEY
2744 This flag, used in the length slot of hash entries and magic
2745 structures, specifies the structure contains an "SV*" pointer
2746 where a "char*" pointer is to be expected. (For information
2747 only--not to be used).
2748 HeHASH Returns the computed hash stored in the hash entry.
2750 U32 HeHASH(HE* he)
2752 HeKEY Returns the actual pointer stored in the key slot of the hash
2754 entry. The pointer may be either "char*" or "SV*", depending
2755 on the value of "HeKLEN()". Can be assigned to. The "HePV()"
2756 or "HeSVKEY()" macros are usually preferable for finding the
2757 value of a key.
2758 void* HeKEY(HE* he)
2760 HeKLEN If this is negative, and amounts to "HEf_SVKEY", it indicates
2762 the entry holds an "SV*" key. Otherwise, holds the actual
2763 length of the key. Can be assigned to. The "HePV()" macro is
2764 usually preferable for finding key lengths.
2765 STRLEN HeKLEN(HE* he)
2767 HePV Returns the key slot of the hash entry as a "char*" value,
2769 doing any necessary dereferencing of possibly "SV*" keys. The
2770 length of the string is placed in "len" (this is a macro, so do
2771 not use &len). If you do not care about what the length of the
2772 key is, you may use the global variable "PL_na", though this is
2773 rather less efficient than using a local variable. Remember
2774 though, that hash keys in perl are free to contain embedded
2775 nulls, so using "strlen()" or similar is not a good way to find
2776 the length of hash keys. This is very similar to the "SvPV()"
2777 macro described elsewhere in this document. See also "HeUTF8".
2778 If you are using "HePV" to get values to pass to "newSVpvn()"
2780 to create a new SV, you should consider using
2781 "newSVhek(HeKEY_hek(he))" as it is more efficient.
2782 char* HePV(HE* he, STRLEN len)
2784 HeSVKEY Returns the key as an "SV*", or "NULL" if the hash entry does
2786 not contain an "SV*" key.
2787 SV* HeSVKEY(HE* he)
2789 HeSVKEY_force
2791 Returns the key as an "SV*". Will create and return a
2792 temporary mortal "SV*" if the hash entry contains only a
2793 "char*" key.
2794 SV* HeSVKEY_force(HE* he)
2796 HeSVKEY_set
2798 Sets the key to a given "SV*", taking care to set the
2799 appropriate flags to indicate the presence of an "SV*" key, and
2800 returns the same "SV*".
2801 SV* HeSVKEY_set(HE* he, SV* sv)
2803 HeUTF8 Returns whether the "char *" value returned by "HePV" is
2805 encoded in UTF-8, doing any necessary dereferencing of possibly
2806 "SV*" keys. The value returned will be 0 or non-0, not
2807 necessarily 1 (or even a value with any low bits set), so do
2808 not blindly assign this to a "bool" variable, as "bool" may be
2809 a typedef for "char".
2810 U32 HeUTF8(HE* he)
2812 HeVAL Returns the value slot (type "SV*") stored in the hash entry.
2814 Can be assigned to.
2815 SV *foo= HeVAL(hv);
2817 HeVAL(hv)= sv;
2818 SV* HeVAL(HE* he)
2821 hv_assert
2823 Check that a hash is in an internally consistent state.
2824 NOTE: this function must be explicitly called as Perl_hv_assert
2826 with an aTHX_ parameter.
2827 void Perl_hv_assert(pTHX_ HV *hv)
2829 hv_bucket_ratio
2831 NOTE: this function is experimental and may change or be
2832 removed without notice.
2833 If the hash is tied dispatches through to the SCALAR tied
2835 method, otherwise if the hash contains no keys returns 0,
2836 otherwise returns a mortal sv containing a string specifying
2837 the number of used buckets, followed by a slash, followed by
2838 the number of available buckets.
2839 This function is expensive, it must scan all of the buckets to
2841 determine which are used, and the count is NOT cached. In a
2842 large hash this could be a lot of buckets.
2843 SV* hv_bucket_ratio(HV *hv)
2845 hv_clear
2847 Frees the all the elements of a hash, leaving it empty. The XS
2848 equivalent of "%hash = ()". See also "hv_undef".
2849 See "av_clear" for a note about the hash possibly being invalid
2851 on return.
2852 void hv_clear(HV *hv)
2854 hv_clear_placeholders
2856 Clears any placeholders from a hash. If a restricted hash has
2857 any of its keys marked as readonly and the key is subsequently
2858 deleted, the key is not actually deleted but is marked by
2859 assigning it a value of &PL_sv_placeholder. This tags it so it
2860 will be ignored by future operations such as iterating over the
2861 hash, but will still allow the hash to have a value reassigned
2862 to the key at some future point. This function clears any such
2863 placeholder keys from the hash. See "Hash::Util::lock_keys()"
2864 for an example of its use.
2865 void hv_clear_placeholders(HV *hv)
2867 hv_copy_hints_hv
2869 A specialised version of "newHVhv" for copying "%^H". "ohv"
2870 must be a pointer to a hash (which may have "%^H" magic, but
2871 should be generally non-magical), or "NULL" (interpreted as an
2872 empty hash). The content of "ohv" is copied to a new hash,
2873 which has the "%^H"-specific magic added to it. A pointer to
2874 the new hash is returned.
2875 HV * hv_copy_hints_hv(HV *const ohv)
2877 hv_delete
2879 Deletes a key/value pair in the hash. The value's SV is
2880 removed from the hash, made mortal, and returned to the caller.
2881 The absolute value of "klen" is the length of the key. If
2882 "klen" is negative the key is assumed to be in UTF-8-encoded
2883 Unicode. The "flags" value will normally be zero; if set to
2884 "G_DISCARD" then "NULL" will be returned. "NULL" will also be
2885 returned if the key is not found.
2886 SV* hv_delete(HV *hv, const char *key, I32 klen,
2888 I32 flags)
2889 hv_delete_ent
2891 Deletes a key/value pair in the hash. The value SV is removed
2892 from the hash, made mortal, and returned to the caller. The
2893 "flags" value will normally be zero; if set to "G_DISCARD" then
2894 "NULL" will be returned. "NULL" will also be returned if the
2895 key is not found. "hash" can be a valid precomputed hash
2896 value, or 0 to ask for it to be computed.
2897 SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags,
2899 U32 hash)
2900 HvENAME Returns the effective name of a stash, or NULL if there is
2902 none. The effective name represents a location in the symbol
2903 table where this stash resides. It is updated automatically
2904 when packages are aliased or deleted. A stash that is no
2905 longer in the symbol table has no effective name. This name is
2906 preferable to "HvNAME" for use in MRO linearisations and isa
2907 caches.
2908 char* HvENAME(HV* stash)
2910 HvENAMELEN
2912 Returns the length of the stash's effective name.
2913 STRLEN HvENAMELEN(HV *stash)
2915 HvENAMEUTF8
2917 Returns true if the effective name is in UTF-8 encoding.
2918 unsigned char HvENAMEUTF8(HV *stash)
2920 hv_exists
2922 Returns a boolean indicating whether the specified hash key
2923 exists. The absolute value of "klen" is the length of the key.
2924 If "klen" is negative the key is assumed to be in UTF-8-encoded
2925 Unicode.
2926 bool hv_exists(HV *hv, const char *key, I32 klen)
2928 hv_exists_ent
2930 Returns a boolean indicating whether the specified hash key
2931 exists. "hash" can be a valid precomputed hash value, or 0 to
2932 ask for it to be computed.
2933 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
2935 hv_fetch
2937 Returns the SV which corresponds to the specified key in the
2938 hash. The absolute value of "klen" is the length of the key.
2939 If "klen" is negative the key is assumed to be in UTF-8-encoded
2940 Unicode. If "lval" is set then the fetch will be part of a
2941 store. This means that if there is no value in the hash
2942 associated with the given key, then one is created and a
2943 pointer to it is returned. The "SV*" it points to can be
2944 assigned to. But always check that the return value is non-
2945 null before dereferencing it to an "SV*".
2946 See "Understanding the Magic of Tied Hashes and Arrays" in
2948 perlguts for more information on how to use this function on
2949 tied hashes.
2950 SV** hv_fetch(HV *hv, const char *key, I32 klen,
2952 I32 lval)
2953 hv_fetchs
2955 Like "hv_fetch", but takes a literal string instead of a
2956 string/length pair.
2957 SV** hv_fetchs(HV* tb, "key", I32 lval)
2959 hv_fetch_ent
2961 Returns the hash entry which corresponds to the specified key
2962 in the hash. "hash" must be a valid precomputed hash number
2963 for the given "key", or 0 if you want the function to compute
2964 it. IF "lval" is set then the fetch will be part of a store.
2965 Make sure the return value is non-null before accessing it.
2966 The return value when "hv" is a tied hash is a pointer to a
2967 static location, so be sure to make a copy of the structure if
2968 you need to store it somewhere.
2969 See "Understanding the Magic of Tied Hashes and Arrays" in
2971 perlguts for more information on how to use this function on
2972 tied hashes.
2973 HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval,
2975 U32 hash)
2976 HvFILL See "hv_fill".
2978 STRLEN HvFILL(HV *const hv)
2980 hv_fill Returns the number of hash buckets that happen to be in use.
2982 This function is wrapped by the macro "HvFILL".
2984 As of perl 5.25 this function is used only for debugging
2986 purposes, and the number of used hash buckets is not in any way
2987 cached, thus this function can be costly to execute as it must
2988 iterate over all the buckets in the hash.
2989 NOTE: this function must be explicitly called as Perl_hv_fill
2991 with an aTHX_ parameter.
2992 STRLEN Perl_hv_fill(pTHX_ HV *const hv)
2994 hv_iterinit
2996 Prepares a starting point to traverse a hash table. Returns
2997 the number of keys in the hash, including placeholders (i.e.
2998 the same as "HvTOTALKEYS(hv)"). The return value is currently
2999 only meaningful for hashes without tie magic.
3000 NOTE: Before version 5.004_65, "hv_iterinit" used to return the
3002 number of hash buckets that happen to be in use. If you still
3003 need that esoteric value, you can get it through the macro
3004 "HvFILL(hv)".
3005 I32 hv_iterinit(HV *hv)
3007 hv_iterkey
3009 Returns the key from the current position of the hash iterator.
3010 See "hv_iterinit".
3011 char* hv_iterkey(HE* entry, I32* retlen)
3013 hv_iterkeysv
3015 Returns the key as an "SV*" from the current position of the
3016 hash iterator. The return value will always be a mortal copy
3017 of the key. Also see "hv_iterinit".
3018 SV* hv_iterkeysv(HE* entry)
3020 hv_iternext
3022 Returns entries from a hash iterator. See "hv_iterinit".
3023 You may call "hv_delete" or "hv_delete_ent" on the hash entry
3025 that the iterator currently points to, without losing your
3026 place or invalidating your iterator. Note that in this case
3027 the current entry is deleted from the hash with your iterator
3028 holding the last reference to it. Your iterator is flagged to
3029 free the entry on the next call to "hv_iternext", so you must
3030 not discard your iterator immediately else the entry will leak
3031 - call "hv_iternext" to trigger the resource deallocation.
3032 HE* hv_iternext(HV *hv)
3034 hv_iternextsv
3036 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in
3037 one operation.
3038 SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
3040 hv_iternext_flags
3042 NOTE: this function is experimental and may change or be
3043 removed without notice.
3044 Returns entries from a hash iterator. See "hv_iterinit" and
3046 "hv_iternext". The "flags" value will normally be zero; if
3047 "HV_ITERNEXT_WANTPLACEHOLDERS" is set the placeholders keys
3048 (for restricted hashes) will be returned in addition to normal
3049 keys. By default placeholders are automatically skipped over.
3050 Currently a placeholder is implemented with a value that is
3051 &PL_sv_placeholder. Note that the implementation of
3052 placeholders and restricted hashes may change, and the
3053 implementation currently is insufficiently abstracted for any
3054 change to be tidy.
3055 HE* hv_iternext_flags(HV *hv, I32 flags)
3057 hv_iterval
3059 Returns the value from the current position of the hash
3060 iterator. See "hv_iterkey".
3061 SV* hv_iterval(HV *hv, HE *entry)
3063 hv_magic
3065 Adds magic to a hash. See "sv_magic".
3066 void hv_magic(HV *hv, GV *gv, int how)
3068 HvNAME Returns the package name of a stash, or "NULL" if "stash" isn't
3070 a stash. See "SvSTASH", "CvSTASH".
3071 char* HvNAME(HV* stash)
3073 HvNAMELEN
3075 Returns the length of the stash's name.
3076 STRLEN HvNAMELEN(HV *stash)
3078 HvNAMEUTF8
3080 Returns true if the name is in UTF-8 encoding.
3081 unsigned char HvNAMEUTF8(HV *stash)
3083 hv_scalar
3085 Evaluates the hash in scalar context and returns the result.
3086 When the hash is tied dispatches through to the SCALAR method,
3088 otherwise returns a mortal SV containing the number of keys in
3089 the hash.
3090 Note, prior to 5.25 this function returned what is now returned
3092 by the hv_bucket_ratio() function.
3093 SV* hv_scalar(HV *hv)
3095 hv_store
3097 Stores an SV in a hash. The hash key is specified as "key" and
3098 the absolute value of "klen" is the length of the key. If
3099 "klen" is negative the key is assumed to be in UTF-8-encoded
3100 Unicode. The "hash" parameter is the precomputed hash value;
3101 if it is zero then Perl will compute it.
3102 The return value will be "NULL" if the operation failed or if
3104 the value did not need to be actually stored within the hash
3105 (as in the case of tied hashes). Otherwise it can be
3106 dereferenced to get the original "SV*". Note that the caller
3107 is responsible for suitably incrementing the reference count of
3108 "val" before the call, and decrementing it if the function
3109 returned "NULL". Effectively a successful "hv_store" takes
3110 ownership of one reference to "val". This is usually what you
3111 want; a newly created SV has a reference count of one, so if
3112 all your code does is create SVs then store them in a hash,
3113 "hv_store" will own the only reference to the new SV, and your
3114 code doesn't need to do anything further to tidy up.
3115 "hv_store" is not implemented as a call to "hv_store_ent", and
3116 does not create a temporary SV for the key, so if your key data
3117 is not already in SV form then use "hv_store" in preference to
3118 "hv_store_ent".
3119 See "Understanding the Magic of Tied Hashes and Arrays" in
3121 perlguts for more information on how to use this function on
3122 tied hashes.
3123 SV** hv_store(HV *hv, const char *key, I32 klen,
3125 SV *val, U32 hash)
3126 hv_stores
3128 Like "hv_store", but takes a literal string instead of a
3129 string/length pair and omits the hash parameter.
3130 SV** hv_stores(HV* tb, "key", SV* val)
3132 hv_store_ent
3134 Stores "val" in a hash. The hash key is specified as "key".
3135 The "hash" parameter is the precomputed hash value; if it is
3136 zero then Perl will compute it. The return value is the new
3137 hash entry so created. It will be "NULL" if the operation
3138 failed or if the value did not need to be actually stored
3139 within the hash (as in the case of tied hashes). Otherwise the
3140 contents of the return value can be accessed using the "He?"
3141 macros described here. Note that the caller is responsible for
3142 suitably incrementing the reference count of "val" before the
3143 call, and decrementing it if the function returned NULL.
3144 Effectively a successful "hv_store_ent" takes ownership of one
3145 reference to "val". This is usually what you want; a newly
3146 created SV has a reference count of one, so if all your code
3147 does is create SVs then store them in a hash, "hv_store" will
3148 own the only reference to the new SV, and your code doesn't
3149 need to do anything further to tidy up. Note that
3150 "hv_store_ent" only reads the "key"; unlike "val" it does not
3151 take ownership of it, so maintaining the correct reference
3152 count on "key" is entirely the caller's responsibility. The
3153 reason it does not take ownership, is that "key" is not used
3154 after this function returns, and so can be freed immediately.
3155 "hv_store" is not implemented as a call to "hv_store_ent", and
3156 does not create a temporary SV for the key, so if your key data
3157 is not already in SV form then use "hv_store" in preference to
3158 "hv_store_ent".
3159 See "Understanding the Magic of Tied Hashes and Arrays" in
3161 perlguts for more information on how to use this function on
3162 tied hashes.
3163 HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
3165 hv_undef
3167 Undefines the hash. The XS equivalent of "undef(%hash)".
3168 As well as freeing all the elements of the hash (like
3170 "hv_clear()"), this also frees any auxiliary data and storage
3171 associated with the hash.
3172 See "av_clear" for a note about the hash possibly being invalid
3174 on return.
3175 void hv_undef(HV *hv)
3177 newHV Creates a new HV. The reference count is set to 1.
3179 HV* newHV()
3181
3183 These functions provide convenient and thread-safe means of
3184 manipulating hook variables.
3185 wrap_op_checker
3187 Puts a C function into the chain of check functions for a
3188 specified op type. This is the preferred way to manipulate the
3189 "PL_check" array. "opcode" specifies which type of op is to be
3190 affected. "new_checker" is a pointer to the C function that is
3191 to be added to that opcode's check chain, and "old_checker_p"
3192 points to the storage location where a pointer to the next
3193 function in the chain will be stored. The value of
3194 "new_checker" is written into the "PL_check" array, while the
3195 value previously stored there is written to *old_checker_p.
3196 "PL_check" is global to an entire process, and a module wishing
3198 to hook op checking may find itself invoked more than once per
3199 process, typically in different threads. To handle that
3200 situation, this function is idempotent. The location
3201 *old_checker_p must initially (once per process) contain a null
3202 pointer. A C variable of static duration (declared at file
3203 scope, typically also marked "static" to give it internal
3204 linkage) will be implicitly initialised appropriately, if it
3205 does not have an explicit initialiser. This function will only
3206 actually modify the check chain if it finds *old_checker_p to
3207 be null. This function is also thread safe on the small scale.
3208 It uses appropriate locking to avoid race conditions in
3209 accessing "PL_check".
3210 When this function is called, the function referenced by
3212 "new_checker" must be ready to be called, except for
3213 *old_checker_p being unfilled. In a threading situation,
3214 "new_checker" may be called immediately, even before this
3215 function has returned. *old_checker_p will always be
3216 appropriately set before "new_checker" is called. If
3217 "new_checker" decides not to do anything special with an op
3218 that it is given (which is the usual case for most uses of op
3219 check hooking), it must chain the check function referenced by
3220 *old_checker_p.
3221 Taken all together, XS code to hook an op checker should
3223 typically look something like this:
3224 static Perl_check_t nxck_frob;
3226 static OP *myck_frob(pTHX_ OP *op) {
3227 ...
3228 op = nxck_frob(aTHX_ op);
3229 ...
3230 return op;
3231 }
3232 BOOT:
3233 wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
3234 If you want to influence compilation of calls to a specific
3236 subroutine, then use "cv_set_call_checker_flags" rather than
3237 hooking checking of all "entersub" ops.
3238 void wrap_op_checker(Optype opcode,
3240 Perl_check_t new_checker,
3241 Perl_check_t *old_checker_p)
3242
3244 This is the lower layer of the Perl parser, managing characters and
3245 tokens.
3246 lex_bufutf8
3248 NOTE: this function is experimental and may change or be
3249 removed without notice.
3250 Indicates whether the octets in the lexer buffer
3252 ("PL_parser->linestr") should be interpreted as the UTF-8
3253 encoding of Unicode characters. If not, they should be
3254 interpreted as Latin-1 characters. This is analogous to the
3255 "SvUTF8" flag for scalars.
3256 In UTF-8 mode, it is not guaranteed that the lexer buffer
3258 actually contains valid UTF-8. Lexing code must be robust in
3259 the face of invalid encoding.
3260 The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
3262 significant, but not the whole story regarding the input
3263 character encoding. Normally, when a file is being read, the
3264 scalar contains octets and its "SvUTF8" flag is off, but the
3265 octets should be interpreted as UTF-8 if the "use utf8" pragma
3266 is in effect. During a string eval, however, the scalar may
3267 have the "SvUTF8" flag on, and in this case its octets should
3268 be interpreted as UTF-8 unless the "use bytes" pragma is in
3269 effect. This logic may change in the future; use this function
3270 instead of implementing the logic yourself.
3271 bool lex_bufutf8()
3273 lex_discard_to
3275 NOTE: this function is experimental and may change or be
3276 removed without notice.
3277 Discards the first part of the "PL_parser->linestr" buffer, up
3279 to "ptr". The remaining content of the buffer will be moved,
3280 and all pointers into the buffer updated appropriately. "ptr"
3281 must not be later in the buffer than the position of
3282 "PL_parser->bufptr": it is not permitted to discard text that
3283 has yet to be lexed.
3284 Normally it is not necessarily to do this directly, because it
3286 suffices to use the implicit discarding behaviour of
3287 "lex_next_chunk" and things based on it. However, if a token
3288 stretches across multiple lines, and the lexing code has kept
3289 multiple lines of text in the buffer for that purpose, then
3290 after completion of the token it would be wise to explicitly
3291 discard the now-unneeded earlier lines, to avoid future multi-
3292 line tokens growing the buffer without bound.
3293 void lex_discard_to(char* ptr)
3295 lex_grow_linestr
3297 NOTE: this function is experimental and may change or be
3298 removed without notice.
3299 Reallocates the lexer buffer ("PL_parser->linestr") to
3301 accommodate at least "len" octets (including terminating
3302 "NUL"). Returns a pointer to the reallocated buffer. This is
3303 necessary before making any direct modification of the buffer
3304 that would increase its length. "lex_stuff_pvn" provides a
3305 more convenient way to insert text into the buffer.
3306 Do not use "SvGROW" or "sv_grow" directly on
3308 "PL_parser->linestr"; this function updates all of the lexer's
3309 variables that point directly into the buffer.
3310 char* lex_grow_linestr(STRLEN len)
3312 lex_next_chunk
3314 NOTE: this function is experimental and may change or be
3315 removed without notice.
3316 Reads in the next chunk of text to be lexed, appending it to
3318 "PL_parser->linestr". This should be called when lexing code
3319 has looked to the end of the current chunk and wants to know
3320 more. It is usual, but not necessary, for lexing to have
3321 consumed the entirety of the current chunk at this time.
3322 If "PL_parser->bufptr" is pointing to the very end of the
3324 current chunk (i.e., the current chunk has been entirely
3325 consumed), normally the current chunk will be discarded at the
3326 same time that the new chunk is read in. If "flags" has the
3327 "LEX_KEEP_PREVIOUS" bit set, the current chunk will not be
3328 discarded. If the current chunk has not been entirely
3329 consumed, then it will not be discarded regardless of the flag.
3330 Returns true if some new text was added to the buffer, or false
3332 if the buffer has reached the end of the input text.
3333 bool lex_next_chunk(U32 flags)
3335 lex_peek_unichar
3337 NOTE: this function is experimental and may change or be
3338 removed without notice.
3339 Looks ahead one (Unicode) character in the text currently being
3341 lexed. Returns the codepoint (unsigned integer value) of the
3342 next character, or -1 if lexing has reached the end of the
3343 input text. To consume the peeked character, use
3344 "lex_read_unichar".
3345 If the next character is in (or extends into) the next chunk of
3347 input text, the next chunk will be read in. Normally the
3348 current chunk will be discarded at the same time, but if
3349 "flags" has the "LEX_KEEP_PREVIOUS" bit set, then the current
3350 chunk will not be discarded.
3351 If the input is being interpreted as UTF-8 and a UTF-8 encoding
3353 error is encountered, an exception is generated.
3354 I32 lex_peek_unichar(U32 flags)
3356 lex_read_space
3358 NOTE: this function is experimental and may change or be
3359 removed without notice.
3360 Reads optional spaces, in Perl style, in the text currently
3362 being lexed. The spaces may include ordinary whitespace
3363 characters and Perl-style comments. "#line" directives are
3364 processed if encountered. "PL_parser->bufptr" is moved past
3365 the spaces, so that it points at a non-space character (or the
3366 end of the input text).
3367 If spaces extend into the next chunk of input text, the next
3369 chunk will be read in. Normally the current chunk will be
3370 discarded at the same time, but if "flags" has the
3371 "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
3372 discarded.
3373 void lex_read_space(U32 flags)
3375 lex_read_to
3377 NOTE: this function is experimental and may change or be
3378 removed without notice.
3379 Consume text in the lexer buffer, from "PL_parser->bufptr" up
3381 to "ptr". This advances "PL_parser->bufptr" to match "ptr",
3382 performing the correct bookkeeping whenever a newline character
3383 is passed. This is the normal way to consume lexed text.
3384 Interpretation of the buffer's octets can be abstracted out by
3386 using the slightly higher-level functions "lex_peek_unichar"
3387 and "lex_read_unichar".
3388 void lex_read_to(char* ptr)
3390 lex_read_unichar
3392 NOTE: this function is experimental and may change or be
3393 removed without notice.
3394 Reads the next (Unicode) character in the text currently being
3396 lexed. Returns the codepoint (unsigned integer value) of the
3397 character read, and moves "PL_parser->bufptr" past the
3398 character, or returns -1 if lexing has reached the end of the
3399 input text. To non-destructively examine the next character,
3400 use "lex_peek_unichar" instead.
3401 If the next character is in (or extends into) the next chunk of
3403 input text, the next chunk will be read in. Normally the
3404 current chunk will be discarded at the same time, but if
3405 "flags" has the "LEX_KEEP_PREVIOUS" bit set, then the current
3406 chunk will not be discarded.
3407 If the input is being interpreted as UTF-8 and a UTF-8 encoding
3409 error is encountered, an exception is generated.
3410 I32 lex_read_unichar(U32 flags)
3412 lex_start
3414 NOTE: this function is experimental and may change or be
3415 removed without notice.
3416 Creates and initialises a new lexer/parser state object,
3418 supplying a context in which to lex and parse from a new source
3419 of Perl code. A pointer to the new state object is placed in
3420 "PL_parser". An entry is made on the save stack so that upon
3421 unwinding, the new state object will be destroyed and the
3422 former value of "PL_parser" will be restored. Nothing else
3423 need be done to clean up the parsing context.
3424 The code to be parsed comes from "line" and "rsfp". "line", if
3426 non-null, provides a string (in SV form) containing code to be
3427 parsed. A copy of the string is made, so subsequent
3428 modification of "line" does not affect parsing. "rsfp", if
3429 non-null, provides an input stream from which code will be read
3430 to be parsed. If both are non-null, the code in "line" comes
3431 first and must consist of complete lines of input, and "rsfp"
3432 supplies the remainder of the source.
3433 The "flags" parameter is reserved for future use. Currently it
3435 is only used by perl internally, so extensions should always
3436 pass zero.
3437 void lex_start(SV* line, PerlIO *rsfp, U32 flags)
3439 lex_stuff_pv
3441 NOTE: this function is experimental and may change or be
3442 removed without notice.
3443 Insert characters into the lexer buffer ("PL_parser->linestr"),
3445 immediately after the current lexing point
3446 ("PL_parser->bufptr"), reallocating the buffer if necessary.
3447 This means that lexing code that runs later will see the
3448 characters as if they had appeared in the input. It is not
3449 recommended to do this as part of normal parsing, and most uses
3450 of this facility run the risk of the inserted characters being
3451 interpreted in an unintended manner.
3452 The string to be inserted is represented by octets starting at
3454 "pv" and continuing to the first nul. These octets are
3455 interpreted as either UTF-8 or Latin-1, according to whether
3456 the "LEX_STUFF_UTF8" flag is set in "flags". The characters
3457 are recoded for the lexer buffer, according to how the buffer
3458 is currently being interpreted ("lex_bufutf8"). If it is not
3459 convenient to nul-terminate a string to be inserted, the
3460 "lex_stuff_pvn" function is more appropriate.
3461 void lex_stuff_pv(const char* pv, U32 flags)
3463 lex_stuff_pvn
3465 NOTE: this function is experimental and may change or be
3466 removed without notice.
3467 Insert characters into the lexer buffer ("PL_parser->linestr"),
3469 immediately after the current lexing point
3470 ("PL_parser->bufptr"), reallocating the buffer if necessary.
3471 This means that lexing code that runs later will see the
3472 characters as if they had appeared in the input. It is not
3473 recommended to do this as part of normal parsing, and most uses
3474 of this facility run the risk of the inserted characters being
3475 interpreted in an unintended manner.
3476 The string to be inserted is represented by "len" octets
3478 starting at "pv". These octets are interpreted as either UTF-8
3479 or Latin-1, according to whether the "LEX_STUFF_UTF8" flag is
3480 set in "flags". The characters are recoded for the lexer
3481 buffer, according to how the buffer is currently being
3482 interpreted ("lex_bufutf8"). If a string to be inserted is
3483 available as a Perl scalar, the "lex_stuff_sv" function is more
3484 convenient.
3485 void lex_stuff_pvn(const char* pv, STRLEN len,
3487 U32 flags)
3488 lex_stuff_pvs
3490 NOTE: this function is experimental and may change or be
3491 removed without notice.
3492 Like "lex_stuff_pvn", but takes a literal string instead of a
3494 string/length pair.
3495 void lex_stuff_pvs("pv", U32 flags)
3497 lex_stuff_sv
3499 NOTE: this function is experimental and may change or be
3500 removed without notice.
3501 Insert characters into the lexer buffer ("PL_parser->linestr"),
3503 immediately after the current lexing point
3504 ("PL_parser->bufptr"), reallocating the buffer if necessary.
3505 This means that lexing code that runs later will see the
3506 characters as if they had appeared in the input. It is not
3507 recommended to do this as part of normal parsing, and most uses
3508 of this facility run the risk of the inserted characters being
3509 interpreted in an unintended manner.
3510 The string to be inserted is the string value of "sv". The
3512 characters are recoded for the lexer buffer, according to how
3513 the buffer is currently being interpreted ("lex_bufutf8"). If
3514 a string to be inserted is not already a Perl scalar, the
3515 "lex_stuff_pvn" function avoids the need to construct a scalar.
3516 void lex_stuff_sv(SV* sv, U32 flags)
3518 lex_unstuff
3520 NOTE: this function is experimental and may change or be
3521 removed without notice.
3522 Discards text about to be lexed, from "PL_parser->bufptr" up to
3524 "ptr". Text following "ptr" will be moved, and the buffer
3525 shortened. This hides the discarded text from any lexing code
3526 that runs later, as if the text had never appeared.
3527 This is not the normal way to consume lexed text. For that,
3529 use "lex_read_to".
3530 void lex_unstuff(char* ptr)
3532 parse_arithexpr
3534 NOTE: this function is experimental and may change or be
3535 removed without notice.
3536 Parse a Perl arithmetic expression. This may contain operators
3538 of precedence down to the bit shift operators. The expression
3539 must be followed (and thus terminated) either by a comparison
3540 or lower-precedence operator or by something that would
3541 normally terminate an expression such as semicolon. If "flags"
3542 has the "PARSE_OPTIONAL" bit set, then the expression is
3543 optional, otherwise it is mandatory. It is up to the caller to
3544 ensure that the dynamic parser state ("PL_parser" et al) is
3545 correctly set to reflect the source of the code to be parsed
3546 and the lexical context for the expression.
3547 The op tree representing the expression is returned. If an
3549 optional expression is absent, a null pointer is returned,
3550 otherwise the pointer will be non-null.
3551 If an error occurs in parsing or compilation, in most cases a
3553 valid op tree is returned anyway. The error is reflected in
3554 the parser state, normally resulting in a single exception at
3555 the top level of parsing which covers all the compilation
3556 errors that occurred. Some compilation errors, however, will
3557 throw an exception immediately.
3558 OP* parse_arithexpr(U32 flags)
3560 parse_barestmt
3562 NOTE: this function is experimental and may change or be
3563 removed without notice.
3564 Parse a single unadorned Perl statement. This may be a normal
3566 imperative statement or a declaration that has compile-time
3567 effect. It does not include any label or other affixture. It
3568 is up to the caller to ensure that the dynamic parser state
3569 ("PL_parser" et al) is correctly set to reflect the source of
3570 the code to be parsed and the lexical context for the
3571 statement.
3572 The op tree representing the statement is returned. This may
3574 be a null pointer if the statement is null, for example if it
3575 was actually a subroutine definition (which has compile-time
3576 side effects). If not null, it will be ops directly
3577 implementing the statement, suitable to pass to "newSTATEOP".
3578 It will not normally include a "nextstate" or equivalent op
3579 (except for those embedded in a scope contained entirely within
3580 the statement).
3581 If an error occurs in parsing or compilation, in most cases a
3583 valid op tree (most likely null) is returned anyway. The error
3584 is reflected in the parser state, normally resulting in a
3585 single exception at the top level of parsing which covers all
3586 the compilation errors that occurred. Some compilation errors,
3587 however, will throw an exception immediately.
3588 The "flags" parameter is reserved for future use, and must
3590 always be zero.
3591 OP* parse_barestmt(U32 flags)
3593 parse_block
3595 NOTE: this function is experimental and may change or be
3596 removed without notice.
3597 Parse a single complete Perl code block. This consists of an
3599 opening brace, a sequence of statements, and a closing brace.
3600 The block constitutes a lexical scope, so "my" variables and
3601 various compile-time effects can be contained within it. It is
3602 up to the caller to ensure that the dynamic parser state
3603 ("PL_parser" et al) is correctly set to reflect the source of
3604 the code to be parsed and the lexical context for the
3605 statement.
3606 The op tree representing the code block is returned. This is
3608 always a real op, never a null pointer. It will normally be a
3609 "lineseq" list, including "nextstate" or equivalent ops. No
3610 ops to construct any kind of runtime scope are included by
3611 virtue of it being a block.
3612 If an error occurs in parsing or compilation, in most cases a
3614 valid op tree (most likely null) is returned anyway. The error
3615 is reflected in the parser state, normally resulting in a
3616 single exception at the top level of parsing which covers all
3617 the compilation errors that occurred. Some compilation errors,
3618 however, will throw an exception immediately.
3619 The "flags" parameter is reserved for future use, and must
3621 always be zero.
3622 OP* parse_block(U32 flags)
3624 parse_fullexpr
3626 NOTE: this function is experimental and may change or be
3627 removed without notice.
3628 Parse a single complete Perl expression. This allows the full
3630 expression grammar, including the lowest-precedence operators
3631 such as "or". The expression must be followed (and thus
3632 terminated) by a token that an expression would normally be
3633 terminated by: end-of-file, closing bracketing punctuation,
3634 semicolon, or one of the keywords that signals a postfix
3635 expression-statement modifier. If "flags" has the
3636 "PARSE_OPTIONAL" bit set, then the expression is optional,
3637 otherwise it is mandatory. It is up to the caller to ensure
3638 that the dynamic parser state ("PL_parser" et al) is correctly
3639 set to reflect the source of the code to be parsed and the
3640 lexical context for the expression.
3641 The op tree representing the expression is returned. If an
3643 optional expression is absent, a null pointer is returned,
3644 otherwise the pointer will be non-null.
3645 If an error occurs in parsing or compilation, in most cases a
3647 valid op tree is returned anyway. The error is reflected in
3648 the parser state, normally resulting in a single exception at
3649 the top level of parsing which covers all the compilation
3650 errors that occurred. Some compilation errors, however, will
3651 throw an exception immediately.
3652 OP* parse_fullexpr(U32 flags)
3654 parse_fullstmt
3656 NOTE: this function is experimental and may change or be
3657 removed without notice.
3658 Parse a single complete Perl statement. This may be a normal
3660 imperative statement or a declaration that has compile-time
3661 effect, and may include optional labels. It is up to the
3662 caller to ensure that the dynamic parser state ("PL_parser" et
3663 al) is correctly set to reflect the source of the code to be
3664 parsed and the lexical context for the statement.
3665 The op tree representing the statement is returned. This may
3667 be a null pointer if the statement is null, for example if it
3668 was actually a subroutine definition (which has compile-time
3669 side effects). If not null, it will be the result of a
3670 "newSTATEOP" call, normally including a "nextstate" or
3671 equivalent op.
3672 If an error occurs in parsing or compilation, in most cases a
3674 valid op tree (most likely null) is returned anyway. The error
3675 is reflected in the parser state, normally resulting in a
3676 single exception at the top level of parsing which covers all
3677 the compilation errors that occurred. Some compilation errors,
3678 however, will throw an exception immediately.
3679 The "flags" parameter is reserved for future use, and must
3681 always be zero.
3682 OP* parse_fullstmt(U32 flags)
3684 parse_label
3686 NOTE: this function is experimental and may change or be
3687 removed without notice.
3688 Parse a single label, possibly optional, of the type that may
3690 prefix a Perl statement. It is up to the caller to ensure that
3691 the dynamic parser state ("PL_parser" et al) is correctly set
3692 to reflect the source of the code to be parsed. If "flags" has
3693 the "PARSE_OPTIONAL" bit set, then the label is optional,
3694 otherwise it is mandatory.
3695 The name of the label is returned in the form of a fresh
3697 scalar. If an optional label is absent, a null pointer is
3698 returned.
3699 If an error occurs in parsing, which can only occur if the
3701 label is mandatory, a valid label is returned anyway. The
3702 error is reflected in the parser state, normally resulting in a
3703 single exception at the top level of parsing which covers all
3704 the compilation errors that occurred.
3705 SV* parse_label(U32 flags)
3707 parse_listexpr
3709 NOTE: this function is experimental and may change or be
3710 removed without notice.
3711 Parse a Perl list expression. This may contain operators of
3713 precedence down to the comma operator. The expression must be
3714 followed (and thus terminated) either by a low-precedence logic
3715 operator such as "or" or by something that would normally
3716 terminate an expression such as semicolon. If "flags" has the
3717 "PARSE_OPTIONAL" bit set, then the expression is optional,
3718 otherwise it is mandatory. It is up to the caller to ensure
3719 that the dynamic parser state ("PL_parser" et al) is correctly
3720 set to reflect the source of the code to be parsed and the
3721 lexical context for the expression.
3722 The op tree representing the expression is returned. If an
3724 optional expression is absent, a null pointer is returned,
3725 otherwise the pointer will be non-null.
3726 If an error occurs in parsing or compilation, in most cases a
3728 valid op tree is returned anyway. The error is reflected in
3729 the parser state, normally resulting in a single exception at
3730 the top level of parsing which covers all the compilation
3731 errors that occurred. Some compilation errors, however, will
3732 throw an exception immediately.
3733 OP* parse_listexpr(U32 flags)
3735 parse_stmtseq
3737 NOTE: this function is experimental and may change or be
3738 removed without notice.
3739 Parse a sequence of zero or more Perl statements. These may be
3741 normal imperative statements, including optional labels, or
3742 declarations that have compile-time effect, or any mixture
3743 thereof. The statement sequence ends when a closing brace or
3744 end-of-file is encountered in a place where a new statement
3745 could have validly started. It is up to the caller to ensure
3746 that the dynamic parser state ("PL_parser" et al) is correctly
3747 set to reflect the source of the code to be parsed and the
3748 lexical context for the statements.
3749 The op tree representing the statement sequence is returned.
3751 This may be a null pointer if the statements were all null, for
3752 example if there were no statements or if there were only
3753 subroutine definitions (which have compile-time side effects).
3754 If not null, it will be a "lineseq" list, normally including
3755 "nextstate" or equivalent ops.
3756 If an error occurs in parsing or compilation, in most cases a
3758 valid op tree is returned anyway. The error is reflected in
3759 the parser state, normally resulting in a single exception at
3760 the top level of parsing which covers all the compilation
3761 errors that occurred. Some compilation errors, however, will
3762 throw an exception immediately.
3763 The "flags" parameter is reserved for future use, and must
3765 always be zero.
3766 OP* parse_stmtseq(U32 flags)
3768 parse_subsignature
3770 NOTE: this function is experimental and may change or be
3771 removed without notice.
3772 Parse a subroutine signature declaration. This is the contents
3774 of the parentheses following a named or anonymous subroutine
3775 declaration when the "signatures" feature is enabled. Note that
3776 this function neither expects nor consumes the opening and
3777 closing parentheses around the signature; it is the caller's
3778 job to handle these.
3779 This function must only be called during parsing of a
3781 subroutine; after "start_subparse" has been called. It might
3782 allocate lexical variables on the pad for the current
3783 subroutine.
3784 The op tree to unpack the arguments from the stack at runtime
3786 is returned. This op tree should appear at the beginning of
3787 the compiled function. The caller may wish to use
3788 "op_append_list" to build their function body after it, or
3789 splice it together with the body before calling "newATTRSUB".
3790 The "flags" parameter is reserved for future use, and must
3792 always be zero.
3793 OP* parse_subsignature(U32 flags)
3795 parse_termexpr
3797 NOTE: this function is experimental and may change or be
3798 removed without notice.
3799 Parse a Perl term expression. This may contain operators of
3801 precedence down to the assignment operators. The expression
3802 must be followed (and thus terminated) either by a comma or
3803 lower-precedence operator or by something that would normally
3804 terminate an expression such as semicolon. If "flags" has the
3805 "PARSE_OPTIONAL" bit set, then the expression is optional,
3806 otherwise it is mandatory. It is up to the caller to ensure
3807 that the dynamic parser state ("PL_parser" et al) is correctly
3808 set to reflect the source of the code to be parsed and the
3809 lexical context for the expression.
3810 The op tree representing the expression is returned. If an
3812 optional expression is absent, a null pointer is returned,
3813 otherwise the pointer will be non-null.
3814 If an error occurs in parsing or compilation, in most cases a
3816 valid op tree is returned anyway. The error is reflected in
3817 the parser state, normally resulting in a single exception at
3818 the top level of parsing which covers all the compilation
3819 errors that occurred. Some compilation errors, however, will
3820 throw an exception immediately.
3821 OP* parse_termexpr(U32 flags)
3823 PL_parser
3825 Pointer to a structure encapsulating the state of the parsing
3826 operation currently in progress. The pointer can be locally
3827 changed to perform a nested parse without interfering with the
3828 state of an outer parse. Individual members of "PL_parser"
3829 have their own documentation.
3830 PL_parser->bufend
3832 NOTE: this function is experimental and may change or be
3833 removed without notice.
3834 Direct pointer to the end of the chunk of text currently being
3836 lexed, the end of the lexer buffer. This is equal to
3837 "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)". A
3838 "NUL" character (zero octet) is always located at the end of
3839 the buffer, and does not count as part of the buffer's
3840 contents.
3841 PL_parser->bufptr
3843 NOTE: this function is experimental and may change or be
3844 removed without notice.
3845 Points to the current position of lexing inside the lexer
3847 buffer. Characters around this point may be freely examined,
3848 within the range delimited by "SvPVX("PL_parser->linestr")" and
3849 "PL_parser->bufend". The octets of the buffer may be intended
3850 to be interpreted as either UTF-8 or Latin-1, as indicated by
3851 "lex_bufutf8".
3852 Lexing code (whether in the Perl core or not) moves this
3854 pointer past the characters that it consumes. It is also
3855 expected to perform some bookkeeping whenever a newline
3856 character is consumed. This movement can be more conveniently
3857 performed by the function "lex_read_to", which handles newlines
3858 appropriately.
3859 Interpretation of the buffer's octets can be abstracted out by
3861 using the slightly higher-level functions "lex_peek_unichar"
3862 and "lex_read_unichar".
3863 PL_parser->linestart
3865 NOTE: this function is experimental and may change or be
3866 removed without notice.
3867 Points to the start of the current line inside the lexer
3869 buffer. This is useful for indicating at which column an error
3870 occurred, and not much else. This must be updated by any
3871 lexing code that consumes a newline; the function "lex_read_to"
3872 handles this detail.
3873 PL_parser->linestr
3875 NOTE: this function is experimental and may change or be
3876 removed without notice.
3877 Buffer scalar containing the chunk currently under
3879 consideration of the text currently being lexed. This is
3880 always a plain string scalar (for which "SvPOK" is true). It
3881 is not intended to be used as a scalar by normal scalar means;
3882 instead refer to the buffer directly by the pointer variables
3883 described below.
3884 The lexer maintains various "char*" pointers to things in the
3886 "PL_parser->linestr" buffer. If "PL_parser->linestr" is ever
3887 reallocated, all of these pointers must be updated. Don't
3888 attempt to do this manually, but rather use "lex_grow_linestr"
3889 if you need to reallocate the buffer.
3890 The content of the text chunk in the buffer is commonly exactly
3892 one complete line of input, up to and including a newline
3893 terminator, but there are situations where it is otherwise.
3894 The octets of the buffer may be intended to be interpreted as
3895 either UTF-8 or Latin-1. The function "lex_bufutf8" tells you
3896 which. Do not use the "SvUTF8" flag on this scalar, which may
3897 disagree with it.
3898 For direct examination of the buffer, the variable
3900 "PL_parser->bufend" points to the end of the buffer. The
3901 current lexing position is pointed to by "PL_parser->bufptr".
3902 Direct use of these pointers is usually preferable to
3903 examination of the scalar through normal scalar means.
3904 wrap_keyword_plugin
3906 NOTE: this function is experimental and may change or be
3907 removed without notice.
3908 Puts a C function into the chain of keyword plugins. This is
3910 the preferred way to manipulate the "PL_keyword_plugin"
3911 variable. "new_plugin" is a pointer to the C function that is
3912 to be added to the keyword plugin chain, and "old_plugin_p"
3913 points to the storage location where a pointer to the next
3914 function in the chain will be stored. The value of
3915 "new_plugin" is written into the "PL_keyword_plugin" variable,
3916 while the value previously stored there is written to
3917 *old_plugin_p.
3918 "PL_keyword_plugin" is global to an entire process, and a
3920 module wishing to hook keyword parsing may find itself invoked
3921 more than once per process, typically in different threads. To
3922 handle that situation, this function is idempotent. The
3923 location *old_plugin_p must initially (once per process)
3924 contain a null pointer. A C variable of static duration
3925 (declared at file scope, typically also marked "static" to give
3926 it internal linkage) will be implicitly initialised
3927 appropriately, if it does not have an explicit initialiser.
3928 This function will only actually modify the plugin chain if it
3929 finds *old_plugin_p to be null. This function is also thread
3930 safe on the small scale. It uses appropriate locking to avoid
3931 race conditions in accessing "PL_keyword_plugin".
3932 When this function is called, the function referenced by
3934 "new_plugin" must be ready to be called, except for
3935 *old_plugin_p being unfilled. In a threading situation,
3936 "new_plugin" may be called immediately, even before this
3937 function has returned. *old_plugin_p will always be
3938 appropriately set before "new_plugin" is called. If
3939 "new_plugin" decides not to do anything special with the
3940 identifier that it is given (which is the usual case for most
3941 calls to a keyword plugin), it must chain the plugin function
3942 referenced by *old_plugin_p.
3943 Taken all together, XS code to install a keyword plugin should
3945 typically look something like this:
3946 static Perl_keyword_plugin_t next_keyword_plugin;
3948 static OP *my_keyword_plugin(pTHX_
3949 char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
3950 {
3951 if (memEQs(keyword_ptr, keyword_len,
3952 "my_new_keyword")) {
3953 ...
3954 } else {
3955 return next_keyword_plugin(aTHX_
3956 keyword_ptr, keyword_len, op_ptr);
3957 }
3958 }
3959 BOOT:
3960 wrap_keyword_plugin(my_keyword_plugin,
3961 &next_keyword_plugin);
3962 Direct access to "PL_keyword_plugin" should be avoided.
3964 void wrap_keyword_plugin(
3966 Perl_keyword_plugin_t new_plugin,
3967 Perl_keyword_plugin_t *old_plugin_p
3968 )
3969
3971 DECLARATION_FOR_LC_NUMERIC_MANIPULATION
3972 This macro should be used as a statement. It declares a
3973 private variable (whose name begins with an underscore) that is
3974 needed by the other macros in this section. Failing to include
3975 this correctly should lead to a syntax error. For
3976 compatibility with C89 C compilers it should be placed in a
3977 block before any executable statements.
3978 void DECLARATION_FOR_LC_NUMERIC_MANIPULATION
3980 IN_LOCALE
3982 Evaluates to TRUE if the plain locale pragma without a
3983 parameter ("use locale") is in effect.
3984 bool IN_LOCALE
3986 IN_LOCALE_COMPILETIME
3988 Evaluates to TRUE if, when compiling a perl program (including
3989 an "eval") if the plain locale pragma without a parameter
3990 ("use locale") is in effect.
3991 bool IN_LOCALE_COMPILETIME
3993 IN_LOCALE_RUNTIME
3995 Evaluates to TRUE if, when executing a perl program (including
3996 an "eval") if the plain locale pragma without a parameter
3997 ("use locale") is in effect.
3998 bool IN_LOCALE_RUNTIME
4000 Perl_langinfo
4002 This is an (almost) drop-in replacement for the system
4003 nl_langinfo(3), taking the same "item" parameter values, and
4004 returning the same information. But it is more thread-safe
4005 than regular "nl_langinfo()", and hides the quirks of Perl's
4006 locale handling from your code, and can be used on systems that
4007 lack a native "nl_langinfo".
4008 Expanding on these:
4010 • The reason it isn't quite a drop-in replacement is actually
4012 an advantage. The only difference is that it returns
4013 "const char *", whereas plain "nl_langinfo()" returns
4014 "char *", but you are (only by documentation) forbidden to
4015 write into the buffer. By declaring this "const", the
4016 compiler enforces this restriction, so if it is violated,
4017 you know at compilation time, rather than getting segfaults
4018 at runtime.
4019 • It delivers the correct results for the "RADIXCHAR" and
4021 "THOUSEP" items, without you having to write extra code.
4022 The reason for the extra code would be because these are
4023 from the "LC_NUMERIC" locale category, which is normally
4024 kept set by Perl so that the radix is a dot, and the
4025 separator is the empty string, no matter what the
4026 underlying locale is supposed to be, and so to get the
4027 expected results, you have to temporarily toggle into the
4028 underlying locale, and later toggle back. (You could use
4029 plain "nl_langinfo" and
4030 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" for this but then
4031 you wouldn't get the other advantages of "Perl_langinfo()";
4032 not keeping "LC_NUMERIC" in the C (or equivalent) locale
4033 would break a lot of CPAN, which is expecting the radix
4034 (decimal point) character to be a dot.)
4035 • The system function it replaces can have its static return
4037 buffer trashed, not only by a subesequent call to that
4038 function, but by a "freelocale", "setlocale", or other
4039 locale change. The returned buffer of this function is not
4040 changed until the next call to it, so the buffer is never
4041 in a trashed state.
4042 • Its return buffer is per-thread, so it also is never
4044 overwritten by a call to this function from another thread;
4045 unlike the function it replaces.
4046 • But most importantly, it works on systems that don't have
4048 "nl_langinfo", such as Windows, hence makes your code more
4049 portable. Of the fifty-some possible items specified by
4050 the POSIX 2008 standard,
4051 <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
4052 only one is completely unimplemented, though on non-Windows
4053 platforms, another significant one is also not
4054 implemented). It uses various techniques to recover the
4055 other items, including calling localeconv(3), and
4056 strftime(3), both of which are specified in C89, so should
4057 be always be available. Later "strftime()" versions have
4058 additional capabilities; "" is returned for those not
4059 available on your system.
4060 It is important to note that when called with an item that
4062 is recovered by using "localeconv", the buffer from any
4063 previous explicit call to "localeconv" will be overwritten.
4064 This means you must save that buffer's contents if you need
4065 to access them after a call to this function. (But note
4066 that you might not want to be using "localeconv()" directly
4067 anyway, because of issues like the ones listed in the
4068 second item of this list (above) for "RADIXCHAR" and
4069 "THOUSEP". You can use the methods given in perlcall to
4070 call "localeconv" in POSIX and avoid all the issues, but
4071 then you have a hash to unpack).
4072 The details for those items which may deviate from what
4074 this emulation returns and what a native "nl_langinfo()"
4075 would return are specified in I18N::Langinfo.
4076 When using "Perl_langinfo" on systems that don't have a native
4078 "nl_langinfo()", you must
4079 #include "perl_langinfo.h"
4081 before the "perl.h" "#include". You can replace your
4083 "langinfo.h" "#include" with this one. (Doing it this way
4084 keeps out the symbols that plain "langinfo.h" would try to
4085 import into the namespace for code that doesn't need it.)
4086 The original impetus for "Perl_langinfo()" was so that code
4088 that needs to find out the current currency symbol, floating
4089 point radix character, or digit grouping separator can use, on
4090 all systems, the simpler and more thread-friendly "nl_langinfo"
4091 API instead of localeconv(3) which is a pain to make thread-
4092 friendly. For other fields returned by "localeconv", it is
4093 better to use the methods given in perlcall to call
4094 "POSIX::localeconv()", which is thread-friendly.
4095 const char* Perl_langinfo(const nl_item item)
4097 Perl_setlocale
4099 This is an (almost) drop-in replacement for the system
4100 setlocale(3), taking the same parameters, and returning the
4101 same information, except that it returns the correct underlying
4102 "LC_NUMERIC" locale. Regular "setlocale" will instead return
4103 "C" if the underlying locale has a non-dot decimal point
4104 character, or a non-empty thousands separator for displaying
4105 floating point numbers. This is because perl keeps that locale
4106 category such that it has a dot and empty separator, changing
4107 the locale briefly during the operations where the underlying
4108 one is required. "Perl_setlocale" knows about this, and
4109 compensates; regular "setlocale" doesn't.
4110 Another reason it isn't completely a drop-in replacement is
4112 that it is declared to return "const char *", whereas the
4113 system setlocale omits the "const" (presumably because its API
4114 was specified long ago, and can't be updated; it is illegal to
4115 change the information "setlocale" returns; doing so leads to
4116 segfaults.)
4117 Finally, "Perl_setlocale" works under all circumstances,
4119 whereas plain "setlocale" can be completely ineffective on some
4120 platforms under some configurations.
4121 "Perl_setlocale" should not be used to change the locale except
4123 on systems where the predefined variable "${^SAFE_LOCALES}" is
4124 1. On some such systems, the system "setlocale()" is
4125 ineffective, returning the wrong information, and failing to
4126 actually change the locale. "Perl_setlocale", however works
4127 properly in all circumstances.
4128 The return points to a per-thread static buffer, which is
4130 overwritten the next time "Perl_setlocale" is called from the
4131 same thread.
4132 const char* Perl_setlocale(const int category,
4134 const char* locale)
4135 RESTORE_LC_NUMERIC
4137 This is used in conjunction with one of the macros
4138 "STORE_LC_NUMERIC_SET_TO_NEEDED" and
4139 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
4140 "LC_NUMERIC" state.
4141 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
4143 been made to declare at compile time a private variable used by
4144 this macro and the two "STORE" ones. This macro should be
4145 called as a single statement, not an expression, but with an
4146 empty argument list, like this:
4147 {
4149 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4150 ...
4151 RESTORE_LC_NUMERIC();
4152 ...
4153 }
4154 void RESTORE_LC_NUMERIC()
4156 STORE_LC_NUMERIC_FORCE_TO_UNDERLYING
4158 This is used by XS code that is "LC_NUMERIC" locale-aware to
4159 force the locale for category "LC_NUMERIC" to be what perl
4160 thinks is the current underlying locale. (The perl interpreter
4161 could be wrong about what the underlying locale actually is if
4162 some C or XS code has called the C library function
4163 setlocale(3) behind its back; calling "sync_locale" before
4164 calling this macro will update perl's records.)
4165 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
4167 been made to declare at compile time a private variable used by
4168 this macro. This macro should be called as a single statement,
4169 not an expression, but with an empty argument list, like this:
4170 {
4172 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4173 ...
4174 STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
4175 ...
4176 RESTORE_LC_NUMERIC();
4177 ...
4178 }
4179 The private variable is used to save the current locale state,
4181 so that the requisite matching call to "RESTORE_LC_NUMERIC" can
4182 restore it.
4183 On threaded perls not operating with thread-safe functionality,
4185 this macro uses a mutex to force a critical section. Therefore
4186 the matching RESTORE should be close by, and guaranteed to be
4187 called.
4188 void STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
4190 STORE_LC_NUMERIC_SET_TO_NEEDED
4192 This is used to help wrap XS or C code that is "LC_NUMERIC"
4193 locale-aware. This locale category is generally kept set to a
4194 locale where the decimal radix character is a dot, and the
4195 separator between groups of digits is empty. This is because
4196 most XS code that reads floating point numbers is expecting
4197 them to have this syntax.
4198 This macro makes sure the current "LC_NUMERIC" state is set
4200 properly, to be aware of locale if the call to the XS or C code
4201 from the Perl program is from within the scope of a
4202 "use locale"; or to ignore locale if the call is instead from
4203 outside such scope.
4204 This macro is the start of wrapping the C or XS code; the wrap
4206 ending is done by calling the "RESTORE_LC_NUMERIC" macro after
4207 the operation. Otherwise the state can be changed that will
4208 adversely affect other XS code.
4209 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
4211 been made to declare at compile time a private variable used by
4212 this macro. This macro should be called as a single statement,
4213 not an expression, but with an empty argument list, like this:
4214 {
4216 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4217 ...
4218 STORE_LC_NUMERIC_SET_TO_NEEDED();
4219 ...
4220 RESTORE_LC_NUMERIC();
4221 ...
4222 }
4223 On threaded perls not operating with thread-safe functionality,
4225 this macro uses a mutex to force a critical section. Therefore
4226 the matching RESTORE should be close by, and guaranteed to be
4227 called; see "WITH_LC_NUMERIC_SET_TO_NEEDED" for a more
4228 contained way to ensure that.
4229 void STORE_LC_NUMERIC_SET_TO_NEEDED()
4231 STORE_LC_NUMERIC_SET_TO_NEEDED_IN
4233 Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
4234 provided as the precalculated value of "IN_LC(LC_NUMERIC)". It
4235 is the caller's responsibility to ensure that the status of
4236 "PL_compiling" and "PL_hints" cannot have changed since the
4237 precalculation.
4238 void STORE_LC_NUMERIC_SET_TO_NEEDED_IN(
4240 bool in_lc_numeric
4241 )
4242 switch_to_global_locale
4244 On systems without locale support, or on typical single-
4245 threaded builds, or on platforms that do not support per-thread
4246 locale operations, this function does nothing. On such systems
4247 that do have locale support, only a locale global to the whole
4248 program is available.
4249 On multi-threaded builds on systems that do have per-thread
4251 locale operations, this function converts the thread it is
4252 running in to use the global locale. This is for code that has
4253 not yet or cannot be updated to handle multi-threaded locale
4254 operation. As long as only a single thread is so-converted,
4255 everything works fine, as all the other threads continue to
4256 ignore the global one, so only this thread looks at it.
4257 However, on Windows systems this isn't quite true prior to
4259 Visual Studio 15, at which point Microsoft fixed a bug. A race
4260 can occur if you use the following operations on earlier
4261 Windows platforms:
4262 POSIX::localeconv
4264 I18N::Langinfo, items "CRNCYSTR" and "THOUSEP"
4265 "Perl_langinfo" in perlapi, items "CRNCYSTR" and "THOUSEP"
4266 The first item is not fixable (except by upgrading to a later
4268 Visual Studio release), but it would be possible to work around
4269 the latter two items by using the Windows API functions
4270 "GetNumberFormat" and "GetCurrencyFormat"; patches welcome.
4271 Without this function call, threads that use the setlocale(3)
4273 system function will not work properly, as all the locale-
4274 sensitive functions will look at the per-thread locale, and
4275 "setlocale" will have no effect on this thread.
4276 Perl code should convert to either call "Perl_setlocale" (which
4278 is a drop-in for the system "setlocale") or use the methods
4279 given in perlcall to call "POSIX::setlocale". Either one will
4280 transparently properly handle all cases of single- vs multi-
4281 thread, POSIX 2008-supported or not.
4282 Non-Perl libraries, such as "gtk", that call the system
4284 "setlocale" can continue to work if this function is called
4285 before transferring control to the library.
4286 Upon return from the code that needs to use the global locale,
4288 "sync_locale()" should be called to restore the safe multi-
4289 thread operation.
4290 void switch_to_global_locale()
4292 sync_locale
4294 "Perl_setlocale" can be used at any time to query or change the
4295 locale (though changing the locale is antisocial and dangerous
4296 on multi-threaded systems that don't have multi-thread safe
4297 locale operations. (See "Multi-threaded operation" in
4298 perllocale). Using the system setlocale(3) should be avoided.
4299 Nevertheless, certain non-Perl libraries called from XS, such
4300 as "Gtk" do so, and this can't be changed. When the locale is
4301 changed by XS code that didn't use "Perl_setlocale", Perl needs
4302 to be told that the locale has changed. Use this function to
4303 do so, before returning to Perl.
4304 The return value is a boolean: TRUE if the global locale at the
4306 time of call was in effect; and FALSE if a per-thread locale
4307 was in effect. This can be used by the caller that needs to
4308 restore things as-they-were to decide whether or not to call
4309 "Perl_switch_to_global_locale".
4310 bool sync_locale()
4312 WITH_LC_NUMERIC_SET_TO_NEEDED
4314 This macro invokes the supplied statement or block within the
4315 context of a "STORE_LC_NUMERIC_SET_TO_NEEDED" ..
4316 "RESTORE_LC_NUMERIC" pair if required, so eg:
4317 WITH_LC_NUMERIC_SET_TO_NEEDED(
4319 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
4320 );
4321 is equivalent to:
4323 {
4325 #ifdef USE_LOCALE_NUMERIC
4326 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4327 STORE_LC_NUMERIC_SET_TO_NEEDED();
4328 #endif
4329 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
4330 #ifdef USE_LOCALE_NUMERIC
4331 RESTORE_LC_NUMERIC();
4332 #endif
4333 }
4334 void WITH_LC_NUMERIC_SET_TO_NEEDED(block)
4336 WITH_LC_NUMERIC_SET_TO_NEEDED_IN
4338 Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
4339 provided as the precalculated value of "IN_LC(LC_NUMERIC)". It
4340 is the caller's responsibility to ensure that the status of
4341 "PL_compiling" and "PL_hints" cannot have changed since the
4342 precalculation.
4343 void WITH_LC_NUMERIC_SET_TO_NEEDED_IN(
4345 bool in_lc_numeric, block
4346 )
4347
4349 mg_clear
4350 Clear something magical that the SV represents. See
4351 "sv_magic".
4352 int mg_clear(SV* sv)
4354 mg_copy Copies the magic from one SV to another. See "sv_magic".
4356 int mg_copy(SV *sv, SV *nsv, const char *key,
4358 I32 klen)
4359 mg_find Finds the magic pointer for "type" matching the SV. See
4361 "sv_magic".
4362 MAGIC* mg_find(const SV* sv, int type)
4364 mg_findext
4366 Finds the magic pointer of "type" with the given "vtbl" for the
4367 "SV". See "sv_magicext".
4368 MAGIC* mg_findext(const SV* sv, int type,
4370 const MGVTBL *vtbl)
4371 mg_free Free any magic storage used by the SV. See "sv_magic".
4373 int mg_free(SV* sv)
4375 mg_freeext
4377 Remove any magic of type "how" using virtual table "vtbl" from
4378 the SV "sv". See "sv_magic".
4379 "mg_freeext(sv, how, NULL)" is equivalent to "mg_free_type(sv,
4381 how)".
4382 void mg_freeext(SV* sv, int how, const MGVTBL *vtbl)
4384 mg_free_type
4386 Remove any magic of type "how" from the SV "sv". See
4387 "sv_magic".
4388 void mg_free_type(SV* sv, int how)
4390 mg_get Do magic before a value is retrieved from the SV. The type of
4392 SV must be >= "SVt_PVMG". See "sv_magic".
4393 int mg_get(SV* sv)
4395 mg_length
4397 DEPRECATED! It is planned to remove this function from a
4398 future release of Perl. Do not use it for new code; remove it
4399 from existing code.
4400 Reports on the SV's length in bytes, calling length magic if
4402 available, but does not set the UTF8 flag on "sv". It will
4403 fall back to 'get' magic if there is no 'length' magic, but
4404 with no indication as to whether it called 'get' magic. It
4405 assumes "sv" is a "PVMG" or higher. Use "sv_len()" instead.
4406 U32 mg_length(SV* sv)
4408 mg_magical
4410 Turns on the magical status of an SV. See "sv_magic".
4411 void mg_magical(SV* sv)
4413 mg_set Do magic after a value is assigned to the SV. See "sv_magic".
4415 int mg_set(SV* sv)
4417 SvGETMAGIC
4419 Invokes "mg_get" on an SV if it has 'get' magic. For example,
4420 this will call "FETCH" on a tied variable. This macro
4421 evaluates its argument more than once.
4422 void SvGETMAGIC(SV* sv)
4424 SvLOCK Arranges for a mutual exclusion lock to be obtained on "sv" if
4426 a suitable module has been loaded.
4427 void SvLOCK(SV* sv)
4429 SvSETMAGIC
4431 Invokes "mg_set" on an SV if it has 'set' magic. This is
4432 necessary after modifying a scalar, in case it is a magical
4433 variable like $| or a tied variable (it calls "STORE"). This
4434 macro evaluates its argument more than once.
4435 void SvSETMAGIC(SV* sv)
4437 SvSetMagicSV
4439 Like "SvSetSV", but does any set magic required afterwards.
4440 void SvSetMagicSV(SV* dsv, SV* ssv)
4442 SvSetMagicSV_nosteal
4444 Like "SvSetSV_nosteal", but does any set magic required
4445 afterwards.
4446 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
4448 SvSetSV Calls "sv_setsv" if "dsv" is not the same as "ssv". May
4450 evaluate arguments more than once. Does not handle 'set' magic
4451 on the destination SV.
4452 void SvSetSV(SV* dsv, SV* ssv)
4454 SvSetSV_nosteal
4456 Calls a non-destructive version of "sv_setsv" if "dsv" is not
4457 the same as "ssv". May evaluate arguments more than once.
4458 void SvSetSV_nosteal(SV* dsv, SV* ssv)
4460 SvSHARE Arranges for "sv" to be shared between threads if a suitable
4462 module has been loaded.
4463 void SvSHARE(SV* sv)
4465 sv_string_from_errnum
4467 Generates the message string describing an OS error and returns
4468 it as an SV. "errnum" must be a value that "errno" could take,
4469 identifying the type of error.
4470 If "tgtsv" is non-null then the string will be written into
4472 that SV (overwriting existing content) and it will be returned.
4473 If "tgtsv" is a null pointer then the string will be written
4474 into a new mortal SV which will be returned.
4475 The message will be taken from whatever locale would be used by
4477 $!, and will be encoded in the SV in whatever manner would be
4478 used by $!. The details of this process are subject to future
4479 change. Currently, the message is taken from the C locale by
4480 default (usually producing an English message), and from the
4481 currently selected locale when in the scope of the "use locale"
4482 pragma. A heuristic attempt is made to decode the message from
4483 the locale's character encoding, but it will only be decoded as
4484 either UTF-8 or ISO-8859-1. It is always correctly decoded in
4485 a UTF-8 locale, usually in an ISO-8859-1 locale, and never in
4486 any other locale.
4487 The SV is always returned containing an actual string, and with
4489 no other OK bits set. Unlike $!, a message is even yielded for
4490 "errnum" zero (meaning success), and if no useful message is
4491 available then a useless string (currently empty) is returned.
4492 SV* sv_string_from_errnum(int errnum, SV* tgtsv)
4494 SvUNLOCK
4496 Releases a mutual exclusion lock on "sv" if a suitable module
4497 has been loaded.
4498 void SvUNLOCK(SV* sv)
4500
4502 Copy The XSUB-writer's interface to the C "memcpy" function. The
4503 "src" is the source, "dest" is the destination, "nitems" is the
4504 number of items, and "type" is the type. May fail on
4505 overlapping copies. See also "Move".
4506 void Copy(void* src, void* dest, int nitems, type)
4508 CopyD Like "Copy" but returns "dest". Useful for encouraging
4510 compilers to tail-call optimise.
4511 void * CopyD(void* src, void* dest, int nitems, type)
4513 Move The XSUB-writer's interface to the C "memmove" function. The
4515 "src" is the source, "dest" is the destination, "nitems" is the
4516 number of items, and "type" is the type. Can do overlapping
4517 moves. See also "Copy".
4518 void Move(void* src, void* dest, int nitems, type)
4520 MoveD Like "Move" but returns "dest". Useful for encouraging
4522 compilers to tail-call optimise.
4523 void * MoveD(void* src, void* dest, int nitems, type)
4525 Newx The XSUB-writer's interface to the C "malloc" function.
4527 Memory obtained by this should ONLY be freed with "Safefree".
4529 In 5.9.3, Newx() and friends replace the older New() API, and
4531 drops the first parameter, x, a debug aid which allowed callers
4532 to identify themselves. This aid has been superseded by a new
4533 build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in
4534 perlhacktips). The older API is still there for use in XS
4535 modules supporting older perls.
4536 void Newx(void* ptr, int nitems, type)
4538 Newxc The XSUB-writer's interface to the C "malloc" function, with
4540 cast. See also "Newx".
4541 Memory obtained by this should ONLY be freed with "Safefree".
4543 void Newxc(void* ptr, int nitems, type, cast)
4545 Newxz The XSUB-writer's interface to the C "malloc" function. The
4547 allocated memory is zeroed with "memzero". See also "Newx".
4548 Memory obtained by this should ONLY be freed with "Safefree".
4550 void Newxz(void* ptr, int nitems, type)
4552 Poison PoisonWith(0xEF) for catching access to freed memory.
4554 void Poison(void* dest, int nitems, type)
4556 PoisonFree
4558 PoisonWith(0xEF) for catching access to freed memory.
4559 void PoisonFree(void* dest, int nitems, type)
4561 PoisonNew
4563 PoisonWith(0xAB) for catching access to allocated but
4564 uninitialized memory.
4565 void PoisonNew(void* dest, int nitems, type)
4567 PoisonWith
4569 Fill up memory with a byte pattern (a byte repeated over and
4570 over again) that hopefully catches attempts to access
4571 uninitialized memory.
4572 void PoisonWith(void* dest, int nitems, type,
4574 U8 byte)
4575 Renew The XSUB-writer's interface to the C "realloc" function.
4577 Memory obtained by this should ONLY be freed with "Safefree".
4579 void Renew(void* ptr, int nitems, type)
4581 Renewc The XSUB-writer's interface to the C "realloc" function, with
4583 cast.
4584 Memory obtained by this should ONLY be freed with "Safefree".
4586 void Renewc(void* ptr, int nitems, type, cast)
4588 Safefree
4590 The XSUB-writer's interface to the C "free" function.
4591 This should ONLY be used on memory obtained using "Newx" and
4593 friends.
4594 void Safefree(void* ptr)
4596 savepv Perl's version of "strdup()". Returns a pointer to a newly
4598 allocated string which is a duplicate of "pv". The size of the
4599 string is determined by "strlen()", which means it may not
4600 contain embedded "NUL" characters and must have a trailing
4601 "NUL". To prevent memory leaks, the memory allocated for the
4602 new string needs to be freed when no longer needed. This can
4603 be done with the ""Safefree"" function, or "SAVEFREEPV".
4604 On some platforms, Windows for example, all allocated memory
4606 owned by a thread is deallocated when that thread ends. So if
4607 you need that not to happen, you need to use the shared memory
4608 functions, such as "savesharedpv".
4609 char* savepv(const char* pv)
4611 savepvn Perl's version of what "strndup()" would be if it existed.
4613 Returns a pointer to a newly allocated string which is a
4614 duplicate of the first "len" bytes from "pv", plus a trailing
4615 "NUL" byte. The memory allocated for the new string can be
4616 freed with the "Safefree()" function.
4617 On some platforms, Windows for example, all allocated memory
4619 owned by a thread is deallocated when that thread ends. So if
4620 you need that not to happen, you need to use the shared memory
4621 functions, such as "savesharedpvn".
4622 char* savepvn(const char* pv, Size_t len)
4624 savepvs Like "savepvn", but takes a literal string instead of a
4626 string/length pair.
4627 char* savepvs("literal string")
4629 savesharedpv
4631 A version of "savepv()" which allocates the duplicate string in
4632 memory which is shared between threads.
4633 char* savesharedpv(const char* pv)
4635 savesharedpvn
4637 A version of "savepvn()" which allocates the duplicate string
4638 in memory which is shared between threads. (With the specific
4639 difference that a "NULL" pointer is not acceptable)
4640 char* savesharedpvn(const char *const pv,
4642 const STRLEN len)
4643 savesharedpvs
4645 A version of "savepvs()" which allocates the duplicate string
4646 in memory which is shared between threads.
4647 char* savesharedpvs("literal string")
4649 savesharedsvpv
4651 A version of "savesharedpv()" which allocates the duplicate
4652 string in memory which is shared between threads.
4653 char* savesharedsvpv(SV *sv)
4655 savesvpv
4657 A version of "savepv()"/"savepvn()" which gets the string to
4658 duplicate from the passed in SV using "SvPV()"
4659 On some platforms, Windows for example, all allocated memory
4661 owned by a thread is deallocated when that thread ends. So if
4662 you need that not to happen, you need to use the shared memory
4663 functions, such as "savesharedsvpv".
4664 char* savesvpv(SV* sv)
4666 StructCopy
4668 This is an architecture-independent macro to copy one structure
4669 to another.
4670 void StructCopy(type *src, type *dest, type)
4672 Zero The XSUB-writer's interface to the C "memzero" function. The
4674 "dest" is the destination, "nitems" is the number of items, and
4675 "type" is the type.
4676 void Zero(void* dest, int nitems, type)
4678 ZeroD Like "Zero" but returns dest. Useful for encouraging compilers
4680 to tail-call optimise.
4681 void * ZeroD(void* dest, int nitems, type)
4683
4685 dump_c_backtrace
4686 Dumps the C backtrace to the given "fp".
4687 Returns true if a backtrace could be retrieved, false if not.
4689 bool dump_c_backtrace(PerlIO* fp, int max_depth,
4691 int skip)
4692 fbm_compile
4694 Analyzes the string in order to make fast searches on it using
4695 "fbm_instr()" -- the Boyer-Moore algorithm.
4696 void fbm_compile(SV* sv, U32 flags)
4698 fbm_instr
4700 Returns the location of the SV in the string delimited by "big"
4701 and "bigend" ("bigend") is the char following the last char).
4702 It returns "NULL" if the string can't be found. The "sv" does
4703 not have to be "fbm_compiled", but the search will not be as
4704 fast then.
4705 char* fbm_instr(unsigned char* big,
4707 unsigned char* bigend, SV* littlestr,
4708 U32 flags)
4709 foldEQ Returns true if the leading "len" bytes of the strings "s1" and
4711 "s2" are the same case-insensitively; false otherwise.
4712 Uppercase and lowercase ASCII range bytes match themselves and
4713 their opposite case counterparts. Non-cased and non-ASCII
4714 range bytes match only themselves.
4715 I32 foldEQ(const char* a, const char* b, I32 len)
4717 foldEQ_locale
4719 Returns true if the leading "len" bytes of the strings "s1" and
4720 "s2" are the same case-insensitively in the current locale;
4721 false otherwise.
4722 I32 foldEQ_locale(const char* a, const char* b,
4724 I32 len)
4725 form Takes a sprintf-style format pattern and conventional (non-SV)
4727 arguments and returns the formatted string.
4728 (char *) Perl_form(pTHX_ const char* pat, ...)
4730 can be used any place a string (char *) is required:
4732 char * s = Perl_form("%d.%d",major,minor);
4734 Uses a single private buffer so if you want to format several
4736 strings you must explicitly copy the earlier strings away (and
4737 free the copies when you are done).
4738 char* form(const char* pat, ...)
4740 getcwd_sv
4742 Fill "sv" with current working directory
4743 int getcwd_sv(SV* sv)
4745 get_c_backtrace_dump
4747 Returns a SV containing a dump of "depth" frames of the call
4748 stack, skipping the "skip" innermost ones. "depth" of 20 is
4749 usually enough.
4750 The appended output looks like:
4752 ... 1 10e004812:0082 Perl_croak util.c:1716
4754 /usr/bin/perl 2 10df8d6d2:1d72 perl_parse perl.c:3975
4755 /usr/bin/perl ...
4756 The fields are tab-separated. The first column is the depth
4758 (zero being the innermost non-skipped frame). In the
4759 hex:offset, the hex is where the program counter was in
4760 "S_parse_body", and the :offset (might be missing) tells how
4761 much inside the "S_parse_body" the program counter was.
4762 The "util.c:1716" is the source code file and line number.
4764 The /usr/bin/perl is obvious (hopefully).
4766 Unknowns are "-". Unknowns can happen unfortunately quite
4768 easily: if the platform doesn't support retrieving the
4769 information; if the binary is missing the debug information; if
4770 the optimizer has transformed the code by for example inlining.
4771 SV* get_c_backtrace_dump(int max_depth, int skip)
4773 ibcmp This is a synonym for "(! foldEQ())"
4775 I32 ibcmp(const char* a, const char* b, I32 len)
4777 ibcmp_locale
4779 This is a synonym for "(! foldEQ_locale())"
4780 I32 ibcmp_locale(const char* a, const char* b,
4782 I32 len)
4783 instr Same as strstr(3), which finds and returns a pointer to the
4785 first occurrence of the NUL-terminated substring "little" in
4786 the NUL-terminated string "big", returning NULL if not found.
4787 The terminating NUL bytes are not compared.
4788 char* instr(const char* big, const char* little)
4790 IS_SAFE_SYSCALL
4792 Same as "is_safe_syscall".
4793 bool IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
4795 NN const char *what,
4796 NN const char *op_name)
4797 is_safe_syscall
4799 Test that the given "pv" (with length "len") doesn't contain
4800 any internal "NUL" characters. If it does, set "errno" to
4801 "ENOENT", optionally warn using the "syscalls" category, and
4802 return FALSE.
4803 Return TRUE if the name is safe.
4805 "what" and "op_name" are used in any warning.
4807 Used by the "IS_SAFE_SYSCALL()" macro.
4809 bool is_safe_syscall(const char *pv, STRLEN len,
4811 const char *what,
4812 const char *op_name)
4813 LIKELY Returns the input unchanged, but at the same time it gives a
4815 branch prediction hint to the compiler that this condition is
4816 likely to be true.
4817 memCHRs Returns the position of the first occurence of the byte "c" in
4819 the literal string "list", or NULL if "c" doesn't appear in
4820 "list". All bytes are treated as unsigned char. Thus this
4821 macro can be used to determine if "c" is in a set of particular
4822 characters. Unlike strchr(3), it works even if "c" is "NUL"
4823 (and the set doesn't include "NUL").
4824 bool memCHRs("list", char c)
4826 memEQ Test two buffers (which may contain embedded "NUL" characters,
4828 to see if they are equal. The "len" parameter indicates the
4829 number of bytes to compare. Returns zero if equal, or non-zero
4830 if non-equal.
4831 bool memEQ(char* s1, char* s2, STRLEN len)
4833 memEQs Like "memEQ", but the second string is a literal enclosed in
4835 double quotes, "l1" gives the number of bytes in "s1". Returns
4836 zero if equal, or non-zero if non-equal.
4837 bool memEQs(char* s1, STRLEN l1, "s2")
4839 memNE Test two buffers (which may contain embedded "NUL" characters,
4841 to see if they are not equal. The "len" parameter indicates
4842 the number of bytes to compare. Returns zero if non-equal, or
4843 non-zero if equal.
4844 bool memNE(char* s1, char* s2, STRLEN len)
4846 memNEs Like "memNE", but the second string is a literal enclosed in
4848 double quotes, "l1" gives the number of bytes in "s1". Returns
4849 zero if non-equal, or zero if non-equal.
4850 bool memNEs(char* s1, STRLEN l1, "s2")
4852 mess Take a sprintf-style format pattern and argument list. These
4854 are used to generate a string message. If the message does not
4855 end with a newline, then it will be extended with some
4856 indication of the current location in the code, as described
4857 for "mess_sv".
4858 Normally, the resulting message is returned in a new mortal SV.
4860 During global destruction a single SV may be shared between
4861 uses of this function.
4862 SV* mess(const char* pat, ...)
4864 mess_sv Expands a message, intended for the user, to include an
4866 indication of the current location in the code, if the message
4867 does not already appear to be complete.
4868 "basemsg" is the initial message or object. If it is a
4870 reference, it will be used as-is and will be the result of this
4871 function. Otherwise it is used as a string, and if it already
4872 ends with a newline, it is taken to be complete, and the result
4873 of this function will be the same string. If the message does
4874 not end with a newline, then a segment such as "at foo.pl line
4875 37" will be appended, and possibly other clauses indicating the
4876 current state of execution. The resulting message will end
4877 with a dot and a newline.
4878 Normally, the resulting message is returned in a new mortal SV.
4880 During global destruction a single SV may be shared between
4881 uses of this function. If "consume" is true, then the function
4882 is permitted (but not required) to modify and return "basemsg"
4883 instead of allocating a new SV.
4884 SV* mess_sv(SV* basemsg, bool consume)
4886 my_snprintf
4888 The C library "snprintf" functionality, if available and
4889 standards-compliant (uses "vsnprintf", actually). However, if
4890 the "vsnprintf" is not available, will unfortunately use the
4891 unsafe "vsprintf" which can overrun the buffer (there is an
4892 overrun check, but that may be too late). Consider using
4893 "sv_vcatpvf" instead, or getting "vsnprintf".
4894 int my_snprintf(char *buffer, const Size_t len,
4896 const char *format, ...)
4897 my_sprintf
4899 DEPRECATED! It is planned to remove this function from a
4900 future release of Perl. Do not use it for new code; remove it
4901 from existing code.
4902 Do NOT use this due to the possibility of overflowing "buffer".
4904 Instead use my_snprintf()
4905 int my_sprintf(NN char *buffer, NN const char *pat,
4907 ...)
4908 my_strlcat
4910 The C library "strlcat" if available, or a Perl implementation
4911 of it. This operates on C "NUL"-terminated strings.
4912 "my_strlcat()" appends string "src" to the end of "dst". It
4914 will append at most "size - strlen(dst) - 1" characters. It
4915 will then "NUL"-terminate, unless "size" is 0 or the original
4916 "dst" string was longer than "size" (in practice this should
4917 not happen as it means that either "size" is incorrect or that
4918 "dst" is not a proper "NUL"-terminated string).
4919 Note that "size" is the full size of the destination buffer and
4921 the result is guaranteed to be "NUL"-terminated if there is
4922 room. Note that room for the "NUL" should be included in
4923 "size".
4924 The return value is the total length that "dst" would have if
4926 "size" is sufficiently large. Thus it is the initial length of
4927 "dst" plus the length of "src". If "size" is smaller than the
4928 return, the excess was not appended.
4929 Size_t my_strlcat(char *dst, const char *src,
4931 Size_t size)
4932 my_strlcpy
4934 The C library "strlcpy" if available, or a Perl implementation
4935 of it. This operates on C "NUL"-terminated strings.
4936 "my_strlcpy()" copies up to "size - 1" characters from the
4938 string "src" to "dst", "NUL"-terminating the result if "size"
4939 is not 0.
4940 The return value is the total length "src" would be if the copy
4942 completely succeeded. If it is larger than "size", the excess
4943 was not copied.
4944 Size_t my_strlcpy(char *dst, const char *src,
4946 Size_t size)
4947 my_strnlen
4949 The C library "strnlen" if available, or a Perl implementation
4950 of it.
4951 "my_strnlen()" computes the length of the string, up to
4953 "maxlen" characters. It will never attempt to address more
4954 than "maxlen" characters, making it suitable for use with
4955 strings that are not guaranteed to be NUL-terminated.
4956 Size_t my_strnlen(const char *str, Size_t maxlen)
4958 my_vsnprintf
4960 The C library "vsnprintf" if available and standards-compliant.
4961 However, if the "vsnprintf" is not available, will
4962 unfortunately use the unsafe "vsprintf" which can overrun the
4963 buffer (there is an overrun check, but that may be too late).
4964 Consider using "sv_vcatpvf" instead, or getting "vsnprintf".
4965 int my_vsnprintf(char *buffer, const Size_t len,
4967 const char *format, va_list ap)
4968 ninstr Find the first (leftmost) occurrence of a sequence of bytes
4970 within another sequence. This is the Perl version of
4971 "strstr()", extended to handle arbitrary sequences, potentially
4972 containing embedded "NUL" characters ("NUL" is what the initial
4973 "n" in the function name stands for; some systems have an
4974 equivalent, "memmem()", but with a somewhat different API).
4975 Another way of thinking about this function is finding a needle
4977 in a haystack. "big" points to the first byte in the haystack.
4978 "big_end" points to one byte beyond the final byte in the
4979 haystack. "little" points to the first byte in the needle.
4980 "little_end" points to one byte beyond the final byte in the
4981 needle. All the parameters must be non-"NULL".
4982 The function returns "NULL" if there is no occurrence of
4984 "little" within "big". If "little" is the empty string, "big"
4985 is returned.
4986 Because this function operates at the byte level, and because
4988 of the inherent characteristics of UTF-8 (or UTF-EBCDIC), it
4989 will work properly if both the needle and the haystack are
4990 strings with the same UTF-8ness, but not if the UTF-8ness
4991 differs.
4992 char* ninstr(const char* big, const char* bigend,
4994 const char* little, const char* lend)
4995 PERL_SYS_INIT
4997 Provides system-specific tune up of the C runtime environment
4998 necessary to run Perl interpreters. This should be called only
4999 once, before creating any Perl interpreters.
5000 void PERL_SYS_INIT(int *argc, char*** argv)
5002 PERL_SYS_INIT3
5004 Provides system-specific tune up of the C runtime environment
5005 necessary to run Perl interpreters. This should be called only
5006 once, before creating any Perl interpreters.
5007 void PERL_SYS_INIT3(int *argc, char*** argv,
5009 char*** env)
5010 PERL_SYS_TERM
5012 Provides system-specific clean up of the C runtime environment
5013 after running Perl interpreters. This should be called only
5014 once, after freeing any remaining Perl interpreters.
5015 void PERL_SYS_TERM()
5017 READ_XDIGIT
5019 Returns the value of an ASCII-range hex digit and advances the
5020 string pointer. Behaviour is only well defined when
5021 isXDIGIT(*str) is true.
5022 U8 READ_XDIGIT(char str*)
5024 rninstr Like "ninstr", but instead finds the final (rightmost)
5026 occurrence of a sequence of bytes within another sequence,
5027 returning "NULL" if there is no such occurrence.
5028 char* rninstr(const char* big, const char* bigend,
5030 const char* little, const char* lend)
5031 STMT_START
5033 STMT_START { statements; } STMT_END;
5034 can be used as a single statement, as in
5036 if (x) STMT_START { ... } STMT_END; else ...
5038 These are often used in macro definitions. Note that you can't
5040 return a value out of them.
5041 strEQ Test two "NUL"-terminated strings to see if they are equal.
5043 Returns true or false.
5044 bool strEQ(char* s1, char* s2)
5046 strGE Test two "NUL"-terminated strings to see if the first, "s1", is
5048 greater than or equal to the second, "s2". Returns true or
5049 false.
5050 bool strGE(char* s1, char* s2)
5052 strGT Test two "NUL"-terminated strings to see if the first, "s1", is
5054 greater than the second, "s2". Returns true or false.
5055 bool strGT(char* s1, char* s2)
5057 strLE Test two "NUL"-terminated strings to see if the first, "s1", is
5059 less than or equal to the second, "s2". Returns true or false.
5060 bool strLE(char* s1, char* s2)
5062 strLT Test two "NUL"-terminated strings to see if the first, "s1", is
5064 less than the second, "s2". Returns true or false.
5065 bool strLT(char* s1, char* s2)
5067 strNE Test two "NUL"-terminated strings to see if they are different.
5069 Returns true or false.
5070 bool strNE(char* s1, char* s2)
5072 strnEQ Test two "NUL"-terminated strings to see if they are equal.
5074 The "len" parameter indicates the number of bytes to compare.
5075 Returns true or false. (A wrapper for "strncmp").
5076 bool strnEQ(char* s1, char* s2, STRLEN len)
5078 strnNE Test two "NUL"-terminated strings to see if they are different.
5080 The "len" parameter indicates the number of bytes to compare.
5081 Returns true or false. (A wrapper for "strncmp").
5082 bool strnNE(char* s1, char* s2, STRLEN len)
5084 sv_destroyable
5086 Dummy routine which reports that object can be destroyed when
5087 there is no sharing module present. It ignores its single SV
5088 argument, and returns 'true'. Exists to avoid test for a
5089 "NULL" function pointer and because it could potentially warn
5090 under some level of strict-ness.
5091 bool sv_destroyable(SV *sv)
5093 sv_nosharing
5095 Dummy routine which "shares" an SV when there is no sharing
5096 module present. Or "locks" it. Or "unlocks" it. In other
5097 words, ignores its single SV argument. Exists to avoid test
5098 for a "NULL" function pointer and because it could potentially
5099 warn under some level of strict-ness.
5100 void sv_nosharing(SV *sv)
5102 UNLIKELY
5104 Returns the input unchanged, but at the same time it gives a
5105 branch prediction hint to the compiler that this condition is
5106 likely to be false.
5107 vmess "pat" and "args" are a sprintf-style format pattern and
5109 encapsulated argument list, respectively. These are used to
5110 generate a string message. If the message does not end with a
5111 newline, then it will be extended with some indication of the
5112 current location in the code, as described for "mess_sv".
5113 Normally, the resulting message is returned in a new mortal SV.
5115 During global destruction a single SV may be shared between
5116 uses of this function.
5117 SV* vmess(const char* pat, va_list* args)
5119
5121 These functions are related to the method resolution order of perl
5122 classes Also see perlmroapi.
5123 mro_get_linear_isa
5125 Returns the mro linearisation for the given stash. By default,
5126 this will be whatever "mro_get_linear_isa_dfs" returns unless
5127 some other MRO is in effect for the stash. The return value is
5128 a read-only AV*.
5129 You are responsible for "SvREFCNT_inc()" on the return value if
5131 you plan to store it anywhere semi-permanently (otherwise it
5132 might be deleted out from under you the next time the cache is
5133 invalidated).
5134 AV* mro_get_linear_isa(HV* stash)
5136 mro_method_changed_in
5138 Invalidates method caching on any child classes of the given
5139 stash, so that they might notice the changes in this one.
5140 Ideally, all instances of "PL_sub_generation++" in perl source
5142 outside of mro.c should be replaced by calls to this.
5143 Perl automatically handles most of the common ways a method
5145 might be redefined. However, there are a few ways you could
5146 change a method in a stash without the cache code noticing, in
5147 which case you need to call this method afterwards:
5148 1) Directly manipulating the stash HV entries from XS code.
5150 2) Assigning a reference to a readonly scalar constant into a
5152 stash entry in order to create a constant subroutine (like
5153 constant.pm does).
5154 This same method is available from pure perl via,
5156 "mro::method_changed_in(classname)".
5157 void mro_method_changed_in(HV* stash)
5159 mro_register
5161 Registers a custom mro plugin. See perlmroapi for details on
5162 this and other mro functions.
5163 NOTE: this function must be explicitly called as
5165 Perl_mro_register with an aTHX_ parameter.
5166 void Perl_mro_register(pTHX_
5168 const struct mro_alg *mro)
5169
5171 dMULTICALL
5172 Declare local variables for a multicall. See "LIGHTWEIGHT
5173 CALLBACKS" in perlcall.
5174 dMULTICALL;
5176 MULTICALL
5178 Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in
5179 perlcall.
5180 MULTICALL;
5182 POP_MULTICALL
5184 Closing bracket for a lightweight callback. See "LIGHTWEIGHT
5185 CALLBACKS" in perlcall.
5186 POP_MULTICALL;
5188 PUSH_MULTICALL
5190 Opening bracket for a lightweight callback. See "LIGHTWEIGHT
5191 CALLBACKS" in perlcall.
5192 PUSH_MULTICALL(CV* the_cv);
5194
5196 grok_bin
5197 converts a string representing a binary number to numeric form.
5198 On entry "start" and *len_p give the string to scan, *flags
5200 gives conversion flags, and "result" should be "NULL" or a
5201 pointer to an NV. The scan stops at the end of the string, or
5202 at just before the first invalid character. Unless
5203 "PERL_SCAN_SILENT_ILLDIGIT" is set in *flags, encountering an
5204 invalid character (except NUL) will also trigger a warning. On
5205 return *len_p is set to the length of the scanned string, and
5206 *flags gives output flags.
5207 If the value is <= "UV_MAX" it is returned as a UV, the output
5209 flags are clear, and nothing is written to *result. If the
5210 value is > "UV_MAX", "grok_bin" returns "UV_MAX", sets
5211 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
5212 an approximation of the correct value into *result (which is an
5213 NV; or the approximation is discarded if "result" is NULL).
5214 The binary number may optionally be prefixed with "0b" or "b"
5216 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
5217 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or
5219 all pairs of digits may be separated from each other by a
5220 single underscore; also a single leading underscore is
5221 accepted.
5222 UV grok_bin(const char* start, STRLEN* len_p,
5224 I32* flags, NV *result)
5225 grok_hex
5227 converts a string representing a hex number to numeric form.
5228 On entry "start" and *len_p give the string to scan, *flags
5230 gives conversion flags, and "result" should be "NULL" or a
5231 pointer to an NV. The scan stops at the end of the string, or
5232 at just before the first invalid character. Unless
5233 "PERL_SCAN_SILENT_ILLDIGIT" is set in *flags, encountering an
5234 invalid character (except NUL) will also trigger a warning. On
5235 return *len_p is set to the length of the scanned string, and
5236 *flags gives output flags.
5237 If the value is <= "UV_MAX" it is returned as a UV, the output
5239 flags are clear, and nothing is written to *result. If the
5240 value is > "UV_MAX", "grok_hex" returns "UV_MAX", sets
5241 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
5242 an approximation of the correct value into *result (which is an
5243 NV; or the approximation is discarded if "result" is NULL).
5244 The hex number may optionally be prefixed with "0x" or "x"
5246 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
5247 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or
5249 all pairs of digits may be separated from each other by a
5250 single underscore; also a single leading underscore is
5251 accepted.
5252 UV grok_hex(const char* start, STRLEN* len_p,
5254 I32* flags, NV *result)
5255 grok_infnan
5257 Helper for "grok_number()", accepts various ways of spelling
5258 "infinity" or "not a number", and returns one of the following
5259 flag combinations:
5260 IS_NUMBER_INFINITY
5262 IS_NUMBER_NAN
5263 IS_NUMBER_INFINITY | IS_NUMBER_NEG
5264 IS_NUMBER_NAN | IS_NUMBER_NEG
5265 0
5266 possibly |-ed with "IS_NUMBER_TRAILING".
5268 If an infinity or a not-a-number is recognized, *sp will point
5270 to one byte past the end of the recognized string. If the
5271 recognition fails, zero is returned, and *sp will not move.
5272 int grok_infnan(const char** sp, const char *send)
5274 grok_number
5276 Identical to "grok_number_flags()" with "flags" set to zero.
5277 int grok_number(const char *pv, STRLEN len,
5279 UV *valuep)
5280 grok_number_flags
5282 Recognise (or not) a number. The type of the number is
5283 returned (0 if unrecognised), otherwise it is a bit-ORed
5284 combination of "IS_NUMBER_IN_UV",
5285 "IS_NUMBER_GREATER_THAN_UV_MAX", "IS_NUMBER_NOT_INT",
5286 "IS_NUMBER_NEG", "IS_NUMBER_INFINITY", "IS_NUMBER_NAN" (defined
5287 in perl.h).
5288 If the value of the number can fit in a UV, it is returned in
5290 *valuep. "IS_NUMBER_IN_UV" will be set to indicate that
5291 *valuep is valid, "IS_NUMBER_IN_UV" will never be set unless
5292 *valuep is valid, but *valuep may have been assigned to during
5293 processing even though "IS_NUMBER_IN_UV" is not set on return.
5294 If "valuep" is "NULL", "IS_NUMBER_IN_UV" will be set for the
5295 same cases as when "valuep" is non-"NULL", but no actual
5296 assignment (or SEGV) will occur.
5297 "IS_NUMBER_NOT_INT" will be set with "IS_NUMBER_IN_UV" if
5299 trailing decimals were seen (in which case *valuep gives the
5300 true value truncated to an integer), and "IS_NUMBER_NEG" if the
5301 number is negative (in which case *valuep holds the absolute
5302 value). "IS_NUMBER_IN_UV" is not set if e notation was used or
5303 the number is larger than a UV.
5304 "flags" allows only "PERL_SCAN_TRAILING", which allows for
5306 trailing non-numeric text on an otherwise successful grok,
5307 setting "IS_NUMBER_TRAILING" on the result.
5308 int grok_number_flags(const char *pv, STRLEN len,
5310 UV *valuep, U32 flags)
5311 GROK_NUMERIC_RADIX
5313 A synonym for "grok_numeric_radix"
5314 bool GROK_NUMERIC_RADIX(NN const char **sp,
5316 NN const char *send)
5317 grok_numeric_radix
5319 Scan and skip for a numeric decimal separator (radix).
5320 bool grok_numeric_radix(const char **sp,
5322 const char *send)
5323 grok_oct
5325 converts a string representing an octal number to numeric form.
5326 On entry "start" and *len_p give the string to scan, *flags
5328 gives conversion flags, and "result" should be "NULL" or a
5329 pointer to an NV. The scan stops at the end of the string, or
5330 at just before the first invalid character. Unless
5331 "PERL_SCAN_SILENT_ILLDIGIT" is set in *flags, encountering an
5332 invalid character (except NUL) will also trigger a warning. On
5333 return *len_p is set to the length of the scanned string, and
5334 *flags gives output flags.
5335 If the value is <= "UV_MAX" it is returned as a UV, the output
5337 flags are clear, and nothing is written to *result. If the
5338 value is > "UV_MAX", "grok_oct" returns "UV_MAX", sets
5339 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
5340 an approximation of the correct value into *result (which is an
5341 NV; or the approximation is discarded if "result" is NULL).
5342 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or
5344 all pairs of digits may be separated from each other by a
5345 single underscore; also a single leading underscore is
5346 accepted.
5347 The "PERL_SCAN_DISALLOW_PREFIX" flag is always treated as being
5349 set for this function.
5350 UV grok_oct(const char* start, STRLEN* len_p,
5352 I32* flags, NV *result)
5353 isinfnan
5355 "Perl_isinfnan()" is a utility function that returns true if
5356 the NV argument is either an infinity or a "NaN", false
5357 otherwise. To test in more detail, use "Perl_isinf()" and
5358 "Perl_isnan()".
5359 This is also the logical inverse of Perl_isfinite().
5361 bool isinfnan(NV nv)
5363 IS_NUMBER_GREATER_THAN_UV_MAX bool IS_NUMBER_GREATER_THAN_UV_MAX
5365 IS_NUMBER_INFINITY bool IS_NUMBER_INFINITY
5366 IS_NUMBER_IN_UV bool IS_NUMBER_IN_UV
5367 IS_NUMBER_NAN bool IS_NUMBER_NAN
5368 IS_NUMBER_NEG bool IS_NUMBER_NEG
5369 IS_NUMBER_NOT_INT
5370 bool IS_NUMBER_NOT_INT
5371 my_strtod
5373 This function is equivalent to the libc strtod() function, and
5374 is available even on platforms that lack plain strtod(). Its
5375 return value is the best available precision depending on
5376 platform capabilities and Configure options.
5377 It properly handles the locale radix character, meaning it
5379 expects a dot except when called from within the scope of
5380 "use locale", in which case the radix character should be that
5381 specified by the current locale.
5382 The synonym Strtod() may be used instead.
5384 NV my_strtod(const char * const s, char ** e)
5386 PERL_ABS
5388 Typeless "abs" or "fabs", etc. (The usage below indicates it
5389 is for integers, but it works for any type.) Use instead of
5390 these, since the C library ones force their argument to be what
5391 it is expecting, potentially leading to disaster. But also
5392 beware that this evaluates its argument twice, so no "x++".
5393 int PERL_ABS(int)
5395 PERL_INT_MAX
5397 This and "PERL_INT_MIN", "PERL_LONG_MAX", "PERL_LONG_MIN",
5398 "PERL_QUAD_MAX", "PERL_SHORT_MAX", "PERL_SHORT_MIN",
5399 "PERL_UCHAR_MAX", "PERL_UCHAR_MIN", "PERL_UINT_MAX",
5400 "PERL_ULONG_MAX", "PERL_ULONG_MIN", "PERL_UQUAD_MAX",
5401 "PERL_UQUAD_MIN", "PERL_USHORT_MAX", "PERL_USHORT_MIN",
5402 "PERL_QUAD_MIN" give the largest and smallest number
5403 representable in the current platform in variables of the
5404 corresponding types.
5405 For signed types, the smallest representable number is the most
5407 negative number, the one furthest away from zero.
5408 For C99 and later compilers, these correspond to things like
5410 "INT_MAX", which are available to the C code. But these
5411 constants, furnished by Perl, allow code compiled on earlier
5412 compilers to portably have access to the same constants.
5413 Perl_signbit
5415 NOTE: this function is experimental and may change or be
5416 removed without notice.
5417 Return a non-zero integer if the sign bit on an NV is set, and
5419 0 if it is not.
5420 If Configure detects this system has a "signbit()" that will
5422 work with our NVs, then we just use it via the "#define" in
5423 perl.h. Otherwise, fall back on this implementation. The main
5424 use of this function is catching "-0.0".
5425 "Configure" notes: This function is called 'Perl_signbit'
5427 instead of a plain 'signbit' because it is easy to imagine a
5428 system having a "signbit()" function or macro that doesn't
5429 happen to work with our particular choice of NVs. We shouldn't
5430 just re-"#define" "signbit" as "Perl_signbit" and expect the
5431 standard system headers to be happy. Also, this is a no-
5432 context function (no "pTHX_") because "Perl_signbit()" is
5433 usually re-"#defined" in perl.h as a simple macro call to the
5434 system's "signbit()". Users should just always call
5435 "Perl_signbit()".
5436 int Perl_signbit(NV f)
5438 scan_bin
5440 For backwards compatibility. Use "grok_bin" instead.
5441 NV scan_bin(const char* start, STRLEN len,
5443 STRLEN* retlen)
5444 scan_hex
5446 For backwards compatibility. Use "grok_hex" instead.
5447 NV scan_hex(const char* start, STRLEN len,
5449 STRLEN* retlen)
5450 scan_oct
5452 For backwards compatibility. Use "grok_oct" instead.
5453 NV scan_oct(const char* start, STRLEN len,
5455 STRLEN* retlen)
5456 Strtod This is a synonym for "my_strtod".
5458 NV Strtod(NN const char * const s,
5460 NULLOK char ** e)
5461 Strtol Platform and configuration independent "strtol". This expands
5463 to the appropriate "strotol"-like function based on the
5464 platform and Configure options>. For example it could expand
5465 to "strtoll" or "strtoq" instead of "strtol".
5466 NV Strtol(NN const char * const s,
5468 NULLOK char ** e, int base)
5469 Strtoul Platform and configuration independent "strtoul". This expands
5471 to the appropriate "strotoul"-like function based on the
5472 platform and Configure options>. For example it could expand
5473 to "strtoull" or "strtouq" instead of "strtoul".
5474 NV Strtoul(NN const char * const s,
5476 NULLOK char ** e, int base)
5477
5479 Some of these are also deprecated. You can exclude these from your
5480 compiled Perl by adding this option to Configure:
5481 "-Accflags='-DNO_MATHOMS'"
5482 custom_op_desc
5484 DEPRECATED! It is planned to remove this function from a
5485 future release of Perl. Do not use it for new code; remove it
5486 from existing code.
5487 Return the description of a given custom op. This was once
5489 used by the "OP_DESC" macro, but is no longer: it has only been
5490 kept for compatibility, and should not be used.
5491 const char * custom_op_desc(const OP *o)
5493 custom_op_name
5495 DEPRECATED! It is planned to remove this function from a
5496 future release of Perl. Do not use it for new code; remove it
5497 from existing code.
5498 Return the name for a given custom op. This was once used by
5500 the "OP_NAME" macro, but is no longer: it has only been kept
5501 for compatibility, and should not be used.
5502 const char * custom_op_name(const OP *o)
5504 gv_fetchmethod
5506 See "gv_fetchmethod_autoload".
5507 GV* gv_fetchmethod(HV* stash, const char* name)
5509 is_utf8_char
5511 DEPRECATED! It is planned to remove this function from a
5512 future release of Perl. Do not use it for new code; remove it
5513 from existing code.
5514 Tests if some arbitrary number of bytes begins in a valid UTF-8
5516 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC
5517 machines) character is a valid UTF-8 character. The actual
5518 number of bytes in the UTF-8 character will be returned if it
5519 is valid, otherwise 0.
5520 This function is deprecated due to the possibility that
5522 malformed input could cause reading beyond the end of the input
5523 buffer. Use "isUTF8_CHAR" instead.
5524 STRLEN is_utf8_char(const U8 *s)
5526 is_utf8_char_buf
5528 This is identical to the macro "isUTF8_CHAR" in perlapi.
5529 STRLEN is_utf8_char_buf(const U8 *buf,
5531 const U8 *buf_end)
5532 pack_cat
5534 The engine implementing "pack()" Perl function. Note:
5535 parameters "next_in_list" and "flags" are not used. This call
5536 should not be used; use "packlist" instead.
5537 void pack_cat(SV *cat, const char *pat,
5539 const char *patend, SV **beglist,
5540 SV **endlist, SV ***next_in_list,
5541 U32 flags)
5542 pad_compname_type
5544 Looks up the type of the lexical variable at position "po" in
5545 the currently-compiling pad. If the variable is typed, the
5546 stash of the class to which it is typed is returned. If not,
5547 "NULL" is returned.
5548 HV* pad_compname_type(const PADOFFSET po)
5550 sv_2pvbyte_nolen
5552 Return a pointer to the byte-encoded representation of the SV.
5553 May cause the SV to be downgraded from UTF-8 as a side-effect.
5554 Usually accessed via the "SvPVbyte_nolen" macro.
5556 char* sv_2pvbyte_nolen(SV* sv)
5558 sv_2pvutf8_nolen
5560 Return a pointer to the UTF-8-encoded representation of the SV.
5561 May cause the SV to be upgraded to UTF-8 as a side-effect.
5562 Usually accessed via the "SvPVutf8_nolen" macro.
5564 char* sv_2pvutf8_nolen(SV* sv)
5566 sv_2pv_nolen
5568 Like "sv_2pv()", but doesn't return the length too. You should
5569 usually use the macro wrapper "SvPV_nolen(sv)" instead.
5570 char* sv_2pv_nolen(SV* sv)
5572 sv_catpvn_mg
5574 Like "sv_catpvn", but also handles 'set' magic.
5575 void sv_catpvn_mg(SV *sv, const char *ptr,
5577 STRLEN len)
5578 sv_catsv_mg
5580 Like "sv_catsv", but also handles 'set' magic.
5581 void sv_catsv_mg(SV *dsv, SV *ssv)
5583 sv_force_normal
5585 Undo various types of fakery on an SV: if the PV is a shared
5586 string, make a private copy; if we're a ref, stop refing; if
5587 we're a glob, downgrade to an "xpvmg". See also
5588 "sv_force_normal_flags".
5589 void sv_force_normal(SV *sv)
5591 sv_iv DEPRECATED! It is planned to remove this function from a
5593 future release of Perl. Do not use it for new code; remove it
5594 from existing code.
5595 A private implementation of the "SvIVx" macro for compilers
5597 which can't cope with complex macro expressions. Always use
5598 the macro instead.
5599 IV sv_iv(SV* sv)
5601 sv_nolocking
5603 DEPRECATED! It is planned to remove this function from a
5604 future release of Perl. Do not use it for new code; remove it
5605 from existing code.
5606 Dummy routine which "locks" an SV when there is no locking
5608 module present. Exists to avoid test for a "NULL" function
5609 pointer and because it could potentially warn under some level
5610 of strict-ness.
5611 "Superseded" by "sv_nosharing()".
5613 void sv_nolocking(SV *sv)
5615 sv_nounlocking
5617 DEPRECATED! It is planned to remove this function from a
5618 future release of Perl. Do not use it for new code; remove it
5619 from existing code.
5620 Dummy routine which "unlocks" an SV when there is no locking
5622 module present. Exists to avoid test for a "NULL" function
5623 pointer and because it could potentially warn under some level
5624 of strict-ness.
5625 "Superseded" by "sv_nosharing()".
5627 void sv_nounlocking(SV *sv)
5629 sv_nv DEPRECATED! It is planned to remove this function from a
5631 future release of Perl. Do not use it for new code; remove it
5632 from existing code.
5633 A private implementation of the "SvNVx" macro for compilers
5635 which can't cope with complex macro expressions. Always use
5636 the macro instead.
5637 NV sv_nv(SV* sv)
5639 sv_pv Use the "SvPV_nolen" macro instead
5641 char* sv_pv(SV *sv)
5643 sv_pvbyte
5645 Use "SvPVbyte_nolen" instead.
5646 char* sv_pvbyte(SV *sv)
5648 sv_pvbyten
5650 DEPRECATED! It is planned to remove this function from a
5651 future release of Perl. Do not use it for new code; remove it
5652 from existing code.
5653 A private implementation of the "SvPVbyte" macro for compilers
5655 which can't cope with complex macro expressions. Always use
5656 the macro instead.
5657 char* sv_pvbyten(SV *sv, STRLEN *lp)
5659 sv_pvn DEPRECATED! It is planned to remove this function from a
5661 future release of Perl. Do not use it for new code; remove it
5662 from existing code.
5663 A private implementation of the "SvPV" macro for compilers
5665 which can't cope with complex macro expressions. Always use
5666 the macro instead.
5667 char* sv_pvn(SV *sv, STRLEN *lp)
5669 sv_pvutf8
5671 Use the "SvPVutf8_nolen" macro instead
5672 char* sv_pvutf8(SV *sv)
5674 sv_pvutf8n
5676 DEPRECATED! It is planned to remove this function from a
5677 future release of Perl. Do not use it for new code; remove it
5678 from existing code.
5679 A private implementation of the "SvPVutf8" macro for compilers
5681 which can't cope with complex macro expressions. Always use
5682 the macro instead.
5683 char* sv_pvutf8n(SV *sv, STRLEN *lp)
5685 sv_taint
5687 Taint an SV. Use "SvTAINTED_on" instead.
5688 void sv_taint(SV* sv)
5690 sv_unref
5692 Unsets the RV status of the SV, and decrements the reference
5693 count of whatever was being referenced by the RV. This can
5694 almost be thought of as a reversal of "newSVrv". This is
5695 "sv_unref_flags" with the "flag" being zero. See "SvROK_off".
5696 void sv_unref(SV* sv)
5698 sv_usepvn
5700 Tells an SV to use "ptr" to find its string value. Implemented
5701 by calling "sv_usepvn_flags" with "flags" of 0, hence does not
5702 handle 'set' magic. See "sv_usepvn_flags".
5703 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
5705 sv_usepvn_mg
5707 Like "sv_usepvn", but also handles 'set' magic.
5708 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
5710 sv_uv DEPRECATED! It is planned to remove this function from a
5712 future release of Perl. Do not use it for new code; remove it
5713 from existing code.
5714 A private implementation of the "SvUVx" macro for compilers
5716 which can't cope with complex macro expressions. Always use
5717 the macro instead.
5718 UV sv_uv(SV* sv)
5720 unpack_str
5722 DEPRECATED! It is planned to remove this function from a
5723 future release of Perl. Do not use it for new code; remove it
5724 from existing code.
5725 The engine implementing "unpack()" Perl function. Note:
5727 parameters "strbeg", "new_s" and "ocnt" are not used. This
5728 call should not be used, use "unpackstring" instead.
5729 SSize_t unpack_str(const char *pat, const char *patend,
5731 const char *s, const char *strbeg,
5732 const char *strend, char **new_s,
5733 I32 ocnt, U32 flags)
5734 utf8_to_uvchr
5736 DEPRECATED! It is planned to remove this function from a
5737 future release of Perl. Do not use it for new code; remove it
5738 from existing code.
5739 Returns the native code point of the first character in the
5741 string "s" which is assumed to be in UTF-8 encoding; "retlen"
5742 will be set to the length, in bytes, of that character.
5743 Some, but not all, UTF-8 malformations are detected, and in
5745 fact, some malformed input could cause reading beyond the end
5746 of the input buffer, which is why this function is deprecated.
5747 Use "utf8_to_uvchr_buf" instead.
5748 If "s" points to one of the detected malformations, and UTF8
5750 warnings are enabled, zero is returned and *retlen is set (if
5751 "retlen" isn't "NULL") to -1. If those warnings are off, the
5752 computed value if well-defined (or the Unicode REPLACEMENT
5753 CHARACTER, if not) is silently returned, and *retlen is set (if
5754 "retlen" isn't NULL) so that ("s" + *retlen) is the next
5755 possible position in "s" that could begin a non-malformed
5756 character. See "utf8n_to_uvchr" for details on when the
5757 REPLACEMENT CHARACTER is returned.
5758 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
5760
5762 newASSIGNOP
5763 Constructs, checks, and returns an assignment op. "left" and
5764 "right" supply the parameters of the assignment; they are
5765 consumed by this function and become part of the constructed op
5766 tree.
5767 If "optype" is "OP_ANDASSIGN", "OP_ORASSIGN", or
5769 "OP_DORASSIGN", then a suitable conditional optree is
5770 constructed. If "optype" is the opcode of a binary operator,
5771 such as "OP_BIT_OR", then an op is constructed that performs
5772 the binary operation and assigns the result to the left
5773 argument. Either way, if "optype" is non-zero then "flags" has
5774 no effect.
5775 If "optype" is zero, then a plain scalar or list assignment is
5777 constructed. Which type of assignment it is is automatically
5778 determined. "flags" gives the eight bits of "op_flags", except
5779 that "OPf_KIDS" will be set automatically, and, shifted up
5780 eight bits, the eight bits of "op_private", except that the bit
5781 with value 1 or 2 is automatically set as required.
5782 OP* newASSIGNOP(I32 flags, OP* left, I32 optype,
5784 OP* right)
5785 newBINOP
5787 Constructs, checks, and returns an op of any binary type.
5788 "type" is the opcode. "flags" gives the eight bits of
5789 "op_flags", except that "OPf_KIDS" will be set automatically,
5790 and, shifted up eight bits, the eight bits of "op_private",
5791 except that the bit with value 1 or 2 is automatically set as
5792 required. "first" and "last" supply up to two ops to be the
5793 direct children of the binary op; they are consumed by this
5794 function and become part of the constructed op tree.
5795 OP* newBINOP(I32 type, I32 flags, OP* first,
5797 OP* last)
5798 newCONDOP
5800 Constructs, checks, and returns a conditional-expression
5801 ("cond_expr") op. "flags" gives the eight bits of "op_flags",
5802 except that "OPf_KIDS" will be set automatically, and, shifted
5803 up eight bits, the eight bits of "op_private", except that the
5804 bit with value 1 is automatically set. "first" supplies the
5805 expression selecting between the two branches, and "trueop" and
5806 "falseop" supply the branches; they are consumed by this
5807 function and become part of the constructed op tree.
5808 OP* newCONDOP(I32 flags, OP* first, OP* trueop,
5810 OP* falseop)
5811 newDEFSVOP
5813 Constructs and returns an op to access $_.
5814 OP* newDEFSVOP()
5816 newFOROP
5818 Constructs, checks, and returns an op tree expressing a
5819 "foreach" loop (iteration through a list of values). This is a
5820 heavyweight loop, with structure that allows exiting the loop
5821 by "last" and suchlike.
5822 "sv" optionally supplies the variable that will be aliased to
5824 each item in turn; if null, it defaults to $_. "expr" supplies
5825 the list of values to iterate over. "block" supplies the main
5826 body of the loop, and "cont" optionally supplies a "continue"
5827 block that operates as a second half of the body. All of these
5828 optree inputs are consumed by this function and become part of
5829 the constructed op tree.
5830 "flags" gives the eight bits of "op_flags" for the "leaveloop"
5832 op and, shifted up eight bits, the eight bits of "op_private"
5833 for the "leaveloop" op, except that (in both cases) some bits
5834 will be set automatically.
5835 OP* newFOROP(I32 flags, OP* sv, OP* expr, OP* block,
5837 OP* cont)
5838 newGIVENOP
5840 Constructs, checks, and returns an op tree expressing a "given"
5841 block. "cond" supplies the expression to whose value $_ will
5842 be locally aliased, and "block" supplies the body of the
5843 "given" construct; they are consumed by this function and
5844 become part of the constructed op tree. "defsv_off" must be
5845 zero (it used to identity the pad slot of lexical $_).
5846 OP* newGIVENOP(OP* cond, OP* block,
5848 PADOFFSET defsv_off)
5849 newGVOP Constructs, checks, and returns an op of any type that involves
5851 an embedded reference to a GV. "type" is the opcode. "flags"
5852 gives the eight bits of "op_flags". "gv" identifies the GV
5853 that the op should reference; calling this function does not
5854 transfer ownership of any reference to it.
5855 OP* newGVOP(I32 type, I32 flags, GV* gv)
5857 newLISTOP
5859 Constructs, checks, and returns an op of any list type. "type"
5860 is the opcode. "flags" gives the eight bits of "op_flags",
5861 except that "OPf_KIDS" will be set automatically if required.
5862 "first" and "last" supply up to two ops to be direct children
5863 of the list op; they are consumed by this function and become
5864 part of the constructed op tree.
5865 For most list operators, the check function expects all the kid
5867 ops to be present already, so calling "newLISTOP(OP_JOIN, ...)"
5868 (e.g.) is not appropriate. What you want to do in that case is
5869 create an op of type "OP_LIST", append more children to it, and
5870 then call "op_convert_list". See "op_convert_list" for more
5871 information.
5872 OP* newLISTOP(I32 type, I32 flags, OP* first,
5874 OP* last)
5875 newLOGOP
5877 Constructs, checks, and returns a logical (flow control) op.
5878 "type" is the opcode. "flags" gives the eight bits of
5879 "op_flags", except that "OPf_KIDS" will be set automatically,
5880 and, shifted up eight bits, the eight bits of "op_private",
5881 except that the bit with value 1 is automatically set. "first"
5882 supplies the expression controlling the flow, and "other"
5883 supplies the side (alternate) chain of ops; they are consumed
5884 by this function and become part of the constructed op tree.
5885 OP* newLOGOP(I32 optype, I32 flags, OP *first,
5887 OP *other)
5888 newLOOPEX
5890 Constructs, checks, and returns a loop-exiting op (such as
5891 "goto" or "last"). "type" is the opcode. "label" supplies the
5892 parameter determining the target of the op; it is consumed by
5893 this function and becomes part of the constructed op tree.
5894 OP* newLOOPEX(I32 type, OP* label)
5896 newLOOPOP
5898 Constructs, checks, and returns an op tree expressing a loop.
5899 This is only a loop in the control flow through the op tree; it
5900 does not have the heavyweight loop structure that allows
5901 exiting the loop by "last" and suchlike. "flags" gives the
5902 eight bits of "op_flags" for the top-level op, except that some
5903 bits will be set automatically as required. "expr" supplies
5904 the expression controlling loop iteration, and "block" supplies
5905 the body of the loop; they are consumed by this function and
5906 become part of the constructed op tree. "debuggable" is
5907 currently unused and should always be 1.
5908 OP* newLOOPOP(I32 flags, I32 debuggable, OP* expr,
5910 OP* block)
5911 newMETHOP
5913 Constructs, checks, and returns an op of method type with a
5914 method name evaluated at runtime. "type" is the opcode.
5915 "flags" gives the eight bits of "op_flags", except that
5916 "OPf_KIDS" will be set automatically, and, shifted up eight
5917 bits, the eight bits of "op_private", except that the bit with
5918 value 1 is automatically set. "dynamic_meth" supplies an op
5919 which evaluates method name; it is consumed by this function
5920 and become part of the constructed op tree. Supported optypes:
5921 "OP_METHOD".
5922 OP* newMETHOP(I32 type, I32 flags, OP* dynamic_meth)
5924 newMETHOP_named
5926 Constructs, checks, and returns an op of method type with a
5927 constant method name. "type" is the opcode. "flags" gives the
5928 eight bits of "op_flags", and, shifted up eight bits, the eight
5929 bits of "op_private". "const_meth" supplies a constant method
5930 name; it must be a shared COW string. Supported optypes:
5931 "OP_METHOD_NAMED".
5932 OP* newMETHOP_named(I32 type, I32 flags,
5934 SV* const_meth)
5935 newNULLLIST
5937 Constructs, checks, and returns a new "stub" op, which
5938 represents an empty list expression.
5939 OP* newNULLLIST()
5941 newOP Constructs, checks, and returns an op of any base type (any
5943 type that has no extra fields). "type" is the opcode. "flags"
5944 gives the eight bits of "op_flags", and, shifted up eight bits,
5945 the eight bits of "op_private".
5946 OP* newOP(I32 optype, I32 flags)
5948 newPADOP
5950 Constructs, checks, and returns an op of any type that involves
5951 a reference to a pad element. "type" is the opcode. "flags"
5952 gives the eight bits of "op_flags". A pad slot is
5953 automatically allocated, and is populated with "sv"; this
5954 function takes ownership of one reference to it.
5955 This function only exists if Perl has been compiled to use
5957 ithreads.
5958 OP* newPADOP(I32 type, I32 flags, SV* sv)
5960 newPMOP Constructs, checks, and returns an op of any pattern matching
5962 type. "type" is the opcode. "flags" gives the eight bits of
5963 "op_flags" and, shifted up eight bits, the eight bits of
5964 "op_private".
5965 OP* newPMOP(I32 type, I32 flags)
5967 newPVOP Constructs, checks, and returns an op of any type that involves
5969 an embedded C-level pointer (PV). "type" is the opcode.
5970 "flags" gives the eight bits of "op_flags". "pv" supplies the
5971 C-level pointer. Depending on the op type, the memory
5972 referenced by "pv" may be freed when the op is destroyed. If
5973 the op is of a freeing type, "pv" must have been allocated
5974 using "PerlMemShared_malloc".
5975 OP* newPVOP(I32 type, I32 flags, char* pv)
5977 newRANGE
5979 Constructs and returns a "range" op, with subordinate "flip"
5980 and "flop" ops. "flags" gives the eight bits of "op_flags" for
5981 the "flip" op and, shifted up eight bits, the eight bits of
5982 "op_private" for both the "flip" and "range" ops, except that
5983 the bit with value 1 is automatically set. "left" and "right"
5984 supply the expressions controlling the endpoints of the range;
5985 they are consumed by this function and become part of the
5986 constructed op tree.
5987 OP* newRANGE(I32 flags, OP* left, OP* right)
5989 newSLICEOP
5991 Constructs, checks, and returns an "lslice" (list slice) op.
5992 "flags" gives the eight bits of "op_flags", except that
5993 "OPf_KIDS" will be set automatically, and, shifted up eight
5994 bits, the eight bits of "op_private", except that the bit with
5995 value 1 or 2 is automatically set as required. "listval" and
5996 "subscript" supply the parameters of the slice; they are
5997 consumed by this function and become part of the constructed op
5998 tree.
5999 OP* newSLICEOP(I32 flags, OP* subscript, OP* listop)
6001 newSTATEOP
6003 Constructs a state op (COP). The state op is normally a
6004 "nextstate" op, but will be a "dbstate" op if debugging is
6005 enabled for currently-compiled code. The state op is populated
6006 from "PL_curcop" (or "PL_compiling"). If "label" is non-null,
6007 it supplies the name of a label to attach to the state op; this
6008 function takes ownership of the memory pointed at by "label",
6009 and will free it. "flags" gives the eight bits of "op_flags"
6010 for the state op.
6011 If "o" is null, the state op is returned. Otherwise the state
6013 op is combined with "o" into a "lineseq" list op, which is
6014 returned. "o" is consumed by this function and becomes part of
6015 the returned op tree.
6016 OP* newSTATEOP(I32 flags, char* label, OP* o)
6018 newSVOP Constructs, checks, and returns an op of any type that involves
6020 an embedded SV. "type" is the opcode. "flags" gives the eight
6021 bits of "op_flags". "sv" gives the SV to embed in the op; this
6022 function takes ownership of one reference to it.
6023 OP* newSVOP(I32 type, I32 flags, SV* sv)
6025 newUNOP Constructs, checks, and returns an op of any unary type.
6027 "type" is the opcode. "flags" gives the eight bits of
6028 "op_flags", except that "OPf_KIDS" will be set automatically if
6029 required, and, shifted up eight bits, the eight bits of
6030 "op_private", except that the bit with value 1 is automatically
6031 set. "first" supplies an optional op to be the direct child of
6032 the unary op; it is consumed by this function and become part
6033 of the constructed op tree.
6034 OP* newUNOP(I32 type, I32 flags, OP* first)
6036 newUNOP_AUX
6038 Similar to "newUNOP", but creates an "UNOP_AUX" struct instead,
6039 with "op_aux" initialised to "aux"
6040 OP* newUNOP_AUX(I32 type, I32 flags, OP* first,
6042 UNOP_AUX_item *aux)
6043 newWHENOP
6045 Constructs, checks, and returns an op tree expressing a "when"
6046 block. "cond" supplies the test expression, and "block"
6047 supplies the block that will be executed if the test evaluates
6048 to true; they are consumed by this function and become part of
6049 the constructed op tree. "cond" will be interpreted
6050 DWIMically, often as a comparison against $_, and may be null
6051 to generate a "default" block.
6052 OP* newWHENOP(OP* cond, OP* block)
6054 newWHILEOP
6056 Constructs, checks, and returns an op tree expressing a "while"
6057 loop. This is a heavyweight loop, with structure that allows
6058 exiting the loop by "last" and suchlike.
6059 "loop" is an optional preconstructed "enterloop" op to use in
6061 the loop; if it is null then a suitable op will be constructed
6062 automatically. "expr" supplies the loop's controlling
6063 expression. "block" supplies the main body of the loop, and
6064 "cont" optionally supplies a "continue" block that operates as
6065 a second half of the body. All of these optree inputs are
6066 consumed by this function and become part of the constructed op
6067 tree.
6068 "flags" gives the eight bits of "op_flags" for the "leaveloop"
6070 op and, shifted up eight bits, the eight bits of "op_private"
6071 for the "leaveloop" op, except that (in both cases) some bits
6072 will be set automatically. "debuggable" is currently unused
6073 and should always be 1. "has_my" can be supplied as true to
6074 force the loop body to be enclosed in its own scope.
6075 OP* newWHILEOP(I32 flags, I32 debuggable,
6077 LOOP* loop, OP* expr, OP* block,
6078 OP* cont, I32 has_my)
6079
6081 alloccopstash
6082 NOTE: this function is experimental and may change or be
6083 removed without notice.
6084 Available only under threaded builds, this function allocates
6086 an entry in "PL_stashpad" for the stash passed to it.
6087 PADOFFSET alloccopstash(HV *hv)
6089 block_end
6091 Handles compile-time scope exit. "floor" is the savestack
6092 index returned by "block_start", and "seq" is the body of the
6093 block. Returns the block, possibly modified.
6094 OP* block_end(I32 floor, OP* seq)
6096 block_start
6098 Handles compile-time scope entry. Arranges for hints to be
6099 restored on block exit and also handles pad sequence numbers to
6100 make lexical variables scope right. Returns a savestack index
6101 for use with "block_end".
6102 int block_start(int full)
6104 ck_entersub_args_list
6106 Performs the default fixup of the arguments part of an
6107 "entersub" op tree. This consists of applying list context to
6108 each of the argument ops. This is the standard treatment used
6109 on a call marked with "&", or a method call, or a call through
6110 a subroutine reference, or any other call where the callee
6111 can't be identified at compile time, or a call where the callee
6112 has no prototype.
6113 OP* ck_entersub_args_list(OP *entersubop)
6115 ck_entersub_args_proto
6117 Performs the fixup of the arguments part of an "entersub" op
6118 tree based on a subroutine prototype. This makes various
6119 modifications to the argument ops, from applying context up to
6120 inserting "refgen" ops, and checking the number and syntactic
6121 types of arguments, as directed by the prototype. This is the
6122 standard treatment used on a subroutine call, not marked with
6123 "&", where the callee can be identified at compile time and has
6124 a prototype.
6125 "protosv" supplies the subroutine prototype to be applied to
6127 the call. It may be a normal defined scalar, of which the
6128 string value will be used. Alternatively, for convenience, it
6129 may be a subroutine object (a "CV*" that has been cast to
6130 "SV*") which has a prototype. The prototype supplied, in
6131 whichever form, does not need to match the actual callee
6132 referenced by the op tree.
6133 If the argument ops disagree with the prototype, for example by
6135 having an unacceptable number of arguments, a valid op tree is
6136 returned anyway. The error is reflected in the parser state,
6137 normally resulting in a single exception at the top level of
6138 parsing which covers all the compilation errors that occurred.
6139 In the error message, the callee is referred to by the name
6140 defined by the "namegv" parameter.
6141 OP* ck_entersub_args_proto(OP *entersubop,
6143 GV *namegv, SV *protosv)
6144 ck_entersub_args_proto_or_list
6146 Performs the fixup of the arguments part of an "entersub" op
6147 tree either based on a subroutine prototype or using default
6148 list-context processing. This is the standard treatment used
6149 on a subroutine call, not marked with "&", where the callee can
6150 be identified at compile time.
6151 "protosv" supplies the subroutine prototype to be applied to
6153 the call, or indicates that there is no prototype. It may be a
6154 normal scalar, in which case if it is defined then the string
6155 value will be used as a prototype, and if it is undefined then
6156 there is no prototype. Alternatively, for convenience, it may
6157 be a subroutine object (a "CV*" that has been cast to "SV*"),
6158 of which the prototype will be used if it has one. The
6159 prototype (or lack thereof) supplied, in whichever form, does
6160 not need to match the actual callee referenced by the op tree.
6161 If the argument ops disagree with the prototype, for example by
6163 having an unacceptable number of arguments, a valid op tree is
6164 returned anyway. The error is reflected in the parser state,
6165 normally resulting in a single exception at the top level of
6166 parsing which covers all the compilation errors that occurred.
6167 In the error message, the callee is referred to by the name
6168 defined by the "namegv" parameter.
6169 OP* ck_entersub_args_proto_or_list(OP *entersubop,
6171 GV *namegv,
6172 SV *protosv)
6173 cv_const_sv
6175 If "cv" is a constant sub eligible for inlining, returns the
6176 constant value returned by the sub. Otherwise, returns "NULL".
6177 Constant subs can be created with "newCONSTSUB" or as described
6179 in "Constant Functions" in perlsub.
6180 SV* cv_const_sv(const CV *const cv)
6182 cv_get_call_checker
6184 The original form of "cv_get_call_checker_flags", which does
6185 not return checker flags. When using a checker function
6186 returned by this function, it is only safe to call it with a
6187 genuine GV as its "namegv" argument.
6188 void cv_get_call_checker(CV *cv,
6190 Perl_call_checker *ckfun_p,
6191 SV **ckobj_p)
6192 cv_get_call_checker_flags
6194 Retrieves the function that will be used to fix up a call to
6195 "cv". Specifically, the function is applied to an "entersub"
6196 op tree for a subroutine call, not marked with "&", where the
6197 callee can be identified at compile time as "cv".
6198 The C-level function pointer is returned in *ckfun_p, an SV
6200 argument for it is returned in *ckobj_p, and control flags are
6201 returned in *ckflags_p. The function is intended to be called
6202 in this manner:
6203 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
6205 In this call, "entersubop" is a pointer to the "entersub" op,
6207 which may be replaced by the check function, and "namegv"
6208 supplies the name that should be used by the check function to
6209 refer to the callee of the "entersub" op if it needs to emit
6210 any diagnostics. It is permitted to apply the check function
6211 in non-standard situations, such as to a call to a different
6212 subroutine or to a method call.
6213 "namegv" may not actually be a GV. If the
6215 "CALL_CHECKER_REQUIRE_GV" bit is clear in *ckflags_p, it is
6216 permitted to pass a CV or other SV instead, anything that can
6217 be used as the first argument to "cv_name". If the
6218 "CALL_CHECKER_REQUIRE_GV" bit is set in *ckflags_p then the
6219 check function requires "namegv" to be a genuine GV.
6220 By default, the check function is
6222 Perl_ck_entersub_args_proto_or_list, the SV parameter is "cv"
6223 itself, and the "CALL_CHECKER_REQUIRE_GV" flag is clear. This
6224 implements standard prototype processing. It can be changed,
6225 for a particular subroutine, by "cv_set_call_checker_flags".
6226 If the "CALL_CHECKER_REQUIRE_GV" bit is set in "gflags" then it
6228 indicates that the caller only knows about the genuine GV
6229 version of "namegv", and accordingly the corresponding bit will
6230 always be set in *ckflags_p, regardless of the check function's
6231 recorded requirements. If the "CALL_CHECKER_REQUIRE_GV" bit is
6232 clear in "gflags" then it indicates the caller knows about the
6233 possibility of passing something other than a GV as "namegv",
6234 and accordingly the corresponding bit may be either set or
6235 clear in *ckflags_p, indicating the check function's recorded
6236 requirements.
6237 "gflags" is a bitset passed into "cv_get_call_checker_flags",
6239 in which only the "CALL_CHECKER_REQUIRE_GV" bit currently has a
6240 defined meaning (for which see above). All other bits should
6241 be clear.
6242 void cv_get_call_checker_flags(
6244 CV *cv, U32 gflags,
6245 Perl_call_checker *ckfun_p, SV **ckobj_p,
6246 U32 *ckflags_p
6247 )
6248 cv_set_call_checker
6250 The original form of "cv_set_call_checker_flags", which passes
6251 it the "CALL_CHECKER_REQUIRE_GV" flag for backward-
6252 compatibility. The effect of that flag setting is that the
6253 check function is guaranteed to get a genuine GV as its
6254 "namegv" argument.
6255 void cv_set_call_checker(CV *cv,
6257 Perl_call_checker ckfun,
6258 SV *ckobj)
6259 cv_set_call_checker_flags
6261 Sets the function that will be used to fix up a call to "cv".
6262 Specifically, the function is applied to an "entersub" op tree
6263 for a subroutine call, not marked with "&", where the callee
6264 can be identified at compile time as "cv".
6265 The C-level function pointer is supplied in "ckfun", an SV
6267 argument for it is supplied in "ckobj", and control flags are
6268 supplied in "ckflags". The function should be defined like
6269 this:
6270 STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
6272 It is intended to be called in this manner:
6274 entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
6276 In this call, "entersubop" is a pointer to the "entersub" op,
6278 which may be replaced by the check function, and "namegv"
6279 supplies the name that should be used by the check function to
6280 refer to the callee of the "entersub" op if it needs to emit
6281 any diagnostics. It is permitted to apply the check function
6282 in non-standard situations, such as to a call to a different
6283 subroutine or to a method call.
6284 "namegv" may not actually be a GV. For efficiency, perl may
6286 pass a CV or other SV instead. Whatever is passed can be used
6287 as the first argument to "cv_name". You can force perl to pass
6288 a GV by including "CALL_CHECKER_REQUIRE_GV" in the "ckflags".
6289 "ckflags" is a bitset, in which only the
6291 "CALL_CHECKER_REQUIRE_GV" bit currently has a defined meaning
6292 (for which see above). All other bits should be clear.
6293 The current setting for a particular CV can be retrieved by
6295 "cv_get_call_checker_flags".
6296 void cv_set_call_checker_flags(
6298 CV *cv, Perl_call_checker ckfun, SV *ckobj,
6299 U32 ckflags
6300 )
6301 LINKLIST
6303 Given the root of an optree, link the tree in execution order
6304 using the "op_next" pointers and return the first op executed.
6305 If this has already been done, it will not be redone, and
6306 "o->op_next" will be returned. If "o->op_next" is not already
6307 set, "o" should be at least an "UNOP".
6308 OP* LINKLIST(OP *o)
6310 newCONSTSUB
6312 Behaves like "newCONSTSUB_flags", except that "name" is nul-
6313 terminated rather than of counted length, and no flags are set.
6314 (This means that "name" is always interpreted as Latin-1.)
6315 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
6317 newCONSTSUB_flags
6319 Construct a constant subroutine, also performing some
6320 surrounding jobs. A scalar constant-valued subroutine is
6321 eligible for inlining at compile-time, and in Perl code can be
6322 created by "sub FOO () { 123 }". Other kinds of constant
6323 subroutine have other treatment.
6324 The subroutine will have an empty prototype and will ignore any
6326 arguments when called. Its constant behaviour is determined by
6327 "sv". If "sv" is null, the subroutine will yield an empty
6328 list. If "sv" points to a scalar, the subroutine will always
6329 yield that scalar. If "sv" points to an array, the subroutine
6330 will always yield a list of the elements of that array in list
6331 context, or the number of elements in the array in scalar
6332 context. This function takes ownership of one counted
6333 reference to the scalar or array, and will arrange for the
6334 object to live as long as the subroutine does. If "sv" points
6335 to a scalar then the inlining assumes that the value of the
6336 scalar will never change, so the caller must ensure that the
6337 scalar is not subsequently written to. If "sv" points to an
6338 array then no such assumption is made, so it is ostensibly safe
6339 to mutate the array or its elements, but whether this is really
6340 supported has not been determined.
6341 The subroutine will have "CvFILE" set according to "PL_curcop".
6343 Other aspects of the subroutine will be left in their default
6344 state. The caller is free to mutate the subroutine beyond its
6345 initial state after this function has returned.
6346 If "name" is null then the subroutine will be anonymous, with
6348 its "CvGV" referring to an "__ANON__" glob. If "name" is non-
6349 null then the subroutine will be named accordingly, referenced
6350 by the appropriate glob. "name" is a string of length "len"
6351 bytes giving a sigilless symbol name, in UTF-8 if "flags" has
6352 the "SVf_UTF8" bit set and in Latin-1 otherwise. The name may
6353 be either qualified or unqualified. If the name is unqualified
6354 then it defaults to being in the stash specified by "stash" if
6355 that is non-null, or to "PL_curstash" if "stash" is null. The
6356 symbol is always added to the stash if necessary, with
6357 "GV_ADDMULTI" semantics.
6358 "flags" should not have bits set other than "SVf_UTF8".
6360 If there is already a subroutine of the specified name, then
6362 the new sub will replace the existing one in the glob. A
6363 warning may be generated about the redefinition.
6364 If the subroutine has one of a few special names, such as
6366 "BEGIN" or "END", then it will be claimed by the appropriate
6367 queue for automatic running of phase-related subroutines. In
6368 this case the relevant glob will be left not containing any
6369 subroutine, even if it did contain one before. Execution of
6370 the subroutine will likely be a no-op, unless "sv" was a tied
6371 array or the caller modified the subroutine in some interesting
6372 way before it was executed. In the case of "BEGIN", the
6373 treatment is buggy: the sub will be executed when only half
6374 built, and may be deleted prematurely, possibly causing a
6375 crash.
6376 The function returns a pointer to the constructed subroutine.
6378 If the sub is anonymous then ownership of one counted reference
6379 to the subroutine is transferred to the caller. If the sub is
6380 named then the caller does not get ownership of a reference.
6381 In most such cases, where the sub has a non-phase name, the sub
6382 will be alive at the point it is returned by virtue of being
6383 contained in the glob that names it. A phase-named subroutine
6384 will usually be alive by virtue of the reference owned by the
6385 phase's automatic run queue. A "BEGIN" subroutine may have
6386 been destroyed already by the time this function returns, but
6387 currently bugs occur in that case before the caller gets
6388 control. It is the caller's responsibility to ensure that it
6389 knows which of these situations applies.
6390 CV* newCONSTSUB_flags(HV* stash, const char* name,
6392 STRLEN len, U32 flags, SV* sv)
6393 newXS Used by "xsubpp" to hook up XSUBs as Perl subs. "filename"
6395 needs to be static storage, as it is used directly as CvFILE(),
6396 without a copy being made.
6397 op_append_elem
6399 Append an item to the list of ops contained directly within a
6400 list-type op, returning the lengthened list. "first" is the
6401 list-type op, and "last" is the op to append to the list.
6402 "optype" specifies the intended opcode for the list. If
6403 "first" is not already a list of the right type, it will be
6404 upgraded into one. If either "first" or "last" is null, the
6405 other is returned unchanged.
6406 OP* op_append_elem(I32 optype, OP* first, OP* last)
6408 op_append_list
6410 Concatenate the lists of ops contained directly within two
6411 list-type ops, returning the combined list. "first" and "last"
6412 are the list-type ops to concatenate. "optype" specifies the
6413 intended opcode for the list. If either "first" or "last" is
6414 not already a list of the right type, it will be upgraded into
6415 one. If either "first" or "last" is null, the other is
6416 returned unchanged.
6417 OP* op_append_list(I32 optype, OP* first, OP* last)
6419 OP_CLASS
6421 Return the class of the provided OP: that is, which of the *OP
6422 structures it uses. For core ops this currently gets the
6423 information out of "PL_opargs", which does not always
6424 accurately reflect the type used; in v5.26 onwards, see also
6425 the function "op_class" which can do a better job of
6426 determining the used type.
6427 For custom ops the type is returned from the registration, and
6429 it is up to the registree to ensure it is accurate. The value
6430 returned will be one of the "OA_"* constants from op.h.
6431 U32 OP_CLASS(OP *o)
6433 op_contextualize
6435 Applies a syntactic context to an op tree representing an
6436 expression. "o" is the op tree, and "context" must be
6437 "G_SCALAR", "G_ARRAY", or "G_VOID" to specify the context to
6438 apply. The modified op tree is returned.
6439 OP* op_contextualize(OP* o, I32 context)
6441 op_convert_list
6443 Converts "o" into a list op if it is not one already, and then
6444 converts it into the specified "type", calling its check
6445 function, allocating a target if it needs one, and folding
6446 constants.
6447 A list-type op is usually constructed one kid at a time via
6449 "newLISTOP", "op_prepend_elem" and "op_append_elem". Then
6450 finally it is passed to "op_convert_list" to make it the right
6451 type.
6452 OP* op_convert_list(I32 optype, I32 flags, OP* o)
6454 OP_DESC Return a short description of the provided OP.
6456 const char * OP_DESC(OP *o)
6458 op_free Free an op and its children. Only use this when an op is no
6460 longer linked to from any optree.
6461 void op_free(OP* arg)
6463 OpHAS_SIBLING
6465 Returns true if "o" has a sibling
6466 bool OpHAS_SIBLING(OP *o)
6468 OpLASTSIB_set
6470 Marks "o" as having no further siblings and marks o as having
6471 the specified parent. See also "OpMORESIB_set" and
6472 "OpMAYBESIB_set". For a higher-level interface, see
6473 "op_sibling_splice".
6474 void OpLASTSIB_set(OP *o, OP *parent)
6476 op_linklist
6478 This function is the implementation of the "LINKLIST" macro.
6479 It should not be called directly.
6480 OP* op_linklist(OP *o)
6482 op_lvalue
6484 NOTE: this function is experimental and may change or be
6485 removed without notice.
6486 Propagate lvalue ("modifiable") context to an op and its
6488 children. "type" represents the context type, roughly based on
6489 the type of op that would do the modifying, although "local()"
6490 is represented by "OP_NULL", because it has no op type of its
6491 own (it is signalled by a flag on the lvalue op).
6492 This function detects things that can't be modified, such as
6494 "$x+1", and generates errors for them. For example, "$x+1 = 2"
6495 would cause it to be called with an op of type "OP_ADD" and a
6496 "type" argument of "OP_SASSIGN".
6497 It also flags things that need to behave specially in an lvalue
6499 context, such as "$$x = 5" which might have to vivify a
6500 reference in $x.
6501 OP* op_lvalue(OP* o, I32 type)
6503 OpMAYBESIB_set
6505 Conditionally does "OpMORESIB_set" or "OpLASTSIB_set" depending
6506 on whether "sib" is non-null. For a higher-level interface, see
6507 "op_sibling_splice".
6508 void OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
6510 OpMORESIB_set
6512 Sets the sibling of "o" to the non-zero value "sib". See also
6513 "OpLASTSIB_set" and "OpMAYBESIB_set". For a higher-level
6514 interface, see "op_sibling_splice".
6515 void OpMORESIB_set(OP *o, OP *sib)
6517 OP_NAME Return the name of the provided OP. For core ops this looks up
6519 the name from the op_type; for custom ops from the op_ppaddr.
6520 const char * OP_NAME(OP *o)
6522 op_null Neutralizes an op when it is no longer needed, but is still
6524 linked to from other ops.
6525 void op_null(OP* o)
6527 op_parent
6529 Returns the parent OP of "o", if it has a parent. Returns
6530 "NULL" otherwise.
6531 OP* op_parent(OP *o)
6533 op_prepend_elem
6535 Prepend an item to the list of ops contained directly within a
6536 list-type op, returning the lengthened list. "first" is the op
6537 to prepend to the list, and "last" is the list-type op.
6538 "optype" specifies the intended opcode for the list. If "last"
6539 is not already a list of the right type, it will be upgraded
6540 into one. If either "first" or "last" is null, the other is
6541 returned unchanged.
6542 OP* op_prepend_elem(I32 optype, OP* first, OP* last)
6544 op_scope
6546 NOTE: this function is experimental and may change or be
6547 removed without notice.
6548 Wraps up an op tree with some additional ops so that at runtime
6550 a dynamic scope will be created. The original ops run in the
6551 new dynamic scope, and then, provided that they exit normally,
6552 the scope will be unwound. The additional ops used to create
6553 and unwind the dynamic scope will normally be an
6554 "enter"/"leave" pair, but a "scope" op may be used instead if
6555 the ops are simple enough to not need the full dynamic scope
6556 structure.
6557 OP* op_scope(OP* o)
6559 OpSIBLING
6561 Returns the sibling of "o", or "NULL" if there is no sibling
6562 OP* OpSIBLING(OP *o)
6564 op_sibling_splice
6566 A general function for editing the structure of an existing
6567 chain of op_sibling nodes. By analogy with the perl-level
6568 "splice()" function, allows you to delete zero or more
6569 sequential nodes, replacing them with zero or more different
6570 nodes. Performs the necessary op_first/op_last housekeeping on
6571 the parent node and op_sibling manipulation on the children.
6572 The last deleted node will be marked as the last node by
6573 updating the op_sibling/op_sibparent or op_moresib field as
6574 appropriate.
6575 Note that op_next is not manipulated, and nodes are not freed;
6577 that is the responsibility of the caller. It also won't create
6578 a new list op for an empty list etc; use higher-level functions
6579 like op_append_elem() for that.
6580 "parent" is the parent node of the sibling chain. It may passed
6582 as "NULL" if the splicing doesn't affect the first or last op
6583 in the chain.
6584 "start" is the node preceding the first node to be spliced.
6586 Node(s) following it will be deleted, and ops will be inserted
6587 after it. If it is "NULL", the first node onwards is deleted,
6588 and nodes are inserted at the beginning.
6589 "del_count" is the number of nodes to delete. If zero, no
6591 nodes are deleted. If -1 or greater than or equal to the
6592 number of remaining kids, all remaining kids are deleted.
6593 "insert" is the first of a chain of nodes to be inserted in
6595 place of the nodes. If "NULL", no nodes are inserted.
6596 The head of the chain of deleted ops is returned, or "NULL" if
6598 no ops were deleted.
6599 For example:
6601 action before after returns
6603 ------ ----- ----- -------
6604 P P
6606 splice(P, A, 2, X-Y-Z) | | B-C
6607 A-B-C-D A-X-Y-Z-D
6608 P P
6610 splice(P, NULL, 1, X-Y) | | A
6611 A-B-C-D X-Y-B-C-D
6612 P P
6614 splice(P, NULL, 3, NULL) | | A-B-C
6615 A-B-C-D D
6616 P P
6618 splice(P, B, 0, X-Y) | | NULL
6619 A-B-C-D A-B-X-Y-C-D
6620 For lower-level direct manipulation of "op_sibparent" and
6622 "op_moresib", see "OpMORESIB_set", "OpLASTSIB_set",
6623 "OpMAYBESIB_set".
6624 OP* op_sibling_splice(OP *parent, OP *start,
6626 int del_count, OP* insert)
6627 OP_TYPE_IS
6629 Returns true if the given OP is not a "NULL" pointer and if it
6630 is of the given type.
6631 The negation of this macro, "OP_TYPE_ISNT" is also available as
6633 well as "OP_TYPE_IS_NN" and "OP_TYPE_ISNT_NN" which elide the
6634 NULL pointer check.
6635 bool OP_TYPE_IS(OP *o, Optype type)
6637 OP_TYPE_IS_OR_WAS
6639 Returns true if the given OP is not a NULL pointer and if it is
6640 of the given type or used to be before being replaced by an OP
6641 of type OP_NULL.
6642 The negation of this macro, "OP_TYPE_ISNT_AND_WASNT" is also
6644 available as well as "OP_TYPE_IS_OR_WAS_NN" and
6645 "OP_TYPE_ISNT_AND_WASNT_NN" which elide the "NULL" pointer
6646 check.
6647 bool OP_TYPE_IS_OR_WAS(OP *o, Optype type)
6649 rv2cv_op_cv
6651 Examines an op, which is expected to identify a subroutine at
6652 runtime, and attempts to determine at compile time which
6653 subroutine it identifies. This is normally used during Perl
6654 compilation to determine whether a prototype can be applied to
6655 a function call. "cvop" is the op being considered, normally
6656 an "rv2cv" op. A pointer to the identified subroutine is
6657 returned, if it could be determined statically, and a null
6658 pointer is returned if it was not possible to determine
6659 statically.
6660 Currently, the subroutine can be identified statically if the
6662 RV that the "rv2cv" is to operate on is provided by a suitable
6663 "gv" or "const" op. A "gv" op is suitable if the GV's CV slot
6664 is populated. A "const" op is suitable if the constant value
6665 must be an RV pointing to a CV. Details of this process may
6666 change in future versions of Perl. If the "rv2cv" op has the
6667 "OPpENTERSUB_AMPER" flag set then no attempt is made to
6668 identify the subroutine statically: this flag is used to
6669 suppress compile-time magic on a subroutine call, forcing it to
6670 use default runtime behaviour.
6671 If "flags" has the bit "RV2CVOPCV_MARK_EARLY" set, then the
6673 handling of a GV reference is modified. If a GV was examined
6674 and its CV slot was found to be empty, then the "gv" op has the
6675 "OPpEARLY_CV" flag set. If the op is not optimised away, and
6676 the CV slot is later populated with a subroutine having a
6677 prototype, that flag eventually triggers the warning "called
6678 too early to check prototype".
6679 If "flags" has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then
6681 instead of returning a pointer to the subroutine it returns a
6682 pointer to the GV giving the most appropriate name for the
6683 subroutine in this context. Normally this is just the "CvGV"
6684 of the subroutine, but for an anonymous ("CvANON") subroutine
6685 that is referenced through a GV it will be the referencing GV.
6686 The resulting "GV*" is cast to "CV*" to be returned. A null
6687 pointer is returned as usual if there is no statically-
6688 determinable subroutine.
6689 CV* rv2cv_op_cv(OP *cvop, U32 flags)
6691
6693 packlist
6694 The engine implementing "pack()" Perl function.
6695 void packlist(SV *cat, const char *pat,
6697 const char *patend, SV **beglist,
6698 SV **endlist)
6699 unpackstring
6701 The engine implementing the "unpack()" Perl function.
6702 Using the template "pat..patend", this function unpacks the
6704 string "s..strend" into a number of mortal SVs, which it pushes
6705 onto the perl argument (@_) stack (so you will need to issue a
6706 "PUTBACK" before and "SPAGAIN" after the call to this
6707 function). It returns the number of pushed elements.
6708 The "strend" and "patend" pointers should point to the byte
6710 following the last character of each string.
6711 Although this function returns its values on the perl argument
6713 stack, it doesn't take any parameters from that stack (and thus
6714 in particular there's no need to do a "PUSHMARK" before calling
6715 it, unlike "call_pv" for example).
6716 SSize_t unpackstring(const char *pat,
6718 const char *patend, const char *s,
6719 const char *strend, U32 flags)
6720
6722 CvPADLIST
6723 NOTE: this function is experimental and may change or be
6724 removed without notice.
6725 CV's can have CvPADLIST(cv) set to point to a PADLIST. This is
6727 the CV's scratchpad, which stores lexical variables and opcode
6728 temporary and per-thread values.
6729 For these purposes "formats" are a kind-of CV; eval""s are too
6731 (except they're not callable at will and are always thrown away
6732 after the eval"" is done executing). Require'd files are
6733 simply evals without any outer lexical scope.
6734 XSUBs do not have a "CvPADLIST". "dXSTARG" fetches values from
6736 "PL_curpad", but that is really the callers pad (a slot of
6737 which is allocated by every entersub). Do not get or set
6738 "CvPADLIST" if a CV is an XSUB (as determined by "CvISXSUB()"),
6739 "CvPADLIST" slot is reused for a different internal purpose in
6740 XSUBs.
6741 The PADLIST has a C array where pads are stored.
6743 The 0th entry of the PADLIST is a PADNAMELIST which represents
6745 the "names" or rather the "static type information" for
6746 lexicals. The individual elements of a PADNAMELIST are
6747 PADNAMEs. Future refactorings might stop the PADNAMELIST from
6748 being stored in the PADLIST's array, so don't rely on it. See
6749 "PadlistNAMES".
6750 The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the
6752 stack frame at that depth of recursion into the CV. The 0th
6753 slot of a frame AV is an AV which is @_. Other entries are
6754 storage for variables and op targets.
6755 Iterating over the PADNAMELIST iterates over all possible pad
6757 items. Pad slots for targets ("SVs_PADTMP") and GVs end up
6758 having &PL_padname_undef "names", while slots for constants
6759 have &PL_padname_const "names" (see "pad_alloc"). That
6760 &PL_padname_undef and &PL_padname_const are used is an
6761 implementation detail subject to change. To test for them, use
6762 "!PadnamePV(name)" and "PadnamePV(name) && !PadnameLEN(name)",
6763 respectively.
6764 Only "my"/"our" variable slots get valid names. The rest are
6766 op targets/GVs/constants which are statically allocated or
6767 resolved at compile time. These don't have names by which they
6768 can be looked up from Perl code at run time through eval"" the
6769 way "my"/"our" variables can be. Since they can't be looked up
6770 by "name" but only by their index allocated at compile time
6771 (which is usually in "PL_op->op_targ"), wasting a name SV for
6772 them doesn't make sense.
6773 The pad names in the PADNAMELIST have their PV holding the name
6775 of the variable. The "COP_SEQ_RANGE_LOW" and "_HIGH" fields
6776 form a range (low+1..high inclusive) of cop_seq numbers for
6777 which the name is valid. During compilation, these fields may
6778 hold the special value PERL_PADSEQ_INTRO to indicate various
6779 stages:
6780 COP_SEQ_RANGE_LOW _HIGH
6782 ----------------- -----
6783 PERL_PADSEQ_INTRO 0 variable not yet introduced:
6784 { my ($x
6785 valid-seq# PERL_PADSEQ_INTRO variable in scope:
6786 { my ($x);
6787 valid-seq# valid-seq# compilation of scope complete:
6788 { my ($x); .... }
6789 When a lexical var hasn't yet been introduced, it already
6791 exists from the perspective of duplicate declarations, but not
6792 for variable lookups, e.g.
6793 my ($x, $x); # '"my" variable $x masks earlier declaration'
6795 my $x = $x; # equal to my $x = $::x;
6796 For typed lexicals "PadnameTYPE" points at the type stash. For
6798 "our" lexicals, "PadnameOURSTASH" points at the stash of the
6799 associated global (so that duplicate "our" declarations in the
6800 same package can be detected). "PadnameGEN" is sometimes used
6801 to store the generation number during compilation.
6802 If "PadnameOUTER" is set on the pad name, then that slot in the
6804 frame AV is a REFCNT'ed reference to a lexical from "outside".
6805 Such entries are sometimes referred to as 'fake'. In this
6806 case, the name does not use 'low' and 'high' to store a cop_seq
6807 range, since it is in scope throughout. Instead 'high' stores
6808 some flags containing info about the real lexical (is it
6809 declared in an anon, and is it capable of being instantiated
6810 multiple times?), and for fake ANONs, 'low' contains the index
6811 within the parent's pad where the lexical's value is stored, to
6812 make cloning quicker.
6813 If the 'name' is "&" the corresponding entry in the PAD is a CV
6815 representing a possible closure.
6816 Note that formats are treated as anon subs, and are cloned each
6818 time write is called (if necessary).
6819 The flag "SVs_PADSTALE" is cleared on lexicals each time the
6821 "my()" is executed, and set on scope exit. This allows the
6822 "Variable $x is not available" warning to be generated in
6823 evals, such as
6824 { my $x = 1; sub f { eval '$x'} } f();
6826 For state vars, "SVs_PADSTALE" is overloaded to mean 'not yet
6828 initialised', but this internal state is stored in a separate
6829 pad entry.
6830 PADLIST * CvPADLIST(CV *cv)
6832 pad_add_name_pvs
6834 Exactly like "pad_add_name_pvn", but takes a literal string
6835 instead of a string/length pair.
6836 PADOFFSET pad_add_name_pvs("name", U32 flags,
6838 HV *typestash, HV *ourstash)
6839 PadARRAY
6841 NOTE: this function is experimental and may change or be
6842 removed without notice.
6843 The C array of pad entries.
6845 SV ** PadARRAY(PAD * pad)
6847 pad_findmy_pvs
6849 Exactly like "pad_findmy_pvn", but takes a literal string
6850 instead of a string/length pair.
6851 PADOFFSET pad_findmy_pvs("name", U32 flags)
6853 PadlistARRAY
6855 NOTE: this function is experimental and may change or be
6856 removed without notice.
6857 The C array of a padlist, containing the pads. Only subscript
6859 it with numbers >= 1, as the 0th entry is not guaranteed to
6860 remain usable.
6861 PAD ** PadlistARRAY(PADLIST * padlist)
6863 PadlistMAX
6865 NOTE: this function is experimental and may change or be
6866 removed without notice.
6867 The index of the last allocated space in the padlist. Note
6869 that the last pad may be in an earlier slot. Any entries
6870 following it will be "NULL" in that case.
6871 SSize_t PadlistMAX(PADLIST * padlist)
6873 PadlistNAMES
6875 NOTE: this function is experimental and may change or be
6876 removed without notice.
6877 The names associated with pad entries.
6879 PADNAMELIST * PadlistNAMES(PADLIST * padlist)
6881 PadlistNAMESARRAY
6883 NOTE: this function is experimental and may change or be
6884 removed without notice.
6885 The C array of pad names.
6887 PADNAME ** PadlistNAMESARRAY(PADLIST * padlist)
6889 PadlistNAMESMAX
6891 NOTE: this function is experimental and may change or be
6892 removed without notice.
6893 The index of the last pad name.
6895 SSize_t PadlistNAMESMAX(PADLIST * padlist)
6897 PadlistREFCNT
6899 NOTE: this function is experimental and may change or be
6900 removed without notice.
6901 The reference count of the padlist. Currently this is always
6903 1.
6904 U32 PadlistREFCNT(PADLIST * padlist)
6906 PadMAX NOTE: this function is experimental and may change or be
6908 removed without notice.
6909 The index of the last pad entry.
6911 SSize_t PadMAX(PAD * pad)
6913 PadnameLEN
6915 NOTE: this function is experimental and may change or be
6916 removed without notice.
6917 The length of the name.
6919 STRLEN PadnameLEN(PADNAME * pn)
6921 PadnamelistARRAY
6923 NOTE: this function is experimental and may change or be
6924 removed without notice.
6925 The C array of pad names.
6927 PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl)
6929 PadnamelistMAX
6931 NOTE: this function is experimental and may change or be
6932 removed without notice.
6933 The index of the last pad name.
6935 SSize_t PadnamelistMAX(PADNAMELIST * pnl)
6937 PadnamelistREFCNT
6939 NOTE: this function is experimental and may change or be
6940 removed without notice.
6941 The reference count of the pad name list.
6943 SSize_t PadnamelistREFCNT(PADNAMELIST * pnl)
6945 PadnamelistREFCNT_dec
6947 NOTE: this function is experimental and may change or be
6948 removed without notice.
6949 Lowers the reference count of the pad name list.
6951 void PadnamelistREFCNT_dec(PADNAMELIST * pnl)
6953 PadnamePV
6955 NOTE: this function is experimental and may change or be
6956 removed without notice.
6957 The name stored in the pad name struct. This returns "NULL"
6959 for a target slot.
6960 char * PadnamePV(PADNAME * pn)
6962 PadnameREFCNT
6964 NOTE: this function is experimental and may change or be
6965 removed without notice.
6966 The reference count of the pad name.
6968 SSize_t PadnameREFCNT(PADNAME * pn)
6970 PadnameREFCNT_dec
6972 NOTE: this function is experimental and may change or be
6973 removed without notice.
6974 Lowers the reference count of the pad name.
6976 void PadnameREFCNT_dec(PADNAME * pn)
6978 PadnameSV
6980 NOTE: this function is experimental and may change or be
6981 removed without notice.
6982 Returns the pad name as a mortal SV.
6984 SV * PadnameSV(PADNAME * pn)
6986 PadnameUTF8
6988 NOTE: this function is experimental and may change or be
6989 removed without notice.
6990 Whether PadnamePV is in UTF-8. Currently, this is always true.
6992 bool PadnameUTF8(PADNAME * pn)
6994 pad_new Create a new padlist, updating the global variables for the
6996 currently-compiling padlist to point to the new padlist. The
6997 following flags can be OR'ed together:
6998 padnew_CLONE this pad is for a cloned CV
7000 padnew_SAVE save old globals on the save stack
7001 padnew_SAVESUB also save extra stuff for start of sub
7002 PADLIST* pad_new(int flags)
7004 PL_comppad
7006 NOTE: this function is experimental and may change or be
7007 removed without notice.
7008 During compilation, this points to the array containing the
7010 values part of the pad for the currently-compiling code. (At
7011 runtime a CV may have many such value arrays; at compile time
7012 just one is constructed.) At runtime, this points to the array
7013 containing the currently-relevant values for the pad for the
7014 currently-executing code.
7015 PL_comppad_name
7017 NOTE: this function is experimental and may change or be
7018 removed without notice.
7019 During compilation, this points to the array containing the
7021 names part of the pad for the currently-compiling code.
7022 PL_curpad
7024 NOTE: this function is experimental and may change or be
7025 removed without notice.
7026 Points directly to the body of the "PL_comppad" array. (I.e.,
7028 this is "PadARRAY(PL_comppad)".)
7029
7031 PL_curcop
7032 The currently active COP (control op) roughly representing the
7033 current statement in the source.
7034 COP* PL_curcop
7036 PL_curstash
7038 The stash for the package code will be compiled into.
7039 HV* PL_curstash
7041 PL_defgv
7043 The GV representing *_. Useful for access to $_.
7044 GV * PL_defgv
7046 PL_exit_flags
7048 Contains flags controlling perl's behaviour on exit():
7049 • "PERL_EXIT_DESTRUCT_END"
7051 If set, END blocks are executed when the interpreter is
7053 destroyed. This is normally set by perl itself after the
7054 interpreter is constructed.
7055 • "PERL_EXIT_ABORT"
7057 Call "abort()" on exit. This is used internally by perl
7059 itself to abort if exit is called while processing exit.
7060 • "PERL_EXIT_WARN"
7062 Warn on exit.
7064 • "PERL_EXIT_EXPECTED"
7066 Set by the "exit" in perlfunc operator.
7068 U8 PL_exit_flags
7070 PL_modglobal
7072 "PL_modglobal" is a general purpose, interpreter global HV for
7073 use by extensions that need to keep information on a per-
7074 interpreter basis. In a pinch, it can also be used as a symbol
7075 table for extensions to share data among each other. It is a
7076 good idea to use keys prefixed by the package name of the
7077 extension that owns the data.
7078 HV* PL_modglobal
7080 PL_na A convenience variable which is typically used with "SvPV" when
7082 one doesn't care about the length of the string. It is usually
7083 more efficient to either declare a local variable and use that
7084 instead or to use the "SvPV_nolen" macro.
7085 STRLEN PL_na
7087 PL_opfreehook
7089 When non-"NULL", the function pointed by this variable will be
7090 called each time an OP is freed with the corresponding OP as
7091 the argument. This allows extensions to free any extra
7092 attribute they have locally attached to an OP. It is also
7093 assured to first fire for the parent OP and then for its kids.
7094 When you replace this variable, it is considered a good
7096 practice to store the possibly previously installed hook and
7097 that you recall it inside your own.
7098 Perl_ophook_t PL_opfreehook
7100 PL_peepp
7102 Pointer to the per-subroutine peephole optimiser. This is a
7103 function that gets called at the end of compilation of a Perl
7104 subroutine (or equivalently independent piece of Perl code) to
7105 perform fixups of some ops and to perform small-scale
7106 optimisations. The function is called once for each subroutine
7107 that is compiled, and is passed, as sole parameter, a pointer
7108 to the op that is the entry point to the subroutine. It
7109 modifies the op tree in place.
7110 The peephole optimiser should never be completely replaced.
7112 Rather, add code to it by wrapping the existing optimiser. The
7113 basic way to do this can be seen in "Compile pass 3: peephole
7114 optimization" in perlguts. If the new code wishes to operate
7115 on ops throughout the subroutine's structure, rather than just
7116 at the top level, it is likely to be more convenient to wrap
7117 the "PL_rpeepp" hook.
7118 peep_t PL_peepp
7120 PL_perl_destruct_level
7122 This value may be set when embedding for full cleanup.
7123 Possible values:
7125 • 0 - none
7127 • 1 - full
7129 • 2 or greater - full with checks.
7131 If $ENV{PERL_DESTRUCT_LEVEL} is set to an integer greater than
7133 the value of "PL_perl_destruct_level" its value is used
7134 instead.
7135 signed char PL_perl_destruct_level
7137 PL_rpeepp
7139 Pointer to the recursive peephole optimiser. This is a
7140 function that gets called at the end of compilation of a Perl
7141 subroutine (or equivalently independent piece of Perl code) to
7142 perform fixups of some ops and to perform small-scale
7143 optimisations. The function is called once for each chain of
7144 ops linked through their "op_next" fields; it is recursively
7145 called to handle each side chain. It is passed, as sole
7146 parameter, a pointer to the op that is at the head of the
7147 chain. It modifies the op tree in place.
7148 The peephole optimiser should never be completely replaced.
7150 Rather, add code to it by wrapping the existing optimiser. The
7151 basic way to do this can be seen in "Compile pass 3: peephole
7152 optimization" in perlguts. If the new code wishes to operate
7153 only on ops at a subroutine's top level, rather than throughout
7154 the structure, it is likely to be more convenient to wrap the
7155 "PL_peepp" hook.
7156 peep_t PL_rpeepp
7158 PL_runops
7160 See "Pluggable runops" in perlguts.
7161 runops_proc_t PL_runops
7163 PL_sv_no
7165 This is the "false" SV. See "PL_sv_yes". Always refer to this
7166 as &PL_sv_no.
7167 SV PL_sv_no
7169 PL_sv_undef
7171 This is the "undef" SV. Always refer to this as &PL_sv_undef.
7172 SV PL_sv_undef
7174 PL_sv_yes
7176 This is the "true" SV. See "PL_sv_no". Always refer to this
7177 as &PL_sv_yes.
7178 SV PL_sv_yes
7180 PL_sv_zero
7182 This readonly SV has a zero numeric value and a "0" string
7183 value. It's similar to "PL_sv_no" except for its string value.
7184 Can be used as a cheap alternative to mXPUSHi(0) for example.
7185 Always refer to this as &PL_sv_zero. Introduced in 5.28.
7186 SV PL_sv_zero
7188
7190 SvRX Convenience macro to get the REGEXP from a SV. This is
7191 approximately equivalent to the following snippet:
7192 if (SvMAGICAL(sv))
7194 mg_get(sv);
7195 if (SvROK(sv))
7196 sv = MUTABLE_SV(SvRV(sv));
7197 if (SvTYPE(sv) == SVt_REGEXP)
7198 return (REGEXP*) sv;
7199 "NULL" will be returned if a REGEXP* is not found.
7201 REGEXP * SvRX(SV *sv)
7203 SvRXOK Returns a boolean indicating whether the SV (or the one it
7205 references) is a REGEXP.
7206 If you want to do something with the REGEXP* later use SvRX
7208 instead and check for NULL.
7209 bool SvRXOK(SV* sv)
7211
7213 dMARK Declare a stack marker variable, "mark", for the XSUB. See
7214 "MARK" and "dORIGMARK".
7215 dMARK;
7217 dORIGMARK
7219 Saves the original stack mark for the XSUB. See "ORIGMARK".
7220 dORIGMARK;
7222 dSP Declares a local copy of perl's stack pointer for the XSUB,
7224 available via the "SP" macro. See "SP".
7225 dSP;
7227 EXTEND Used to extend the argument stack for an XSUB's return values.
7229 Once used, guarantees that there is room for at least "nitems"
7230 to be pushed onto the stack.
7231 void EXTEND(SP, SSize_t nitems)
7233 MARK Stack marker variable for the XSUB. See "dMARK".
7235 mPUSHi Push an integer onto the stack. The stack must have room for
7237 this element. Does not use "TARG". See also "PUSHi",
7238 "mXPUSHi" and "XPUSHi".
7239 void mPUSHi(IV iv)
7241 mPUSHn Push a double onto the stack. The stack must have room for
7243 this element. Does not use "TARG". See also "PUSHn",
7244 "mXPUSHn" and "XPUSHn".
7245 void mPUSHn(NV nv)
7247 mPUSHp Push a string onto the stack. The stack must have room for
7249 this element. The "len" indicates the length of the string.
7250 Does not use "TARG". See also "PUSHp", "mXPUSHp" and "XPUSHp".
7251 void mPUSHp(char* str, STRLEN len)
7253 mPUSHs Push an SV onto the stack and mortalizes the SV. The stack
7255 must have room for this element. Does not use "TARG". See
7256 also "PUSHs" and "mXPUSHs".
7257 void mPUSHs(SV* sv)
7259 mPUSHu Push an unsigned integer onto the stack. The stack must have
7261 room for this element. Does not use "TARG". See also "PUSHu",
7262 "mXPUSHu" and "XPUSHu".
7263 void mPUSHu(UV uv)
7265 mXPUSHi Push an integer onto the stack, extending the stack if
7267 necessary. Does not use "TARG". See also "XPUSHi", "mPUSHi"
7268 and "PUSHi".
7269 void mXPUSHi(IV iv)
7271 mXPUSHn Push a double onto the stack, extending the stack if necessary.
7273 Does not use "TARG". See also "XPUSHn", "mPUSHn" and "PUSHn".
7274 void mXPUSHn(NV nv)
7276 mXPUSHp Push a string onto the stack, extending the stack if necessary.
7278 The "len" indicates the length of the string. Does not use
7279 "TARG". See also "XPUSHp", "mPUSHp" and "PUSHp".
7280 void mXPUSHp(char* str, STRLEN len)
7282 mXPUSHs Push an SV onto the stack, extending the stack if necessary and
7284 mortalizes the SV. Does not use "TARG". See also "XPUSHs" and
7285 "mPUSHs".
7286 void mXPUSHs(SV* sv)
7288 mXPUSHu Push an unsigned integer onto the stack, extending the stack if
7290 necessary. Does not use "TARG". See also "XPUSHu", "mPUSHu"
7291 and "PUSHu".
7292 void mXPUSHu(UV uv)
7294 ORIGMARK
7296 The original stack mark for the XSUB. See "dORIGMARK".
7297 POPi Pops an integer off the stack.
7299 IV POPi
7301 POPl Pops a long off the stack.
7303 long POPl
7305 POPn Pops a double off the stack.
7307 NV POPn
7309 POPp Pops a string off the stack.
7311 char* POPp
7313 POPpbytex
7315 Pops a string off the stack which must consist of bytes i.e.
7316 characters < 256.
7317 char* POPpbytex
7319 POPpx Pops a string off the stack. Identical to POPp. There are two
7321 names for historical reasons.
7322 char* POPpx
7324 POPs Pops an SV off the stack.
7326 SV* POPs
7328 POPu Pops an unsigned integer off the stack.
7330 UV POPu
7332 POPul Pops an unsigned long off the stack.
7334 long POPul
7336 PUSHi Push an integer onto the stack. The stack must have room for
7338 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
7339 or "dXSTARG" should be called to declare it. Do not call
7340 multiple "TARG"-oriented macros to return lists from XSUB's -
7341 see "mPUSHi" instead. See also "XPUSHi" and "mXPUSHi".
7342 void PUSHi(IV iv)
7344 PUSHMARK
7346 Opening bracket for arguments on a callback. See "PUTBACK" and
7347 perlcall.
7348 void PUSHMARK(SP)
7350 PUSHmortal
7352 Push a new mortal SV onto the stack. The stack must have room
7353 for this element. Does not use "TARG". See also "PUSHs",
7354 "XPUSHmortal" and "XPUSHs".
7355 void PUSHmortal
7357 PUSHn Push a double onto the stack. The stack must have room for
7359 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
7360 or "dXSTARG" should be called to declare it. Do not call
7361 multiple "TARG"-oriented macros to return lists from XSUB's -
7362 see "mPUSHn" instead. See also "XPUSHn" and "mXPUSHn".
7363 void PUSHn(NV nv)
7365 PUSHp Push a string onto the stack. The stack must have room for
7367 this element. The "len" indicates the length of the string.
7368 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
7369 should be called to declare it. Do not call multiple
7370 "TARG"-oriented macros to return lists from XSUB's - see
7371 "mPUSHp" instead. See also "XPUSHp" and "mXPUSHp".
7372 void PUSHp(char* str, STRLEN len)
7374 PUSHs Push an SV onto the stack. The stack must have room for this
7376 element. Does not handle 'set' magic. Does not use "TARG".
7377 See also "PUSHmortal", "XPUSHs", and "XPUSHmortal".
7378 void PUSHs(SV* sv)
7380 PUSHu Push an unsigned integer onto the stack. The stack must have
7382 room for this element. Handles 'set' magic. Uses "TARG", so
7383 "dTARGET" or "dXSTARG" should be called to declare it. Do not
7384 call multiple "TARG"-oriented macros to return lists from
7385 XSUB's - see "mPUSHu" instead. See also "XPUSHu" and
7386 "mXPUSHu".
7387 void PUSHu(UV uv)
7389 PUTBACK Closing bracket for XSUB arguments. This is usually handled by
7391 "xsubpp". See "PUSHMARK" and perlcall for other uses.
7392 PUTBACK;
7394 SP Stack pointer. This is usually handled by "xsubpp". See "dSP"
7396 and "SPAGAIN".
7397 SPAGAIN Refetch the stack pointer. Used after a callback. See
7399 perlcall.
7400 SPAGAIN;
7402 XPUSHi Push an integer onto the stack, extending the stack if
7404 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
7405 "dXSTARG" should be called to declare it. Do not call multiple
7406 "TARG"-oriented macros to return lists from XSUB's - see
7407 "mXPUSHi" instead. See also "PUSHi" and "mPUSHi".
7408 void XPUSHi(IV iv)
7410 XPUSHmortal
7412 Push a new mortal SV onto the stack, extending the stack if
7413 necessary. Does not use "TARG". See also "XPUSHs",
7414 "PUSHmortal" and "PUSHs".
7415 void XPUSHmortal
7417 XPUSHn Push a double onto the stack, extending the stack if necessary.
7419 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
7420 should be called to declare it. Do not call multiple
7421 "TARG"-oriented macros to return lists from XSUB's - see
7422 "mXPUSHn" instead. See also "PUSHn" and "mPUSHn".
7423 void XPUSHn(NV nv)
7425 XPUSHp Push a string onto the stack, extending the stack if necessary.
7427 The "len" indicates the length of the string. Handles 'set'
7428 magic. Uses "TARG", so "dTARGET" or "dXSTARG" should be called
7429 to declare it. Do not call multiple "TARG"-oriented macros to
7430 return lists from XSUB's - see "mXPUSHp" instead. See also
7431 "PUSHp" and "mPUSHp".
7432 void XPUSHp(char* str, STRLEN len)
7434 XPUSHs Push an SV onto the stack, extending the stack if necessary.
7436 Does not handle 'set' magic. Does not use "TARG". See also
7437 "XPUSHmortal", "PUSHs" and "PUSHmortal".
7438 void XPUSHs(SV* sv)
7440 XPUSHu Push an unsigned integer onto the stack, extending the stack if
7442 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
7443 "dXSTARG" should be called to declare it. Do not call multiple
7444 "TARG"-oriented macros to return lists from XSUB's - see
7445 "mXPUSHu" instead. See also "PUSHu" and "mPUSHu".
7446 void XPUSHu(UV uv)
7448 XSRETURN
7450 Return from XSUB, indicating number of items on the stack.
7451 This is usually handled by "xsubpp".
7452 void XSRETURN(int nitems)
7454 XSRETURN_EMPTY
7456 Return an empty list from an XSUB immediately.
7457 XSRETURN_EMPTY;
7459 XSRETURN_IV
7461 Return an integer from an XSUB immediately. Uses "XST_mIV".
7462 void XSRETURN_IV(IV iv)
7464 XSRETURN_NO
7466 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
7467 XSRETURN_NO;
7469 XSRETURN_NV
7471 Return a double from an XSUB immediately. Uses "XST_mNV".
7472 void XSRETURN_NV(NV nv)
7474 XSRETURN_PV
7476 Return a copy of a string from an XSUB immediately. Uses
7477 "XST_mPV".
7478 void XSRETURN_PV(char* str)
7480 XSRETURN_UNDEF
7482 Return &PL_sv_undef from an XSUB immediately. Uses
7483 "XST_mUNDEF".
7484 XSRETURN_UNDEF;
7486 XSRETURN_UV
7488 Return an integer from an XSUB immediately. Uses "XST_mUV".
7489 void XSRETURN_UV(IV uv)
7491 XSRETURN_YES
7493 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
7494 XSRETURN_YES;
7496 XST_mIV Place an integer into the specified position "pos" on the
7498 stack. The value is stored in a new mortal SV.
7499 void XST_mIV(int pos, IV iv)
7501 XST_mNO Place &PL_sv_no into the specified position "pos" on the stack.
7503 void XST_mNO(int pos)
7505 XST_mNV Place a double into the specified position "pos" on the stack.
7507 The value is stored in a new mortal SV.
7508 void XST_mNV(int pos, NV nv)
7510 XST_mPV Place a copy of a string into the specified position "pos" on
7512 the stack. The value is stored in a new mortal SV.
7513 void XST_mPV(int pos, char* str)
7515 XST_mUNDEF
7517 Place &PL_sv_undef into the specified position "pos" on the
7518 stack.
7519 void XST_mUNDEF(int pos)
7521 XST_mUV Place an unsigned integer into the specified position "pos" on
7523 the stack. The value is stored in a new mortal SV.
7524 void XST_mUV(int pos, UV uv)
7526 XST_mYES
7528 Place &PL_sv_yes into the specified position "pos" on the
7529 stack.
7530 void XST_mYES(int pos)
7532
7534 SVt_IV Type flag for scalars. See "svtype".
7535 SVt_NULL
7537 Type flag for scalars. See "svtype".
7538 SVt_NV Type flag for scalars. See "svtype".
7540 SVt_PV Type flag for scalars. See "svtype".
7542 SVt_PVAV
7544 Type flag for arrays. See "svtype".
7545 SVt_PVCV
7547 Type flag for subroutines. See "svtype".
7548 SVt_PVFM
7550 Type flag for formats. See "svtype".
7551 SVt_PVGV
7553 Type flag for typeglobs. See "svtype".
7554 SVt_PVHV
7556 Type flag for hashes. See "svtype".
7557 SVt_PVIO
7559 Type flag for I/O objects. See "svtype".
7560 SVt_PVIV
7562 Type flag for scalars. See "svtype".
7563 SVt_PVLV
7565 Type flag for scalars. See "svtype".
7566 SVt_PVMG
7568 Type flag for scalars. See "svtype".
7569 SVt_PVNV
7571 Type flag for scalars. See "svtype".
7572 SVt_REGEXP
7574 Type flag for regular expressions. See "svtype".
7575 svtype An enum of flags for Perl types. These are found in the file
7577 sv.h in the "svtype" enum. Test these flags with the "SvTYPE"
7578 macro.
7579 The types are:
7581 SVt_NULL
7583 SVt_IV
7584 SVt_NV
7585 SVt_RV
7586 SVt_PV
7587 SVt_PVIV
7588 SVt_PVNV
7589 SVt_PVMG
7590 SVt_INVLIST
7591 SVt_REGEXP
7592 SVt_PVGV
7593 SVt_PVLV
7594 SVt_PVAV
7595 SVt_PVHV
7596 SVt_PVCV
7597 SVt_PVFM
7598 SVt_PVIO
7599 These are most easily explained from the bottom up.
7601 "SVt_PVIO" is for I/O objects, "SVt_PVFM" for formats,
7603 "SVt_PVCV" for subroutines, "SVt_PVHV" for hashes and
7604 "SVt_PVAV" for arrays.
7605 All the others are scalar types, that is, things that can be
7607 bound to a "$" variable. For these, the internal types are
7608 mostly orthogonal to types in the Perl language.
7609 Hence, checking "SvTYPE(sv) < SVt_PVAV" is the best way to see
7611 whether something is a scalar.
7612 "SVt_PVGV" represents a typeglob. If "!SvFAKE(sv)", then it is
7614 a real, incoercible typeglob. If "SvFAKE(sv)", then it is a
7615 scalar to which a typeglob has been assigned. Assigning to it
7616 again will stop it from being a typeglob. "SVt_PVLV"
7617 represents a scalar that delegates to another scalar behind the
7618 scenes. It is used, e.g., for the return value of "substr" and
7619 for tied hash and array elements. It can hold any scalar
7620 value, including a typeglob. "SVt_REGEXP" is for regular
7621 expressions. "SVt_INVLIST" is for Perl core internal use only.
7622 "SVt_PVMG" represents a "normal" scalar (not a typeglob,
7624 regular expression, or delegate). Since most scalars do not
7625 need all the internal fields of a PVMG, we save memory by
7626 allocating smaller structs when possible. All the other types
7627 are just simpler forms of "SVt_PVMG", with fewer internal
7628 fields. "SVt_NULL" can only hold undef. "SVt_IV" can hold
7629 undef, an integer, or a reference. ("SVt_RV" is an alias for
7630 "SVt_IV", which exists for backward compatibility.) "SVt_NV"
7631 can hold any of those or a double. "SVt_PV" can only hold
7632 "undef" or a string. "SVt_PVIV" is a superset of "SVt_PV" and
7633 "SVt_IV". "SVt_PVNV" is similar. "SVt_PVMG" can hold anything
7634 "SVt_PVNV" can hold, but it can, but does not have to, be
7635 blessed or magical.
7636
7638 boolSV Returns a true SV if "b" is a true value, or a false SV if "b"
7639 is 0.
7640 See also "PL_sv_yes" and "PL_sv_no".
7642 SV * boolSV(bool b)
7644 croak_xs_usage
7646 A specialised variant of "croak()" for emitting the usage
7647 message for xsubs
7648 croak_xs_usage(cv, "eee_yow");
7650 works out the package name and subroutine name from "cv", and
7652 then calls "croak()". Hence if "cv" is &ouch::awk, it would
7653 call "croak" as:
7654 Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
7656 "eee_yow");
7657 void croak_xs_usage(const CV *const cv,
7659 const char *const params)
7660 get_sv Returns the SV of the specified Perl scalar. "flags" are
7662 passed to "gv_fetchpv". If "GV_ADD" is set and the Perl
7663 variable does not exist then it will be created. If "flags" is
7664 zero and the variable does not exist then NULL is returned.
7665 NOTE: the perl_ form of this function is deprecated.
7667 SV* get_sv(const char *name, I32 flags)
7669 looks_like_number
7671 Test if the content of an SV looks like a number (or is a
7672 number). "Inf" and "Infinity" are treated as numbers (so will
7673 not issue a non-numeric warning), even if your "atof()" doesn't
7674 grok them. Get-magic is ignored.
7675 I32 looks_like_number(SV *const sv)
7677 newRV_inc
7679 Creates an RV wrapper for an SV. The reference count for the
7680 original SV is incremented.
7681 SV* newRV_inc(SV* sv)
7683 newRV_noinc
7685 Creates an RV wrapper for an SV. The reference count for the
7686 original SV is not incremented.
7687 SV* newRV_noinc(SV *const tmpRef)
7689 newSV Creates a new SV. A non-zero "len" parameter indicates the
7691 number of bytes of preallocated string space the SV should
7692 have. An extra byte for a trailing "NUL" is also reserved.
7693 ("SvPOK" is not set for the SV even if string space is
7694 allocated.) The reference count for the new SV is set to 1.
7695 In 5.9.3, "newSV()" replaces the older "NEWSV()" API, and drops
7697 the first parameter, x, a debug aid which allowed callers to
7698 identify themselves. This aid has been superseded by a new
7699 build option, "PERL_MEM_LOG" (see "PERL_MEM_LOG" in
7700 perlhacktips). The older API is still there for use in XS
7701 modules supporting older perls.
7702 SV* newSV(const STRLEN len)
7704 newSVhek
7706 Creates a new SV from the hash key structure. It will generate
7707 scalars that point to the shared string table where possible.
7708 Returns a new (undefined) SV if "hek" is NULL.
7709 SV* newSVhek(const HEK *const hek)
7711 newSViv Creates a new SV and copies an integer into it. The reference
7713 count for the SV is set to 1.
7714 SV* newSViv(const IV i)
7716 newSVnv Creates a new SV and copies a floating point value into it.
7718 The reference count for the SV is set to 1.
7719 SV* newSVnv(const NV n)
7721 newSVpadname
7723 NOTE: this function is experimental and may change or be
7724 removed without notice.
7725 Creates a new SV containing the pad name.
7727 SV* newSVpadname(PADNAME *pn)
7729 newSVpv Creates a new SV and copies a string (which may contain "NUL"
7731 ("\0") characters) into it. The reference count for the SV is
7732 set to 1. If "len" is zero, Perl will compute the length using
7733 "strlen()", (which means if you use this option, that "s" can't
7734 have embedded "NUL" characters and has to have a terminating
7735 "NUL" byte).
7736 This function can cause reliability issues if you are likely to
7738 pass in empty strings that are not null terminated, because it
7739 will run strlen on the string and potentially run past valid
7740 memory.
7741 Using "newSVpvn" is a safer alternative for non "NUL"
7743 terminated strings. For string literals use "newSVpvs"
7744 instead. This function will work fine for "NUL" terminated
7745 strings, but if you want to avoid the if statement on whether
7746 to call "strlen" use "newSVpvn" instead (calling "strlen"
7747 yourself).
7748 SV* newSVpv(const char *const s, const STRLEN len)
7750 newSVpvf
7752 Creates a new SV and initializes it with the string formatted
7753 like "sv_catpvf".
7754 SV* newSVpvf(const char *const pat, ...)
7756 newSVpvn
7758 Creates a new SV and copies a string into it, which may contain
7759 "NUL" characters ("\0") and other binary data. The reference
7760 count for the SV is set to 1. Note that if "len" is zero, Perl
7761 will create a zero length (Perl) string. You are responsible
7762 for ensuring that the source buffer is at least "len" bytes
7763 long. If the "buffer" argument is NULL the new SV will be
7764 undefined.
7765 SV* newSVpvn(const char *const buffer,
7767 const STRLEN len)
7768 newSVpvn_flags
7770 Creates a new SV and copies a string (which may contain "NUL"
7771 ("\0") characters) into it. The reference count for the SV is
7772 set to 1. Note that if "len" is zero, Perl will create a zero
7773 length string. You are responsible for ensuring that the
7774 source string is at least "len" bytes long. If the "s"
7775 argument is NULL the new SV will be undefined. Currently the
7776 only flag bits accepted are "SVf_UTF8" and "SVs_TEMP". If
7777 "SVs_TEMP" is set, then "sv_2mortal()" is called on the result
7778 before returning. If "SVf_UTF8" is set, "s" is considered to
7779 be in UTF-8 and the "SVf_UTF8" flag will be set on the new SV.
7780 "newSVpvn_utf8()" is a convenience wrapper for this function,
7781 defined as
7782 #define newSVpvn_utf8(s, len, u) \
7784 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
7785 SV* newSVpvn_flags(const char *const s,
7787 const STRLEN len,
7788 const U32 flags)
7789 newSVpvn_share
7791 Creates a new SV with its "SvPVX_const" pointing to a shared
7792 string in the string table. If the string does not already
7793 exist in the table, it is created first. Turns on the
7794 "SvIsCOW" flag (or "READONLY" and "FAKE" in 5.16 and earlier).
7795 If the "hash" parameter is non-zero, that value is used;
7796 otherwise the hash is computed. The string's hash can later be
7797 retrieved from the SV with the "SvSHARED_HASH()" macro. The
7798 idea here is that as the string table is used for shared hash
7799 keys these strings will have "SvPVX_const == HeKEY" and hash
7800 lookup will avoid string compare.
7801 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
7803 newSVpvn_utf8
7805 Creates a new SV and copies a string (which may contain "NUL"
7806 ("\0") characters) into it. If "utf8" is true, calls
7807 "SvUTF8_on" on the new SV. Implemented as a wrapper around
7808 "newSVpvn_flags".
7809 SV* newSVpvn_utf8(const char* s, STRLEN len,
7811 U32 utf8)
7812 newSVpvs
7814 Like "newSVpvn", but takes a literal string instead of a
7815 string/length pair.
7816 SV* newSVpvs("literal string")
7818 newSVpvs_flags
7820 Like "newSVpvn_flags", but takes a literal string instead of a
7821 string/length pair.
7822 SV* newSVpvs_flags("literal string", U32 flags)
7824 newSVpv_share
7826 Like "newSVpvn_share", but takes a "NUL"-terminated string
7827 instead of a string/length pair.
7828 SV* newSVpv_share(const char* s, U32 hash)
7830 newSVpvs_share
7832 Like "newSVpvn_share", but takes a literal string instead of a
7833 string/length pair and omits the hash parameter.
7834 SV* newSVpvs_share("literal string")
7836 newSVrv Creates a new SV for the existing RV, "rv", to point to. If
7838 "rv" is not an RV then it will be upgraded to one. If
7839 "classname" is non-null then the new SV will be blessed in the
7840 specified package. The new SV is returned and its reference
7841 count is 1. The reference count 1 is owned by "rv". See also
7842 newRV_inc() and newRV_noinc() for creating a new RV properly.
7843 SV* newSVrv(SV *const rv,
7845 const char *const classname)
7846 newSVsv Creates a new SV which is an exact duplicate of the original
7848 SV. (Uses "sv_setsv".)
7849 SV* newSVsv(SV *const old)
7851 newSVsv_nomg
7853 Like "newSVsv" but does not process get magic.
7854 SV* newSVsv_nomg(SV *const old)
7856 newSV_type
7858 Creates a new SV, of the type specified. The reference count
7859 for the new SV is set to 1.
7860 SV* newSV_type(const svtype type)
7862 newSVuv Creates a new SV and copies an unsigned integer into it. The
7864 reference count for the SV is set to 1.
7865 SV* newSVuv(const UV u)
7867 sortsv_flags
7869 In-place sort an array of SV pointers with the given comparison
7870 routine, with various SORTf_* flag options.
7871 void sortsv_flags(SV** array, size_t num_elts,
7873 SVCOMPARE_t cmp, U32 flags)
7874 sv_2bool
7876 This macro is only used by "sv_true()" or its macro equivalent,
7877 and only if the latter's argument is neither "SvPOK", "SvIOK"
7878 nor "SvNOK". It calls "sv_2bool_flags" with the "SV_GMAGIC"
7879 flag.
7880 bool sv_2bool(SV *const sv)
7882 sv_2bool_flags
7884 This function is only used by "sv_true()" and friends, and
7885 only if the latter's argument is neither "SvPOK", "SvIOK" nor
7886 "SvNOK". If the flags contain "SV_GMAGIC", then it does an
7887 "mg_get()" first.
7888 bool sv_2bool_flags(SV *sv, I32 flags)
7890 sv_2cv Using various gambits, try to get a CV from an SV; in addition,
7892 try if possible to set *st and *gvp to the stash and GV
7893 associated with it. The flags in "lref" are passed to
7894 "gv_fetchsv".
7895 CV* sv_2cv(SV* sv, HV **const st, GV **const gvp,
7897 const I32 lref)
7898 sv_2io Using various gambits, try to get an IO from an SV: the IO slot
7900 if its a GV; or the recursive result if we're an RV; or the IO
7901 slot of the symbol named after the PV if we're a string.
7902 'Get' magic is ignored on the "sv" passed in, but will be
7904 called on "SvRV(sv)" if "sv" is an RV.
7905 IO* sv_2io(SV *const sv)
7907 sv_2iv_flags
7909 Return the integer value of an SV, doing any necessary string
7910 conversion. If "flags" has the "SV_GMAGIC" bit set, does an
7911 "mg_get()" first. Normally used via the "SvIV(sv)" and
7912 "SvIVx(sv)" macros.
7913 IV sv_2iv_flags(SV *const sv, const I32 flags)
7915 sv_2mortal
7917 Marks an existing SV as mortal. The SV will be destroyed
7918 "soon", either by an explicit call to "FREETMPS", or by an
7919 implicit call at places such as statement boundaries.
7920 "SvTEMP()" is turned on which means that the SV's string buffer
7921 can be "stolen" if this SV is copied. See also "sv_newmortal"
7922 and "sv_mortalcopy".
7923 SV* sv_2mortal(SV *const sv)
7925 sv_2nv_flags
7927 Return the num value of an SV, doing any necessary string or
7928 integer conversion. If "flags" has the "SV_GMAGIC" bit set,
7929 does an "mg_get()" first. Normally used via the "SvNV(sv)" and
7930 "SvNVx(sv)" macros.
7931 NV sv_2nv_flags(SV *const sv, const I32 flags)
7933 sv_2pvbyte
7935 Return a pointer to the byte-encoded representation of the SV,
7936 and set *lp to its length. If the SV is marked as being
7937 encoded as UTF-8, it will downgrade it to a byte string as a
7938 side-effect, if possible. If the SV cannot be downgraded, this
7939 croaks.
7940 Usually accessed via the "SvPVbyte" macro.
7942 char* sv_2pvbyte(SV *sv, STRLEN *const lp)
7944 sv_2pvutf8
7946 Return a pointer to the UTF-8-encoded representation of the SV,
7947 and set *lp to its length. May cause the SV to be upgraded to
7948 UTF-8 as a side-effect.
7949 Usually accessed via the "SvPVutf8" macro.
7951 char* sv_2pvutf8(SV *sv, STRLEN *const lp)
7953 sv_2pv_flags
7955 Returns a pointer to the string value of an SV, and sets *lp to
7956 its length. If flags has the "SV_GMAGIC" bit set, does an
7957 "mg_get()" first. Coerces "sv" to a string if necessary.
7958 Normally invoked via the "SvPV_flags" macro. "sv_2pv()" and
7959 "sv_2pv_nomg" usually end up here too.
7960 char* sv_2pv_flags(SV *const sv, STRLEN *const lp,
7962 const I32 flags)
7963 sv_2uv_flags
7965 Return the unsigned integer value of an SV, doing any necessary
7966 string conversion. If "flags" has the "SV_GMAGIC" bit set,
7967 does an "mg_get()" first. Normally used via the "SvUV(sv)" and
7968 "SvUVx(sv)" macros.
7969 UV sv_2uv_flags(SV *const sv, const I32 flags)
7971 sv_backoff
7973 Remove any string offset. You should normally use the
7974 "SvOOK_off" macro wrapper instead.
7975 void sv_backoff(SV *const sv)
7977 sv_bless
7979 Blesses an SV into a specified package. The SV must be an RV.
7980 The package must be designated by its stash (see "gv_stashpv").
7981 The reference count of the SV is unaffected.
7982 SV* sv_bless(SV *const sv, HV *const stash)
7984 sv_catpv
7986 Concatenates the "NUL"-terminated string onto the end of the
7987 string which is in the SV. If the SV has the UTF-8 status set,
7988 then the bytes appended should be valid UTF-8. Handles 'get'
7989 magic, but not 'set' magic. See "sv_catpv_mg".
7990 void sv_catpv(SV *const sv, const char* ptr)
7992 sv_catpvf
7994 Processes its arguments like "sprintf", and appends the
7995 formatted output to an SV. As with "sv_vcatpvfn" called with a
7996 non-null C-style variable argument list, argument reordering is
7997 not supported. If the appended data contains "wide" characters
7998 (including, but not limited to, SVs with a UTF-8 PV formatted
7999 with %s, and characters >255 formatted with %c), the original
8000 SV might get upgraded to UTF-8. Handles 'get' magic, but not
8001 'set' magic. See "sv_catpvf_mg". If the original SV was
8002 UTF-8, the pattern should be valid UTF-8; if the original SV
8003 was bytes, the pattern should be too.
8004 void sv_catpvf(SV *const sv, const char *const pat,
8006 ...)
8007 sv_catpvf_mg
8009 Like "sv_catpvf", but also handles 'set' magic.
8010 void sv_catpvf_mg(SV *const sv,
8012 const char *const pat, ...)
8013 sv_catpvn
8015 Concatenates the string onto the end of the string which is in
8016 the SV. "len" indicates number of bytes to copy. If the SV
8017 has the UTF-8 status set, then the bytes appended should be
8018 valid UTF-8. Handles 'get' magic, but not 'set' magic. See
8019 "sv_catpvn_mg".
8020 void sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
8022 sv_catpvn_flags
8024 Concatenates the string onto the end of the string which is in
8025 the SV. The "len" indicates number of bytes to copy.
8026 By default, the string appended is assumed to be valid UTF-8 if
8028 the SV has the UTF-8 status set, and a string of bytes
8029 otherwise. One can force the appended string to be interpreted
8030 as UTF-8 by supplying the "SV_CATUTF8" flag, and as bytes by
8031 supplying the "SV_CATBYTES" flag; the SV or the string appended
8032 will be upgraded to UTF-8 if necessary.
8033 If "flags" has the "SV_SMAGIC" bit set, will "mg_set" on "dsv"
8035 afterwards if appropriate. "sv_catpvn" and "sv_catpvn_nomg"
8036 are implemented in terms of this function.
8037 void sv_catpvn_flags(SV *const dstr,
8039 const char *sstr,
8040 const STRLEN len,
8041 const I32 flags)
8042 sv_catpvn_nomg
8044 Like "sv_catpvn" but doesn't process magic.
8045 void sv_catpvn_nomg(SV* sv, const char* ptr,
8047 STRLEN len)
8048 sv_catpvs
8050 Like "sv_catpvn", but takes a literal string instead of a
8051 string/length pair.
8052 void sv_catpvs(SV* sv, "literal string")
8054 sv_catpvs_flags
8056 Like "sv_catpvn_flags", but takes a literal string instead of a
8057 string/length pair.
8058 void sv_catpvs_flags(SV* sv, "literal string",
8060 I32 flags)
8061 sv_catpvs_mg
8063 Like "sv_catpvn_mg", but takes a literal string instead of a
8064 string/length pair.
8065 void sv_catpvs_mg(SV* sv, "literal string")
8067 sv_catpvs_nomg
8069 Like "sv_catpvn_nomg", but takes a literal string instead of a
8070 string/length pair.
8071 void sv_catpvs_nomg(SV* sv, "literal string")
8073 sv_catpv_flags
8075 Concatenates the "NUL"-terminated string onto the end of the
8076 string which is in the SV. If the SV has the UTF-8 status set,
8077 then the bytes appended should be valid UTF-8. If "flags" has
8078 the "SV_SMAGIC" bit set, will "mg_set" on the modified SV if
8079 appropriate.
8080 void sv_catpv_flags(SV *dstr, const char *sstr,
8082 const I32 flags)
8083 sv_catpv_mg
8085 Like "sv_catpv", but also handles 'set' magic.
8086 void sv_catpv_mg(SV *const sv, const char *const ptr)
8088 sv_catpv_nomg
8090 Like "sv_catpv" but doesn't process magic.
8091 void sv_catpv_nomg(SV* sv, const char* ptr)
8093 sv_catsv
8095 Concatenates the string from SV "ssv" onto the end of the
8096 string in SV "dsv". If "ssv" is null, does nothing; otherwise
8097 modifies only "dsv". Handles 'get' magic on both SVs, but no
8098 'set' magic. See "sv_catsv_mg" and "sv_catsv_nomg".
8099 void sv_catsv(SV *dstr, SV *sstr)
8101 sv_catsv_flags
8103 Concatenates the string from SV "ssv" onto the end of the
8104 string in SV "dsv". If "ssv" is null, does nothing; otherwise
8105 modifies only "dsv". If "flags" has the "SV_GMAGIC" bit set,
8106 will call "mg_get" on both SVs if appropriate. If "flags" has
8107 the "SV_SMAGIC" bit set, "mg_set" will be called on the
8108 modified SV afterward, if appropriate. "sv_catsv",
8109 "sv_catsv_nomg", and "sv_catsv_mg" are implemented in terms of
8110 this function.
8111 void sv_catsv_flags(SV *const dsv, SV *const ssv,
8113 const I32 flags)
8114 sv_catsv_nomg
8116 Like "sv_catsv" but doesn't process magic.
8117 void sv_catsv_nomg(SV* dsv, SV* ssv)
8119 sv_chop Efficient removal of characters from the beginning of the
8121 string buffer. "SvPOK(sv)", or at least "SvPOKp(sv)", must be
8122 true and "ptr" must be a pointer to somewhere inside the string
8123 buffer. "ptr" becomes the first character of the adjusted
8124 string. Uses the "OOK" hack. On return, only "SvPOK(sv)" and
8125 "SvPOKp(sv)" among the "OK" flags will be true.
8126 Beware: after this function returns, "ptr" and SvPVX_const(sv)
8128 may no longer refer to the same chunk of data.
8129 The unfortunate similarity of this function's name to that of
8131 Perl's "chop" operator is strictly coincidental. This function
8132 works from the left; "chop" works from the right.
8133 void sv_chop(SV *const sv, const char *const ptr)
8135 sv_clear
8137 Clear an SV: call any destructors, free up any memory used by
8138 the body, and free the body itself. The SV's head is not
8139 freed, although its type is set to all 1's so that it won't
8140 inadvertently be assumed to be live during global destruction
8141 etc. This function should only be called when "REFCNT" is
8142 zero. Most of the time you'll want to call "sv_free()" (or its
8143 macro wrapper "SvREFCNT_dec") instead.
8144 void sv_clear(SV *const orig_sv)
8146 sv_cmp Compares the strings in two SVs. Returns -1, 0, or 1
8148 indicating whether the string in "sv1" is less than, equal to,
8149 or greater than the string in "sv2". Is UTF-8 and 'use bytes'
8150 aware, handles get magic, and will coerce its args to strings
8151 if necessary. See also "sv_cmp_locale".
8152 I32 sv_cmp(SV *const sv1, SV *const sv2)
8154 sv_cmp_flags
8156 Compares the strings in two SVs. Returns -1, 0, or 1
8157 indicating whether the string in "sv1" is less than, equal to,
8158 or greater than the string in "sv2". Is UTF-8 and 'use bytes'
8159 aware and will coerce its args to strings if necessary. If the
8160 flags has the "SV_GMAGIC" bit set, it handles get magic. See
8161 also "sv_cmp_locale_flags".
8162 I32 sv_cmp_flags(SV *const sv1, SV *const sv2,
8164 const U32 flags)
8165 sv_cmp_locale
8167 Compares the strings in two SVs in a locale-aware manner. Is
8168 UTF-8 and 'use bytes' aware, handles get magic, and will coerce
8169 its args to strings if necessary. See also "sv_cmp".
8170 I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
8172 sv_cmp_locale_flags
8174 Compares the strings in two SVs in a locale-aware manner. Is
8175 UTF-8 and 'use bytes' aware and will coerce its args to strings
8176 if necessary. If the flags contain "SV_GMAGIC", it handles get
8177 magic. See also "sv_cmp_flags".
8178 I32 sv_cmp_locale_flags(SV *const sv1,
8180 SV *const sv2,
8181 const U32 flags)
8182 sv_collxfrm
8184 This calls "sv_collxfrm_flags" with the SV_GMAGIC flag. See
8185 "sv_collxfrm_flags".
8186 char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
8188 sv_collxfrm_flags
8190 Add Collate Transform magic to an SV if it doesn't already have
8191 it. If the flags contain "SV_GMAGIC", it handles get-magic.
8192 Any scalar variable may carry "PERL_MAGIC_collxfrm" magic that
8194 contains the scalar data of the variable, but transformed to
8195 such a format that a normal memory comparison can be used to
8196 compare the data according to the locale settings.
8197 char* sv_collxfrm_flags(SV *const sv,
8199 STRLEN *const nxp,
8200 I32 const flags)
8201 sv_copypv
8203 Copies a stringified representation of the source SV into the
8204 destination SV. Automatically performs any necessary "mg_get"
8205 and coercion of numeric values into strings. Guaranteed to
8206 preserve "UTF8" flag even from overloaded objects. Similar in
8207 nature to "sv_2pv[_flags]" but operates directly on an SV
8208 instead of just the string. Mostly uses "sv_2pv_flags" to do
8209 its work, except when that would lose the UTF-8'ness of the PV.
8210 void sv_copypv(SV *const dsv, SV *const ssv)
8212 sv_copypv_flags
8214 Implementation of "sv_copypv" and "sv_copypv_nomg". Calls get
8215 magic iff flags has the "SV_GMAGIC" bit set.
8216 void sv_copypv_flags(SV *const dsv, SV *const ssv,
8218 const I32 flags)
8219 sv_copypv_nomg
8221 Like "sv_copypv", but doesn't invoke get magic first.
8222 void sv_copypv_nomg(SV *const dsv, SV *const ssv)
8224 SvCUR Returns the length of the string which is in the SV. See
8226 "SvLEN".
8227 STRLEN SvCUR(SV* sv)
8229 SvCUR_set
8231 Set the current length of the string which is in the SV. See
8232 "SvCUR" and "SvIV_set">.
8233 void SvCUR_set(SV* sv, STRLEN len)
8235 sv_dec Auto-decrement of the value in the SV, doing string to numeric
8237 conversion if necessary. Handles 'get' magic and operator
8238 overloading.
8239 void sv_dec(SV *const sv)
8241 sv_dec_nomg
8243 Auto-decrement of the value in the SV, doing string to numeric
8244 conversion if necessary. Handles operator overloading. Skips
8245 handling 'get' magic.
8246 void sv_dec_nomg(SV *const sv)
8248 sv_derived_from
8250 Exactly like "sv_derived_from_pv", but doesn't take a "flags"
8251 parameter.
8252 bool sv_derived_from(SV* sv, const char *const name)
8254 sv_derived_from_pv
8256 Exactly like "sv_derived_from_pvn", but takes a nul-terminated
8257 string instead of a string/length pair.
8258 bool sv_derived_from_pv(SV* sv,
8260 const char *const name,
8261 U32 flags)
8262 sv_derived_from_pvn
8264 Returns a boolean indicating whether the SV is derived from the
8265 specified class at the C level. To check derivation at the
8266 Perl level, call "isa()" as a normal Perl method.
8267 Currently, the only significant value for "flags" is SVf_UTF8.
8269 bool sv_derived_from_pvn(SV* sv,
8271 const char *const name,
8272 const STRLEN len, U32 flags)
8273 sv_derived_from_sv
8275 Exactly like "sv_derived_from_pvn", but takes the name string
8276 in the form of an SV instead of a string/length pair. This is
8277 the advised form.
8278 bool sv_derived_from_sv(SV* sv, SV *namesv,
8280 U32 flags)
8281 sv_does Like "sv_does_pv", but doesn't take a "flags" parameter.
8283 bool sv_does(SV* sv, const char *const name)
8285 sv_does_pv
8287 Like "sv_does_sv", but takes a nul-terminated string instead of
8288 an SV.
8289 bool sv_does_pv(SV* sv, const char *const name,
8291 U32 flags)
8292 sv_does_pvn
8294 Like "sv_does_sv", but takes a string/length pair instead of an
8295 SV.
8296 bool sv_does_pvn(SV* sv, const char *const name,
8298 const STRLEN len, U32 flags)
8299 sv_does_sv
8301 Returns a boolean indicating whether the SV performs a
8302 specific, named role. The SV can be a Perl object or the name
8303 of a Perl class.
8304 bool sv_does_sv(SV* sv, SV* namesv, U32 flags)
8306 SvEND Returns a pointer to the spot just after the last character in
8308 the string which is in the SV, where there is usually a
8309 trailing "NUL" character (even though Perl scalars do not
8310 strictly require it). See "SvCUR". Access the character as
8311 "*(SvEND(sv))".
8312 Warning: If "SvCUR" is equal to "SvLEN", then "SvEND" points to
8314 unallocated memory.
8315 char* SvEND(SV* sv)
8317 sv_eq Returns a boolean indicating whether the strings in the two SVs
8319 are identical. Is UTF-8 and 'use bytes' aware, handles get
8320 magic, and will coerce its args to strings if necessary.
8321 I32 sv_eq(SV* sv1, SV* sv2)
8323 sv_eq_flags
8325 Returns a boolean indicating whether the strings in the two SVs
8326 are identical. Is UTF-8 and 'use bytes' aware and coerces its
8327 args to strings if necessary. If the flags has the "SV_GMAGIC"
8328 bit set, it handles get-magic, too.
8329 I32 sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)
8331 sv_force_normal_flags
8333 Undo various types of fakery on an SV, where fakery means "more
8334 than" a string: if the PV is a shared string, make a private
8335 copy; if we're a ref, stop refing; if we're a glob, downgrade
8336 to an "xpvmg"; if we're a copy-on-write scalar, this is the on-
8337 write time when we do the copy, and is also used locally; if
8338 this is a vstring, drop the vstring magic. If "SV_COW_DROP_PV"
8339 is set then a copy-on-write scalar drops its PV buffer (if any)
8340 and becomes "SvPOK_off" rather than making a copy. (Used where
8341 this scalar is about to be set to some other value.) In
8342 addition, the "flags" parameter gets passed to
8343 "sv_unref_flags()" when unreffing. "sv_force_normal" calls
8344 this function with flags set to 0.
8345 This function is expected to be used to signal to perl that
8347 this SV is about to be written to, and any extra book-keeping
8348 needs to be taken care of. Hence, it croaks on read-only
8349 values.
8350 void sv_force_normal_flags(SV *const sv,
8352 const U32 flags)
8353 sv_free Decrement an SV's reference count, and if it drops to zero,
8355 call "sv_clear" to invoke destructors and free up any memory
8356 used by the body; finally, deallocating the SV's head itself.
8357 Normally called via a wrapper macro "SvREFCNT_dec".
8358 void sv_free(SV *const sv)
8360 SvGAMAGIC
8362 Returns true if the SV has get magic or overloading. If either
8363 is true then the scalar is active data, and has the potential
8364 to return a new value every time it is accessed. Hence you
8365 must be careful to only read it once per user logical operation
8366 and work with that returned value. If neither is true then the
8367 scalar's value cannot change unless written to.
8368 U32 SvGAMAGIC(SV* sv)
8370 sv_gets Get a line from the filehandle and store it into the SV,
8372 optionally appending to the currently-stored string. If
8373 "append" is not 0, the line is appended to the SV instead of
8374 overwriting it. "append" should be set to the byte offset that
8375 the appended string should start at in the SV (typically,
8376 "SvCUR(sv)" is a suitable choice).
8377 char* sv_gets(SV *const sv, PerlIO *const fp,
8379 I32 append)
8380 sv_get_backrefs
8382 NOTE: this function is experimental and may change or be
8383 removed without notice.
8384 If "sv" is the target of a weak reference then it returns the
8386 back references structure associated with the sv; otherwise
8387 return "NULL".
8388 When returning a non-null result the type of the return is
8390 relevant. If it is an AV then the elements of the AV are the
8391 weak reference RVs which point at this item. If it is any other
8392 type then the item itself is the weak reference.
8393 See also "Perl_sv_add_backref()", "Perl_sv_del_backref()",
8395 "Perl_sv_kill_backrefs()"
8396 SV* sv_get_backrefs(SV *const sv)
8398 SvGROW Expands the character buffer in the SV so that it has room for
8400 the indicated number of bytes (remember to reserve space for an
8401 extra trailing "NUL" character). Calls "sv_grow" to perform
8402 the expansion if necessary. Returns a pointer to the character
8403 buffer. SV must be of type >= "SVt_PV". One alternative is to
8404 call "sv_grow" if you are not sure of the type of SV.
8405 You might mistakenly think that "len" is the number of bytes to
8407 add to the existing size, but instead it is the total size "sv"
8408 should be.
8409 char * SvGROW(SV* sv, STRLEN len)
8411 sv_grow Expands the character buffer in the SV. If necessary, uses
8413 "sv_unref" and upgrades the SV to "SVt_PV". Returns a pointer
8414 to the character buffer. Use the "SvGROW" wrapper instead.
8415 char* sv_grow(SV *const sv, STRLEN newlen)
8417 sv_inc Auto-increment of the value in the SV, doing string to numeric
8419 conversion if necessary. Handles 'get' magic and operator
8420 overloading.
8421 void sv_inc(SV *const sv)
8423 sv_inc_nomg
8425 Auto-increment of the value in the SV, doing string to numeric
8426 conversion if necessary. Handles operator overloading. Skips
8427 handling 'get' magic.
8428 void sv_inc_nomg(SV *const sv)
8430 sv_insert
8432 Inserts and/or replaces a string at the specified offset/length
8433 within the SV. Similar to the Perl "substr()" function, with
8434 "littlelen" bytes starting at "little" replacing "len" bytes of
8435 the string in "bigstr" starting at "offset". Handles get
8436 magic.
8437 void sv_insert(SV *const bigstr, const STRLEN offset,
8439 const STRLEN len,
8440 const char *const little,
8441 const STRLEN littlelen)
8442 sv_insert_flags
8444 Same as "sv_insert", but the extra "flags" are passed to the
8445 "SvPV_force_flags" that applies to "bigstr".
8446 void sv_insert_flags(SV *const bigstr,
8448 const STRLEN offset,
8449 const STRLEN len,
8450 const char *little,
8451 const STRLEN littlelen,
8452 const U32 flags)
8453 SvIOK Returns a U32 value indicating whether the SV contains an
8455 integer.
8456 U32 SvIOK(SV* sv)
8458 SvIOK_notUV
8460 Returns a boolean indicating whether the SV contains a signed
8461 integer.
8462 bool SvIOK_notUV(SV* sv)
8464 SvIOK_off
8466 Unsets the IV status of an SV.
8467 void SvIOK_off(SV* sv)
8469 SvIOK_on
8471 Tells an SV that it is an integer.
8472 void SvIOK_on(SV* sv)
8474 SvIOK_only
8476 Tells an SV that it is an integer and disables all other "OK"
8477 bits.
8478 void SvIOK_only(SV* sv)
8480 SvIOK_only_UV
8482 Tells an SV that it is an unsigned integer and disables all
8483 other "OK" bits.
8484 void SvIOK_only_UV(SV* sv)
8486 SvIOKp Returns a U32 value indicating whether the SV contains an
8488 integer. Checks the private setting. Use "SvIOK" instead.
8489 U32 SvIOKp(SV* sv)
8491 SvIOK_UV
8493 Returns a boolean indicating whether the SV contains an integer
8494 that must be interpreted as unsigned. A non-negative integer
8495 whose value is within the range of both an IV and a UV may be
8496 flagged as either "SvUOK" or "SvIOK".
8497 bool SvIOK_UV(SV* sv)
8499 sv_isa Returns a boolean indicating whether the SV is blessed into the
8501 specified class.
8502 This does not check for subtypes or method overloading. Use
8504 "sv_isa_sv" to verify an inheritance relationship in the same
8505 way as the "isa" operator by respecting any "isa()" method
8506 overloading; or "sv_derived_from_sv" to test directly on the
8507 actual object type.
8508 int sv_isa(SV* sv, const char *const name)
8510 sv_isa_sv
8512 NOTE: this function is experimental and may change or be
8513 removed without notice.
8514 Returns a boolean indicating whether the SV is an object
8516 reference and is derived from the specified class, respecting
8517 any "isa()" method overloading it may have. Returns false if
8518 "sv" is not a reference to an object, or is not derived from
8519 the specified class.
8520 This is the function used to implement the behaviour of the
8522 "isa" operator.
8523 Does not invoke magic on "sv".
8525 Not to be confused with the older "sv_isa" function, which does
8527 not use an overloaded "isa()" method, nor will check
8528 subclassing.
8529 bool sv_isa_sv(SV* sv, SV* namesv)
8531 SvIsCOW Returns a U32 value indicating whether the SV is Copy-On-Write
8533 (either shared hash key scalars, or full Copy On Write scalars
8534 if 5.9.0 is configured for COW).
8535 U32 SvIsCOW(SV* sv)
8537 SvIsCOW_shared_hash
8539 Returns a boolean indicating whether the SV is Copy-On-Write
8540 shared hash key scalar.
8541 bool SvIsCOW_shared_hash(SV* sv)
8543 sv_isobject
8545 Returns a boolean indicating whether the SV is an RV pointing
8546 to a blessed object. If the SV is not an RV, or if the object
8547 is not blessed, then this will return false.
8548 int sv_isobject(SV* sv)
8550 SvIV Coerces the given SV to IV and returns it. The returned value
8552 in many circumstances will get stored in "sv"'s IV slot, but
8553 not in all cases. (Use "sv_setiv" to make sure it does).
8554 See "SvIVx" for a version which guarantees to evaluate "sv"
8556 only once.
8557 IV SvIV(SV* sv)
8559 SvIV_nomg
8561 Like "SvIV" but doesn't process magic.
8562 IV SvIV_nomg(SV* sv)
8564 SvIV_set
8566 Set the value of the IV pointer in sv to val. It is possible
8567 to perform the same function of this macro with an lvalue
8568 assignment to "SvIVX". With future Perls, however, it will be
8569 more efficient to use "SvIV_set" instead of the lvalue
8570 assignment to "SvIVX".
8571 void SvIV_set(SV* sv, IV val)
8573 SvIVX Returns the raw value in the SV's IV slot, without checks or
8575 conversions. Only use when you are sure "SvIOK" is true. See
8576 also "SvIV".
8577 IV SvIVX(SV* sv)
8579 SvIVx Coerces the given SV to IV and returns it. The returned value
8581 in many circumstances will get stored in "sv"'s IV slot, but
8582 not in all cases. (Use "sv_setiv" to make sure it does).
8583 This form guarantees to evaluate "sv" only once. Only use this
8585 if "sv" is an expression with side effects, otherwise use the
8586 more efficient "SvIV".
8587 IV SvIVx(SV* sv)
8589 SvLEN Returns the size of the string buffer in the SV, not including
8591 any part attributable to "SvOOK". See "SvCUR".
8592 STRLEN SvLEN(SV* sv)
8594 sv_len Returns the length of the string in the SV. Handles magic and
8596 type coercion and sets the UTF8 flag appropriately. See also
8597 "SvCUR", which gives raw access to the "xpv_cur" slot.
8598 STRLEN sv_len(SV *const sv)
8600 SvLEN_set
8602 Set the size of the string buffer for the SV. See "SvLEN".
8603 void SvLEN_set(SV* sv, STRLEN len)
8605 sv_len_utf8
8607 Returns the number of characters in the string in an SV,
8608 counting wide UTF-8 bytes as a single character. Handles magic
8609 and type coercion.
8610 STRLEN sv_len_utf8(SV *const sv)
8612 sv_magic
8614 Adds magic to an SV. First upgrades "sv" to type "SVt_PVMG" if
8615 necessary, then adds a new magic item of type "how" to the head
8616 of the magic list.
8617 See "sv_magicext" (which "sv_magic" now calls) for a
8619 description of the handling of the "name" and "namlen"
8620 arguments.
8621 You need to use "sv_magicext" to add magic to "SvREADONLY" SVs
8623 and also to add more than one instance of the same "how".
8624 void sv_magic(SV *const sv, SV *const obj,
8626 const int how, const char *const name,
8627 const I32 namlen)
8628 sv_magicext
8630 Adds magic to an SV, upgrading it if necessary. Applies the
8631 supplied "vtable" and returns a pointer to the magic added.
8632 Note that "sv_magicext" will allow things that "sv_magic" will
8634 not. In particular, you can add magic to "SvREADONLY" SVs, and
8635 add more than one instance of the same "how".
8636 If "namlen" is greater than zero then a "savepvn" copy of
8638 "name" is stored, if "namlen" is zero then "name" is stored as-
8639 is and - as another special case - if "(name && namlen ==
8640 HEf_SVKEY)" then "name" is assumed to contain an SV* and is
8641 stored as-is with its "REFCNT" incremented.
8642 (This is now used as a subroutine by "sv_magic".)
8644 MAGIC * sv_magicext(SV *const sv, SV *const obj,
8646 const int how,
8647 const MGVTBL *const vtbl,
8648 const char *const name,
8649 const I32 namlen)
8650 SvMAGIC_set
8652 Set the value of the MAGIC pointer in "sv" to val. See
8653 "SvIV_set".
8654 void SvMAGIC_set(SV* sv, MAGIC* val)
8656 sv_mortalcopy
8658 Creates a new SV which is a copy of the original SV (using
8659 "sv_setsv"). The new SV is marked as mortal. It will be
8660 destroyed "soon", either by an explicit call to "FREETMPS", or
8661 by an implicit call at places such as statement boundaries.
8662 See also "sv_newmortal" and "sv_2mortal".
8663 SV* sv_mortalcopy(SV *const oldsv)
8665 sv_mortalcopy_flags
8667 Like "sv_mortalcopy", but the extra "flags" are passed to the
8668 "sv_setsv_flags".
8669 SV* sv_mortalcopy_flags(SV *const oldsv, U32 flags)
8671 sv_newmortal
8673 Creates a new null SV which is mortal. The reference count of
8674 the SV is set to 1. It will be destroyed "soon", either by an
8675 explicit call to "FREETMPS", or by an implicit call at places
8676 such as statement boundaries. See also "sv_mortalcopy" and
8677 "sv_2mortal".
8678 SV* sv_newmortal()
8680 sv_newref
8682 Increment an SV's reference count. Use the "SvREFCNT_inc()"
8683 wrapper instead.
8684 SV* sv_newref(SV *const sv)
8686 SvNIOK Returns a U32 value indicating whether the SV contains a
8688 number, integer or double.
8689 U32 SvNIOK(SV* sv)
8691 SvNIOK_off
8693 Unsets the NV/IV status of an SV.
8694 void SvNIOK_off(SV* sv)
8696 SvNIOKp Returns a U32 value indicating whether the SV contains a
8698 number, integer or double. Checks the private setting. Use
8699 "SvNIOK" instead.
8700 U32 SvNIOKp(SV* sv)
8702 SvNOK Returns a U32 value indicating whether the SV contains a
8704 double.
8705 U32 SvNOK(SV* sv)
8707 SvNOK_off
8709 Unsets the NV status of an SV.
8710 void SvNOK_off(SV* sv)
8712 SvNOK_on
8714 Tells an SV that it is a double.
8715 void SvNOK_on(SV* sv)
8717 SvNOK_only
8719 Tells an SV that it is a double and disables all other OK bits.
8720 void SvNOK_only(SV* sv)
8722 SvNOKp Returns a U32 value indicating whether the SV contains a
8724 double. Checks the private setting. Use "SvNOK" instead.
8725 U32 SvNOKp(SV* sv)
8727 SvNV Coerces the given SV to NV and returns it. The returned value
8729 in many circumstances will get stored in "sv"'s NV slot, but
8730 not in all cases. (Use "sv_setnv" to make sure it does).
8731 See "SvNVx" for a version which guarantees to evaluate "sv"
8733 only once.
8734 NV SvNV(SV* sv)
8736 SvNV_nomg
8738 Like "SvNV" but doesn't process magic.
8739 NV SvNV_nomg(SV* sv)
8741 SvNV_set
8743 Set the value of the NV pointer in "sv" to val. See
8744 "SvIV_set".
8745 void SvNV_set(SV* sv, NV val)
8747 SvNVX Returns the raw value in the SV's NV slot, without checks or
8749 conversions. Only use when you are sure "SvNOK" is true. See
8750 also "SvNV".
8751 NV SvNVX(SV* sv)
8753 SvNVx Coerces the given SV to NV and returns it. The returned value
8755 in many circumstances will get stored in "sv"'s NV slot, but
8756 not in all cases. (Use "sv_setnv" to make sure it does).
8757 This form guarantees to evaluate "sv" only once. Only use this
8759 if "sv" is an expression with side effects, otherwise use the
8760 more efficient "SvNV".
8761 NV SvNVx(SV* sv)
8763 SvOK Returns a U32 value indicating whether the value is defined.
8765 This is only meaningful for scalars.
8766 U32 SvOK(SV* sv)
8768 SvOOK Returns a U32 indicating whether the pointer to the string
8770 buffer is offset. This hack is used internally to speed up
8771 removal of characters from the beginning of a "SvPV". When
8772 "SvOOK" is true, then the start of the allocated string buffer
8773 is actually "SvOOK_offset()" bytes before "SvPVX". This offset
8774 used to be stored in "SvIVX", but is now stored within the
8775 spare part of the buffer.
8776 U32 SvOOK(SV* sv)
8778 SvOOK_offset
8780 Reads into "len" the offset from "SvPVX" back to the true start
8781 of the allocated buffer, which will be non-zero if "sv_chop"
8782 has been used to efficiently remove characters from start of
8783 the buffer. Implemented as a macro, which takes the address of
8784 "len", which must be of type "STRLEN". Evaluates "sv" more
8785 than once. Sets "len" to 0 if "SvOOK(sv)" is false.
8786 void SvOOK_offset(SV*sv, STRLEN len)
8788 SvPOK Returns a U32 value indicating whether the SV contains a
8790 character string.
8791 U32 SvPOK(SV* sv)
8793 SvPOK_off
8795 Unsets the PV status of an SV.
8796 void SvPOK_off(SV* sv)
8798 SvPOK_on
8800 Tells an SV that it is a string.
8801 void SvPOK_on(SV* sv)
8803 SvPOK_only
8805 Tells an SV that it is a string and disables all other "OK"
8806 bits. Will also turn off the UTF-8 status.
8807 void SvPOK_only(SV* sv)
8809 SvPOK_only_UTF8
8811 Tells an SV that it is a string and disables all other "OK"
8812 bits, and leaves the UTF-8 status as it was.
8813 void SvPOK_only_UTF8(SV* sv)
8815 SvPOKp Returns a U32 value indicating whether the SV contains a
8817 character string. Checks the private setting. Use "SvPOK"
8818 instead.
8819 U32 SvPOKp(SV* sv)
8821 sv_pos_b2u
8823 Converts the value pointed to by "offsetp" from a count of
8824 bytes from the start of the string, to a count of the
8825 equivalent number of UTF-8 chars. Handles magic and type
8826 coercion.
8827 Use "sv_pos_b2u_flags" in preference, which correctly handles
8829 strings longer than 2Gb.
8830 void sv_pos_b2u(SV *const sv, I32 *const offsetp)
8832 sv_pos_b2u_flags
8834 Converts "offset" from a count of bytes from the start of the
8835 string, to a count of the equivalent number of UTF-8 chars.
8836 Handles type coercion. "flags" is passed to "SvPV_flags", and
8837 usually should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
8838 STRLEN sv_pos_b2u_flags(SV *const sv,
8840 STRLEN const offset, U32 flags)
8841 sv_pos_u2b
8843 Converts the value pointed to by "offsetp" from a count of
8844 UTF-8 chars from the start of the string, to a count of the
8845 equivalent number of bytes; if "lenp" is non-zero, it does the
8846 same to "lenp", but this time starting from the offset, rather
8847 than from the start of the string. Handles magic and type
8848 coercion.
8849 Use "sv_pos_u2b_flags" in preference, which correctly handles
8851 strings longer than 2Gb.
8852 void sv_pos_u2b(SV *const sv, I32 *const offsetp,
8854 I32 *const lenp)
8855 sv_pos_u2b_flags
8857 Converts the offset from a count of UTF-8 chars from the start
8858 of the string, to a count of the equivalent number of bytes; if
8859 "lenp" is non-zero, it does the same to "lenp", but this time
8860 starting from "offset", rather than from the start of the
8861 string. Handles type coercion. "flags" is passed to
8862 "SvPV_flags", and usually should be "SV_GMAGIC|SV_CONST_RETURN"
8863 to handle magic.
8864 STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
8866 STRLEN *const lenp, U32 flags)
8867 SvPV Returns a pointer to the string in the SV, or a stringified
8869 form of the SV if the SV does not contain a string. The SV may
8870 cache the stringified version becoming "SvPOK". Handles 'get'
8871 magic. The "len" variable will be set to the length of the
8872 string (this is a macro, so don't use &len). See also "SvPVx"
8873 for a version which guarantees to evaluate "sv" only once.
8874 Note that there is no guarantee that the return value of
8876 "SvPV()" is equal to "SvPVX(sv)", or that "SvPVX(sv)" contains
8877 valid data, or that successive calls to "SvPV(sv)" will return
8878 the same pointer value each time. This is due to the way that
8879 things like overloading and Copy-On-Write are handled. In
8880 these cases, the return value may point to a temporary buffer
8881 or similar. If you absolutely need the "SvPVX" field to be
8882 valid (for example, if you intend to write to it), then see
8883 "SvPV_force".
8884 char* SvPV(SV* sv, STRLEN len)
8886 SvPVbyte
8888 Like "SvPV", but converts "sv" to byte representation first if
8889 necessary. If the SV cannot be downgraded from UTF-8, this
8890 croaks.
8891 char* SvPVbyte(SV* sv, STRLEN len)
8893 SvPVbyte_force
8895 Like "SvPV_force", but converts "sv" to byte representation
8896 first if necessary. If the SV cannot be downgraded from UTF-8,
8897 this croaks.
8898 char* SvPVbyte_force(SV* sv, STRLEN len)
8900 SvPVbyte_nolen
8902 Like "SvPV_nolen", but converts "sv" to byte representation
8903 first if necessary. If the SV cannot be downgraded from UTF-8,
8904 this croaks.
8905 char* SvPVbyte_nolen(SV* sv)
8907 SvPVbyte_nomg
8909 Like "SvPVbyte", but does not process get magic.
8910 char* SvPVbyte_nomg(SV* sv, STRLEN len)
8912 sv_pvbyten_force
8914 The backend for the "SvPVbytex_force" macro. Always use the
8915 macro instead. If the SV cannot be downgraded from UTF-8, this
8916 croaks.
8917 char* sv_pvbyten_force(SV *const sv, STRLEN *const lp)
8919 SvPVbyte_or_null
8921 Like "SvPVbyte", but when "sv" is undef, returns "NULL".
8922 char* SvPVbyte_or_null(SV* sv, STRLEN len)
8924 SvPVbyte_or_null_nomg
8926 Like "SvPVbyte_or_null", but does not process get magic.
8927 char* SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
8929 SvPVbytex
8931 Like "SvPV", but converts "sv" to byte representation first if
8932 necessary. Guarantees to evaluate "sv" only once; use the more
8933 efficient "SvPVbyte" otherwise. If the SV cannot be downgraded
8934 from UTF-8, this croaks.
8935 char* SvPVbytex(SV* sv, STRLEN len)
8937 SvPVbytex_force
8939 Like "SvPV_force", but converts "sv" to byte representation
8940 first if necessary. Guarantees to evaluate "sv" only once; use
8941 the more efficient "SvPVbyte_force" otherwise. If the SV
8942 cannot be downgraded from UTF-8, this croaks.
8943 char* SvPVbytex_force(SV* sv, STRLEN len)
8945 SvPVCLEAR
8947 Ensures that sv is a SVt_PV and that its SvCUR is 0, and that
8948 it is properly null terminated. Equivalent to sv_setpvs(""),
8949 but more efficient.
8950 char * SvPVCLEAR(SV* sv)
8952 SvPV_force
8954 Like "SvPV" but will force the SV into containing a string
8955 ("SvPOK"), and only a string ("SvPOK_only"), by hook or by
8956 crook. You need force if you are going to update the "SvPVX"
8957 directly. Processes get magic.
8958 Note that coercing an arbitrary scalar into a plain PV will
8960 potentially strip useful data from it. For example if the SV
8961 was "SvROK", then the referent will have its reference count
8962 decremented, and the SV itself may be converted to an "SvPOK"
8963 scalar with a string buffer containing a value such as
8964 "ARRAY(0x1234)".
8965 char* SvPV_force(SV* sv, STRLEN len)
8967 SvPV_force_nomg
8969 Like "SvPV_force", but doesn't process get magic.
8970 char* SvPV_force_nomg(SV* sv, STRLEN len)
8972 SvPV_nolen
8974 Like "SvPV" but doesn't set a length variable.
8975 char* SvPV_nolen(SV* sv)
8977 SvPV_nomg
8979 Like "SvPV" but doesn't process magic.
8980 char* SvPV_nomg(SV* sv, STRLEN len)
8982 SvPV_nomg_nolen
8984 Like "SvPV_nolen" but doesn't process magic.
8985 char* SvPV_nomg_nolen(SV* sv)
8987 sv_pvn_force
8989 Get a sensible string out of the SV somehow. A private
8990 implementation of the "SvPV_force" macro for compilers which
8991 can't cope with complex macro expressions. Always use the
8992 macro instead.
8993 char* sv_pvn_force(SV* sv, STRLEN* lp)
8995 sv_pvn_force_flags
8997 Get a sensible string out of the SV somehow. If "flags" has
8998 the "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate,
8999 else not. "sv_pvn_force" and "sv_pvn_force_nomg" are
9000 implemented in terms of this function. You normally want to
9001 use the various wrapper macros instead: see "SvPV_force" and
9002 "SvPV_force_nomg".
9003 char* sv_pvn_force_flags(SV *const sv,
9005 STRLEN *const lp,
9006 const I32 flags)
9007 SvPV_set
9009 This is probably not what you want to use, you probably wanted
9010 "sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
9011 Set the value of the PV pointer in "sv" to the Perl allocated
9013 "NUL"-terminated string "val". See also "SvIV_set".
9014 Remember to free the previous PV buffer. There are many things
9016 to check. Beware that the existing pointer may be involved in
9017 copy-on-write or other mischief, so do "SvOOK_off(sv)" and use
9018 "sv_force_normal" or "SvPV_force" (or check the "SvIsCOW" flag)
9019 first to make sure this modification is safe. Then finally, if
9020 it is not a COW, call "SvPV_free" to free the previous PV
9021 buffer.
9022 void SvPV_set(SV* sv, char* val)
9024 SvPVutf8
9026 Like "SvPV", but converts "sv" to UTF-8 first if necessary.
9027 char* SvPVutf8(SV* sv, STRLEN len)
9029 sv_pvutf8n_force
9031 The backend for the "SvPVutf8x_force" macro. Always use the
9032 macro instead.
9033 char* sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
9035 SvPVutf8x
9037 Like "SvPV", but converts "sv" to UTF-8 first if necessary.
9038 Guarantees to evaluate "sv" only once; use the more efficient
9039 "SvPVutf8" otherwise.
9040 char* SvPVutf8x(SV* sv, STRLEN len)
9042 SvPVutf8x_force
9044 Like "SvPV_force", but converts "sv" to UTF-8 first if
9045 necessary. Guarantees to evaluate "sv" only once; use the more
9046 efficient "SvPVutf8_force" otherwise.
9047 char* SvPVutf8x_force(SV* sv, STRLEN len)
9049 SvPVutf8_force
9051 Like "SvPV_force", but converts "sv" to UTF-8 first if
9052 necessary.
9053 char* SvPVutf8_force(SV* sv, STRLEN len)
9055 SvPVutf8_nolen
9057 Like "SvPV_nolen", but converts "sv" to UTF-8 first if
9058 necessary.
9059 char* SvPVutf8_nolen(SV* sv)
9061 SvPVutf8_nomg
9063 Like "SvPVutf8", but does not process get magic.
9064 char* SvPVutf8_nomg(SV* sv, STRLEN len)
9066 SvPVutf8_or_null
9068 Like "SvPVutf8", but when "sv" is undef, returns "NULL".
9069 char* SvPVutf8_or_null(SV* sv, STRLEN len)
9071 SvPVutf8_or_null_nomg
9073 Like "SvPVutf8_or_null", but does not process get magic.
9074 char* SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
9076 SvPVX Returns a pointer to the physical string in the SV. The SV
9078 must contain a string. Prior to 5.9.3 it is not safe to
9079 execute this macro unless the SV's type >= "SVt_PV".
9080 This is also used to store the name of an autoloaded subroutine
9082 in an XS AUTOLOAD routine. See "Autoloading with XSUBs" in
9083 perlguts.
9084 char* SvPVX(SV* sv)
9086 SvPVx A version of "SvPV" which guarantees to evaluate "sv" only
9088 once. Only use this if "sv" is an expression with side
9089 effects, otherwise use the more efficient "SvPV".
9090 char* SvPVx(SV* sv, STRLEN len)
9092 SvREADONLY
9094 Returns true if the argument is readonly, otherwise returns
9095 false. Exposed to perl code via Internals::SvREADONLY().
9096 U32 SvREADONLY(SV* sv)
9098 SvREADONLY_off
9100 Mark an object as not-readonly. Exactly what this mean depends
9101 on the object type. Exposed to perl code via
9102 Internals::SvREADONLY().
9103 U32 SvREADONLY_off(SV* sv)
9105 SvREADONLY_on
9107 Mark an object as readonly. Exactly what this means depends on
9108 the object type. Exposed to perl code via
9109 Internals::SvREADONLY().
9110 U32 SvREADONLY_on(SV* sv)
9112 sv_ref Returns a SV describing what the SV passed in is a reference
9114 to.
9115 dst can be a SV to be set to the description or NULL, in which
9117 case a mortal SV is returned.
9118 If ob is true and the SV is blessed, the description is the
9120 class name, otherwise it is the type of the SV, "SCALAR",
9121 "ARRAY" etc.
9122 SV* sv_ref(SV *dst, const SV *const sv,
9124 const int ob)
9125 SvREFCNT
9127 Returns the value of the object's reference count. Exposed to
9128 perl code via Internals::SvREFCNT().
9129 U32 SvREFCNT(SV* sv)
9131 SvREFCNT_dec
9133 Decrements the reference count of the given SV. "sv" may be
9134 "NULL".
9135 void SvREFCNT_dec(SV *sv)
9137 SvREFCNT_dec_NN
9139 Same as "SvREFCNT_dec", but can only be used if you know "sv"
9140 is not "NULL". Since we don't have to check the NULLness, it's
9141 faster and smaller.
9142 void SvREFCNT_dec_NN(SV *sv)
9144 SvREFCNT_inc
9146 Increments the reference count of the given SV, returning the
9147 SV.
9148 All of the following "SvREFCNT_inc"* are optimized versions of
9150 "SvREFCNT_inc", and can be replaced with "SvREFCNT_inc".
9151 SV * SvREFCNT_inc(SV *sv)
9153 SvREFCNT_inc_NN
9155 Same as "SvREFCNT_inc", but can only be used if you know "sv"
9156 is not "NULL". Since we don't have to check the NULLness, it's
9157 faster and smaller.
9158 SV * SvREFCNT_inc_NN(SV *sv)
9160 SvREFCNT_inc_simple
9162 Same as "SvREFCNT_inc", but can only be used with expressions
9163 without side effects. Since we don't have to store a temporary
9164 value, it's faster.
9165 SV* SvREFCNT_inc_simple(SV* sv)
9167 SvREFCNT_inc_simple_NN
9169 Same as "SvREFCNT_inc_simple", but can only be used if you know
9170 "sv" is not "NULL". Since we don't have to check the NULLness,
9171 it's faster and smaller.
9172 SV* SvREFCNT_inc_simple_NN(SV* sv)
9174 SvREFCNT_inc_simple_void
9176 Same as "SvREFCNT_inc_simple", but can only be used if you
9177 don't need the return value. The macro doesn't need to return
9178 a meaningful value.
9179 void SvREFCNT_inc_simple_void(SV* sv)
9181 SvREFCNT_inc_simple_void_NN
9183 Same as "SvREFCNT_inc", but can only be used if you don't need
9184 the return value, and you know that "sv" is not "NULL". The
9185 macro doesn't need to return a meaningful value, or check for
9186 NULLness, so it's smaller and faster.
9187 void SvREFCNT_inc_simple_void_NN(SV* sv)
9189 SvREFCNT_inc_void
9191 Same as "SvREFCNT_inc", but can only be used if you don't need
9192 the return value. The macro doesn't need to return a
9193 meaningful value.
9194 void SvREFCNT_inc_void(SV *sv)
9196 SvREFCNT_inc_void_NN
9198 Same as "SvREFCNT_inc", but can only be used if you don't need
9199 the return value, and you know that "sv" is not "NULL". The
9200 macro doesn't need to return a meaningful value, or check for
9201 NULLness, so it's smaller and faster.
9202 void SvREFCNT_inc_void_NN(SV* sv)
9204 sv_reftype
9206 Returns a string describing what the SV is a reference to.
9207 If ob is true and the SV is blessed, the string is the class
9209 name, otherwise it is the type of the SV, "SCALAR", "ARRAY"
9210 etc.
9211 const char* sv_reftype(const SV *const sv, const int ob)
9213 sv_replace
9215 Make the first argument a copy of the second, then delete the
9216 original. The target SV physically takes over ownership of the
9217 body of the source SV and inherits its flags; however, the
9218 target keeps any magic it owns, and any magic in the source is
9219 discarded. Note that this is a rather specialist SV copying
9220 operation; most of the time you'll want to use "sv_setsv" or
9221 one of its many macro front-ends.
9222 void sv_replace(SV *const sv, SV *const nsv)
9224 sv_report_used
9226 Dump the contents of all SVs not yet freed (debugging aid).
9227 void sv_report_used()
9229 sv_reset
9231 Underlying implementation for the "reset" Perl function. Note
9232 that the perl-level function is vaguely deprecated.
9233 void sv_reset(const char* s, HV *const stash)
9235 SvROK Tests if the SV is an RV.
9237 U32 SvROK(SV* sv)
9239 SvROK_off
9241 Unsets the RV status of an SV.
9242 void SvROK_off(SV* sv)
9244 SvROK_on
9246 Tells an SV that it is an RV.
9247 void SvROK_on(SV* sv)
9249 SvRV Dereferences an RV to return the SV.
9251 SV* SvRV(SV* sv)
9253 SvRV_set
9255 Set the value of the RV pointer in "sv" to val. See
9256 "SvIV_set".
9257 void SvRV_set(SV* sv, SV* val)
9259 sv_rvunweaken
9261 Unweaken a reference: Clear the "SvWEAKREF" flag on this RV;
9262 remove the backreference to this RV from the array of
9263 backreferences associated with the target SV, increment the
9264 refcount of the target. Silently ignores "undef" and warns on
9265 non-weak references.
9266 SV* sv_rvunweaken(SV *const sv)
9268 sv_rvweaken
9270 Weaken a reference: set the "SvWEAKREF" flag on this RV; give
9271 the referred-to SV "PERL_MAGIC_backref" magic if it hasn't
9272 already; and push a back-reference to this RV onto the array of
9273 backreferences associated with that magic. If the RV is
9274 magical, set magic will be called after the RV is cleared.
9275 Silently ignores "undef" and warns on already-weak references.
9276 SV* sv_rvweaken(SV *const sv)
9278 sv_setiv
9280 Copies an integer into the given SV, upgrading first if
9281 necessary. Does not handle 'set' magic. See also
9282 "sv_setiv_mg".
9283 void sv_setiv(SV *const sv, const IV num)
9285 sv_setiv_mg
9287 Like "sv_setiv", but also handles 'set' magic.
9288 void sv_setiv_mg(SV *const sv, const IV i)
9290 sv_setnv
9292 Copies a double into the given SV, upgrading first if
9293 necessary. Does not handle 'set' magic. See also
9294 "sv_setnv_mg".
9295 void sv_setnv(SV *const sv, const NV num)
9297 sv_setnv_mg
9299 Like "sv_setnv", but also handles 'set' magic.
9300 void sv_setnv_mg(SV *const sv, const NV num)
9302 sv_setpv
9304 Copies a string into an SV. The string must be terminated with
9305 a "NUL" character, and not contain embeded "NUL"'s. Does not
9306 handle 'set' magic. See "sv_setpv_mg".
9307 void sv_setpv(SV *const sv, const char *const ptr)
9309 sv_setpvf
9311 Works like "sv_catpvf" but copies the text into the SV instead
9312 of appending it. Does not handle 'set' magic. See
9313 "sv_setpvf_mg".
9314 void sv_setpvf(SV *const sv, const char *const pat,
9316 ...)
9317 sv_setpvf_mg
9319 Like "sv_setpvf", but also handles 'set' magic.
9320 void sv_setpvf_mg(SV *const sv,
9322 const char *const pat, ...)
9323 sv_setpviv
9325 DEPRECATED! It is planned to remove this function from a
9326 future release of Perl. Do not use it for new code; remove it
9327 from existing code.
9328 Copies an integer into the given SV, also updating its string
9330 value. Does not handle 'set' magic. See "sv_setpviv_mg".
9331 void sv_setpviv(SV *const sv, const IV num)
9333 sv_setpviv_mg
9335 DEPRECATED! It is planned to remove this function from a
9336 future release of Perl. Do not use it for new code; remove it
9337 from existing code.
9338 Like "sv_setpviv", but also handles 'set' magic.
9340 void sv_setpviv_mg(SV *const sv, const IV iv)
9342 sv_setpvn
9344 Copies a string (possibly containing embedded "NUL" characters)
9345 into an SV. The "len" parameter indicates the number of bytes
9346 to be copied. If the "ptr" argument is NULL the SV will become
9347 undefined. Does not handle 'set' magic. See "sv_setpvn_mg".
9348 The UTF-8 flag is not changed by this function. A terminating
9350 NUL byte is guaranteed.
9351 void sv_setpvn(SV *const sv, const char *const ptr,
9353 const STRLEN len)
9354 sv_setpvn_mg
9356 Like "sv_setpvn", but also handles 'set' magic.
9357 void sv_setpvn_mg(SV *const sv,
9359 const char *const ptr,
9360 const STRLEN len)
9361 sv_setpvs
9363 Like "sv_setpvn", but takes a literal string instead of a
9364 string/length pair.
9365 void sv_setpvs(SV* sv, "literal string")
9367 sv_setpvs_mg
9369 Like "sv_setpvn_mg", but takes a literal string instead of a
9370 string/length pair.
9371 void sv_setpvs_mg(SV* sv, "literal string")
9373 sv_setpv_bufsize
9375 Sets the SV to be a string of cur bytes length, with at least
9376 len bytes available. Ensures that there is a null byte at
9377 SvEND. Returns a char * pointer to the SvPV buffer.
9378 char * sv_setpv_bufsize(SV *const sv, const STRLEN cur,
9380 const STRLEN len)
9381 sv_setpv_mg
9383 Like "sv_setpv", but also handles 'set' magic.
9384 void sv_setpv_mg(SV *const sv, const char *const ptr)
9386 sv_setref_iv
9388 Copies an integer into a new SV, optionally blessing the SV.
9389 The "rv" argument will be upgraded to an RV. That RV will be
9390 modified to point to the new SV. The "classname" argument
9391 indicates the package for the blessing. Set "classname" to
9392 "NULL" to avoid the blessing. The new SV will have a reference
9393 count of 1, and the RV will be returned.
9394 SV* sv_setref_iv(SV *const rv,
9396 const char *const classname,
9397 const IV iv)
9398 sv_setref_nv
9400 Copies a double into a new SV, optionally blessing the SV. The
9401 "rv" argument will be upgraded to an RV. That RV will be
9402 modified to point to the new SV. The "classname" argument
9403 indicates the package for the blessing. Set "classname" to
9404 "NULL" to avoid the blessing. The new SV will have a reference
9405 count of 1, and the RV will be returned.
9406 SV* sv_setref_nv(SV *const rv,
9408 const char *const classname,
9409 const NV nv)
9410 sv_setref_pv
9412 Copies a pointer into a new SV, optionally blessing the SV.
9413 The "rv" argument will be upgraded to an RV. That RV will be
9414 modified to point to the new SV. If the "pv" argument is
9415 "NULL", then "PL_sv_undef" will be placed into the SV. The
9416 "classname" argument indicates the package for the blessing.
9417 Set "classname" to "NULL" to avoid the blessing. The new SV
9418 will have a reference count of 1, and the RV will be returned.
9419 Do not use with other Perl types such as HV, AV, SV, CV,
9421 because those objects will become corrupted by the pointer copy
9422 process.
9423 Note that "sv_setref_pvn" copies the string while this copies
9425 the pointer.
9426 SV* sv_setref_pv(SV *const rv,
9428 const char *const classname,
9429 void *const pv)
9430 sv_setref_pvn
9432 Copies a string into a new SV, optionally blessing the SV. The
9433 length of the string must be specified with "n". The "rv"
9434 argument will be upgraded to an RV. That RV will be modified
9435 to point to the new SV. The "classname" argument indicates the
9436 package for the blessing. Set "classname" to "NULL" to avoid
9437 the blessing. The new SV will have a reference count of 1, and
9438 the RV will be returned.
9439 Note that "sv_setref_pv" copies the pointer while this copies
9441 the string.
9442 SV* sv_setref_pvn(SV *const rv,
9444 const char *const classname,
9445 const char *const pv,
9446 const STRLEN n)
9447 sv_setref_pvs
9449 Like "sv_setref_pvn", but takes a literal string instead of a
9450 string/length pair.
9451 SV * sv_setref_pvs(SV *const rv,
9453 const char *const classname,
9454 "literal string")
9455 sv_setref_uv
9457 Copies an unsigned integer into a new SV, optionally blessing
9458 the SV. The "rv" argument will be upgraded to an RV. That RV
9459 will be modified to point to the new SV. The "classname"
9460 argument indicates the package for the blessing. Set
9461 "classname" to "NULL" to avoid the blessing. The new SV will
9462 have a reference count of 1, and the RV will be returned.
9463 SV* sv_setref_uv(SV *const rv,
9465 const char *const classname,
9466 const UV uv)
9467 sv_setsv
9469 Copies the contents of the source SV "ssv" into the destination
9470 SV "dsv". The source SV may be destroyed if it is mortal, so
9471 don't use this function if the source SV needs to be reused.
9472 Does not handle 'set' magic on destination SV. Calls 'get'
9473 magic on source SV. Loosely speaking, it performs a copy-by-
9474 value, obliterating any previous content of the destination.
9475 You probably want to use one of the assortment of wrappers,
9477 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
9478 "SvSetMagicSV_nosteal".
9479 void sv_setsv(SV *dstr, SV *sstr)
9481 sv_setsv_flags
9483 Copies the contents of the source SV "ssv" into the destination
9484 SV "dsv". The source SV may be destroyed if it is mortal, so
9485 don't use this function if the source SV needs to be reused.
9486 Does not handle 'set' magic. Loosely speaking, it performs a
9487 copy-by-value, obliterating any previous content of the
9488 destination. If the "flags" parameter has the "SV_GMAGIC" bit
9489 set, will "mg_get" on "ssv" if appropriate, else not. If the
9490 "flags" parameter has the "SV_NOSTEAL" bit set then the buffers
9491 of temps will not be stolen. "sv_setsv" and "sv_setsv_nomg"
9492 are implemented in terms of this function.
9493 You probably want to use one of the assortment of wrappers,
9495 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
9496 "SvSetMagicSV_nosteal".
9497 This is the primary function for copying scalars, and most
9499 other copy-ish functions and macros use this underneath.
9500 void sv_setsv_flags(SV *dstr, SV *sstr,
9502 const I32 flags)
9503 sv_setsv_mg
9505 Like "sv_setsv", but also handles 'set' magic.
9506 void sv_setsv_mg(SV *const dstr, SV *const sstr)
9508 sv_setsv_nomg
9510 Like "sv_setsv" but doesn't process magic.
9511 void sv_setsv_nomg(SV* dsv, SV* ssv)
9513 sv_setuv
9515 Copies an unsigned integer into the given SV, upgrading first
9516 if necessary. Does not handle 'set' magic. See also
9517 "sv_setuv_mg".
9518 void sv_setuv(SV *const sv, const UV num)
9520 sv_setuv_mg
9522 Like "sv_setuv", but also handles 'set' magic.
9523 void sv_setuv_mg(SV *const sv, const UV u)
9525 sv_set_undef
9527 Equivalent to "sv_setsv(sv, &PL_sv_undef)", but more efficient.
9528 Doesn't handle set magic.
9529 The perl equivalent is "$sv = undef;". Note that it doesn't
9531 free any string buffer, unlike "undef $sv".
9532 Introduced in perl 5.25.12.
9534 void sv_set_undef(SV *sv)
9536 SvSTASH Returns the stash of the SV.
9538 HV* SvSTASH(SV* sv)
9540 SvSTASH_set
9542 Set the value of the STASH pointer in "sv" to val. See
9543 "SvIV_set".
9544 void SvSTASH_set(SV* sv, HV* val)
9546 SvTAINT Taints an SV if tainting is enabled, and if some input to the
9548 current expression is tainted--usually a variable, but possibly
9549 also implicit inputs such as locale settings. "SvTAINT"
9550 propagates that taintedness to the outputs of an expression in
9551 a pessimistic fashion; i.e., without paying attention to
9552 precisely which outputs are influenced by which inputs.
9553 void SvTAINT(SV* sv)
9555 SvTAINTED
9557 Checks to see if an SV is tainted. Returns TRUE if it is,
9558 FALSE if not.
9559 bool SvTAINTED(SV* sv)
9561 sv_tainted
9563 Test an SV for taintedness. Use "SvTAINTED" instead.
9564 bool sv_tainted(SV *const sv)
9566 SvTAINTED_off
9568 Untaints an SV. Be very careful with this routine, as it
9569 short-circuits some of Perl's fundamental security features.
9570 XS module authors should not use this function unless they
9571 fully understand all the implications of unconditionally
9572 untainting the value. Untainting should be done in the
9573 standard perl fashion, via a carefully crafted regexp, rather
9574 than directly untainting variables.
9575 void SvTAINTED_off(SV* sv)
9577 SvTAINTED_on
9579 Marks an SV as tainted if tainting is enabled.
9580 void SvTAINTED_on(SV* sv)
9582 SvTRUE Returns a boolean indicating whether Perl would evaluate the SV
9584 as true or false. See "SvOK" for a defined/undefined test.
9585 Handles 'get' magic unless the scalar is already "SvPOK",
9586 "SvIOK" or "SvNOK" (the public, not the private flags).
9587 As of Perl 5.32, this is guaranteed to evaluate "sv" only once.
9589 Prior to that release, use "SvTRUEx" for single evaluation.
9590 bool SvTRUE(SV* sv)
9592 sv_true Returns true if the SV has a true value by Perl's rules. Use
9594 the "SvTRUE" macro instead, which may call "sv_true()" or may
9595 instead use an in-line version.
9596 I32 sv_true(SV *const sv)
9598 SvTRUE_nomg
9600 Returns a boolean indicating whether Perl would evaluate the SV
9601 as true or false. See "SvOK" for a defined/undefined test.
9602 Does not handle 'get' magic.
9603 bool SvTRUE_nomg(SV* sv)
9605 SvTRUEx Returns a boolean indicating whether Perl would evaluate the SV
9607 as true or false. See "SvOK" for a defined/undefined test.
9608 Handles 'get' magic unless the scalar is already "SvPOK",
9609 "SvIOK" or "SvNOK" (the public, not the private flags).
9610 This form guarantees to evaluate "sv" only once. Only use this
9612 if "sv" is an expression with side effects, otherwise use the
9613 more efficient "SvTRUE".
9614 bool SvTRUEx(SV* sv)
9616 SvTYPE Returns the type of the SV. See "svtype".
9618 svtype SvTYPE(SV* sv)
9620 sv_unmagic
9622 Removes all magic of type "type" from an SV.
9623 int sv_unmagic(SV *const sv, const int type)
9625 sv_unmagicext
9627 Removes all magic of type "type" with the specified "vtbl" from
9628 an SV.
9629 int sv_unmagicext(SV *const sv, const int type,
9631 MGVTBL *vtbl)
9632 sv_unref_flags
9634 Unsets the RV status of the SV, and decrements the reference
9635 count of whatever was being referenced by the RV. This can
9636 almost be thought of as a reversal of "newSVrv". The "cflags"
9637 argument can contain "SV_IMMEDIATE_UNREF" to force the
9638 reference count to be decremented (otherwise the decrementing
9639 is conditional on the reference count being different from one
9640 or the reference being a readonly SV). See "SvROK_off".
9641 void sv_unref_flags(SV *const ref, const U32 flags)
9643 sv_untaint
9645 Untaint an SV. Use "SvTAINTED_off" instead.
9646 void sv_untaint(SV *const sv)
9648 SvUOK Returns a boolean indicating whether the SV contains an integer
9650 that must be interpreted as unsigned. A non-negative integer
9651 whose value is within the range of both an IV and a UV may be
9652 flagged as either "SvUOK" or "SvIOK".
9653 bool SvUOK(SV* sv)
9655 SvUPGRADE
9657 Used to upgrade an SV to a more complex form. Uses
9658 "sv_upgrade" to perform the upgrade if necessary. See
9659 "svtype".
9660 void SvUPGRADE(SV* sv, svtype type)
9662 sv_upgrade
9664 Upgrade an SV to a more complex form. Generally adds a new
9665 body type to the SV, then copies across as much information as
9666 possible from the old body. It croaks if the SV is already in
9667 a more complex form than requested. You generally want to use
9668 the "SvUPGRADE" macro wrapper, which checks the type before
9669 calling "sv_upgrade", and hence does not croak. See also
9670 "svtype".
9671 void sv_upgrade(SV *const sv, svtype new_type)
9673 sv_usepvn_flags
9675 Tells an SV to use "ptr" to find its string value. Normally
9676 the string is stored inside the SV, but sv_usepvn allows the SV
9677 to use an outside string. "ptr" should point to memory that
9678 was allocated by "Newx". It must be the start of a "Newx"-ed
9679 block of memory, and not a pointer to the middle of it (beware
9680 of "OOK" and copy-on-write), and not be from a non-"Newx"
9681 memory allocator like "malloc". The string length, "len", must
9682 be supplied. By default this function will "Renew" (i.e.
9683 realloc, move) the memory pointed to by "ptr", so that pointer
9684 should not be freed or used by the programmer after giving it
9685 to "sv_usepvn", and neither should any pointers from "behind"
9686 that pointer (e.g. ptr + 1) be used.
9687 If "flags & SV_SMAGIC" is true, will call "SvSETMAGIC". If
9689 "flags & SV_HAS_TRAILING_NUL" is true, then "ptr[len]" must be
9690 "NUL", and the realloc will be skipped (i.e. the buffer is
9691 actually at least 1 byte longer than "len", and already meets
9692 the requirements for storing in "SvPVX").
9693 void sv_usepvn_flags(SV *const sv, char* ptr,
9695 const STRLEN len,
9696 const U32 flags)
9697 SvUTF8 Returns a U32 value indicating the UTF-8 status of an SV. If
9699 things are set-up properly, this indicates whether or not the
9700 SV contains UTF-8 encoded data. You should use this after a
9701 call to "SvPV()" or one of its variants, in case any call to
9702 string overloading updates the internal flag.
9703 If you want to take into account the bytes pragma, use
9705 "DO_UTF8" instead.
9706 U32 SvUTF8(SV* sv)
9708 sv_utf8_decode
9710 If the PV of the SV is an octet sequence in Perl's extended
9711 UTF-8 and contains a multiple-byte character, the "SvUTF8" flag
9712 is turned on so that it looks like a character. If the PV
9713 contains only single-byte characters, the "SvUTF8" flag stays
9714 off. Scans PV for validity and returns FALSE if the PV is
9715 invalid UTF-8.
9716 bool sv_utf8_decode(SV *const sv)
9718 sv_utf8_downgrade
9720 Attempts to convert the PV of an SV from characters to bytes.
9721 If the PV contains a character that cannot fit in a byte, this
9722 conversion will fail; in this case, either returns false or, if
9723 "fail_ok" is not true, croaks.
9724 This is not a general purpose Unicode to byte encoding
9726 interface: use the "Encode" extension for that.
9727 This function process get magic on "sv".
9729 bool sv_utf8_downgrade(SV *const sv,
9731 const bool fail_ok)
9732 sv_utf8_downgrade_flags
9734 Like "sv_utf8_downgrade", but with additional "flags". If
9735 "flags" has "SV_GMAGIC" bit set, processes get magic on "sv".
9736 bool sv_utf8_downgrade_flags(SV *const sv,
9738 const bool fail_ok,
9739 const U32 flags)
9740 sv_utf8_downgrade_nomg
9742 Like "sv_utf8_downgrade", but does not process get magic on
9743 "sv".
9744 bool sv_utf8_downgrade_nomg(SV *const sv,
9746 const bool fail_ok)
9747 sv_utf8_encode
9749 Converts the PV of an SV to UTF-8, but then turns the "SvUTF8"
9750 flag off so that it looks like octets again.
9751 void sv_utf8_encode(SV *const sv)
9753 sv_utf8_upgrade
9755 Converts the PV of an SV to its UTF-8-encoded form. Forces the
9756 SV to string form if it is not already. Will "mg_get" on "sv"
9757 if appropriate. Always sets the "SvUTF8" flag to avoid future
9758 validity checks even if the whole string is the same in UTF-8
9759 as not. Returns the number of bytes in the converted string
9760 This is not a general purpose byte encoding to Unicode
9762 interface: use the Encode extension for that.
9763 STRLEN sv_utf8_upgrade(SV *sv)
9765 sv_utf8_upgrade_flags
9767 Converts the PV of an SV to its UTF-8-encoded form. Forces the
9768 SV to string form if it is not already. Always sets the SvUTF8
9769 flag to avoid future validity checks even if all the bytes are
9770 invariant in UTF-8. If "flags" has "SV_GMAGIC" bit set, will
9771 "mg_get" on "sv" if appropriate, else not.
9772 The "SV_FORCE_UTF8_UPGRADE" flag is now ignored.
9774 Returns the number of bytes in the converted string.
9776 This is not a general purpose byte encoding to Unicode
9778 interface: use the Encode extension for that.
9779 STRLEN sv_utf8_upgrade_flags(SV *const sv,
9781 const I32 flags)
9782 sv_utf8_upgrade_flags_grow
9784 Like "sv_utf8_upgrade_flags", but has an additional parameter
9785 "extra", which is the number of unused bytes the string of "sv"
9786 is guaranteed to have free after it upon return. This allows
9787 the caller to reserve extra space that it intends to fill, to
9788 avoid extra grows.
9789 "sv_utf8_upgrade", "sv_utf8_upgrade_nomg", and
9791 "sv_utf8_upgrade_flags" are implemented in terms of this
9792 function.
9793 Returns the number of bytes in the converted string (not
9795 including the spares).
9796 STRLEN sv_utf8_upgrade_flags_grow(SV *const sv,
9798 const I32 flags,
9799 STRLEN extra)
9800 sv_utf8_upgrade_nomg
9802 Like "sv_utf8_upgrade", but doesn't do magic on "sv".
9803 STRLEN sv_utf8_upgrade_nomg(SV *sv)
9805 SvUTF8_off
9807 Unsets the UTF-8 status of an SV (the data is not changed, just
9808 the flag). Do not use frivolously.
9809 void SvUTF8_off(SV *sv)
9811 SvUTF8_on
9813 Turn on the UTF-8 status of an SV (the data is not changed,
9814 just the flag). Do not use frivolously.
9815 void SvUTF8_on(SV *sv)
9817 SvUV Coerces the given SV to UV and returns it. The returned value
9819 in many circumstances will get stored in "sv"'s UV slot, but
9820 not in all cases. (Use "sv_setuv" to make sure it does).
9821 See "SvUVx" for a version which guarantees to evaluate "sv"
9823 only once.
9824 UV SvUV(SV* sv)
9826 SvUV_nomg
9828 Like "SvUV" but doesn't process magic.
9829 UV SvUV_nomg(SV* sv)
9831 SvUV_set
9833 Set the value of the UV pointer in "sv" to val. See
9834 "SvIV_set".
9835 void SvUV_set(SV* sv, UV val)
9837 SvUVX Returns the raw value in the SV's UV slot, without checks or
9839 conversions. Only use when you are sure "SvIOK" is true. See
9840 also "SvUV".
9841 UV SvUVX(SV* sv)
9843 SvUVx Coerces the given SV to UV and returns it. The returned value
9845 in many circumstances will get stored in "sv"'s UV slot, but
9846 not in all cases. (Use "sv_setuv" to make sure it does).
9847 This form guarantees to evaluate "sv" only once. Only use this
9849 if "sv" is an expression with side effects, otherwise use the
9850 more efficient "SvUV".
9851 UV SvUVx(SV* sv)
9853 SvUVXx DEPRECATED! It is planned to remove this function from a
9855 future release of Perl. Do not use it for new code; remove it
9856 from existing code.
9857 This is an unnecessary synonym for "SvUVX"
9859 UV SvUVXx(SV* sv)
9861 sv_vcatpvf
9863 Processes its arguments like "sv_vcatpvfn" called with a non-
9864 null C-style variable argument list, and appends the formatted
9865 output to an SV. Does not handle 'set' magic. See
9866 "sv_vcatpvf_mg".
9867 Usually used via its frontend "sv_catpvf".
9869 void sv_vcatpvf(SV *const sv, const char *const pat,
9871 va_list *const args)
9872 sv_vcatpvfn
9874 void sv_vcatpvfn(SV *const sv, const char *const pat,
9875 const STRLEN patlen,
9876 va_list *const args,
9877 SV **const svargs,
9878 const Size_t sv_count,
9879 bool *const maybe_tainted)
9880 sv_vcatpvfn_flags
9882 Processes its arguments like "vsprintf" and appends the
9883 formatted output to an SV. Uses an array of SVs if the C-style
9884 variable argument list is missing ("NULL"). Argument reordering
9885 (using format specifiers like "%2$d" or "%*2$d") is supported
9886 only when using an array of SVs; using a C-style "va_list"
9887 argument list with a format string that uses argument
9888 reordering will yield an exception.
9889 When running with taint checks enabled, indicates via
9891 "maybe_tainted" if results are untrustworthy (often due to the
9892 use of locales).
9893 If called as "sv_vcatpvfn" or flags has the "SV_GMAGIC" bit
9895 set, calls get magic.
9896 It assumes that pat has the same utf8-ness as sv. It's the
9898 caller's responsibility to ensure that this is so.
9899 Usually used via one of its frontends "sv_vcatpvf" and
9901 "sv_vcatpvf_mg".
9902 void sv_vcatpvfn_flags(SV *const sv,
9904 const char *const pat,
9905 const STRLEN patlen,
9906 va_list *const args,
9907 SV **const svargs,
9908 const Size_t sv_count,
9909 bool *const maybe_tainted,
9910 const U32 flags)
9911 sv_vcatpvf_mg
9913 Like "sv_vcatpvf", but also handles 'set' magic.
9914 Usually used via its frontend "sv_catpvf_mg".
9916 void sv_vcatpvf_mg(SV *const sv,
9918 const char *const pat,
9919 va_list *const args)
9920 SvVOK Returns a boolean indicating whether the SV contains a
9922 v-string.
9923 bool SvVOK(SV* sv)
9925 sv_vsetpvf
9927 Works like "sv_vcatpvf" but copies the text into the SV instead
9928 of appending it. Does not handle 'set' magic. See
9929 "sv_vsetpvf_mg".
9930 Usually used via its frontend "sv_setpvf".
9932 void sv_vsetpvf(SV *const sv, const char *const pat,
9934 va_list *const args)
9935 sv_vsetpvfn
9937 Works like "sv_vcatpvfn" but copies the text into the SV
9938 instead of appending it.
9939 Usually used via one of its frontends "sv_vsetpvf" and
9941 "sv_vsetpvf_mg".
9942 void sv_vsetpvfn(SV *const sv, const char *const pat,
9944 const STRLEN patlen,
9945 va_list *const args,
9946 SV **const svargs,
9947 const Size_t sv_count,
9948 bool *const maybe_tainted)
9949 sv_vsetpvf_mg
9951 Like "sv_vsetpvf", but also handles 'set' magic.
9952 Usually used via its frontend "sv_setpvf_mg".
9954 void sv_vsetpvf_mg(SV *const sv,
9956 const char *const pat,
9957 va_list *const args)
9958
9960 "Unicode Support" in perlguts has an introduction to this API.
9961 See also "Character classification", and "Character case changing".
9963 Various functions outside this section also work specially with
9964 Unicode. Search for the string "utf8" in this document.
9965 BOM_UTF8
9967 This is a macro that evaluates to a string constant of the
9968 UTF-8 bytes that define the Unicode BYTE ORDER MARK (U+FEFF)
9969 for the platform that perl is compiled on. This allows code to
9970 use a mnemonic for this character that works on both ASCII and
9971 EBCDIC platforms. "sizeof(BOM_UTF8) - 1" can be used to get
9972 its length in bytes.
9973 bytes_cmp_utf8
9975 Compares the sequence of characters (stored as octets) in "b",
9976 "blen" with the sequence of characters (stored as UTF-8) in
9977 "u", "ulen". Returns 0 if they are equal, -1 or -2 if the
9978 first string is less than the second string, +1 or +2 if the
9979 first string is greater than the second string.
9980 -1 or +1 is returned if the shorter string was identical to the
9982 start of the longer string. -2 or +2 is returned if there was
9983 a difference between characters within the strings.
9984 int bytes_cmp_utf8(const U8 *b, STRLEN blen,
9986 const U8 *u, STRLEN ulen)
9987 bytes_from_utf8
9989 NOTE: this function is experimental and may change or be
9990 removed without notice.
9991 Converts a potentially UTF-8 encoded string "s" of length *lenp
9993 into native byte encoding. On input, the boolean *is_utf8p
9994 gives whether or not "s" is actually encoded in UTF-8.
9995 Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-
9997 destructive of the input string.
9998 Do nothing if *is_utf8p is 0, or if there are code points in
10000 the string not expressible in native byte encoding. In these
10001 cases, *is_utf8p and *lenp are unchanged, and the return value
10002 is the original "s".
10003 Otherwise, *is_utf8p is set to 0, and the return value is a
10005 pointer to a newly created string containing a downgraded copy
10006 of "s", and whose length is returned in *lenp, updated. The
10007 new string is "NUL"-terminated. The caller is responsible for
10008 arranging for the memory used by this string to get freed.
10009 Upon successful return, the number of variants in the string
10011 can be computed by having saved the value of *lenp before the
10012 call, and subtracting the after-call value of *lenp from it.
10013 U8* bytes_from_utf8(const U8 *s, STRLEN *lenp,
10015 bool *is_utf8p)
10016 bytes_to_utf8
10018 NOTE: this function is experimental and may change or be
10019 removed without notice.
10020 Converts a string "s" of length *lenp bytes from the native
10022 encoding into UTF-8. Returns a pointer to the newly-created
10023 string, and sets *lenp to reflect the new length in bytes. The
10024 caller is responsible for arranging for the memory used by this
10025 string to get freed.
10026 Upon successful return, the number of variants in the string
10028 can be computed by having saved the value of *lenp before the
10029 call, and subtracting it from the after-call value of *lenp.
10030 A "NUL" character will be written after the end of the string.
10032 If you want to convert to UTF-8 from encodings other than the
10034 native (Latin1 or EBCDIC), see "sv_recode_to_utf8"().
10035 U8* bytes_to_utf8(const U8 *s, STRLEN *lenp)
10037 DO_UTF8 Returns a bool giving whether or not the PV in "sv" is to be
10039 treated as being encoded in UTF-8.
10040 You should use this after a call to "SvPV()" or one of its
10042 variants, in case any call to string overloading updates the
10043 internal UTF-8 encoding flag.
10044 bool DO_UTF8(SV* sv)
10046 foldEQ_utf8
10048 Returns true if the leading portions of the strings "s1" and
10049 "s2" (either or both of which may be in UTF-8) are the same
10050 case-insensitively; false otherwise. How far into the strings
10051 to compare is determined by other input parameters.
10052 If "u1" is true, the string "s1" is assumed to be in
10054 UTF-8-encoded Unicode; otherwise it is assumed to be in native
10055 8-bit encoding. Correspondingly for "u2" with respect to "s2".
10056 If the byte length "l1" is non-zero, it says how far into "s1"
10058 to check for fold equality. In other words, "s1"+"l1" will be
10059 used as a goal to reach. The scan will not be considered to be
10060 a match unless the goal is reached, and scanning won't continue
10061 past that goal. Correspondingly for "l2" with respect to "s2".
10062 If "pe1" is non-"NULL" and the pointer it points to is not
10064 "NULL", that pointer is considered an end pointer to the
10065 position 1 byte past the maximum point in "s1" beyond which
10066 scanning will not continue under any circumstances. (This
10067 routine assumes that UTF-8 encoded input strings are not
10068 malformed; malformed input can cause it to read past "pe1").
10069 This means that if both "l1" and "pe1" are specified, and "pe1"
10070 is less than "s1"+"l1", the match will never be successful
10071 because it can never get as far as its goal (and in fact is
10072 asserted against). Correspondingly for "pe2" with respect to
10073 "s2".
10074 At least one of "s1" and "s2" must have a goal (at least one of
10076 "l1" and "l2" must be non-zero), and if both do, both have to
10077 be reached for a successful match. Also, if the fold of a
10078 character is multiple characters, all of them must be matched
10079 (see tr21 reference below for 'folding').
10080 Upon a successful match, if "pe1" is non-"NULL", it will be set
10082 to point to the beginning of the next character of "s1" beyond
10083 what was matched. Correspondingly for "pe2" and "s2".
10084 For case-insensitiveness, the "casefolding" of Unicode is used
10086 instead of upper/lowercasing both the characters, see
10087 <https://www.unicode.org/unicode/reports/tr21/> (Case
10088 Mappings).
10089 I32 foldEQ_utf8(const char *s1, char **pe1, UV l1,
10091 bool u1, const char *s2, char **pe2,
10092 UV l2, bool u2)
10093 is_ascii_string
10095 This is a misleadingly-named synonym for
10096 "is_utf8_invariant_string". On ASCII-ish platforms, the name
10097 isn't misleading: the ASCII-range characters are exactly the
10098 UTF-8 invariants. But EBCDIC machines have more invariants
10099 than just the ASCII characters, so "is_utf8_invariant_string"
10100 is preferred.
10101 bool is_ascii_string(const U8* const s, STRLEN len)
10103 is_c9strict_utf8_string
10105 Returns TRUE if the first "len" bytes of string "s" form a
10106 valid UTF-8-encoded string that conforms to Unicode Corrigendum
10107 #9 <http://www.unicode.org/versions/corrigendum9.html>;
10108 otherwise it returns FALSE. If "len" is 0, it will be
10109 calculated using strlen(s) (which means if you use this option,
10110 that "s" can't have embedded "NUL" characters and has to have a
10111 terminating "NUL" byte). Note that all characters being ASCII
10112 constitute 'a valid UTF-8 string'.
10113 This function returns FALSE for strings containing any code
10115 points above the Unicode max of 0x10FFFF or surrogate code
10116 points, but accepts non-character code points per Corrigendum
10117 #9 <http://www.unicode.org/versions/corrigendum9.html>.
10118 See also "is_utf8_invariant_string",
10120 "is_utf8_invariant_string_loc", "is_utf8_string",
10121 "is_utf8_string_flags", "is_utf8_string_loc",
10122 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
10123 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
10124 "is_utf8_fixed_width_buf_loc_flags",
10125 "is_utf8_fixed_width_buf_loclen_flags",
10126 "is_strict_utf8_string", "is_strict_utf8_string_loc",
10127 "is_strict_utf8_string_loclen", "is_c9strict_utf8_string_loc",
10128 and "is_c9strict_utf8_string_loclen".
10129 bool is_c9strict_utf8_string(const U8 *s, STRLEN len)
10131 is_c9strict_utf8_string_loc
10133 Like "is_c9strict_utf8_string" but stores the location of the
10134 failure (in the case of "utf8ness failure") or the location
10135 "s"+"len" (in the case of "utf8ness success") in the "ep"
10136 pointer.
10137 See also "is_c9strict_utf8_string_loclen".
10139 bool is_c9strict_utf8_string_loc(const U8 *s,
10141 STRLEN len,
10142 const U8 **ep)
10143 is_c9strict_utf8_string_loclen
10145 Like "is_c9strict_utf8_string" but stores the location of the
10146 failure (in the case of "utf8ness failure") or the location
10147 "s"+"len" (in the case of "utf8ness success") in the "ep"
10148 pointer, and the number of UTF-8 encoded characters in the "el"
10149 pointer.
10150 See also "is_c9strict_utf8_string_loc".
10152 bool is_c9strict_utf8_string_loclen(const U8 *s,
10154 STRLEN len,
10155 const U8 **ep,
10156 STRLEN *el)
10157 isC9_STRICT_UTF8_CHAR
10159 Evaluates to non-zero if the first few bytes of the string
10160 starting at "s" and looking no further than "e - 1" are well-
10161 formed UTF-8 that represents some Unicode non-surrogate code
10162 point; otherwise it evaluates to 0. If non-zero, the value
10163 gives how many bytes starting at "s" comprise the code point's
10164 representation. Any bytes remaining before "e", but beyond the
10165 ones needed to form the first code point in "s", are not
10166 examined.
10167 The largest acceptable code point is the Unicode maximum
10169 0x10FFFF. This differs from "isSTRICT_UTF8_CHAR" only in that
10170 it accepts non-character code points. This corresponds to
10171 Unicode Corrigendum #9
10172 <http://www.unicode.org/versions/corrigendum9.html>. which
10173 said that non-character code points are merely discouraged
10174 rather than completely forbidden in open interchange. See
10175 "Noncharacter code points" in perlunicode.
10176 Use "isUTF8_CHAR" to check for Perl's extended UTF-8; and
10178 "isUTF8_CHAR_flags" for a more customized definition.
10179 Use "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc",
10181 and "is_c9strict_utf8_string_loclen" to check entire strings.
10182 Size_t isC9_STRICT_UTF8_CHAR(const U8 * const s0,
10184 const U8 * const e)
10185 is_invariant_string
10187 This is a somewhat misleadingly-named synonym for
10188 "is_utf8_invariant_string". "is_utf8_invariant_string" is
10189 preferred, as it indicates under what conditions the string is
10190 invariant.
10191 bool is_invariant_string(const U8* const s,
10193 STRLEN len)
10194 isSTRICT_UTF8_CHAR
10196 Evaluates to non-zero if the first few bytes of the string
10197 starting at "s" and looking no further than "e - 1" are well-
10198 formed UTF-8 that represents some Unicode code point completely
10199 acceptable for open interchange between all applications;
10200 otherwise it evaluates to 0. If non-zero, the value gives how
10201 many bytes starting at "s" comprise the code point's
10202 representation. Any bytes remaining before "e", but beyond the
10203 ones needed to form the first code point in "s", are not
10204 examined.
10205 The largest acceptable code point is the Unicode maximum
10207 0x10FFFF, and must not be a surrogate nor a non-character code
10208 point. Thus this excludes any code point from Perl's extended
10209 UTF-8.
10210 This is used to efficiently decide if the next few bytes in "s"
10212 is legal Unicode-acceptable UTF-8 for a single character.
10213 Use "isC9_STRICT_UTF8_CHAR" to use the Unicode Corrigendum #9
10215 <http://www.unicode.org/versions/corrigendum9.html> definition
10216 of allowable code points; "isUTF8_CHAR" to check for Perl's
10217 extended UTF-8; and "isUTF8_CHAR_flags" for a more customized
10218 definition.
10219 Use "is_strict_utf8_string", "is_strict_utf8_string_loc", and
10221 "is_strict_utf8_string_loclen" to check entire strings.
10222 Size_t isSTRICT_UTF8_CHAR(const U8 * const s0,
10224 const U8 * const e)
10225 is_strict_utf8_string
10227 Returns TRUE if the first "len" bytes of string "s" form a
10228 valid UTF-8-encoded string that is fully interchangeable by any
10229 application using Unicode rules; otherwise it returns FALSE.
10230 If "len" is 0, it will be calculated using strlen(s) (which
10231 means if you use this option, that "s" can't have embedded
10232 "NUL" characters and has to have a terminating "NUL" byte).
10233 Note that all characters being ASCII constitute 'a valid UTF-8
10234 string'.
10235 This function returns FALSE for strings containing any code
10237 points above the Unicode max of 0x10FFFF, surrogate code
10238 points, or non-character code points.
10239 See also "is_utf8_invariant_string",
10241 "is_utf8_invariant_string_loc", "is_utf8_string",
10242 "is_utf8_string_flags", "is_utf8_string_loc",
10243 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
10244 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
10245 "is_utf8_fixed_width_buf_loc_flags",
10246 "is_utf8_fixed_width_buf_loclen_flags",
10247 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
10248 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
10249 "is_c9strict_utf8_string_loclen".
10250 bool is_strict_utf8_string(const U8 *s, STRLEN len)
10252 is_strict_utf8_string_loc
10254 Like "is_strict_utf8_string" but stores the location of the
10255 failure (in the case of "utf8ness failure") or the location
10256 "s"+"len" (in the case of "utf8ness success") in the "ep"
10257 pointer.
10258 See also "is_strict_utf8_string_loclen".
10260 bool is_strict_utf8_string_loc(const U8 *s,
10262 STRLEN len,
10263 const U8 **ep)
10264 is_strict_utf8_string_loclen
10266 Like "is_strict_utf8_string" but stores the location of the
10267 failure (in the case of "utf8ness failure") or the location
10268 "s"+"len" (in the case of "utf8ness success") in the "ep"
10269 pointer, and the number of UTF-8 encoded characters in the "el"
10270 pointer.
10271 See also "is_strict_utf8_string_loc".
10273 bool is_strict_utf8_string_loclen(const U8 *s,
10275 STRLEN len,
10276 const U8 **ep,
10277 STRLEN *el)
10278 is_utf8_fixed_width_buf_flags
10280 Returns TRUE if the fixed-width buffer starting at "s" with
10281 length "len" is entirely valid UTF-8, subject to the
10282 restrictions given by "flags"; otherwise it returns FALSE.
10283 If "flags" is 0, any well-formed UTF-8, as extended by Perl, is
10285 accepted without restriction. If the final few bytes of the
10286 buffer do not form a complete code point, this will return TRUE
10287 anyway, provided that "is_utf8_valid_partial_char_flags"
10288 returns TRUE for them.
10289 If "flags" in non-zero, it can be any combination of the
10291 "UTF8_DISALLOW_foo" flags accepted by "utf8n_to_uvchr", and
10292 with the same meanings.
10293 This function differs from "is_utf8_string_flags" only in that
10295 the latter returns FALSE if the final few bytes of the string
10296 don't form a complete code point.
10297 bool is_utf8_fixed_width_buf_flags(
10299 const U8 * const s, STRLEN len,
10300 const U32 flags
10301 )
10302 is_utf8_fixed_width_buf_loclen_flags
10304 Like "is_utf8_fixed_width_buf_loc_flags" but stores the number
10305 of complete, valid characters found in the "el" pointer.
10306 bool is_utf8_fixed_width_buf_loclen_flags(
10308 const U8 * const s, STRLEN len,
10309 const U8 **ep, STRLEN *el, const U32 flags
10310 )
10311 is_utf8_fixed_width_buf_loc_flags
10313 Like "is_utf8_fixed_width_buf_flags" but stores the location of
10314 the failure in the "ep" pointer. If the function returns TRUE,
10315 *ep will point to the beginning of any partial character at the
10316 end of the buffer; if there is no partial character *ep will
10317 contain "s"+"len".
10318 See also "is_utf8_fixed_width_buf_loclen_flags".
10320 bool is_utf8_fixed_width_buf_loc_flags(
10322 const U8 * const s, STRLEN len,
10323 const U8 **ep, const U32 flags
10324 )
10325 is_utf8_invariant_string
10327 Returns TRUE if the first "len" bytes of the string "s" are the
10328 same regardless of the UTF-8 encoding of the string (or UTF-
10329 EBCDIC encoding on EBCDIC machines); otherwise it returns
10330 FALSE. That is, it returns TRUE if they are UTF-8 invariant.
10331 On ASCII-ish machines, all the ASCII characters and only the
10332 ASCII characters fit this definition. On EBCDIC machines, the
10333 ASCII-range characters are invariant, but so also are the C1
10334 controls.
10335 If "len" is 0, it will be calculated using strlen(s), (which
10337 means if you use this option, that "s" can't have embedded
10338 "NUL" characters and has to have a terminating "NUL" byte).
10339 See also "is_utf8_string", "is_utf8_string_flags",
10341 "is_utf8_string_loc", "is_utf8_string_loc_flags",
10342 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
10343 "is_utf8_fixed_width_buf_flags",
10344 "is_utf8_fixed_width_buf_loc_flags",
10345 "is_utf8_fixed_width_buf_loclen_flags",
10346 "is_strict_utf8_string", "is_strict_utf8_string_loc",
10347 "is_strict_utf8_string_loclen", "is_c9strict_utf8_string",
10348 "is_c9strict_utf8_string_loc", and
10349 "is_c9strict_utf8_string_loclen".
10350 bool is_utf8_invariant_string(const U8* const s,
10352 STRLEN len)
10353 is_utf8_invariant_string_loc
10355 Like "is_utf8_invariant_string" but upon failure, stores the
10356 location of the first UTF-8 variant character in the "ep"
10357 pointer; if all characters are UTF-8 invariant, this function
10358 does not change the contents of *ep.
10359 bool is_utf8_invariant_string_loc(const U8* const s,
10361 STRLEN len,
10362 const U8 ** ep)
10363 is_utf8_string
10365 Returns TRUE if the first "len" bytes of string "s" form a
10366 valid Perl-extended-UTF-8 string; returns FALSE otherwise. If
10367 "len" is 0, it will be calculated using strlen(s) (which means
10368 if you use this option, that "s" can't have embedded "NUL"
10369 characters and has to have a terminating "NUL" byte). Note
10370 that all characters being ASCII constitute 'a valid UTF-8
10371 string'.
10372 This function considers Perl's extended UTF-8 to be valid.
10374 That means that code points above Unicode, surrogates, and non-
10375 character code points are considered valid by this function.
10376 Use "is_strict_utf8_string", "is_c9strict_utf8_string", or
10377 "is_utf8_string_flags" to restrict what code points are
10378 considered valid.
10379 See also "is_utf8_invariant_string",
10381 "is_utf8_invariant_string_loc", "is_utf8_string_loc",
10382 "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags",
10383 "is_utf8_fixed_width_buf_loc_flags",
10384 "is_utf8_fixed_width_buf_loclen_flags",
10385 bool is_utf8_string(const U8 *s, STRLEN len)
10387 is_utf8_string_flags
10389 Returns TRUE if the first "len" bytes of string "s" form a
10390 valid UTF-8 string, subject to the restrictions imposed by
10391 "flags"; returns FALSE otherwise. If "len" is 0, it will be
10392 calculated using strlen(s) (which means if you use this option,
10393 that "s" can't have embedded "NUL" characters and has to have a
10394 terminating "NUL" byte). Note that all characters being ASCII
10395 constitute 'a valid UTF-8 string'.
10396 If "flags" is 0, this gives the same results as
10398 "is_utf8_string"; if "flags" is
10399 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the same
10400 results as "is_strict_utf8_string"; and if "flags" is
10401 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same
10402 results as "is_c9strict_utf8_string". Otherwise "flags" may be
10403 any combination of the "UTF8_DISALLOW_foo" flags understood by
10404 "utf8n_to_uvchr", with the same meanings.
10405 See also "is_utf8_invariant_string",
10407 "is_utf8_invariant_string_loc", "is_utf8_string",
10408 "is_utf8_string_loc", "is_utf8_string_loc_flags",
10409 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
10410 "is_utf8_fixed_width_buf_flags",
10411 "is_utf8_fixed_width_buf_loc_flags",
10412 "is_utf8_fixed_width_buf_loclen_flags",
10413 "is_strict_utf8_string", "is_strict_utf8_string_loc",
10414 "is_strict_utf8_string_loclen", "is_c9strict_utf8_string",
10415 "is_c9strict_utf8_string_loc", and
10416 "is_c9strict_utf8_string_loclen".
10417 bool is_utf8_string_flags(const U8 *s, STRLEN len,
10419 const U32 flags)
10420 is_utf8_string_loc
10422 Like "is_utf8_string" but stores the location of the failure
10423 (in the case of "utf8ness failure") or the location "s"+"len"
10424 (in the case of "utf8ness success") in the "ep" pointer.
10425 See also "is_utf8_string_loclen".
10427 bool is_utf8_string_loc(const U8 *s,
10429 const STRLEN len,
10430 const U8 **ep)
10431 is_utf8_string_loclen
10433 Like "is_utf8_string" but stores the location of the failure
10434 (in the case of "utf8ness failure") or the location "s"+"len"
10435 (in the case of "utf8ness success") in the "ep" pointer, and
10436 the number of UTF-8 encoded characters in the "el" pointer.
10437 See also "is_utf8_string_loc".
10439 bool is_utf8_string_loclen(const U8 *s, STRLEN len,
10441 const U8 **ep, STRLEN *el)
10442 is_utf8_string_loclen_flags
10444 Like "is_utf8_string_flags" but stores the location of the
10445 failure (in the case of "utf8ness failure") or the location
10446 "s"+"len" (in the case of "utf8ness success") in the "ep"
10447 pointer, and the number of UTF-8 encoded characters in the "el"
10448 pointer.
10449 See also "is_utf8_string_loc_flags".
10451 bool is_utf8_string_loclen_flags(const U8 *s,
10453 STRLEN len,
10454 const U8 **ep,
10455 STRLEN *el,
10456 const U32 flags)
10457 is_utf8_string_loc_flags
10459 Like "is_utf8_string_flags" but stores the location of the
10460 failure (in the case of "utf8ness failure") or the location
10461 "s"+"len" (in the case of "utf8ness success") in the "ep"
10462 pointer.
10463 See also "is_utf8_string_loclen_flags".
10465 bool is_utf8_string_loc_flags(const U8 *s,
10467 STRLEN len,
10468 const U8 **ep,
10469 const U32 flags)
10470 is_utf8_valid_partial_char
10472 Returns 0 if the sequence of bytes starting at "s" and looking
10473 no further than "e - 1" is the UTF-8 encoding, as extended by
10474 Perl, for one or more code points. Otherwise, it returns 1 if
10475 there exists at least one non-empty sequence of bytes that when
10476 appended to sequence "s", starting at position "e" causes the
10477 entire sequence to be the well-formed UTF-8 of some code point;
10478 otherwise returns 0.
10479 In other words this returns TRUE if "s" points to a partial
10481 UTF-8-encoded code point.
10482 This is useful when a fixed-length buffer is being tested for
10484 being well-formed UTF-8, but the final few bytes in it don't
10485 comprise a full character; that is, it is split somewhere in
10486 the middle of the final code point's UTF-8 representation.
10487 (Presumably when the buffer is refreshed with the next chunk of
10488 data, the new first bytes will complete the partial code
10489 point.) This function is used to verify that the final bytes
10490 in the current buffer are in fact the legal beginning of some
10491 code point, so that if they aren't, the failure can be
10492 signalled without having to wait for the next read.
10493 bool is_utf8_valid_partial_char(const U8 * const s,
10495 const U8 * const e)
10496 is_utf8_valid_partial_char_flags
10498 Like "is_utf8_valid_partial_char", it returns a boolean giving
10499 whether or not the input is a valid UTF-8 encoded partial
10500 character, but it takes an extra parameter, "flags", which can
10501 further restrict which code points are considered valid.
10502 If "flags" is 0, this behaves identically to
10504 "is_utf8_valid_partial_char". Otherwise "flags" can be any
10505 combination of the "UTF8_DISALLOW_foo" flags accepted by
10506 "utf8n_to_uvchr". If there is any sequence of bytes that can
10507 complete the input partial character in such a way that a non-
10508 prohibited character is formed, the function returns TRUE;
10509 otherwise FALSE. Non character code points cannot be
10510 determined based on partial character input. But many of the
10511 other possible excluded types can be determined from just the
10512 first one or two bytes.
10513 bool is_utf8_valid_partial_char_flags(
10515 const U8 * const s, const U8 * const e,
10516 const U32 flags
10517 )
10518 isUTF8_CHAR
10520 Evaluates to non-zero if the first few bytes of the string
10521 starting at "s" and looking no further than "e - 1" are well-
10522 formed UTF-8, as extended by Perl, that represents some code
10523 point; otherwise it evaluates to 0. If non-zero, the value
10524 gives how many bytes starting at "s" comprise the code point's
10525 representation. Any bytes remaining before "e", but beyond the
10526 ones needed to form the first code point in "s", are not
10527 examined.
10528 The code point can be any that will fit in an IV on this
10530 machine, using Perl's extension to official UTF-8 to represent
10531 those higher than the Unicode maximum of 0x10FFFF. That means
10532 that this macro is used to efficiently decide if the next few
10533 bytes in "s" is legal UTF-8 for a single character.
10534 Use "isSTRICT_UTF8_CHAR" to restrict the acceptable code points
10536 to those defined by Unicode to be fully interchangeable across
10537 applications; "isC9_STRICT_UTF8_CHAR" to use the Unicode
10538 Corrigendum #9
10539 <http://www.unicode.org/versions/corrigendum9.html> definition
10540 of allowable code points; and "isUTF8_CHAR_flags" for a more
10541 customized definition.
10542 Use "is_utf8_string", "is_utf8_string_loc", and
10544 "is_utf8_string_loclen" to check entire strings.
10545 Note also that a UTF-8 "invariant" character (i.e. ASCII on
10547 non-EBCDIC machines) is a valid UTF-8 character.
10548 Size_t isUTF8_CHAR(const U8 * const s0,
10550 const U8 * const e)
10551 isUTF8_CHAR_flags
10553 Evaluates to non-zero if the first few bytes of the string
10554 starting at "s" and looking no further than "e - 1" are well-
10555 formed UTF-8, as extended by Perl, that represents some code
10556 point, subject to the restrictions given by "flags"; otherwise
10557 it evaluates to 0. If non-zero, the value gives how many bytes
10558 starting at "s" comprise the code point's representation. Any
10559 bytes remaining before "e", but beyond the ones needed to form
10560 the first code point in "s", are not examined.
10561 If "flags" is 0, this gives the same results as "isUTF8_CHAR";
10563 if "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives
10564 the same results as "isSTRICT_UTF8_CHAR"; and if "flags" is
10565 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same
10566 results as "isC9_STRICT_UTF8_CHAR". Otherwise "flags" may be
10567 any combination of the "UTF8_DISALLOW_foo" flags understood by
10568 "utf8n_to_uvchr", with the same meanings.
10569 The three alternative macros are for the most commonly needed
10571 validations; they are likely to run somewhat faster than this
10572 more general one, as they can be inlined into your code.
10573 Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
10575 "is_utf8_string_loclen_flags" to check entire strings.
10576 STRLEN isUTF8_CHAR_flags(const U8 *s, const U8 *e,
10578 const U32 flags)
10579 LATIN1_TO_NATIVE
10581 Returns the native equivalent of the input Latin-1 code point
10582 (including ASCII and control characters) given by "ch". Thus,
10583 "LATIN1_TO_NATIVE(66)" on EBCDIC platforms returns 194. These
10584 each represent the character "B" on their respective platforms.
10585 On ASCII platforms no conversion is needed, so this macro
10586 expands to just its input, adding no time nor space
10587 requirements to the implementation.
10588 For conversion of code points potentially larger than will fit
10590 in a character, use "UNI_TO_NATIVE".
10591 U8 LATIN1_TO_NATIVE(U8 ch)
10593 NATIVE_TO_LATIN1
10595 Returns the Latin-1 (including ASCII and control characters)
10596 equivalent of the input native code point given by "ch". Thus,
10597 "NATIVE_TO_LATIN1(193)" on EBCDIC platforms returns 65. These
10598 each represent the character "A" on their respective platforms.
10599 On ASCII platforms no conversion is needed, so this macro
10600 expands to just its input, adding no time nor space
10601 requirements to the implementation.
10602 For conversion of code points potentially larger than will fit
10604 in a character, use "NATIVE_TO_UNI".
10605 U8 NATIVE_TO_LATIN1(U8 ch)
10607 NATIVE_TO_UNI
10609 Returns the Unicode equivalent of the input native code point
10610 given by "ch". Thus, "NATIVE_TO_UNI(195)" on EBCDIC platforms
10611 returns 67. These each represent the character "C" on their
10612 respective platforms. On ASCII platforms no conversion is
10613 needed, so this macro expands to just its input, adding no time
10614 nor space requirements to the implementation.
10615 UV NATIVE_TO_UNI(UV ch)
10617 pv_uni_display
10619 Build to the scalar "dsv" a displayable version of the UTF-8
10620 encoded string "spv", length "len", the displayable version
10621 being at most "pvlim" bytes long (if longer, the rest is
10622 truncated and "..." will be appended).
10623 The "flags" argument can have "UNI_DISPLAY_ISPRINT" set to
10625 display "isPRINT()"able characters as themselves,
10626 "UNI_DISPLAY_BACKSLASH" to display the "\\[nrfta\\]" as the
10627 backslashed versions (like "\n") ("UNI_DISPLAY_BACKSLASH" is
10628 preferred over "UNI_DISPLAY_ISPRINT" for "\\").
10629 "UNI_DISPLAY_QQ" (and its alias "UNI_DISPLAY_REGEX") have both
10630 "UNI_DISPLAY_BACKSLASH" and "UNI_DISPLAY_ISPRINT" turned on.
10631 Additionally, there is now "UNI_DISPLAY_BACKSPACE" which allows
10633 "\b" for a backspace, but only when "UNI_DISPLAY_BACKSLASH"
10634 also is set.
10635 The pointer to the PV of the "dsv" is returned.
10637 See also "sv_uni_display".
10639 char* pv_uni_display(SV *dsv, const U8 *spv,
10641 STRLEN len, STRLEN pvlim,
10642 UV flags)
10643 REPLACEMENT_CHARACTER_UTF8
10645 This is a macro that evaluates to a string constant of the
10646 UTF-8 bytes that define the Unicode REPLACEMENT CHARACTER
10647 (U+FFFD) for the platform that perl is compiled on. This
10648 allows code to use a mnemonic for this character that works on
10649 both ASCII and EBCDIC platforms.
10650 "sizeof(REPLACEMENT_CHARACTER_UTF8) - 1" can be used to get its
10651 length in bytes.
10652 sv_cat_decode
10654 "encoding" is assumed to be an "Encode" object, the PV of "ssv"
10655 is assumed to be octets in that encoding and decoding the input
10656 starts from the position which "(PV + *offset)" pointed to.
10657 "dsv" will be concatenated with the decoded UTF-8 string from
10658 "ssv". Decoding will terminate when the string "tstr" appears
10659 in decoding output or the input ends on the PV of "ssv". The
10660 value which "offset" points will be modified to the last input
10661 position on "ssv".
10662 Returns TRUE if the terminator was found, else returns FALSE.
10664 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv,
10666 int *offset, char* tstr, int tlen)
10667 sv_recode_to_utf8
10669 "encoding" is assumed to be an "Encode" object, on entry the PV
10670 of "sv" is assumed to be octets in that encoding, and "sv" will
10671 be converted into Unicode (and UTF-8).
10672 If "sv" already is UTF-8 (or if it is not "POK"), or if
10674 "encoding" is not a reference, nothing is done to "sv". If
10675 "encoding" is not an "Encode::XS" Encoding object, bad things
10676 will happen. (See cpan/Encode/encoding.pm and Encode.)
10677 The PV of "sv" is returned.
10679 char* sv_recode_to_utf8(SV* sv, SV *encoding)
10681 sv_uni_display
10683 Build to the scalar "dsv" a displayable version of the scalar
10684 "sv", the displayable version being at most "pvlim" bytes long
10685 (if longer, the rest is truncated and "..." will be appended).
10686 The "flags" argument is as in "pv_uni_display"().
10688 The pointer to the PV of the "dsv" is returned.
10690 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim,
10692 UV flags)
10693 UNICODE_REPLACEMENT
10695 Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT
10696 CHARACTER
10697 UNI_TO_NATIVE
10699 Returns the native equivalent of the input Unicode code point
10700 given by "ch". Thus, "UNI_TO_NATIVE(68)" on EBCDIC platforms
10701 returns 196. These each represent the character "D" on their
10702 respective platforms. On ASCII platforms no conversion is
10703 needed, so this macro expands to just its input, adding no time
10704 nor space requirements to the implementation.
10705 UV UNI_TO_NATIVE(UV ch)
10707 utf8n_to_uvchr
10709 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
10710 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"()
10711 rather than call this directly.
10712 Bottom level UTF-8 decode routine. Returns the native code
10714 point value of the first character in the string "s", which is
10715 assumed to be in UTF-8 (or UTF-EBCDIC) encoding, and no longer
10716 than "curlen" bytes; *retlen (if "retlen" isn't NULL) will be
10717 set to the length, in bytes, of that character.
10718 The value of "flags" determines the behavior when "s" does not
10720 point to a well-formed UTF-8 character. If "flags" is 0,
10721 encountering a malformation causes zero to be returned and
10722 *retlen is set so that ("s" + *retlen) is the next possible
10723 position in "s" that could begin a non-malformed character.
10724 Also, if UTF-8 warnings haven't been lexically disabled, a
10725 warning is raised. Some UTF-8 input sequences may contain
10726 multiple malformations. This function tries to find every
10727 possible one in each call, so multiple warnings can be raised
10728 for the same sequence.
10729 Various ALLOW flags can be set in "flags" to allow (and not
10731 warn on) individual types of malformations, such as the
10732 sequence being overlong (that is, when there is a shorter
10733 sequence that can express the same code point; overlong
10734 sequences are expressly forbidden in the UTF-8 standard due to
10735 potential security issues). Another malformation example is
10736 the first byte of a character not being a legal first byte.
10737 See utf8.h for the list of such flags. Even if allowed, this
10738 function generally returns the Unicode REPLACEMENT CHARACTER
10739 when it encounters a malformation. There are flags in utf8.h
10740 to override this behavior for the overlong malformations, but
10741 don't do that except for very specialized purposes.
10742 The "UTF8_CHECK_ONLY" flag overrides the behavior when a non-
10744 allowed (by other flags) malformation is found. If this flag
10745 is set, the routine assumes that the caller will raise a
10746 warning, and this function will silently just set "retlen" to
10747 "-1" (cast to "STRLEN") and return zero.
10748 Note that this API requires disambiguation between successful
10750 decoding a "NUL" character, and an error return (unless the
10751 "UTF8_CHECK_ONLY" flag is set), as in both cases, 0 is
10752 returned, and, depending on the malformation, "retlen" may be
10753 set to 1. To disambiguate, upon a zero return, see if the
10754 first byte of "s" is 0 as well. If so, the input was a "NUL";
10755 if not, the input had an error. Or you can use
10756 "utf8n_to_uvchr_error".
10757 Certain code points are considered problematic. These are
10759 Unicode surrogates, Unicode non-characters, and code points
10760 above the Unicode maximum of 0x10FFFF. By default these are
10761 considered regular code points, but certain situations warrant
10762 special handling for them, which can be specified using the
10763 "flags" parameter. If "flags" contains
10764 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", all three classes are
10765 treated as malformations and handled as such. The flags
10766 "UTF8_DISALLOW_SURROGATE", "UTF8_DISALLOW_NONCHAR", and
10767 "UTF8_DISALLOW_SUPER" (meaning above the legal Unicode maximum)
10768 can be set to disallow these categories individually.
10769 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed
10770 inputs to the strict UTF-8 traditionally defined by Unicode.
10771 Use "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE" to use the
10772 strictness definition given by Unicode Corrigendum #9
10773 <https://www.unicode.org/versions/corrigendum9.html>. The
10774 difference between traditional strictness and C9 strictness is
10775 that the latter does not forbid non-character code points.
10776 (They are still discouraged, however.) For more discussion see
10777 "Noncharacter code points" in perlunicode.
10778 The flags "UTF8_WARN_ILLEGAL_INTERCHANGE",
10780 "UTF8_WARN_ILLEGAL_C9_INTERCHANGE", "UTF8_WARN_SURROGATE",
10781 "UTF8_WARN_NONCHAR", and "UTF8_WARN_SUPER" will cause warning
10782 messages to be raised for their respective categories, but
10783 otherwise the code points are considered valid (not
10784 malformations). To get a category to both be treated as a
10785 malformation and raise a warning, specify both the WARN and
10786 DISALLOW flags. (But note that warnings are not raised if
10787 lexically disabled nor if "UTF8_CHECK_ONLY" is also specified.)
10788 Extremely high code points were never specified in any
10790 standard, and require an extension to UTF-8 to express, which
10791 Perl does. It is likely that programs written in something
10792 other than Perl would not be able to read files that contain
10793 these; nor would Perl understand files written by something
10794 that uses a different extension. For these reasons, there is a
10795 separate set of flags that can warn and/or disallow these
10796 extremely high code points, even if other above-Unicode ones
10797 are accepted. They are the "UTF8_WARN_PERL_EXTENDED" and
10798 "UTF8_DISALLOW_PERL_EXTENDED" flags. For more information see
10799 ""UTF8_GOT_PERL_EXTENDED"". Of course "UTF8_DISALLOW_SUPER"
10800 will treat all above-Unicode code points, including these, as
10801 malformations. (Note that the Unicode standard considers
10802 anything above 0x10FFFF to be illegal, but there are standards
10803 predating it that allow up to 0x7FFF_FFFF (2**31 -1))
10804 A somewhat misleadingly named synonym for
10806 "UTF8_WARN_PERL_EXTENDED" is retained for backward
10807 compatibility: "UTF8_WARN_ABOVE_31_BIT". Similarly,
10808 "UTF8_DISALLOW_ABOVE_31_BIT" is usable instead of the more
10809 accurately named "UTF8_DISALLOW_PERL_EXTENDED". The names are
10810 misleading because these flags can apply to code points that
10811 actually do fit in 31 bits. This happens on EBCDIC platforms,
10812 and sometimes when the overlong malformation is also present.
10813 The new names accurately describe the situation in all cases.
10814 All other code points corresponding to Unicode characters,
10816 including private use and those yet to be assigned, are never
10817 considered malformed and never warn.
10818 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen,
10820 STRLEN *retlen, const U32 flags)
10821 utf8n_to_uvchr_error
10823 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
10824 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"()
10825 rather than call this directly.
10826 This function is for code that needs to know what the precise
10828 malformation(s) are when an error is found. If you also need
10829 to know the generated warning messages, use
10830 "utf8n_to_uvchr_msgs"() instead.
10831 It is like "utf8n_to_uvchr" but it takes an extra parameter
10833 placed after all the others, "errors". If this parameter is 0,
10834 this function behaves identically to "utf8n_to_uvchr".
10835 Otherwise, "errors" should be a pointer to a "U32" variable,
10836 which this function sets to indicate any errors found. Upon
10837 return, if *errors is 0, there were no errors found.
10838 Otherwise, *errors is the bit-wise "OR" of the bits described
10839 in the list below. Some of these bits will be set if a
10840 malformation is found, even if the input "flags" parameter
10841 indicates that the given malformation is allowed; those
10842 exceptions are noted:
10843 "UTF8_GOT_PERL_EXTENDED"
10845 The input sequence is not standard UTF-8, but a Perl
10846 extension. This bit is set only if the input "flags"
10847 parameter contains either the "UTF8_DISALLOW_PERL_EXTENDED"
10848 or the "UTF8_WARN_PERL_EXTENDED" flags.
10849 Code points above 0x7FFF_FFFF (2**31 - 1) were never
10851 specified in any standard, and so some extension must be
10852 used to express them. Perl uses a natural extension to
10853 UTF-8 to represent the ones up to 2**36-1, and invented a
10854 further extension to represent even higher ones, so that
10855 any code point that fits in a 64-bit word can be
10856 represented. Text using these extensions is not likely to
10857 be portable to non-Perl code. We lump both of these
10858 extensions together and refer to them as Perl extended
10859 UTF-8. There exist other extensions that people have
10860 invented, incompatible with Perl's.
10861 On EBCDIC platforms starting in Perl v5.24, the Perl
10863 extension for representing extremely high code points kicks
10864 in at 0x3FFF_FFFF (2**30 -1), which is lower than on ASCII.
10865 Prior to that, code points 2**31 and higher were simply
10866 unrepresentable, and a different, incompatible method was
10867 used to represent code points between 2**30 and 2**31 - 1.
10868 On both platforms, ASCII and EBCDIC,
10870 "UTF8_GOT_PERL_EXTENDED" is set if Perl extended UTF-8 is
10871 used.
10872 In earlier Perls, this bit was named
10874 "UTF8_GOT_ABOVE_31_BIT", which you still may use for
10875 backward compatibility. That name is misleading, as this
10876 flag may be set when the code point actually does fit in 31
10877 bits. This happens on EBCDIC platforms, and sometimes when
10878 the overlong malformation is also present. The new name
10879 accurately describes the situation in all cases.
10880 "UTF8_GOT_CONTINUATION"
10882 The input sequence was malformed in that the first byte was
10883 a UTF-8 continuation byte.
10884 "UTF8_GOT_EMPTY"
10886 The input "curlen" parameter was 0.
10887 "UTF8_GOT_LONG"
10889 The input sequence was malformed in that there is some
10890 other sequence that evaluates to the same code point, but
10891 that sequence is shorter than this one.
10892 Until Unicode 3.1, it was legal for programs to accept this
10894 malformation, but it was discovered that this created
10895 security issues.
10896 "UTF8_GOT_NONCHAR"
10898 The code point represented by the input UTF-8 sequence is
10899 for a Unicode non-character code point. This bit is set
10900 only if the input "flags" parameter contains either the
10901 "UTF8_DISALLOW_NONCHAR" or the "UTF8_WARN_NONCHAR" flags.
10902 "UTF8_GOT_NON_CONTINUATION"
10904 The input sequence was malformed in that a non-continuation
10905 type byte was found in a position where only a continuation
10906 type one should be. See also ""UTF8_GOT_SHORT"".
10907 "UTF8_GOT_OVERFLOW"
10909 The input sequence was malformed in that it is for a code
10910 point that is not representable in the number of bits
10911 available in an IV on the current platform.
10912 "UTF8_GOT_SHORT"
10914 The input sequence was malformed in that "curlen" is
10915 smaller than required for a complete sequence. In other
10916 words, the input is for a partial character sequence.
10917 "UTF8_GOT_SHORT" and "UTF8_GOT_NON_CONTINUATION" both
10919 indicate a too short sequence. The difference is that
10920 "UTF8_GOT_NON_CONTINUATION" indicates always that there is
10921 an error, while "UTF8_GOT_SHORT" means that an incomplete
10922 sequence was looked at. If no other flags are present, it
10923 means that the sequence was valid as far as it went.
10924 Depending on the application, this could mean one of three
10925 things:
10926 • The "curlen" length parameter passed in was too small,
10928 and the function was prevented from examining all the
10929 necessary bytes.
10930 • The buffer being looked at is based on reading data,
10932 and the data received so far stopped in the middle of a
10933 character, so that the next read will read the
10934 remainder of this character. (It is up to the caller
10935 to deal with the split bytes somehow.)
10936 • This is a real error, and the partial sequence is all
10938 we're going to get.
10939 "UTF8_GOT_SUPER"
10941 The input sequence was malformed in that it is for a non-
10942 Unicode code point; that is, one above the legal Unicode
10943 maximum. This bit is set only if the input "flags"
10944 parameter contains either the "UTF8_DISALLOW_SUPER" or the
10945 "UTF8_WARN_SUPER" flags.
10946 "UTF8_GOT_SURROGATE"
10948 The input sequence was malformed in that it is for a
10949 -Unicode UTF-16 surrogate code point. This bit is set only
10950 if the input "flags" parameter contains either the
10951 "UTF8_DISALLOW_SURROGATE" or the "UTF8_WARN_SURROGATE"
10952 flags.
10953 To do your own error handling, call this function with the
10955 "UTF8_CHECK_ONLY" flag to suppress any warnings, and then
10956 examine the *errors return.
10957 UV utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
10959 STRLEN *retlen,
10960 const U32 flags,
10961 U32 * errors)
10962 utf8n_to_uvchr_msgs
10964 NOTE: this function is experimental and may change or be
10965 removed without notice.
10966 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
10968 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"()
10969 rather than call this directly.
10970 This function is for code that needs to know what the precise
10972 malformation(s) are when an error is found, and wants the
10973 corresponding warning and/or error messages to be returned to
10974 the caller rather than be displayed. All messages that would
10975 have been displayed if all lexcial warnings are enabled will be
10976 returned.
10977 It is just like "utf8n_to_uvchr_error" but it takes an extra
10979 parameter placed after all the others, "msgs". If this
10980 parameter is 0, this function behaves identically to
10981 "utf8n_to_uvchr_error". Otherwise, "msgs" should be a pointer
10982 to an "AV *" variable, in which this function creates a new AV
10983 to contain any appropriate messages. The elements of the array
10984 are ordered so that the first message that would have been
10985 displayed is in the 0th element, and so on. Each element is a
10986 hash with three key-value pairs, as follows:
10987 "text"
10989 The text of the message as a "SVpv".
10990 "warn_categories"
10992 The warning category (or categories) packed into a "SVuv".
10993 "flag"
10995 A single flag bit associated with this message, in a
10996 "SVuv". The bit corresponds to some bit in the *errors
10997 return value, such as "UTF8_GOT_LONG".
10998 It's important to note that specifying this parameter as non-
11000 null will cause any warnings this function would otherwise
11001 generate to be suppressed, and instead be placed in *msgs. The
11002 caller can check the lexical warnings state (or not) when
11003 choosing what to do with the returned messages.
11004 If the flag "UTF8_CHECK_ONLY" is passed, no warnings are
11006 generated, and hence no AV is created.
11007 The caller, of course, is responsible for freeing any returned
11009 AV.
11010 UV utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
11012 STRLEN *retlen,
11013 const U32 flags,
11014 U32 * errors, AV ** msgs)
11015 UTF8SKIP
11017 returns the number of bytes a non-malformed UTF-8 encoded
11018 character whose first (perhaps only) byte is pointed to by "s".
11019 If there is a possibility of malformed input, use instead:
11021 ""UTF8_SAFE_SKIP"" if you know the maximum ending pointer in
11023 the buffer pointed to by "s"; or
11024 ""UTF8_CHK_SKIP"" if you don't know it.
11025 It is better to restructure your code so the end pointer is
11027 passed down so that you know what it actually is at the point
11028 of this call, but if that isn't possible, ""UTF8_CHK_SKIP"" can
11029 minimize the chance of accessing beyond the end of the input
11030 buffer.
11031 STRLEN UTF8SKIP(char* s)
11033 UTF8_CHK_SKIP
11035 This is a safer version of ""UTF8SKIP"", but still not as safe
11036 as ""UTF8_SAFE_SKIP"". This version doesn't blindly assume
11037 that the input string pointed to by "s" is well-formed, but
11038 verifies that there isn't a NUL terminating character before
11039 the expected end of the next character in "s". The length
11040 "UTF8_CHK_SKIP" returns stops just before any such NUL.
11041 Perl tends to add NULs, as an insurance policy, after the end
11043 of strings in SV's, so it is likely that using this macro will
11044 prevent inadvertent reading beyond the end of the input buffer,
11045 even if it is malformed UTF-8.
11046 This macro is intended to be used by XS modules where the
11048 inputs could be malformed, and it isn't feasible to restructure
11049 to use the safer ""UTF8_SAFE_SKIP"", for example when
11050 interfacing with a C library.
11051 STRLEN UTF8_CHK_SKIP(char* s)
11053 utf8_distance
11055 Returns the number of UTF-8 characters between the UTF-8
11056 pointers "a" and "b".
11057 WARNING: use only if you *know* that the pointers point inside
11059 the same UTF-8 buffer.
11060 IV utf8_distance(const U8 *a, const U8 *b)
11062 utf8_hop
11064 Return the UTF-8 pointer "s" displaced by "off" characters,
11065 either forward or backward.
11066 WARNING: do not use the following unless you *know* "off" is
11068 within the UTF-8 data pointed to by "s" *and* that on entry "s"
11069 is aligned on the first byte of character or just after the
11070 last byte of a character.
11071 U8* utf8_hop(const U8 *s, SSize_t off)
11073 utf8_hop_back
11075 Return the UTF-8 pointer "s" displaced by up to "off"
11076 characters, backward.
11077 "off" must be non-positive.
11079 "s" must be after or equal to "start".
11081 When moving backward it will not move before "start".
11083 Will not exceed this limit even if the string is not valid
11085 "UTF-8".
11086 U8* utf8_hop_back(const U8 *s, SSize_t off,
11088 const U8 *start)
11089 utf8_hop_forward
11091 Return the UTF-8 pointer "s" displaced by up to "off"
11092 characters, forward.
11093 "off" must be non-negative.
11095 "s" must be before or equal to "end".
11097 When moving forward it will not move beyond "end".
11099 Will not exceed this limit even if the string is not valid
11101 "UTF-8".
11102 U8* utf8_hop_forward(const U8 *s, SSize_t off,
11104 const U8 *end)
11105 utf8_hop_safe
11107 Return the UTF-8 pointer "s" displaced by up to "off"
11108 characters, either forward or backward.
11109 When moving backward it will not move before "start".
11111 When moving forward it will not move beyond "end".
11113 Will not exceed those limits even if the string is not valid
11115 "UTF-8".
11116 U8* utf8_hop_safe(const U8 *s, SSize_t off,
11118 const U8 *start, const U8 *end)
11119 UTF8_IS_INVARIANT
11121 Evaluates to 1 if the byte "c" represents the same character
11122 when encoded in UTF-8 as when not; otherwise evaluates to 0.
11123 UTF-8 invariant characters can be copied as-is when converting
11124 to/from UTF-8, saving time.
11125 In spite of the name, this macro gives the correct result if
11127 the input string from which "c" comes is not encoded in UTF-8.
11128 See "UVCHR_IS_INVARIANT" for checking if a UV is invariant.
11130 bool UTF8_IS_INVARIANT(char c)
11132 UTF8_IS_NONCHAR
11134 Evaluates to non-zero if the first few bytes of the string
11135 starting at "s" and looking no further than "e - 1" are well-
11136 formed UTF-8 that represents one of the Unicode non-character
11137 code points; otherwise it evaluates to 0. If non-zero, the
11138 value gives how many bytes starting at "s" comprise the code
11139 point's representation.
11140 bool UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
11142 UTF8_IS_SUPER
11144 Recall that Perl recognizes an extension to UTF-8 that can
11145 encode code points larger than the ones defined by Unicode,
11146 which are 0..0x10FFFF.
11147 This macro evaluates to non-zero if the first few bytes of the
11149 string starting at "s" and looking no further than "e - 1" are
11150 from this UTF-8 extension; otherwise it evaluates to 0. If
11151 non-zero, the value gives how many bytes starting at "s"
11152 comprise the code point's representation.
11153 0 is returned if the bytes are not well-formed extended UTF-8,
11155 or if they represent a code point that cannot fit in a UV on
11156 the current platform. Hence this macro can give different
11157 results when run on a 64-bit word machine than on one with a
11158 32-bit word size.
11159 Note that it is illegal to have code points that are larger
11161 than what can fit in an IV on the current machine.
11162 bool UTF8_IS_SUPER(const U8 *s, const U8 *e)
11164 UTF8_IS_SURROGATE
11166 Evaluates to non-zero if the first few bytes of the string
11167 starting at "s" and looking no further than "e - 1" are well-
11168 formed UTF-8 that represents one of the Unicode surrogate code
11169 points; otherwise it evaluates to 0. If non-zero, the value
11170 gives how many bytes starting at "s" comprise the code point's
11171 representation.
11172 bool UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
11174 utf8_length
11176 Returns the number of characters in the sequence of
11177 UTF-8-encoded bytes starting at "s" and ending at the byte just
11178 before "e". If <s> and <e> point to the same place, it returns
11179 0 with no warning raised.
11180 If "e < s" or if the scan would end up past "e", it raises a
11182 UTF8 warning and returns the number of valid characters.
11183 STRLEN utf8_length(const U8* s, const U8 *e)
11185 UTF8_MAXBYTES
11187 The maximum width of a single UTF-8 encoded character, in
11188 bytes.
11189 NOTE: Strictly speaking Perl's UTF-8 should not be called UTF-8
11191 since UTF-8 is an encoding of Unicode, and Unicode's upper
11192 limit, 0x10FFFF, can be expressed with 4 bytes. However, Perl
11193 thinks of UTF-8 as a way to encode non-negative integers in a
11194 binary format, even those above Unicode.
11195 UTF8_MAXBYTES_CASE
11197 The maximum number of UTF-8 bytes a single Unicode character
11198 can uppercase/lowercase/titlecase/fold into.
11199 UTF8_SAFE_SKIP
11201 returns 0 if "s >= e"; otherwise returns the number of bytes in
11202 the UTF-8 encoded character whose first byte is pointed to by
11203 "s". But it never returns beyond "e". On DEBUGGING builds, it
11204 asserts that "s <= e".
11205 STRLEN UTF8_SAFE_SKIP(char* s, char* e)
11207 UTF8_SKIP
11209 This is a synonym for ""UTF8SKIP""
11210 STRLEN UTF8_SKIP(char* s)
11212 utf8_to_bytes
11214 NOTE: this function is experimental and may change or be
11215 removed without notice.
11216 Converts a string "s" of length *lenp from UTF-8 into native
11218 byte encoding. Unlike "bytes_to_utf8", this over-writes the
11219 original string, and updates *lenp to contain the new length.
11220 Returns zero on failure (leaving "s" unchanged) setting *lenp
11221 to -1.
11222 Upon successful return, the number of variants in the string
11224 can be computed by having saved the value of *lenp before the
11225 call, and subtracting the after-call value of *lenp from it.
11226 If you need a copy of the string, see "bytes_from_utf8".
11228 U8* utf8_to_bytes(U8 *s, STRLEN *lenp)
11230 utf8_to_uvchr_buf
11232 Returns the native code point of the first character in the
11233 string "s" which is assumed to be in UTF-8 encoding; "send"
11234 points to 1 beyond the end of "s". *retlen will be set to the
11235 length, in bytes, of that character.
11236 If "s" does not point to a well-formed UTF-8 character and UTF8
11238 warnings are enabled, zero is returned and *retlen is set (if
11239 "retlen" isn't "NULL") to -1. If those warnings are off, the
11240 computed value, if well-defined (or the Unicode REPLACEMENT
11241 CHARACTER if not), is silently returned, and *retlen is set (if
11242 "retlen" isn't "NULL") so that ("s" + *retlen) is the next
11243 possible position in "s" that could begin a non-malformed
11244 character. See "utf8n_to_uvchr" for details on when the
11245 REPLACEMENT CHARACTER is returned.
11246 UV utf8_to_uvchr_buf(const U8 *s, const U8 *send,
11248 STRLEN *retlen)
11249 UVCHR_IS_INVARIANT
11251 Evaluates to 1 if the representation of code point "cp" is the
11252 same whether or not it is encoded in UTF-8; otherwise evaluates
11253 to 0. UTF-8 invariant characters can be copied as-is when
11254 converting to/from UTF-8, saving time. "cp" is Unicode if
11255 above 255; otherwise is platform-native.
11256 bool UVCHR_IS_INVARIANT(UV cp)
11258 UVCHR_SKIP
11260 returns the number of bytes required to represent the code
11261 point "cp" when encoded as UTF-8. "cp" is a native (ASCII or
11262 EBCDIC) code point if less than 255; a Unicode code point
11263 otherwise.
11264 STRLEN UVCHR_SKIP(UV cp)
11266 uvchr_to_utf8
11268 Adds the UTF-8 representation of the native code point "uv" to
11269 the end of the string "d"; "d" should have at least
11270 "UVCHR_SKIP(uv)+1" (up to "UTF8_MAXBYTES+1") free bytes
11271 available. The return value is the pointer to the byte after
11272 the end of the new character. In other words,
11273 d = uvchr_to_utf8(d, uv);
11275 is the recommended wide native character-aware way of saying
11277 *(d++) = uv;
11279 This function accepts any code point from 0.."IV_MAX" as input.
11281 "IV_MAX" is typically 0x7FFF_FFFF in a 32-bit word.
11282 It is possible to forbid or warn on non-Unicode code points, or
11284 those that may be problematic by using "uvchr_to_utf8_flags".
11285 U8* uvchr_to_utf8(U8 *d, UV uv)
11287 uvchr_to_utf8_flags
11289 Adds the UTF-8 representation of the native code point "uv" to
11290 the end of the string "d"; "d" should have at least
11291 "UVCHR_SKIP(uv)+1" (up to "UTF8_MAXBYTES+1") free bytes
11292 available. The return value is the pointer to the byte after
11293 the end of the new character. In other words,
11294 d = uvchr_to_utf8_flags(d, uv, flags);
11296 or, in most cases,
11298 d = uvchr_to_utf8_flags(d, uv, 0);
11300 This is the Unicode-aware way of saying
11302 *(d++) = uv;
11304 If "flags" is 0, this function accepts any code point from
11306 0.."IV_MAX" as input. "IV_MAX" is typically 0x7FFF_FFFF in a
11307 32-bit word.
11308 Specifying "flags" can further restrict what is allowed and not
11310 warned on, as follows:
11311 If "uv" is a Unicode surrogate code point and
11313 "UNICODE_WARN_SURROGATE" is set, the function will raise a
11314 warning, provided UTF8 warnings are enabled. If instead
11315 "UNICODE_DISALLOW_SURROGATE" is set, the function will fail and
11316 return NULL. If both flags are set, the function will both
11317 warn and return NULL.
11318 Similarly, the "UNICODE_WARN_NONCHAR" and
11320 "UNICODE_DISALLOW_NONCHAR" flags affect how the function
11321 handles a Unicode non-character.
11322 And likewise, the "UNICODE_WARN_SUPER" and
11324 "UNICODE_DISALLOW_SUPER" flags affect the handling of code
11325 points that are above the Unicode maximum of 0x10FFFF.
11326 Languages other than Perl may not be able to accept files that
11327 contain these.
11328 The flag "UNICODE_WARN_ILLEGAL_INTERCHANGE" selects all three
11330 of the above WARN flags; and
11331 "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE" selects all three
11332 DISALLOW flags. "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE"
11333 restricts the allowed inputs to the strict UTF-8 traditionally
11334 defined by Unicode. Similarly,
11335 "UNICODE_WARN_ILLEGAL_C9_INTERCHANGE" and
11336 "UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE" are shortcuts to
11337 select the above-Unicode and surrogate flags, but not the non-
11338 character ones, as defined in Unicode Corrigendum #9
11339 <https://www.unicode.org/versions/corrigendum9.html>. See
11340 "Noncharacter code points" in perlunicode.
11341 Extremely high code points were never specified in any
11343 standard, and require an extension to UTF-8 to express, which
11344 Perl does. It is likely that programs written in something
11345 other than Perl would not be able to read files that contain
11346 these; nor would Perl understand files written by something
11347 that uses a different extension. For these reasons, there is a
11348 separate set of flags that can warn and/or disallow these
11349 extremely high code points, even if other above-Unicode ones
11350 are accepted. They are the "UNICODE_WARN_PERL_EXTENDED" and
11351 "UNICODE_DISALLOW_PERL_EXTENDED" flags. For more information
11352 see ""UTF8_GOT_PERL_EXTENDED"". Of course
11353 "UNICODE_DISALLOW_SUPER" will treat all above-Unicode code
11354 points, including these, as malformations. (Note that the
11355 Unicode standard considers anything above 0x10FFFF to be
11356 illegal, but there are standards predating it that allow up to
11357 0x7FFF_FFFF (2**31 -1))
11358 A somewhat misleadingly named synonym for
11360 "UNICODE_WARN_PERL_EXTENDED" is retained for backward
11361 compatibility: "UNICODE_WARN_ABOVE_31_BIT". Similarly,
11362 "UNICODE_DISALLOW_ABOVE_31_BIT" is usable instead of the more
11363 accurately named "UNICODE_DISALLOW_PERL_EXTENDED". The names
11364 are misleading because on EBCDIC platforms,these flags can
11365 apply to code points that actually do fit in 31 bits. The new
11366 names accurately describe the situation in all cases.
11367 U8* uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
11369 uvchr_to_utf8_flags_msgs
11371 NOTE: this function is experimental and may change or be
11372 removed without notice.
11373 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
11375 CIRCUMSTANCES.
11376 Most code should use ""uvchr_to_utf8_flags"()" rather than call
11378 this directly.
11379 This function is for code that wants any warning and/or error
11381 messages to be returned to the caller rather than be displayed.
11382 All messages that would have been displayed if all lexical
11383 warnings are enabled will be returned.
11384 It is just like "uvchr_to_utf8_flags" but it takes an extra
11386 parameter placed after all the others, "msgs". If this
11387 parameter is 0, this function behaves identically to
11388 "uvchr_to_utf8_flags". Otherwise, "msgs" should be a pointer
11389 to an "HV *" variable, in which this function creates a new HV
11390 to contain any appropriate messages. The hash has three key-
11391 value pairs, as follows:
11392 "text"
11394 The text of the message as a "SVpv".
11395 "warn_categories"
11397 The warning category (or categories) packed into a "SVuv".
11398 "flag"
11400 A single flag bit associated with this message, in a
11401 "SVuv". The bit corresponds to some bit in the *errors
11402 return value, such as "UNICODE_GOT_SURROGATE".
11403 It's important to note that specifying this parameter as non-
11405 null will cause any warnings this function would otherwise
11406 generate to be suppressed, and instead be placed in *msgs. The
11407 caller can check the lexical warnings state (or not) when
11408 choosing what to do with the returned messages.
11409 The caller, of course, is responsible for freeing any returned
11411 HV.
11412 U8* uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags,
11414 HV ** msgs)
11415
11417 newXSproto
11418 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl
11419 prototypes to the subs.
11420 XS_APIVERSION_BOOTCHECK
11422 Macro to verify that the perl api version an XS module has been
11423 compiled against matches the api version of the perl
11424 interpreter it's being loaded into.
11425 XS_APIVERSION_BOOTCHECK;
11427 XS_VERSION
11429 The version identifier for an XS module. This is usually
11430 handled automatically by "ExtUtils::MakeMaker". See
11431 "XS_VERSION_BOOTCHECK".
11432 XS_VERSION_BOOTCHECK
11434 Macro to verify that a PM module's $VERSION variable matches
11435 the XS module's "XS_VERSION" variable. This is usually handled
11436 automatically by "xsubpp". See "The VERSIONCHECK: Keyword" in
11437 perlxs.
11438 XS_VERSION_BOOTCHECK;
11440
11442 In all these calls, the "U32 wn" parameters are warning category
11443 constants. You can see the ones currently available in "Category
11444 Hierarchy" in warnings, just capitalize all letters in the names and
11445 prefix them by "WARN_". So, for example, the category "void" used in a
11446 perl program becomes "WARN_VOID" when used in XS code and passed to one
11447 of the calls below.
11448 ckWARN Returns a boolean as to whether or not warnings are enabled for
11450 the warning category "w". If the category is by default
11451 enabled even if not within the scope of "use warnings", instead
11452 use the "ckWARN_d" macro.
11453 bool ckWARN(U32 w)
11455 ckWARN2 Like "ckWARN", but takes two warnings categories as input, and
11457 returns TRUE if either is enabled. If either category is by
11458 default enabled even if not within the scope of "use warnings",
11459 instead use the "ckWARN2_d" macro. The categories must be
11460 completely independent, one may not be subclassed from the
11461 other.
11462 bool ckWARN2(U32 w1, U32 w2)
11464 ckWARN3 Like "ckWARN2", but takes three warnings categories as input,
11466 and returns TRUE if any is enabled. If any of the categories
11467 is by default enabled even if not within the scope of
11468 "use warnings", instead use the "ckWARN3_d" macro. The
11469 categories must be completely independent, one may not be
11470 subclassed from any other.
11471 bool ckWARN3(U32 w1, U32 w2, U32 w3)
11473 ckWARN4 Like "ckWARN3", but takes four warnings categories as input,
11475 and returns TRUE if any is enabled. If any of the categories
11476 is by default enabled even if not within the scope of
11477 "use warnings", instead use the "ckWARN4_d" macro. The
11478 categories must be completely independent, one may not be
11479 subclassed from any other.
11480 bool ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
11482 ckWARN_d
11484 Like "ckWARN", but for use if and only if the warning category
11485 is by default enabled even if not within the scope of
11486 "use warnings".
11487 bool ckWARN_d(U32 w)
11489 ckWARN2_d
11491 Like "ckWARN2", but for use if and only if either warning
11492 category is by default enabled even if not within the scope of
11493 "use warnings".
11494 bool ckWARN2_d(U32 w1, U32 w2)
11496 ckWARN3_d
11498 Like "ckWARN3", but for use if and only if any of the warning
11499 categories is by default enabled even if not within the scope
11500 of "use warnings".
11501 bool ckWARN3_d(U32 w1, U32 w2, U32 w3)
11503 ckWARN4_d
11505 Like "ckWARN4", but for use if and only if any of the warning
11506 categories is by default enabled even if not within the scope
11507 of "use warnings".
11508 bool ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
11510 CLEAR_ERRSV
11512 Clear the contents of $@, setting it to the empty string.
11513 This replaces any read-only SV with a fresh SV and removes any
11515 magic.
11516 void CLEAR_ERRSV()
11518 croak This is an XS interface to Perl's "die" function.
11520 Take a sprintf-style format pattern and argument list. These
11522 are used to generate a string message. If the message does not
11523 end with a newline, then it will be extended with some
11524 indication of the current location in the code, as described
11525 for "mess_sv".
11526 The error message will be used as an exception, by default
11528 returning control to the nearest enclosing "eval", but subject
11529 to modification by a $SIG{__DIE__} handler. In any case, the
11530 "croak" function never returns normally.
11531 For historical reasons, if "pat" is null then the contents of
11533 "ERRSV" ($@) will be used as an error message or object instead
11534 of building an error message from arguments. If you want to
11535 throw a non-string object, or build an error message in an SV
11536 yourself, it is preferable to use the "croak_sv" function,
11537 which does not involve clobbering "ERRSV".
11538 void croak(const char* pat, ...)
11540 croak_no_modify
11542 Exactly equivalent to "Perl_croak(aTHX_ "%s", PL_no_modify)",
11543 but generates terser object code than using "Perl_croak". Less
11544 code used on exception code paths reduces CPU cache pressure.
11545 void croak_no_modify()
11547 croak_sv
11549 This is an XS interface to Perl's "die" function.
11550 "baseex" is the error message or object. If it is a reference,
11552 it will be used as-is. Otherwise it is used as a string, and
11553 if it does not end with a newline then it will be extended with
11554 some indication of the current location in the code, as
11555 described for "mess_sv".
11556 The error message or object will be used as an exception, by
11558 default returning control to the nearest enclosing "eval", but
11559 subject to modification by a $SIG{__DIE__} handler. In any
11560 case, the "croak_sv" function never returns normally.
11561 To die with a simple string message, the "croak" function may
11563 be more convenient.
11564 void croak_sv(SV *baseex)
11566 die Behaves the same as "croak", except for the return type. It
11568 should be used only where the "OP *" return type is required.
11569 The function never actually returns.
11570 OP* die(const char* pat, ...)
11572 die_sv Behaves the same as "croak_sv", except for the return type. It
11574 should be used only where the "OP *" return type is required.
11575 The function never actually returns.
11576 OP* die_sv(SV *baseex)
11578 ERRSV Returns the SV for $@, creating it if needed.
11580 SV * ERRSV
11582 my_setenv
11584 A wrapper for the C library setenv(3). Don't use the latter,
11585 as the perl version has desirable safeguards
11586 void my_setenv(const char* nam, const char* val)
11588 rsignal A wrapper for the C library signal(2). Don't use the latter,
11590 as the Perl version knows things that interact with the rest of
11591 the perl interpreter.
11592 Sighandler_t rsignal(int i, Sighandler_t t)
11594 SANE_ERRSV
11596 Clean up ERRSV so we can safely set it.
11597 This replaces any read-only SV with a fresh writable copy and
11599 removes any magic.
11600 void SANE_ERRSV()
11602 vcroak This is an XS interface to Perl's "die" function.
11604 "pat" and "args" are a sprintf-style format pattern and
11606 encapsulated argument list. These are used to generate a
11607 string message. If the message does not end with a newline,
11608 then it will be extended with some indication of the current
11609 location in the code, as described for "mess_sv".
11610 The error message will be used as an exception, by default
11612 returning control to the nearest enclosing "eval", but subject
11613 to modification by a $SIG{__DIE__} handler. In any case, the
11614 "croak" function never returns normally.
11615 For historical reasons, if "pat" is null then the contents of
11617 "ERRSV" ($@) will be used as an error message or object instead
11618 of building an error message from arguments. If you want to
11619 throw a non-string object, or build an error message in an SV
11620 yourself, it is preferable to use the "croak_sv" function,
11621 which does not involve clobbering "ERRSV".
11622 void vcroak(const char* pat, va_list* args)
11624 vwarn This is an XS interface to Perl's "warn" function.
11626 "pat" and "args" are a sprintf-style format pattern and
11628 encapsulated argument list. These are used to generate a
11629 string message. If the message does not end with a newline,
11630 then it will be extended with some indication of the current
11631 location in the code, as described for "mess_sv".
11632 The error message or object will by default be written to
11634 standard error, but this is subject to modification by a
11635 $SIG{__WARN__} handler.
11636 Unlike with "vcroak", "pat" is not permitted to be null.
11638 void vwarn(const char* pat, va_list* args)
11640 warn This is an XS interface to Perl's "warn" function.
11642 Take a sprintf-style format pattern and argument list. These
11644 are used to generate a string message. If the message does not
11645 end with a newline, then it will be extended with some
11646 indication of the current location in the code, as described
11647 for "mess_sv".
11648 The error message or object will by default be written to
11650 standard error, but this is subject to modification by a
11651 $SIG{__WARN__} handler.
11652 Unlike with "croak", "pat" is not permitted to be null.
11654 void warn(const char* pat, ...)
11656 warn_sv This is an XS interface to Perl's "warn" function.
11658 "baseex" is the error message or object. If it is a reference,
11660 it will be used as-is. Otherwise it is used as a string, and
11661 if it does not end with a newline then it will be extended with
11662 some indication of the current location in the code, as
11663 described for "mess_sv".
11664 The error message or object will by default be written to
11666 standard error, but this is subject to modification by a
11667 $SIG{__WARN__} handler.
11668 To warn with a simple string message, the "warn" function may
11670 be more convenient.
11671 void warn_sv(SV *baseex)
11673
11675 The following functions have been flagged as part of the public API,
11676 but are currently undocumented. Use them at your own risk, as the
11677 interfaces are subject to change. Functions that are not listed in
11678 this document are not intended for public use, and should NOT be used
11679 under any circumstances.
11680 If you feel you need to use one of these functions, first send email to
11682 perl5-porters@perl.org <mailto:perl5-porters@perl.org>. It may be that
11683 there is a good reason for the function not being documented, and it
11684 should be removed from this list; or it may just be that no one has
11685 gotten around to documenting it. In the latter case, you will be asked
11686 to submit a patch to document the function. Once your patch is
11687 accepted, it will indicate that the interface is stable (unless it is
11688 explicitly marked otherwise) and usable by you.
11689 CvDEPTH
11691 CvGV
11692 GetVars
11693 Gv_AMupdate
11694 PerlIO_close
11695 PerlIO_context_layers
11696 PerlIO_error
11697 PerlIO_fill
11698 PerlIO_flush
11699 PerlIO_get_bufsiz
11700 PerlIO_get_ptr
11701 PerlIO_read
11702 PerlIO_seek
11703 PerlIO_set_cnt
11704 PerlIO_setlinebuf
11705 PerlIO_stdout
11706 PerlIO_unread
11707 SvAMAGIC_off
11708 SvAMAGIC_on
11709 amagic_call
11710 amagic_deref_call
11711 any_dup
11712 atfork_lock
11713 atfork_unlock
11714 av_arylen_p
11715 av_iter_p
11716 block_gimme
11717 call_atexit
11718 call_list
11719 calloc
11720 cast_i32
11721 cast_iv
11722 cast_ulong
11723 cast_uv
11724 ck_warner
11725 ck_warner_d
11726 ckwarn
11727 ckwarn_d
11728 clear_defarray
11729 clone_params_del
11730 clone_params_new
11731 croak_nocontext
11732 csighandler
11733 csighandler1
11734 csighandler3
11735 cx_dump
11736 cx_dup
11737 cxinc
11738 deb
11739 deb_nocontext
11740 debop
11741 debprofdump
11742 debstack
11743 debstackptrs
11744 delimcpy
11745 despatch_signals
11746 die_nocontext
11747 dirp_dup
11748 do_aspawn
11749 do_close
11750 do_gv_dump
11751 do_gvgv_dump
11752 do_hv_dump
11753 do_join
11754 do_magic_dump
11755 do_op_dump
11756 do_open
11757 do_openn
11758 do_pmop_dump
11759 do_spawn
11760 do_spawn_nowait
11761 do_sprintf
11762 do_sv_dump
11763 doing_taint
11764 doref
11765 dounwind
11766 dowantarray
11767 dump_eval
11768 dump_form
11769 dump_indent
11770 dump_mstats
11771 dump_sub
11772 dump_vindent
11773 filter_del
11774 filter_read
11775 foldEQ_latin1
11776 form_nocontext
11777 fp_dup
11778 free_global_struct
11779 free_tmps
11780 get_context
11781 get_mstats
11782 get_op_descs
11783 get_op_names
11784 get_ppaddr
11785 get_vtbl
11786 gp_dup
11787 gp_free
11788 gp_ref
11789 gv_AVadd
11790 gv_HVadd
11791 gv_IOadd
11792 gv_SVadd
11793 gv_add_by_type
11794 gv_autoload4
11795 gv_autoload_pv
11796 gv_autoload_pvn
11797 gv_autoload_sv
11798 gv_check
11799 gv_dump
11800 gv_efullname3
11801 gv_efullname4
11802 gv_fetchfile
11803 gv_fetchfile_flags
11804 gv_fetchpv
11805 gv_fetchpvn_flags
11806 gv_fetchsv
11807 gv_fullname3
11808 gv_fullname4
11809 gv_handler
11810 gv_name_set
11811 he_dup
11812 hek_dup
11813 hv_common
11814 hv_common_key_len
11815 hv_delayfree_ent
11816 hv_eiter_p
11817 hv_eiter_set
11818 hv_free_ent
11819 hv_ksplit
11820 hv_name_set
11821 hv_placeholders_get
11822 hv_placeholders_set
11823 hv_rand_set
11824 hv_riter_p
11825 hv_riter_set
11826 ibcmp_utf8
11827 init_global_struct
11828 init_stacks
11829 init_tm
11830 is_lvalue_sub
11831 leave_scope
11832 load_module_nocontext
11833 magic_dump
11834 markstack_grow
11835 mess_nocontext
11836 mfree
11837 mg_dup
11838 mg_size
11839 mini_mktime
11840 moreswitches
11841 mro_get_from_name
11842 mro_set_mro
11843 mro_set_private_data
11844 my_atof
11845 my_chsize
11846 my_cxt_index
11847 my_cxt_init
11848 my_dirfd
11849 my_failure_exit
11850 my_fflush_all
11851 my_fork
11852 my_lstat
11853 my_pclose
11854 my_popen
11855 my_popen_list
11856 my_socketpair
11857 my_stat
11858 my_strftime
11859 newANONATTRSUB
11860 newANONHASH
11861 newANONLIST
11862 newANONSUB
11863 newATTRSUB
11864 newAVREF
11865 newCVREF
11866 newFORM
11867 newGVREF
11868 newGVgen
11869 newGVgen_flags
11870 newHVREF
11871 newHVhv
11872 newIO
11873 newMYSUB
11874 newPROG
11875 newRV
11876 newSUB
11877 newSVREF
11878 newSVpvf_nocontext
11879 newSVsv_flags
11880 new_stackinfo
11881 op_refcnt_lock
11882 op_refcnt_unlock
11883 parser_dup
11884 perl_alloc_using
11885 perl_clone_using
11886 perly_sighandler
11887 pmop_dump
11888 pop_scope
11889 pregcomp
11890 pregexec
11891 pregfree
11892 pregfree2
11893 ptr_table_fetch
11894 ptr_table_free
11895 ptr_table_new
11896 ptr_table_split
11897 ptr_table_store
11898 push_scope
11899 re_compile
11900 re_dup_guts
11901 reentrant_free
11902 reentrant_init
11903 reentrant_retry
11904 reentrant_size
11905 ref
11906 reg_named_buff_all
11907 reg_named_buff_exists
11908 reg_named_buff_fetch
11909 reg_named_buff_firstkey
11910 reg_named_buff_nextkey
11911 reg_named_buff_scalar
11912 regdump
11913 regdupe_internal
11914 regexec_flags
11915 regfree_internal
11916 reginitcolors
11917 regnext
11918 repeatcpy
11919 rsignal_state
11920 runops_debug
11921 runops_standard
11922 rvpv_dup
11923 safesyscalloc
11924 safesysfree
11925 safesysmalloc
11926 safesysrealloc
11927 save_I16
11928 save_I32
11929 save_I8
11930 save_adelete
11931 save_aelem
11932 save_aelem_flags
11933 save_alloc
11934 save_ary
11935 save_bool
11936 save_clearsv
11937 save_delete
11938 save_destructor
11939 save_destructor_x
11940 save_freeop
11941 save_freepv
11942 save_freesv
11943 save_generic_pvref
11944 save_generic_svref
11945 save_hdelete
11946 save_helem
11947 save_helem_flags
11948 save_hints
11949 save_hptr
11950 save_int
11951 save_item
11952 save_iv
11953 save_mortalizesv
11954 save_op
11955 save_padsv_and_mortalize
11956 save_pptr
11957 save_pushi32ptr
11958 save_pushptr
11959 save_pushptrptr
11960 save_re_context
11961 save_set_svflags
11962 save_shared_pvref
11963 save_sptr
11964 save_svref
11965 save_vptr
11966 savestack_grow
11967 savestack_grow_cnt
11968 scan_num
11969 scan_vstring
11970 seed
11971 set_context
11972 share_hek
11973 si_dup
11974 ss_dup
11975 stack_grow
11976 start_subparse
11977 str_to_version
11978 sv_2iv
11979 sv_2pv
11980 sv_2pvbyte_flags
11981 sv_2pvutf8_flags
11982 sv_2uv
11983 sv_catpvf_mg_nocontext
11984 sv_catpvf_nocontext
11985 sv_dup
11986 sv_dup_inc
11987 sv_peek
11988 sv_setpvf_mg_nocontext
11989 sv_setpvf_nocontext
11990 sys_init
11991 sys_init3
11992 sys_intern_clear
11993 sys_intern_dup
11994 sys_intern_init
11995 sys_term
11996 taint_env
11997 taint_proper
11998 unlnk
11999 unsharepvn
12000 vdeb
12001 vform
12002 vload_module
12003 vnewSVpvf
12004 vwarner
12005 warn_nocontext
12006 warner
12007 warner_nocontext
12008 whichsig
12009 whichsig_pv
12010 whichsig_pvn
12011 whichsig_sv
12012
12014 Until May 1997, this document was maintained by Jeff Okamoto
12015 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
12016 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
12018 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
12019 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
12020 Stephen McCamant, and Gurusamy Sarathy.
12021 API Listing originally by Dean Roehrich <roehrich@cray.com>.
12023 Updated to be autogenerated from comments in the source by Benjamin
12025 Stuhl.
12026
12028 config.h perlapio perlcall perlclib perlfilter perlguts perlintern
12029 perlmroapi perlxs perlxstut warnings
12030perl v5.32.1 2021-05-31 PERLAPI(1)