1PERLAPI(1) Perl Programmers Reference Guide PERLAPI(1)
2
6 perlapi - autogenerated documentation for the perl public API
7
9 This file contains the documentation of the perl public API generated
10 by embed.pl, specifically a listing of functions, macros, flags, and
11 variables that may be used by extension writers. At the end is a list
12 of functions which have yet to be documented. The interfaces of those
13 are subject to change without notice. Anything not listed here is not
14 part of the public API, and should not be used by extension writers at
15 all. For these reasons, blindly using functions listed in proto.h is
16 to be avoided when writing extensions.
17 In Perl, unlike C, a string of characters may generally contain
19 embedded "NUL" characters. Sometimes in the documentation a Perl
20 string is referred to as a "buffer" to distinguish it from a C string,
21 but sometimes they are both just referred to as strings.
22 Note that all Perl API global variables must be referenced with the
24 "PL_" prefix. Again, those not listed here are not to be used by
25 extension writers, and can be changed or removed without notice; same
26 with macros. Some macros are provided for compatibility with the
27 older, unadorned names, but this support may be disabled in a future
28 release.
29 Perl was originally written to handle US-ASCII only (that is characters
31 whose ordinal numbers are in the range 0 - 127). And documentation and
32 comments may still use the term ASCII, when sometimes in fact the
33 entire range from 0 - 255 is meant.
34 The non-ASCII characters below 256 can have various meanings, depending
36 on various things. (See, most notably, perllocale.) But usually the
37 whole range can be referred to as ISO-8859-1. Often, the term
38 "Latin-1" (or "Latin1") is used as an equivalent for ISO-8859-1. But
39 some people treat "Latin1" as referring just to the characters in the
40 range 128 through 255, or somethimes from 160 through 255. This
41 documentation uses "Latin1" and "Latin-1" to refer to all 256
42 characters.
43 Note that Perl can be compiled and run under either ASCII or EBCDIC
45 (See perlebcdic). Most of the documentation (and even comments in the
46 code) ignore the EBCDIC possibility. For almost all purposes the
47 differences are transparent. As an example, under EBCDIC, instead of
48 UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so whenever
49 this documentation refers to "utf8" (and variants of that name,
50 including in function names), it also (essentially transparently) means
51 "UTF-EBCDIC". But the ordinals of characters differ between ASCII,
52 EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may
53 occupy a different number of bytes than in UTF-8.
54 The listing below is alphabetical, case insensitive.
56
58 av_clear
59 Frees the all the elements of an array, leaving it empty. The
60 XS equivalent of "@array = ()". See also "av_undef".
61 Note that it is possible that the actions of a destructor
63 called directly or indirectly by freeing an element of the
64 array could cause the reference count of the array itself to be
65 reduced (e.g. by deleting an entry in the symbol table). So it
66 is a possibility that the AV could have been freed (or even
67 reallocated) on return from the call unless you hold a
68 reference to it.
69 void av_clear(AV *av)
71 av_create_and_push
73 NOTE: this function is experimental and may change or be
74 removed without notice.
75 Push an SV onto the end of the array, creating the array if
77 necessary. A small internal helper function to remove a
78 commonly duplicated idiom.
79 void av_create_and_push(AV **const avp,
81 SV *const val)
82 av_create_and_unshift_one
84 NOTE: this function is experimental and may change or be
85 removed without notice.
86 Unshifts an SV onto the beginning of the array, creating the
88 array if necessary. A small internal helper function to remove
89 a commonly duplicated idiom.
90 SV** av_create_and_unshift_one(AV **const avp,
92 SV *const val)
93 av_delete
95 Deletes the element indexed by "key" from the array, makes the
96 element mortal, and returns it. If "flags" equals "G_DISCARD",
97 the element is freed and NULL is returned. NULL is also
98 returned if "key" is out of range.
99 Perl equivalent: "splice(@myarray, $key, 1, undef)" (with the
101 "splice" in void context if "G_DISCARD" is present).
102 SV* av_delete(AV *av, SSize_t key, I32 flags)
104 av_exists
106 Returns true if the element indexed by "key" has been
107 initialized.
108 This relies on the fact that uninitialized array elements are
110 set to "NULL".
111 Perl equivalent: "exists($myarray[$key])".
113 bool av_exists(AV *av, SSize_t key)
115 av_extend
117 Pre-extend an array. The "key" is the index to which the array
118 should be extended.
119 void av_extend(AV *av, SSize_t key)
121 av_fetch
123 Returns the SV at the specified index in the array. The "key"
124 is the index. If lval is true, you are guaranteed to get a
125 real SV back (in case it wasn't real before), which you can
126 then modify. Check that the return value is non-null before
127 dereferencing it to a "SV*".
128 See "Understanding the Magic of Tied Hashes and Arrays" in
130 perlguts for more information on how to use this function on
131 tied arrays.
132 The rough perl equivalent is $myarray[$key].
134 SV** av_fetch(AV *av, SSize_t key, I32 lval)
136 AvFILL Same as "av_top_index()". Deprecated, use "av_top_index()"
138 instead.
139 int AvFILL(AV* av)
141 av_fill Set the highest index in the array to the given number,
143 equivalent to Perl's "$#array = $fill;".
144 The number of elements in the array will be "fill + 1" after
146 "av_fill()" returns. If the array was previously shorter, then
147 the additional elements appended are set to NULL. If the array
148 was longer, then the excess elements are freed.
149 "av_fill(av, -1)" is the same as "av_clear(av)".
150 void av_fill(AV *av, SSize_t fill)
152 av_len Same as "av_top_index". Note that, unlike what the name
154 implies, it returns the highest index in the array, so to get
155 the size of the array you need to use "av_len(av) + 1". This
156 is unlike "sv_len", which returns what you would expect.
157 SSize_t av_len(AV *av)
159 av_make Creates a new AV and populates it with a list of SVs. The SVs
161 are copied into the array, so they may be freed after the call
162 to "av_make". The new AV will have a reference count of 1.
163 Perl equivalent: "my @new_array = ($scalar1, $scalar2,
165 $scalar3...);"
166 AV* av_make(SSize_t size, SV **strp)
168 av_pop Removes one SV from the end of the array, reducing its size by
170 one and returning the SV (transferring control of one reference
171 count) to the caller. Returns &PL_sv_undef if the array is
172 empty.
173 Perl equivalent: "pop(@myarray);"
175 SV* av_pop(AV *av)
177 av_push Pushes an SV (transferring control of one reference count) onto
179 the end of the array. The array will grow automatically to
180 accommodate the addition.
181 Perl equivalent: "push @myarray, $val;".
183 void av_push(AV *av, SV *val)
185 av_shift
187 Removes one SV from the start of the array, reducing its size
188 by one and returning the SV (transferring control of one
189 reference count) to the caller. Returns &PL_sv_undef if the
190 array is empty.
191 Perl equivalent: "shift(@myarray);"
193 SV* av_shift(AV *av)
195 av_store
197 Stores an SV in an array. The array index is specified as
198 "key". The return value will be "NULL" if the operation failed
199 or if the value did not need to be actually stored within the
200 array (as in the case of tied arrays). Otherwise, it can be
201 dereferenced to get the "SV*" that was stored there (= "val")).
202 Note that the caller is responsible for suitably incrementing
204 the reference count of "val" before the call, and decrementing
205 it if the function returned "NULL".
206 Approximate Perl equivalent: "splice(@myarray, $key, 1, $val)".
208 See "Understanding the Magic of Tied Hashes and Arrays" in
210 perlguts for more information on how to use this function on
211 tied arrays.
212 SV** av_store(AV *av, SSize_t key, SV *val)
214 av_tindex
216 Same as "av_top_index()".
217 int av_tindex(AV* av)
219 av_top_index
221 Returns the highest index in the array. The number of elements
222 in the array is "av_top_index(av) + 1". Returns -1 if the
223 array is empty.
224 The Perl equivalent for this is $#myarray.
226 (A slightly shorter form is "av_tindex".)
228 SSize_t av_top_index(AV *av)
230 av_undef
232 Undefines the array. The XS equivalent of "undef(@array)".
233 As well as freeing all the elements of the array (like
235 "av_clear()"), this also frees the memory used by the av to
236 store its list of scalars.
237 See "av_clear" for a note about the array possibly being
239 invalid on return.
240 void av_undef(AV *av)
242 av_unshift
244 Unshift the given number of "undef" values onto the beginning
245 of the array. The array will grow automatically to accommodate
246 the addition.
247 Perl equivalent: "unshift @myarray, ((undef) x $num);"
249 void av_unshift(AV *av, SSize_t num)
251 get_av Returns the AV of the specified Perl global or package array
253 with the given name (so it won't work on lexical variables).
254 "flags" are passed to "gv_fetchpv". If "GV_ADD" is set and the
255 Perl variable does not exist then it will be created. If
256 "flags" is zero and the variable does not exist then NULL is
257 returned.
258 Perl equivalent: "@{"$name"}".
260 NOTE: the perl_ form of this function is deprecated.
262 AV* get_av(const char *name, I32 flags)
264 newAV Creates a new AV. The reference count is set to 1.
266 Perl equivalent: "my @array;".
268 AV* newAV()
270 sortsv In-place sort an array of SV pointers with the given comparison
272 routine.
273 Currently this always uses mergesort. See "sortsv_flags" for a
275 more flexible routine.
276 void sortsv(SV** array, size_t num_elts,
278 SVCOMPARE_t cmp)
279 sortsv_flags
281 In-place sort an array of SV pointers with the given comparison
282 routine, with various SORTf_* flag options.
283 void sortsv_flags(SV** array, size_t num_elts,
285 SVCOMPARE_t cmp, U32 flags)
286
288 call_argv
289 Performs a callback to the specified named and package-scoped
290 Perl subroutine with "argv" (a "NULL"-terminated array of
291 strings) as arguments. See perlcall.
292 Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
294 NOTE: the perl_ form of this function is deprecated.
296 I32 call_argv(const char* sub_name, I32 flags,
298 char** argv)
299 call_method
301 Performs a callback to the specified Perl method. The blessed
302 object must be on the stack. See perlcall.
303 NOTE: the perl_ form of this function is deprecated.
305 I32 call_method(const char* methname, I32 flags)
307 call_pv Performs a callback to the specified Perl sub. See perlcall.
309 NOTE: the perl_ form of this function is deprecated.
311 I32 call_pv(const char* sub_name, I32 flags)
313 call_sv Performs a callback to the Perl sub specified by the SV.
315 If neither the "G_METHOD" nor "G_METHOD_NAMED" flag is
317 supplied, the SV may be any of a CV, a GV, a reference to a CV,
318 a reference to a GV or "SvPV(sv)" will be used as the name of
319 the sub to call.
320 If the "G_METHOD" flag is supplied, the SV may be a reference
322 to a CV or "SvPV(sv)" will be used as the name of the method to
323 call.
324 If the "G_METHOD_NAMED" flag is supplied, "SvPV(sv)" will be
326 used as the name of the method to call.
327 Some other values are treated specially for internal use and
329 should not be depended on.
330 See perlcall.
332 NOTE: the perl_ form of this function is deprecated.
334 I32 call_sv(SV* sv, VOL I32 flags)
336 ENTER Opening bracket on a callback. See "LEAVE" and perlcall.
338 ENTER;
340 ENTER_with_name(name)
342 Same as "ENTER", but when debugging is enabled it also
343 associates the given literal string with the new scope.
344 ENTER_with_name(name);
346 eval_pv Tells Perl to "eval" the given string in scalar context and
348 return an SV* result.
349 NOTE: the perl_ form of this function is deprecated.
351 SV* eval_pv(const char* p, I32 croak_on_error)
353 eval_sv Tells Perl to "eval" the string in the SV. It supports the
355 same flags as "call_sv", with the obvious exception of
356 "G_EVAL". See perlcall.
357 NOTE: the perl_ form of this function is deprecated.
359 I32 eval_sv(SV* sv, I32 flags)
361 FREETMPS
363 Closing bracket for temporaries on a callback. See "SAVETMPS"
364 and perlcall.
365 FREETMPS;
367 LEAVE Closing bracket on a callback. See "ENTER" and perlcall.
369 LEAVE;
371 LEAVE_with_name(name)
373 Same as "LEAVE", but when debugging is enabled it first checks
374 that the scope has the given name. "name" must be a
375 "NUL"-terminated literal string.
376 LEAVE_with_name(name);
378 SAVETMPS
380 Opening bracket for temporaries on a callback. See "FREETMPS"
381 and perlcall.
382 SAVETMPS;
384
386 Perl uses "full" Unicode case mappings. This means that converting a
387 single character to another case may result in a sequence of more than
388 one character. For example, the uppercase of "ss" (LATIN SMALL LETTER
389 SHARP S) is the two character sequence "SS". This presents some
390 complications The lowercase of all characters in the range 0..255 is
391 a single character, and thus "toLOWER_L1" is furnished. But,
392 "toUPPER_L1" can't exist, as it couldn't return a valid result for all
393 legal inputs. Instead "toUPPER_uvchr" has an API that does allow every
394 possible legal result to be returned.) Likewise no other function that
395 is crippled by not being able to give the correct results for the full
396 range of possible inputs has been implemented here.
397 toFOLD Converts the specified character to foldcase. If the input is
399 anything but an ASCII uppercase character, that input character
400 itself is returned. Variant "toFOLD_A" is equivalent. (There
401 is no equivalent "to_FOLD_L1" for the full Latin1 range, as the
402 full generality of "toFOLD_uvchr" is needed there.)
403 U8 toFOLD(U8 ch)
405 toFOLD_utf8
407 This is like "toFOLD_utf8_safe", but doesn't have the "e"
408 parameter The function therefore can't check if it is reading
409 beyond the end of the string. Starting in Perl v5.30, it will
410 take the "e" parameter, becoming a synonym for
411 "toFOLD_utf8_safe". At that time every program that uses it
412 will have to be changed to successfully compile. In the
413 meantime, the first runtime call to "toFOLD_utf8" from each
414 call point in the program will raise a deprecation warning,
415 enabled by default. You can convert your program now to use
416 "toFOLD_utf8_safe", and avoid the warnings, and get an extra
417 measure of protection, or you can wait until v5.30, when you'll
418 be forced to add the "e" parameter.
419 UV toFOLD_utf8(U8* p, U8* s, STRLEN* lenp)
421 toFOLD_utf8_safe
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 The suffix "_safe" in the function's name indicates that it
435 will not attempt to read beyond "e - 1", provided that the
436 constraint "s < e" is true (this is asserted for in
437 "-DDEBUGGING" builds). If the UTF-8 for the input character is
438 malformed in some way, the program may croak, or the function
439 may return the REPLACEMENT CHARACTER, at the discretion of the
440 implementation, and subject to change in future releases.
441 UV toFOLD_utf8_safe(U8* p, U8* e, U8* s,
443 STRLEN* lenp)
444 toFOLD_uvchr
446 Converts the code point "cp" to its foldcase version, and
447 stores that in UTF-8 in "s", and its length in bytes in "lenp".
448 The code point is interpreted as native if less than 256;
449 otherwise as Unicode. Note that the buffer pointed to by "s"
450 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
451 foldcase version may be longer than the original character.
452 The first code point of the foldcased version is returned (but
454 note, as explained at the top of this section, that there may
455 be more).
456 UV toFOLD_uvchr(UV cp, U8* s, STRLEN* lenp)
458 toLOWER Converts the specified character to lowercase. If the input is
460 anything but an ASCII uppercase character, that input character
461 itself is returned. Variant "toLOWER_A" is equivalent.
462 U8 toLOWER(U8 ch)
464 toLOWER_L1
466 Converts the specified Latin1 character to lowercase. The
467 results are undefined if the input doesn't fit in a byte.
468 U8 toLOWER_L1(U8 ch)
470 toLOWER_LC
472 Converts the specified character to lowercase using the current
473 locale's rules, if possible; otherwise returns the input
474 character itself.
475 U8 toLOWER_LC(U8 ch)
477 toLOWER_utf8
479 This is like "toLOWER_utf8_safe", but doesn't have the "e"
480 parameter The function therefore can't check if it is reading
481 beyond the end of the string. Starting in Perl v5.30, it will
482 take the "e" parameter, becoming a synonym for
483 "toLOWER_utf8_safe". At that time every program that uses it
484 will have to be changed to successfully compile. In the
485 meantime, the first runtime call to "toLOWER_utf8" from each
486 call point in the program will raise a deprecation warning,
487 enabled by default. You can convert your program now to use
488 "toLOWER_utf8_safe", and avoid the warnings, and get an extra
489 measure of protection, or you can wait until v5.30, when you'll
490 be forced to add the "e" parameter.
491 UV toLOWER_utf8(U8* p, U8* s, STRLEN* lenp)
493 toLOWER_utf8_safe
495 Converts the first UTF-8 encoded character in the sequence
496 starting at "p" and extending no further than "e - 1" to its
497 lowercase version, and stores that in UTF-8 in "s", and its
498 length in bytes in "lenp". Note that the buffer pointed to by
499 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
500 lowercase version may be longer than the original character.
501 The first code point of the lowercased version is returned (but
503 note, as explained at the top of this section, that there may
504 be more).
505 The suffix "_safe" in the function's name indicates that it
507 will not attempt to read beyond "e - 1", provided that the
508 constraint "s < e" is true (this is asserted for in
509 "-DDEBUGGING" builds). If the UTF-8 for the input character is
510 malformed in some way, the program may croak, or the function
511 may return the REPLACEMENT CHARACTER, at the discretion of the
512 implementation, and subject to change in future releases.
513 UV toLOWER_utf8_safe(U8* p, U8* e, U8* s,
515 STRLEN* lenp)
516 toLOWER_uvchr
518 Converts the code point "cp" to its lowercase version, and
519 stores that in UTF-8 in "s", and its length in bytes in "lenp".
520 The code point is interpreted as native if less than 256;
521 otherwise as Unicode. Note that the buffer pointed to by "s"
522 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
523 lowercase version may be longer than the original character.
524 The first code point of the lowercased version is returned (but
526 note, as explained at the top of this section, that there may
527 be more).
528 UV toLOWER_uvchr(UV cp, U8* s, STRLEN* lenp)
530 toTITLE Converts the specified character to titlecase. If the input is
532 anything but an ASCII lowercase character, that input character
533 itself is returned. Variant "toTITLE_A" is equivalent. (There
534 is no "toTITLE_L1" for the full Latin1 range, as the full
535 generality of "toTITLE_uvchr" is needed there. Titlecase is
536 not a concept used in locale handling, so there is no
537 functionality for that.)
538 U8 toTITLE(U8 ch)
540 toTITLE_utf8
542 This is like "toLOWER_utf8_safe", but doesn't have the "e"
543 parameter The function therefore can't check if it is reading
544 beyond the end of the string. Starting in Perl v5.30, it will
545 take the "e" parameter, becoming a synonym for
546 "toTITLE_utf8_safe". At that time every program that uses it
547 will have to be changed to successfully compile. In the
548 meantime, the first runtime call to "toTITLE_utf8" from each
549 call point in the program will raise a deprecation warning,
550 enabled by default. You can convert your program now to use
551 "toTITLE_utf8_safe", and avoid the warnings, and get an extra
552 measure of protection, or you can wait until v5.30, when you'll
553 be forced to add the "e" parameter.
554 UV toTITLE_utf8(U8* p, U8* s, STRLEN* lenp)
556 toTITLE_utf8_safe
558 Converts the first UTF-8 encoded character in the sequence
559 starting at "p" and extending no further than "e - 1" to its
560 titlecase version, and stores that in UTF-8 in "s", and its
561 length in bytes in "lenp". Note that the buffer pointed to by
562 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
563 titlecase version may be longer than the original character.
564 The first code point of the titlecased version is returned (but
566 note, as explained at the top of this section, that there may
567 be more).
568 The suffix "_safe" in the function's name indicates that it
570 will not attempt to read beyond "e - 1", provided that the
571 constraint "s < e" is true (this is asserted for in
572 "-DDEBUGGING" builds). If the UTF-8 for the input character is
573 malformed in some way, the program may croak, or the function
574 may return the REPLACEMENT CHARACTER, at the discretion of the
575 implementation, and subject to change in future releases.
576 UV toTITLE_utf8_safe(U8* p, U8* e, U8* s,
578 STRLEN* lenp)
579 toTITLE_uvchr
581 Converts the code point "cp" to its titlecase version, and
582 stores that in UTF-8 in "s", and its length in bytes in "lenp".
583 The code point is interpreted as native if less than 256;
584 otherwise as Unicode. Note that the buffer pointed to by "s"
585 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
586 titlecase version may be longer than the original character.
587 The first code point of the titlecased version is returned (but
589 note, as explained at the top of this section, that there may
590 be more).
591 UV toTITLE_uvchr(UV cp, U8* s, STRLEN* lenp)
593 toUPPER Converts the specified character to uppercase. If the input is
595 anything but an ASCII lowercase character, that input character
596 itself is returned. Variant "toUPPER_A" is equivalent.
597 U8 toUPPER(U8 ch)
599 toUPPER_utf8
601 This is like "toUPPER_utf8_safe", but doesn't have the "e"
602 parameter The function therefore can't check if it is reading
603 beyond the end of the string. Starting in Perl v5.30, it will
604 take the "e" parameter, becoming a synonym for
605 "toUPPER_utf8_safe". At that time every program that uses it
606 will have to be changed to successfully compile. In the
607 meantime, the first runtime call to "toUPPER_utf8" from each
608 call point in the program will raise a deprecation warning,
609 enabled by default. You can convert your program now to use
610 "toUPPER_utf8_safe", and avoid the warnings, and get an extra
611 measure of protection, or you can wait until v5.30, when you'll
612 be forced to add the "e" parameter.
613 UV toUPPER_utf8(U8* p, U8* s, STRLEN* lenp)
615 toUPPER_utf8_safe
617 Converts the first UTF-8 encoded character in the sequence
618 starting at "p" and extending no further than "e - 1" to its
619 uppercase version, and stores that in UTF-8 in "s", and its
620 length in bytes in "lenp". Note that the buffer pointed to by
621 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
622 uppercase version may be longer than the original character.
623 The first code point of the uppercased version is returned (but
625 note, as explained at the top of this section, that there may
626 be more).
627 The suffix "_safe" in the function's name indicates that it
629 will not attempt to read beyond "e - 1", provided that the
630 constraint "s < e" is true (this is asserted for in
631 "-DDEBUGGING" builds). If the UTF-8 for the input character is
632 malformed in some way, the program may croak, or the function
633 may return the REPLACEMENT CHARACTER, at the discretion of the
634 implementation, and subject to change in future releases.
635 UV toUPPER_utf8_safe(U8* p, U8* e, U8* s,
637 STRLEN* lenp)
638 toUPPER_uvchr
640 Converts the code point "cp" to its uppercase version, and
641 stores that in UTF-8 in "s", and its length in bytes in "lenp".
642 The code point is interpreted as native if less than 256;
643 otherwise as Unicode. Note that the buffer pointed to by "s"
644 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
645 uppercase version may be longer than the original character.
646 The first code point of the uppercased version is returned (but
648 note, as explained at the top of this section, that there may
649 be more.)
650 UV toUPPER_uvchr(UV cp, U8* s, STRLEN* lenp)
652
654 This section is about functions (really macros) that classify
655 characters into types, such as punctuation versus alphabetic, etc.
656 Most of these are analogous to regular expression character classes.
657 (See "POSIX Character Classes" in perlrecharclass.) There are several
658 variants for each class. (Not all macros have all variants; each item
659 below lists the ones valid for it.) None are affected by "use bytes",
660 and only the ones with "LC" in the name are affected by the current
661 locale.
662 The base function, e.g., "isALPHA()", takes an octet (either a "char"
664 or a "U8") as input and returns a boolean as to whether or not the
665 character represented by that octet is (or on non-ASCII platforms,
666 corresponds to) an ASCII character in the named class based on
667 platform, Unicode, and Perl rules. If the input is a number that
668 doesn't fit in an octet, FALSE is returned.
669 Variant "isFOO_A" (e.g., "isALPHA_A()") is identical to the base
671 function with no suffix "_A". This variant is used to emphasize by its
672 name that only ASCII-range characters can return TRUE.
673 Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivalent) character
675 set onto the platform. That is, the code points that are ASCII are
676 unaffected, since ASCII is a subset of Latin-1. But the non-ASCII code
677 points are treated as if they are Latin-1 characters. For example,
678 "isWORDCHAR_L1()" will return true when called with the code point
679 0xDF, which is a word character in both ASCII and EBCDIC (though it
680 represents different characters in each).
681 Variant "isFOO_uvchr" is like the "isFOO_L1" variant, but accepts any
683 UV code point as input. If the code point is larger than 255, Unicode
684 rules are used to determine if it is in the character class. For
685 example, "isWORDCHAR_uvchr(0x100)" returns TRUE, since 0x100 is LATIN
686 CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.
687 Variant "isFOO_utf8_safe" is like "isFOO_uvchr", but is used for UTF-8
689 encoded strings. Each call classifies one character, even if the
690 string contains many. This variant takes two parameters. The first,
691 "p", is a pointer to the first byte of the character to be classified.
692 (Recall that it may take more than one byte to represent a character in
693 UTF-8 strings.) The second parameter, "e", points to anywhere in the
694 string beyond the first character, up to one byte past the end of the
695 entire string. The suffix "_safe" in the function's name indicates
696 that it will not attempt to read beyond "e - 1", provided that the
697 constraint "s < e" is true (this is asserted for in "-DDEBUGGING"
698 builds). If the UTF-8 for the input character is malformed in some
699 way, the program may croak, or the function may return FALSE, at the
700 discretion of the implementation, and subject to change in future
701 releases.
702 Variant "isFOO_utf8" is like "isFOO_utf8_safe", but takes just a single
704 parameter, "p", which has the same meaning as the corresponding
705 parameter does in "isFOO_utf8_safe". The function therefore can't
706 check if it is reading beyond the end of the string. Starting in Perl
707 v5.30, it will take a second parameter, becoming a synonym for
708 "isFOO_utf8_safe". At that time every program that uses it will have
709 to be changed to successfully compile. In the meantime, the first
710 runtime call to "isFOO_utf8" from each call point in the program will
711 raise a deprecation warning, enabled by default. You can convert your
712 program now to use "isFOO_utf8_safe", and avoid the warnings, and get
713 an extra measure of protection, or you can wait until v5.30, when
714 you'll be forced to add the "e" parameter.
715 Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but
717 the result is based on the current locale, which is what "LC" in the
718 name stands for. If Perl can determine that the current locale is a
719 UTF-8 locale, it uses the published Unicode rules; otherwise, it uses
720 the C library function that gives the named classification. For
721 example, "isDIGIT_LC()" when not in a UTF-8 locale returns the result
722 of calling "isdigit()". FALSE is always returned if the input won't
723 fit into an octet. On some platforms where the C library function is
724 known to be defective, Perl changes its result to follow the POSIX
725 standard's rules.
726 Variant "isFOO_LC_uvchr" is like "isFOO_LC", but is defined on any UV.
728 It returns the same as "isFOO_LC" for input code points less than 256,
729 and returns the hard-coded, not-affected-by-locale, Unicode results for
730 larger ones.
731 Variant "isFOO_LC_utf8_safe" is like "isFOO_LC_uvchr", but is used for
733 UTF-8 encoded strings. Each call classifies one character, even if the
734 string contains many. This variant takes two parameters. The first,
735 "p", is a pointer to the first byte of the character to be classified.
736 (Recall that it may take more than one byte to represent a character in
737 UTF-8 strings.) The second parameter, "e", points to anywhere in the
738 string beyond the first character, up to one byte past the end of the
739 entire string. The suffix "_safe" in the function's name indicates
740 that it will not attempt to read beyond "e - 1", provided that the
741 constraint "s < e" is true (this is asserted for in "-DDEBUGGING"
742 builds). If the UTF-8 for the input character is malformed in some
743 way, the program may croak, or the function may return FALSE, at the
744 discretion of the implementation, and subject to change in future
745 releases.
746 Variant "isFOO_LC_utf8" is like "isFOO_LC_utf8_safe", but takes just a
748 single parameter, "p", which has the same meaning as the corresponding
749 parameter does in "isFOO_LC_utf8_safe". The function therefore can't
750 check if it is reading beyond the end of the string. Starting in Perl
751 v5.30, it will take a second parameter, becoming a synonym for
752 "isFOO_LC_utf8_safe". At that time every program that uses it will
753 have to be changed to successfully compile. In the meantime, the first
754 runtime call to "isFOO_LC_utf8" from each call point in the program
755 will raise a deprecation warning, enabled by default. You can convert
756 your program now to use "isFOO_LC_utf8_safe", and avoid the warnings,
757 and get an extra measure of protection, or you can wait until v5.30,
758 when you'll be forced to add the "e" parameter.
759 isALPHA Returns a boolean indicating whether the specified character is
761 an alphabetic character, analogous to "m/[[:alpha:]]/". See
762 the top of this section for an explanation of variants
763 "isALPHA_A", "isALPHA_L1", "isALPHA_uvchr",
764 "isALPHA_utf8_safe", "isALPHA_LC", "isALPHA_LC_uvchr", and
765 "isALPHA_LC_utf8_safe".
766 bool isALPHA(char ch)
768 isALPHANUMERIC
770 Returns a boolean indicating whether the specified character is
771 a either an alphabetic character or decimal digit, analogous to
772 "m/[[:alnum:]]/". See the top of this section for an
773 explanation of variants "isALPHANUMERIC_A",
774 "isALPHANUMERIC_L1", "isALPHANUMERIC_uvchr",
775 "isALPHANUMERIC_utf8_safe", "isALPHANUMERIC_LC",
776 "isALPHANUMERIC_LC_uvchr", and "isALPHANUMERIC_LC_utf8_safe".
777 bool isALPHANUMERIC(char ch)
779 isASCII Returns a boolean indicating whether the specified character is
781 one of the 128 characters in the ASCII character set, analogous
782 to "m/[[:ascii:]]/". On non-ASCII platforms, it returns TRUE
783 iff this character corresponds to an ASCII character. Variants
784 "isASCII_A()" and "isASCII_L1()" are identical to "isASCII()".
785 See the top of this section for an explanation of variants
786 "isASCII_uvchr", "isASCII_utf8_safe", "isASCII_LC",
787 "isASCII_LC_uvchr", and "isASCII_LC_utf8_safe". Note, however,
788 that some platforms do not have the C library routine
789 "isascii()". In these cases, the variants whose names contain
790 "LC" are the same as the corresponding ones without.
791 Also note, that because all ASCII characters are UTF-8
793 invariant (meaning they have the exact same representation
794 (always a single byte) whether encoded in UTF-8 or not),
795 "isASCII" will give the correct results when called with any
796 byte in any string encoded or not in UTF-8. And similarly
797 "isASCII_utf8_safe" will work properly on any string encoded or
798 not in UTF-8.
799 bool isASCII(char ch)
801 isBLANK Returns a boolean indicating whether the specified character is
803 a character considered to be a blank, analogous to
804 "m/[[:blank:]]/". See the top of this section for an
805 explanation of variants "isBLANK_A", "isBLANK_L1",
806 "isBLANK_uvchr", "isBLANK_utf8_safe", "isBLANK_LC",
807 "isBLANK_LC_uvchr", and "isBLANK_LC_utf8_safe". Note, however,
808 that some platforms do not have the C library routine
809 "isblank()". In these cases, the variants whose names contain
810 "LC" are the same as the corresponding ones without.
811 bool isBLANK(char ch)
813 isCNTRL Returns a boolean indicating whether the specified character is
815 a control character, analogous to "m/[[:cntrl:]]/". See the
816 top of this section for an explanation of variants "isCNTRL_A",
817 "isCNTRL_L1", "isCNTRL_uvchr", "isCNTRL_utf8_safe",
818 "isCNTRL_LC", "isCNTRL_LC_uvchr", and "isCNTRL_LC_utf8_safe" On
819 EBCDIC platforms, you almost always want to use the
820 "isCNTRL_L1" variant.
821 bool isCNTRL(char ch)
823 isDIGIT Returns a boolean indicating whether the specified character is
825 a digit, analogous to "m/[[:digit:]]/". Variants "isDIGIT_A"
826 and "isDIGIT_L1" are identical to "isDIGIT". See the top of
827 this section for an explanation of variants "isDIGIT_uvchr",
828 "isDIGIT_utf8_safe", "isDIGIT_LC", "isDIGIT_LC_uvchr", and
829 "isDIGIT_LC_utf8_safe".
830 bool isDIGIT(char ch)
832 isGRAPH Returns a boolean indicating whether the specified character is
834 a graphic character, analogous to "m/[[:graph:]]/". See the
835 top of this section for an explanation of variants "isGRAPH_A",
836 "isGRAPH_L1", "isGRAPH_uvchr", "isGRAPH_utf8_safe",
837 "isGRAPH_LC", "isGRAPH_LC_uvchr", and "isGRAPH_LC_utf8_safe".
838 bool isGRAPH(char ch)
840 isIDCONT
842 Returns a boolean indicating whether the specified character
843 can be the second or succeeding character of an identifier.
844 This is very close to, but not quite the same as the official
845 Unicode property "XID_Continue". The difference is that this
846 returns true only if the input character also matches
847 "isWORDCHAR". See the top of this section for an explanation
848 of variants "isIDCONT_A", "isIDCONT_L1", "isIDCONT_uvchr",
849 "isIDCONT_utf8_safe", "isIDCONT_LC", "isIDCONT_LC_uvchr", and
850 "isIDCONT_LC_utf8_safe".
851 bool isIDCONT(char ch)
853 isIDFIRST
855 Returns a boolean indicating whether the specified character
856 can be the first character of an identifier. This is very
857 close to, but not quite the same as the official Unicode
858 property "XID_Start". The difference is that this returns true
859 only if the input character also matches "isWORDCHAR". See the
860 top of this section for an explanation of variants
861 "isIDFIRST_A", "isIDFIRST_L1", "isIDFIRST_uvchr",
862 "isIDFIRST_utf8_safe", "isIDFIRST_LC", "isIDFIRST_LC_uvchr",
863 and "isIDFIRST_LC_utf8_safe".
864 bool isIDFIRST(char ch)
866 isLOWER Returns a boolean indicating whether the specified character is
868 a lowercase character, analogous to "m/[[:lower:]]/". See the
869 top of this section for an explanation of variants "isLOWER_A",
870 "isLOWER_L1", "isLOWER_uvchr", "isLOWER_utf8_safe",
871 "isLOWER_LC", "isLOWER_LC_uvchr", and "isLOWER_LC_utf8_safe".
872 bool isLOWER(char ch)
874 isOCTAL Returns a boolean indicating whether the specified character is
876 an octal digit, [0-7]. The only two variants are "isOCTAL_A"
877 and "isOCTAL_L1"; each is identical to "isOCTAL".
878 bool isOCTAL(char ch)
880 isPRINT Returns a boolean indicating whether the specified character is
882 a printable character, analogous to "m/[[:print:]]/". See the
883 top of this section for an explanation of variants "isPRINT_A",
884 "isPRINT_L1", "isPRINT_uvchr", "isPRINT_utf8_safe",
885 "isPRINT_LC", "isPRINT_LC_uvchr", and "isPRINT_LC_utf8_safe".
886 bool isPRINT(char ch)
888 isPSXSPC
890 (short for Posix Space) Starting in 5.18, this is identical in
891 all its forms to the corresponding "isSPACE()" macros. The
892 locale forms of this macro are identical to their corresponding
893 "isSPACE()" forms in all Perl releases. In releases prior to
894 5.18, the non-locale forms differ from their "isSPACE()" forms
895 only in that the "isSPACE()" forms don't match a Vertical Tab,
896 and the "isPSXSPC()" forms do. Otherwise they are identical.
897 Thus this macro is analogous to what "m/[[:space:]]/" matches
898 in a regular expression. See the top of this section for an
899 explanation of variants "isPSXSPC_A", "isPSXSPC_L1",
900 "isPSXSPC_uvchr", "isPSXSPC_utf8_safe", "isPSXSPC_LC",
901 "isPSXSPC_LC_uvchr", and "isPSXSPC_LC_utf8_safe".
902 bool isPSXSPC(char ch)
904 isPUNCT Returns a boolean indicating whether the specified character is
906 a punctuation character, analogous to "m/[[:punct:]]/". Note
907 that the definition of what is punctuation isn't as
908 straightforward as one might desire. See "POSIX Character
909 Classes" in perlrecharclass for details. See the top of this
910 section for an explanation of variants "isPUNCT_A",
911 "isPUNCT_L1", "isPUNCT_uvchr", "isPUNCT_utf8_safe",
912 "isPUNCT_LC", "isPUNCT_LC_uvchr", and "isPUNCT_LC_utf8_safe".
913 bool isPUNCT(char ch)
915 isSPACE Returns a boolean indicating whether the specified character is
917 a whitespace character. This is analogous to what "m/\s/"
918 matches in a regular expression. Starting in Perl 5.18 this
919 also matches what "m/[[:space:]]/" does. Prior to 5.18, only
920 the locale forms of this macro (the ones with "LC" in their
921 names) matched precisely what "m/[[:space:]]/" does. In those
922 releases, the only difference, in the non-locale variants, was
923 that "isSPACE()" did not match a vertical tab. (See "isPSXSPC"
924 for a macro that matches a vertical tab in all releases.) See
925 the top of this section for an explanation of variants
926 "isSPACE_A", "isSPACE_L1", "isSPACE_uvchr",
927 "isSPACE_utf8_safe", "isSPACE_LC", "isSPACE_LC_uvchr", and
928 "isSPACE_LC_utf8_safe".
929 bool isSPACE(char ch)
931 isUPPER Returns a boolean indicating whether the specified character is
933 an uppercase character, analogous to "m/[[:upper:]]/". See the
934 top of this section for an explanation of variants "isUPPER_A",
935 "isUPPER_L1", "isUPPER_uvchr", "isUPPER_utf8_safe",
936 "isUPPER_LC", "isUPPER_LC_uvchr", and "isUPPER_LC_utf8_safe".
937 bool isUPPER(char ch)
939 isWORDCHAR
941 Returns a boolean indicating whether the specified character is
942 a character that is a word character, analogous to what "m/\w/"
943 and "m/[[:word:]]/" match in a regular expression. A word
944 character is an alphabetic character, a decimal digit, a
945 connecting punctuation character (such as an underscore), or a
946 "mark" character that attaches to one of those (like some sort
947 of accent). "isALNUM()" is a synonym provided for backward
948 compatibility, even though a word character includes more than
949 the standard C language meaning of alphanumeric. See the top
950 of this section for an explanation of variants "isWORDCHAR_A",
951 "isWORDCHAR_L1", "isWORDCHAR_uvchr", and
952 "isWORDCHAR_utf8_safe". "isWORDCHAR_LC",
953 "isWORDCHAR_LC_uvchr", and "isWORDCHAR_LC_utf8_safe" are also
954 as described there, but additionally include the platform's
955 native underscore.
956 bool isWORDCHAR(char ch)
958 isXDIGIT
960 Returns a boolean indicating whether the specified character is
961 a hexadecimal digit. In the ASCII range these are
962 "[0-9A-Fa-f]". Variants "isXDIGIT_A()" and "isXDIGIT_L1()" are
963 identical to "isXDIGIT()". See the top of this section for an
964 explanation of variants "isXDIGIT_uvchr", "isXDIGIT_utf8_safe",
965 "isXDIGIT_LC", "isXDIGIT_LC_uvchr", and
966 "isXDIGIT_LC_utf8_safe".
967 bool isXDIGIT(char ch)
969
971 perl_clone
972 Create and return a new interpreter by cloning the current one.
973 "perl_clone" takes these flags as parameters:
975 "CLONEf_COPY_STACKS" - is used to, well, copy the stacks also,
977 without it we only clone the data and zero the stacks, with it
978 we copy the stacks and the new perl interpreter is ready to run
979 at the exact same point as the previous one. The pseudo-fork
980 code uses "COPY_STACKS" while the threads->create doesn't.
981 "CLONEf_KEEP_PTR_TABLE" - "perl_clone" keeps a ptr_table with
983 the pointer of the old variable as a key and the new variable
984 as a value, this allows it to check if something has been
985 cloned and not clone it again but rather just use the value and
986 increase the refcount. If "KEEP_PTR_TABLE" is not set then
987 "perl_clone" will kill the ptr_table using the function
988 "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;", reason to
989 keep it around is if you want to dup some of your own variable
990 who are outside the graph perl scans, an example of this code
991 is in threads.xs create.
992 "CLONEf_CLONE_HOST" - This is a win32 thing, it is ignored on
994 unix, it tells perls win32host code (which is c++) to clone
995 itself, this is needed on win32 if you want to run two threads
996 at the same time, if you just want to do some stuff in a
997 separate perl interpreter and then throw it away and return to
998 the original one, you don't need to do anything.
999 PerlInterpreter* perl_clone(
1001 PerlInterpreter *proto_perl,
1002 UV flags
1003 )
1004
1006 BhkDISABLE
1007 NOTE: this function is experimental and may change or be
1008 removed without notice.
1009 Temporarily disable an entry in this BHK structure, by clearing
1011 the appropriate flag. "which" is a preprocessor token
1012 indicating which entry to disable.
1013 void BhkDISABLE(BHK *hk, which)
1015 BhkENABLE
1017 NOTE: this function is experimental and may change or be
1018 removed without notice.
1019 Re-enable an entry in this BHK structure, by setting the
1021 appropriate flag. "which" is a preprocessor token indicating
1022 which entry to enable. This will assert (under -DDEBUGGING) if
1023 the entry doesn't contain a valid pointer.
1024 void BhkENABLE(BHK *hk, which)
1026 BhkENTRY_set
1028 NOTE: this function is experimental and may change or be
1029 removed without notice.
1030 Set an entry in the BHK structure, and set the flags to
1032 indicate it is valid. "which" is a preprocessing token
1033 indicating which entry to set. The type of "ptr" depends on
1034 the entry.
1035 void BhkENTRY_set(BHK *hk, which, void *ptr)
1037 blockhook_register
1039 NOTE: this function is experimental and may change or be
1040 removed without notice.
1041 Register a set of hooks to be called when the Perl lexical
1043 scope changes at compile time. See "Compile-time scope hooks"
1044 in perlguts.
1045 NOTE: this function must be explicitly called as
1047 Perl_blockhook_register with an aTHX_ parameter.
1048 void Perl_blockhook_register(pTHX_ BHK *hk)
1050
1052 cophh_2hv
1053 NOTE: this function is experimental and may change or be
1054 removed without notice.
1055 Generates and returns a standard Perl hash representing the
1057 full set of key/value pairs in the cop hints hash "cophh".
1058 "flags" is currently unused and must be zero.
1059 HV * cophh_2hv(const COPHH *cophh, U32 flags)
1061 cophh_copy
1063 NOTE: this function is experimental and may change or be
1064 removed without notice.
1065 Make and return a complete copy of the cop hints hash "cophh".
1067 COPHH * cophh_copy(COPHH *cophh)
1069 cophh_delete_pv
1071 NOTE: this function is experimental and may change or be
1072 removed without notice.
1073 Like "cophh_delete_pvn", but takes a nul-terminated string
1075 instead of a string/length pair.
1076 COPHH * cophh_delete_pv(const COPHH *cophh,
1078 const char *key, U32 hash,
1079 U32 flags)
1080 cophh_delete_pvn
1082 NOTE: this function is experimental and may change or be
1083 removed without notice.
1084 Delete a key and its associated value from the cop hints hash
1086 "cophh", and returns the modified hash. The returned hash
1087 pointer is in general not the same as the hash pointer that was
1088 passed in. The input hash is consumed by the function, and the
1089 pointer to it must not be subsequently used. Use "cophh_copy"
1090 if you need both hashes.
1091 The key is specified by "keypv" and "keylen". If "flags" has
1093 the "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1094 UTF-8, otherwise they are interpreted as Latin-1. "hash" is a
1095 precomputed hash of the key string, or zero if it has not been
1096 precomputed.
1097 COPHH * cophh_delete_pvn(COPHH *cophh,
1099 const char *keypv,
1100 STRLEN keylen, U32 hash,
1101 U32 flags)
1102 cophh_delete_pvs
1104 NOTE: this function is experimental and may change or be
1105 removed without notice.
1106 Like "cophh_delete_pvn", but takes a "NUL"-terminated literal
1108 string instead of a string/length pair, and no precomputed
1109 hash.
1110 COPHH * cophh_delete_pvs(const COPHH *cophh,
1112 const char *key, U32 flags)
1113 cophh_delete_sv
1115 NOTE: this function is experimental and may change or be
1116 removed without notice.
1117 Like "cophh_delete_pvn", but takes a Perl scalar instead of a
1119 string/length pair.
1120 COPHH * cophh_delete_sv(const COPHH *cophh, SV *key,
1122 U32 hash, U32 flags)
1123 cophh_fetch_pv
1125 NOTE: this function is experimental and may change or be
1126 removed without notice.
1127 Like "cophh_fetch_pvn", but takes a nul-terminated string
1129 instead of a string/length pair.
1130 SV * cophh_fetch_pv(const COPHH *cophh,
1132 const char *key, U32 hash,
1133 U32 flags)
1134 cophh_fetch_pvn
1136 NOTE: this function is experimental and may change or be
1137 removed without notice.
1138 Look up the entry in the cop hints hash "cophh" with the key
1140 specified by "keypv" and "keylen". If "flags" has the
1141 "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1142 UTF-8, otherwise they are interpreted as Latin-1. "hash" is a
1143 precomputed hash of the key string, or zero if it has not been
1144 precomputed. Returns a mortal scalar copy of the value
1145 associated with the key, or &PL_sv_placeholder if there is no
1146 value associated with the key.
1147 SV * cophh_fetch_pvn(const COPHH *cophh,
1149 const char *keypv,
1150 STRLEN keylen, U32 hash,
1151 U32 flags)
1152 cophh_fetch_pvs
1154 NOTE: this function is experimental and may change or be
1155 removed without notice.
1156 Like "cophh_fetch_pvn", but takes a "NUL"-terminated literal
1158 string instead of a string/length pair, and no precomputed
1159 hash.
1160 SV * cophh_fetch_pvs(const COPHH *cophh,
1162 const char *key, U32 flags)
1163 cophh_fetch_sv
1165 NOTE: this function is experimental and may change or be
1166 removed without notice.
1167 Like "cophh_fetch_pvn", but takes a Perl scalar instead of a
1169 string/length pair.
1170 SV * cophh_fetch_sv(const COPHH *cophh, SV *key,
1172 U32 hash, U32 flags)
1173 cophh_free
1175 NOTE: this function is experimental and may change or be
1176 removed without notice.
1177 Discard the cop hints hash "cophh", freeing all resources
1179 associated with it.
1180 void cophh_free(COPHH *cophh)
1182 cophh_new_empty
1184 NOTE: this function is experimental and may change or be
1185 removed without notice.
1186 Generate and return a fresh cop hints hash containing no
1188 entries.
1189 COPHH * cophh_new_empty()
1191 cophh_store_pv
1193 NOTE: this function is experimental and may change or be
1194 removed without notice.
1195 Like "cophh_store_pvn", but takes a nul-terminated string
1197 instead of a string/length pair.
1198 COPHH * cophh_store_pv(const COPHH *cophh,
1200 const char *key, U32 hash,
1201 SV *value, U32 flags)
1202 cophh_store_pvn
1204 NOTE: this function is experimental and may change or be
1205 removed without notice.
1206 Stores a value, associated with a key, in the cop hints hash
1208 "cophh", and returns the modified hash. The returned hash
1209 pointer is in general not the same as the hash pointer that was
1210 passed in. The input hash is consumed by the function, and the
1211 pointer to it must not be subsequently used. Use "cophh_copy"
1212 if you need both hashes.
1213 The key is specified by "keypv" and "keylen". If "flags" has
1215 the "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1216 UTF-8, otherwise they are interpreted as Latin-1. "hash" is a
1217 precomputed hash of the key string, or zero if it has not been
1218 precomputed.
1219 "value" is the scalar value to store for this key. "value" is
1221 copied by this function, which thus does not take ownership of
1222 any reference to it, and later changes to the scalar will not
1223 be reflected in the value visible in the cop hints hash.
1224 Complex types of scalar will not be stored with referential
1225 integrity, but will be coerced to strings.
1226 COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
1228 STRLEN keylen, U32 hash,
1229 SV *value, U32 flags)
1230 cophh_store_pvs
1232 NOTE: this function is experimental and may change or be
1233 removed without notice.
1234 Like "cophh_store_pvn", but takes a "NUL"-terminated literal
1236 string instead of a string/length pair, and no precomputed
1237 hash.
1238 COPHH * cophh_store_pvs(const COPHH *cophh,
1240 const char *key, SV *value,
1241 U32 flags)
1242 cophh_store_sv
1244 NOTE: this function is experimental and may change or be
1245 removed without notice.
1246 Like "cophh_store_pvn", but takes a Perl scalar instead of a
1248 string/length pair.
1249 COPHH * cophh_store_sv(const COPHH *cophh, SV *key,
1251 U32 hash, SV *value, U32 flags)
1252
1254 cop_hints_2hv
1255 Generates and returns a standard Perl hash representing the
1256 full set of hint entries in the cop "cop". "flags" is
1257 currently unused and must be zero.
1258 HV * cop_hints_2hv(const COP *cop, U32 flags)
1260 cop_hints_fetch_pv
1262 Like "cop_hints_fetch_pvn", but takes a nul-terminated string
1263 instead of a string/length pair.
1264 SV * cop_hints_fetch_pv(const COP *cop,
1266 const char *key, U32 hash,
1267 U32 flags)
1268 cop_hints_fetch_pvn
1270 Look up the hint entry in the cop "cop" with the key specified
1271 by "keypv" and "keylen". If "flags" has the "COPHH_KEY_UTF8"
1272 bit set, the key octets are interpreted as UTF-8, otherwise
1273 they are interpreted as Latin-1. "hash" is a precomputed hash
1274 of the key string, or zero if it has not been precomputed.
1275 Returns a mortal scalar copy of the value associated with the
1276 key, or &PL_sv_placeholder if there is no value associated with
1277 the key.
1278 SV * cop_hints_fetch_pvn(const COP *cop,
1280 const char *keypv,
1281 STRLEN keylen, U32 hash,
1282 U32 flags)
1283 cop_hints_fetch_pvs
1285 Like "cop_hints_fetch_pvn", but takes a "NUL"-terminated
1286 literal string instead of a string/length pair, and no
1287 precomputed hash.
1288 SV * cop_hints_fetch_pvs(const COP *cop,
1290 const char *key, U32 flags)
1291 cop_hints_fetch_sv
1293 Like "cop_hints_fetch_pvn", but takes a Perl scalar instead of
1294 a string/length pair.
1295 SV * cop_hints_fetch_sv(const COP *cop, SV *key,
1297 U32 hash, U32 flags)
1298
1300 custom_op_register
1301 Register a custom op. See "Custom Operators" in perlguts.
1302 NOTE: this function must be explicitly called as
1304 Perl_custom_op_register with an aTHX_ parameter.
1305 void Perl_custom_op_register(pTHX_
1307 Perl_ppaddr_t ppaddr,
1308 const XOP *xop)
1309 custom_op_xop
1311 Return the XOP structure for a given custom op. This macro
1312 should be considered internal to "OP_NAME" and the other access
1313 macros: use them instead. This macro does call a function.
1314 Prior to 5.19.6, this was implemented as a function.
1315 NOTE: this function must be explicitly called as
1317 Perl_custom_op_xop with an aTHX_ parameter.
1318 const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
1320 XopDISABLE
1322 Temporarily disable a member of the XOP, by clearing the
1323 appropriate flag.
1324 void XopDISABLE(XOP *xop, which)
1326 XopENABLE
1328 Reenable a member of the XOP which has been disabled.
1329 void XopENABLE(XOP *xop, which)
1331 XopENTRY
1333 Return a member of the XOP structure. "which" is a cpp token
1334 indicating which entry to return. If the member is not set
1335 this will return a default value. The return type depends on
1336 "which". This macro evaluates its arguments more than once.
1337 If you are using "Perl_custom_op_xop" to retreive a "XOP *"
1338 from a "OP *", use the more efficient "XopENTRYCUSTOM" instead.
1339 XopENTRY(XOP *xop, which)
1341 XopENTRYCUSTOM
1343 Exactly like "XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o),
1344 which)" but more efficient. The "which" parameter is identical
1345 to "XopENTRY".
1346 XopENTRYCUSTOM(const OP *o, which)
1348 XopENTRY_set
1350 Set a member of the XOP structure. "which" is a cpp token
1351 indicating which entry to set. See "Custom Operators" in
1352 perlguts for details about the available members and how they
1353 are used. This macro evaluates its argument more than once.
1354 void XopENTRY_set(XOP *xop, which, value)
1356 XopFLAGS
1358 Return the XOP's flags.
1359 U32 XopFLAGS(XOP *xop)
1361
1363 This section documents functions to manipulate CVs which are code-
1364 values, or subroutines. For more information, see perlguts.
1365 caller_cx
1367 The XSUB-writer's equivalent of caller(). The returned
1368 "PERL_CONTEXT" structure can be interrogated to find all the
1369 information returned to Perl by "caller". Note that XSUBs
1370 don't get a stack frame, so "caller_cx(0, NULL)" will return
1371 information for the immediately-surrounding Perl code.
1372 This function skips over the automatic calls to &DB::sub made
1374 on the behalf of the debugger. If the stack frame requested
1375 was a sub called by "DB::sub", the return value will be the
1376 frame for the call to "DB::sub", since that has the correct
1377 line number/etc. for the call site. If dbcxp is non-"NULL", it
1378 will be set to a pointer to the frame for the sub call itself.
1379 const PERL_CONTEXT * caller_cx(
1381 I32 level,
1382 const PERL_CONTEXT **dbcxp
1383 )
1384 CvSTASH Returns the stash of the CV. A stash is the symbol table hash,
1386 containing the package-scoped variables in the package where
1387 the subroutine was defined. For more information, see
1388 perlguts.
1389 This also has a special use with XS AUTOLOAD subs. See
1391 "Autoloading with XSUBs" in perlguts.
1392 HV* CvSTASH(CV* cv)
1394 find_runcv
1396 Locate the CV corresponding to the currently executing sub or
1397 eval. If "db_seqp" is non_null, skip CVs that are in the DB
1398 package and populate *db_seqp with the cop sequence number at
1399 the point that the DB:: code was entered. (This allows
1400 debuggers to eval in the scope of the breakpoint rather than in
1401 the scope of the debugger itself.)
1402 CV* find_runcv(U32 *db_seqp)
1404 get_cv Uses "strlen" to get the length of "name", then calls
1406 "get_cvn_flags".
1407 NOTE: the perl_ form of this function is deprecated.
1409 CV* get_cv(const char* name, I32 flags)
1411 get_cvn_flags
1413 Returns the CV of the specified Perl subroutine. "flags" are
1414 passed to "gv_fetchpvn_flags". If "GV_ADD" is set and the Perl
1415 subroutine does not exist then it will be declared (which has
1416 the same effect as saying "sub name;"). If "GV_ADD" is not set
1417 and the subroutine does not exist then NULL is returned.
1418 NOTE: the perl_ form of this function is deprecated.
1420 CV* get_cvn_flags(const char* name, STRLEN len,
1422 I32 flags)
1423
1425 ax Variable which is setup by "xsubpp" to indicate the stack base
1426 offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros.
1427 The "dMARK" macro must be called prior to setup the "MARK"
1428 variable.
1429 I32 ax
1431 CLASS Variable which is setup by "xsubpp" to indicate the class name
1433 for a C++ XS constructor. This is always a "char*". See
1434 "THIS".
1435 char* CLASS
1437 dAX Sets up the "ax" variable. This is usually handled
1439 automatically by "xsubpp" by calling "dXSARGS".
1440 dAX;
1442 dAXMARK Sets up the "ax" variable and stack marker variable "mark".
1444 This is usually handled automatically by "xsubpp" by calling
1445 "dXSARGS".
1446 dAXMARK;
1448 dITEMS Sets up the "items" variable. This is usually handled
1450 automatically by "xsubpp" by calling "dXSARGS".
1451 dITEMS;
1453 dUNDERBAR
1455 Sets up any variable needed by the "UNDERBAR" macro. It used
1456 to define "padoff_du", but it is currently a noop. However, it
1457 is strongly advised to still use it for ensuring past and
1458 future compatibility.
1459 dUNDERBAR;
1461 dXSARGS Sets up stack and mark pointers for an XSUB, calling "dSP" and
1463 "dMARK". Sets up the "ax" and "items" variables by calling
1464 "dAX" and "dITEMS". This is usually handled automatically by
1465 "xsubpp".
1466 dXSARGS;
1468 dXSI32 Sets up the "ix" variable for an XSUB which has aliases. This
1470 is usually handled automatically by "xsubpp".
1471 dXSI32;
1473 items Variable which is setup by "xsubpp" to indicate the number of
1475 items on the stack. See "Variable-length Parameter Lists" in
1476 perlxs.
1477 I32 items
1479 ix Variable which is setup by "xsubpp" to indicate which of an
1481 XSUB's aliases was used to invoke it. See "The ALIAS: Keyword"
1482 in perlxs.
1483 I32 ix
1485 RETVAL Variable which is setup by "xsubpp" to hold the return value
1487 for an XSUB. This is always the proper type for the XSUB. See
1488 "The RETVAL Variable" in perlxs.
1489 (whatever) RETVAL
1491 ST Used to access elements on the XSUB's stack.
1493 SV* ST(int ix)
1495 THIS Variable which is setup by "xsubpp" to designate the object in
1497 a C++ XSUB. This is always the proper type for the C++ object.
1498 See "CLASS" and "Using XS With C++" in perlxs.
1499 (whatever) THIS
1501 UNDERBAR
1503 The SV* corresponding to the $_ variable. Works even if there
1504 is a lexical $_ in scope.
1505 XS Macro to declare an XSUB and its C parameter list. This is
1507 handled by "xsubpp". It is the same as using the more explicit
1508 "XS_EXTERNAL" macro.
1509 XS_EXTERNAL
1511 Macro to declare an XSUB and its C parameter list explicitly
1512 exporting the symbols.
1513 XS_INTERNAL
1515 Macro to declare an XSUB and its C parameter list without
1516 exporting the symbols. This is handled by "xsubpp" and
1517 generally preferable over exporting the XSUB symbols
1518 unnecessarily.
1519
1521 dump_all
1522 Dumps the entire optree of the current program starting at
1523 "PL_main_root" to "STDERR". Also dumps the optrees for all
1524 visible subroutines in "PL_defstash".
1525 void dump_all()
1527 dump_packsubs
1529 Dumps the optrees for all visible subroutines in "stash".
1530 void dump_packsubs(const HV* stash)
1532 op_class
1534 Given an op, determine what type of struct it has been
1535 allocated as. Returns one of the OPclass enums, such as
1536 OPclass_LISTOP.
1537 OPclass op_class(const OP *o)
1539 op_dump Dumps the optree starting at OP "o" to "STDERR".
1541 void op_dump(const OP *o)
1543 sv_dump Dumps the contents of an SV to the "STDERR" filehandle.
1545 For an example of its output, see Devel::Peek.
1547 void sv_dump(SV* sv)
1549
1551 pv_display
1552 Similar to
1553 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
1555 except that an additional "\0" will be appended to the string
1557 when len > cur and pv[cur] is "\0".
1558 Note that the final string may be up to 7 chars longer than
1560 pvlim.
1561 char* pv_display(SV *dsv, const char *pv, STRLEN cur,
1563 STRLEN len, STRLEN pvlim)
1564 pv_escape
1566 Escapes at most the first "count" chars of "pv" and puts the
1567 results into "dsv" such that the size of the escaped string
1568 will not exceed "max" chars and will not contain any incomplete
1569 escape sequences. The number of bytes escaped will be returned
1570 in the "STRLEN *escaped" parameter if it is not null. When the
1571 "dsv" parameter is null no escaping actually occurs, but the
1572 number of bytes that would be escaped were it not null will be
1573 calculated.
1574 If flags contains "PERL_PV_ESCAPE_QUOTE" then any double quotes
1576 in the string will also be escaped.
1577 Normally the SV will be cleared before the escaped string is
1579 prepared, but when "PERL_PV_ESCAPE_NOCLEAR" is set this will
1580 not occur.
1581 If "PERL_PV_ESCAPE_UNI" is set then the input string is treated
1583 as UTF-8 if "PERL_PV_ESCAPE_UNI_DETECT" is set then the input
1584 string is scanned using "is_utf8_string()" to determine if it
1585 is UTF-8.
1586 If "PERL_PV_ESCAPE_ALL" is set then all input chars will be
1588 output using "\x01F1" style escapes, otherwise if
1589 "PERL_PV_ESCAPE_NONASCII" is set, only non-ASCII chars will be
1590 escaped using this style; otherwise, only chars above 255 will
1591 be so escaped; other non printable chars will use octal or
1592 common escaped patterns like "\n". Otherwise, if
1593 "PERL_PV_ESCAPE_NOBACKSLASH" then all chars below 255 will be
1594 treated as printable and will be output as literals.
1595 If "PERL_PV_ESCAPE_FIRSTCHAR" is set then only the first char
1597 of the string will be escaped, regardless of max. If the
1598 output is to be in hex, then it will be returned as a plain hex
1599 sequence. Thus the output will either be a single char, an
1600 octal escape sequence, a special escape like "\n" or a hex
1601 value.
1602 If "PERL_PV_ESCAPE_RE" is set then the escape char used will be
1604 a "%" and not a "\\". This is because regexes very often
1605 contain backslashed sequences, whereas "%" is not a
1606 particularly common character in patterns.
1607 Returns a pointer to the escaped text as held by "dsv".
1609 char* pv_escape(SV *dsv, char const * const str,
1611 const STRLEN count, const STRLEN max,
1612 STRLEN * const escaped,
1613 const U32 flags)
1614 pv_pretty
1616 Converts a string into something presentable, handling escaping
1617 via "pv_escape()" and supporting quoting and ellipses.
1618 If the "PERL_PV_PRETTY_QUOTE" flag is set then the result will
1620 be double quoted with any double quotes in the string escaped.
1621 Otherwise if the "PERL_PV_PRETTY_LTGT" flag is set then the
1622 result be wrapped in angle brackets.
1623 If the "PERL_PV_PRETTY_ELLIPSES" flag is set and not all
1625 characters in string were output then an ellipsis "..." will be
1626 appended to the string. Note that this happens AFTER it has
1627 been quoted.
1628 If "start_color" is non-null then it will be inserted after the
1630 opening quote (if there is one) but before the escaped text.
1631 If "end_color" is non-null then it will be inserted after the
1632 escaped text but before any quotes or ellipses.
1633 Returns a pointer to the prettified text as held by "dsv".
1635 char* pv_pretty(SV *dsv, char const * const str,
1637 const STRLEN count, const STRLEN max,
1638 char const * const start_color,
1639 char const * const end_color,
1640 const U32 flags)
1641
1643 cv_clone
1644 Clone a CV, making a lexical closure. "proto" supplies the
1645 prototype of the function: its code, pad structure, and other
1646 attributes. The prototype is combined with a capture of outer
1647 lexicals to which the code refers, which are taken from the
1648 currently-executing instance of the immediately surrounding
1649 code.
1650 CV * cv_clone(CV *proto)
1652 cv_name Returns an SV containing the name of the CV, mainly for use in
1654 error reporting. The CV may actually be a GV instead, in which
1655 case the returned SV holds the GV's name. Anything other than
1656 a GV or CV is treated as a string already holding the sub name,
1657 but this could change in the future.
1658 An SV may be passed as a second argument. If so, the name will
1660 be assigned to it and it will be returned. Otherwise the
1661 returned SV will be a new mortal.
1662 If "flags" has the "CV_NAME_NOTQUAL" bit set, then the package
1664 name will not be included. If the first argument is neither a
1665 CV nor a GV, this flag is ignored (subject to change).
1666 SV * cv_name(CV *cv, SV *sv, U32 flags)
1668 cv_undef
1670 Clear out all the active components of a CV. This can happen
1671 either by an explicit "undef &foo", or by the reference count
1672 going to zero. In the former case, we keep the "CvOUTSIDE"
1673 pointer, so that any anonymous children can still follow the
1674 full lexical scope chain.
1675 void cv_undef(CV* cv)
1677 find_rundefsv
1679 Returns the global variable $_.
1680 SV * find_rundefsv()
1682 find_rundefsvoffset
1684 DEPRECATED! It is planned to remove this function from a
1685 future release of Perl. Do not use it for new code; remove it
1686 from existing code.
1687 Until the lexical $_ feature was removed, this function would
1689 find the position of the lexical $_ in the pad of the
1690 currently-executing function and returns the offset in the
1691 current pad, or "NOT_IN_PAD".
1692 Now it always returns "NOT_IN_PAD".
1694 NOTE: the perl_ form of this function is deprecated.
1696 PADOFFSET find_rundefsvoffset()
1698 intro_my
1700 "Introduce" "my" variables to visible status. This is called
1701 during parsing at the end of each statement to make lexical
1702 variables visible to subsequent statements.
1703 U32 intro_my()
1705 load_module
1707 Loads the module whose name is pointed to by the string part of
1708 "name". Note that the actual module name, not its filename,
1709 should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver,
1710 if specified and not NULL, provides version semantics similar
1711 to "use Foo::Bar VERSION". The optional trailing arguments can
1712 be used to specify arguments to the module's "import()" method,
1713 similar to "use Foo::Bar VERSION LIST"; their precise handling
1714 depends on the flags. The flags argument is a bitwise-ORed
1715 collection of any of "PERL_LOADMOD_DENY",
1716 "PERL_LOADMOD_NOIMPORT", or "PERL_LOADMOD_IMPORT_OPS" (or 0 for
1717 no flags).
1718 If "PERL_LOADMOD_NOIMPORT" is set, the module is loaded as if
1720 with an empty import list, as in "use Foo::Bar ()"; this is the
1721 only circumstance in which the trailing optional arguments may
1722 be omitted entirely. Otherwise, if "PERL_LOADMOD_IMPORT_OPS" is
1723 set, the trailing arguments must consist of exactly one "OP*",
1724 containing the op tree that produces the relevant import
1725 arguments. Otherwise, the trailing arguments must all be "SV*"
1726 values that will be used as import arguments; and the list must
1727 be terminated with "(SV*) NULL". If neither
1728 "PERL_LOADMOD_NOIMPORT" nor "PERL_LOADMOD_IMPORT_OPS" is set,
1729 the trailing "NULL" pointer is needed even if no import
1730 arguments are desired. The reference count for each specified
1731 "SV*" argument is decremented. In addition, the "name" argument
1732 is modified.
1733 If "PERL_LOADMOD_DENY" is set, the module is loaded as if with
1735 "no" rather than "use".
1736 void load_module(U32 flags, SV* name, SV* ver, ...)
1738 newPADNAMELIST
1740 NOTE: this function is experimental and may change or be
1741 removed without notice.
1742 Creates a new pad name list. "max" is the highest index for
1744 which space is allocated.
1745 PADNAMELIST * newPADNAMELIST(size_t max)
1747 newPADNAMEouter
1749 NOTE: this function is experimental and may change or be
1750 removed without notice.
1751 Constructs and returns a new pad name. Only use this function
1753 for names that refer to outer lexicals. (See also
1754 "newPADNAMEpvn".) "outer" is the outer pad name that this one
1755 mirrors. The returned pad name has the "PADNAMEt_OUTER" flag
1756 already set.
1757 PADNAME * newPADNAMEouter(PADNAME *outer)
1759 newPADNAMEpvn
1761 NOTE: this function is experimental and may change or be
1762 removed without notice.
1763 Constructs and returns a new pad name. "s" must be a UTF-8
1765 string. Do not use this for pad names that point to outer
1766 lexicals. See "newPADNAMEouter".
1767 PADNAME * newPADNAMEpvn(const char *s, STRLEN len)
1769 nothreadhook
1771 Stub that provides thread hook for perl_destruct when there are
1772 no threads.
1773 int nothreadhook()
1775 pad_add_anon
1777 Allocates a place in the currently-compiling pad (via
1778 "pad_alloc") for an anonymous function that is lexically scoped
1779 inside the currently-compiling function. The function "func"
1780 is linked into the pad, and its "CvOUTSIDE" link to the outer
1781 scope is weakened to avoid a reference loop.
1782 One reference count is stolen, so you may need to do
1784 "SvREFCNT_inc(func)".
1785 "optype" should be an opcode indicating the type of operation
1787 that the pad entry is to support. This doesn't affect
1788 operational semantics, but is used for debugging.
1789 PADOFFSET pad_add_anon(CV *func, I32 optype)
1791 pad_add_name_pv
1793 Exactly like "pad_add_name_pvn", but takes a nul-terminated
1794 string instead of a string/length pair.
1795 PADOFFSET pad_add_name_pv(const char *name, U32 flags,
1797 HV *typestash, HV *ourstash)
1798 pad_add_name_pvn
1800 Allocates a place in the currently-compiling pad for a named
1801 lexical variable. Stores the name and other metadata in the
1802 name part of the pad, and makes preparations to manage the
1803 variable's lexical scoping. Returns the offset of the
1804 allocated pad slot.
1805 "namepv"/"namelen" specify the variable's name, including
1807 leading sigil. If "typestash" is non-null, the name is for a
1808 typed lexical, and this identifies the type. If "ourstash" is
1809 non-null, it's a lexical reference to a package variable, and
1810 this identifies the package. The following flags can be OR'ed
1811 together:
1812 padadd_OUR redundantly specifies if it's a package var
1814 padadd_STATE variable will retain value persistently
1815 padadd_NO_DUP_CHECK skip check for lexical shadowing
1816 PADOFFSET pad_add_name_pvn(const char *namepv,
1818 STRLEN namelen, U32 flags,
1819 HV *typestash, HV *ourstash)
1820 pad_add_name_sv
1822 Exactly like "pad_add_name_pvn", but takes the name string in
1823 the form of an SV instead of a string/length pair.
1824 PADOFFSET pad_add_name_sv(SV *name, U32 flags,
1826 HV *typestash, HV *ourstash)
1827 pad_alloc
1829 NOTE: this function is experimental and may change or be
1830 removed without notice.
1831 Allocates a place in the currently-compiling pad, returning the
1833 offset of the allocated pad slot. No name is initially
1834 attached to the pad slot. "tmptype" is a set of flags
1835 indicating the kind of pad entry required, which will be set in
1836 the value SV for the allocated pad entry:
1837 SVs_PADMY named lexical variable ("my", "our", "state")
1839 SVs_PADTMP unnamed temporary store
1840 SVf_READONLY constant shared between recursion levels
1841 "SVf_READONLY" has been supported here only since perl 5.20.
1843 To work with earlier versions as well, use
1844 "SVf_READONLY|SVs_PADTMP". "SVf_READONLY" does not cause the
1845 SV in the pad slot to be marked read-only, but simply tells
1846 "pad_alloc" that it will be made read-only (by the caller), or
1847 at least should be treated as such.
1848 "optype" should be an opcode indicating the type of operation
1850 that the pad entry is to support. This doesn't affect
1851 operational semantics, but is used for debugging.
1852 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
1854 pad_findmy_pv
1856 Exactly like "pad_findmy_pvn", but takes a nul-terminated
1857 string instead of a string/length pair.
1858 PADOFFSET pad_findmy_pv(const char *name, U32 flags)
1860 pad_findmy_pvn
1862 Given the name of a lexical variable, find its position in the
1863 currently-compiling pad. "namepv"/"namelen" specify the
1864 variable's name, including leading sigil. "flags" is reserved
1865 and must be zero. If it is not in the current pad but appears
1866 in the pad of any lexically enclosing scope, then a pseudo-
1867 entry for it is added in the current pad. Returns the offset
1868 in the current pad, or "NOT_IN_PAD" if no such lexical is in
1869 scope.
1870 PADOFFSET pad_findmy_pvn(const char *namepv,
1872 STRLEN namelen, U32 flags)
1873 pad_findmy_sv
1875 Exactly like "pad_findmy_pvn", but takes the name string in the
1876 form of an SV instead of a string/length pair.
1877 PADOFFSET pad_findmy_sv(SV *name, U32 flags)
1879 padnamelist_fetch
1881 NOTE: this function is experimental and may change or be
1882 removed without notice.
1883 Fetches the pad name from the given index.
1885 PADNAME * padnamelist_fetch(PADNAMELIST *pnl,
1887 SSize_t key)
1888 padnamelist_store
1890 NOTE: this function is experimental and may change or be
1891 removed without notice.
1892 Stores the pad name (which may be null) at the given index,
1894 freeing any existing pad name in that slot.
1895 PADNAME ** padnamelist_store(PADNAMELIST *pnl,
1897 SSize_t key, PADNAME *val)
1898 pad_setsv
1900 Set the value at offset "po" in the current (compiling or
1901 executing) pad. Use the macro "PAD_SETSV()" rather than
1902 calling this function directly.
1903 void pad_setsv(PADOFFSET po, SV *sv)
1905 pad_sv Get the value at offset "po" in the current (compiling or
1907 executing) pad. Use macro "PAD_SV" instead of calling this
1908 function directly.
1909 SV * pad_sv(PADOFFSET po)
1911 pad_tidy
1913 NOTE: this function is experimental and may change or be
1914 removed without notice.
1915 Tidy up a pad at the end of compilation of the code to which it
1917 belongs. Jobs performed here are: remove most stuff from the
1918 pads of anonsub prototypes; give it a @_; mark temporaries as
1919 such. "type" indicates the kind of subroutine:
1920 padtidy_SUB ordinary subroutine
1922 padtidy_SUBCLONE prototype for lexical closure
1923 padtidy_FORMAT format
1924 void pad_tidy(padtidy_type type)
1926 perl_alloc
1928 Allocates a new Perl interpreter. See perlembed.
1929 PerlInterpreter* perl_alloc()
1931 perl_construct
1933 Initializes a new Perl interpreter. See perlembed.
1934 void perl_construct(PerlInterpreter *my_perl)
1936 perl_destruct
1938 Shuts down a Perl interpreter. See perlembed.
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. See
1949 perlembed.
1950 int perl_parse(PerlInterpreter *my_perl,
1952 XSINIT_t xsinit, int argc,
1953 char** argv, char** env)
1954 perl_run
1956 Tells a Perl interpreter to run. See perlembed.
1957 int perl_run(PerlInterpreter *my_perl)
1959 require_pv
1961 Tells Perl to "require" the file named by the string argument.
1962 It is analogous to the Perl code "eval "require '$file'"".
1963 It's even implemented that way; consider using load_module
1964 instead.
1965 NOTE: the perl_ form of this function is deprecated.
1967 void require_pv(const char* pv)
1969
1971 dXCPT Set up necessary local variables for exception handling. See
1972 "Exception Handling" in perlguts.
1973 dXCPT;
1975 XCPT_CATCH
1977 Introduces a catch block. See "Exception Handling" in
1978 perlguts.
1979 XCPT_RETHROW
1981 Rethrows a previously caught exception. See "Exception
1982 Handling" in perlguts.
1983 XCPT_RETHROW;
1985 XCPT_TRY_END
1987 Ends a try block. See "Exception Handling" in perlguts.
1988 XCPT_TRY_START
1990 Starts a try block. See "Exception Handling" in perlguts.
1991
1993 save_gp Saves the current GP of gv on the save stack to be restored on
1994 scope exit.
1995 If empty is true, replace the GP with a new GP.
1997 If empty is false, mark gv with GVf_INTRO so the next reference
1999 assigned is localized, which is how " local *foo = $someref; "
2000 works.
2001 void save_gp(GV* gv, I32 empty)
2003
2005 new_version
2006 Returns a new version object based on the passed in SV:
2007 SV *sv = new_version(SV *ver);
2009 Does not alter the passed in ver SV. See "upg_version" if you
2011 want to upgrade the SV.
2012 SV* new_version(SV *ver)
2014 prescan_version
2016 Validate that a given string can be parsed as a version object,
2017 but doesn't actually perform the parsing. Can use either
2018 strict or lax validation rules. Can optionally set a number of
2019 hint variables to save the parsing code some time when
2020 tokenizing.
2021 const char* prescan_version(const char *s, bool strict,
2023 const char** errstr,
2024 bool *sqv,
2025 int *ssaw_decimal,
2026 int *swidth, bool *salpha)
2027 scan_version
2029 Returns a pointer to the next character after the parsed
2030 version string, as well as upgrading the passed in SV to an RV.
2031 Function must be called with an already existing SV like
2033 sv = newSV(0);
2035 s = scan_version(s, SV *sv, bool qv);
2036 Performs some preprocessing to the string to ensure that it has
2038 the correct characteristics of a version. Flags the object if
2039 it contains an underscore (which denotes this is an alpha
2040 version). The boolean qv denotes that the version should be
2041 interpreted as if it had multiple decimals, even if it doesn't.
2042 const char* scan_version(const char *s, SV *rv, bool qv)
2044 upg_version
2046 In-place upgrade of the supplied SV to a version object.
2047 SV *sv = upg_version(SV *sv, bool qv);
2049 Returns a pointer to the upgraded SV. Set the boolean qv if
2051 you want to force this SV to be interpreted as an "extended"
2052 version.
2053 SV* upg_version(SV *ver, bool qv)
2055 vcmp Version object aware cmp. Both operands must already have been
2057 converted into version objects.
2058 int vcmp(SV *lhv, SV *rhv)
2060 vnormal Accepts a version object and returns the normalized string
2062 representation. Call like:
2063 sv = vnormal(rv);
2065 NOTE: you can pass either the object directly or the SV
2067 contained within the RV.
2068 The SV returned has a refcount of 1.
2070 SV* vnormal(SV *vs)
2072 vnumify Accepts a version object and returns the normalized floating
2074 point representation. Call like:
2075 sv = vnumify(rv);
2077 NOTE: you can pass either the object directly or the SV
2079 contained within the RV.
2080 The SV returned has a refcount of 1.
2082 SV* vnumify(SV *vs)
2084 vstringify
2086 In order to maintain maximum compatibility with earlier
2087 versions of Perl, this function will return either the floating
2088 point notation or the multiple dotted notation, depending on
2089 whether the original version contained 1 or more dots,
2090 respectively.
2091 The SV returned has a refcount of 1.
2093 SV* vstringify(SV *vs)
2095 vverify Validates that the SV contains valid internal structure for a
2097 version object. It may be passed either the version object
2098 (RV) or the hash itself (HV). If the structure is valid, it
2099 returns the HV. If the structure is invalid, it returns NULL.
2100 SV *hv = vverify(sv);
2102 Note that it only confirms the bare minimum structure (so as
2104 not to get confused by derived classes which may contain
2105 additional hash entries):
2106 · The SV is an HV or a reference to an HV
2108 · The hash contains a "version" key
2110 · The "version" key has a reference to an AV as its value
2112 SV* vverify(SV *vs)
2114
2116 G_ARRAY Used to indicate list context. See "GIMME_V", "GIMME" and
2117 perlcall.
2118 G_DISCARD
2120 Indicates that arguments returned from a callback should be
2121 discarded. See perlcall.
2122 G_EVAL Used to force a Perl "eval" wrapper around a callback. See
2124 perlcall.
2125 GIMME A backward-compatible version of "GIMME_V" which can only
2127 return "G_SCALAR" or "G_ARRAY"; in a void context, it returns
2128 "G_SCALAR". Deprecated. Use "GIMME_V" instead.
2129 U32 GIMME
2131 GIMME_V The XSUB-writer's equivalent to Perl's "wantarray". Returns
2133 "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list
2134 context, respectively. See perlcall for a usage example.
2135 U32 GIMME_V
2137 G_NOARGS
2139 Indicates that no arguments are being sent to a callback. See
2140 perlcall.
2141 G_SCALAR
2143 Used to indicate scalar context. See "GIMME_V", "GIMME", and
2144 perlcall.
2145 G_VOID Used to indicate void context. See "GIMME_V" and perlcall.
2147
2149 These variables are global to an entire process. They are shared
2150 between all interpreters and all threads in a process. Any variables
2151 not documented here may be changed or removed without notice, so don't
2152 use them! If you feel you really do need to use an unlisted variable,
2153 first send email to perl5-porters@perl.org
2154 <mailto:perl5-porters@perl.org>. It may be that someone there will
2155 point out a way to accomplish what you need without using an internal
2156 variable. But if not, you should get a go-ahead to document and then
2157 use the variable.
2158 PL_check
2160 Array, indexed by opcode, of functions that will be called for
2161 the "check" phase of optree building during compilation of Perl
2162 code. For most (but not all) types of op, once the op has been
2163 initially built and populated with child ops it will be
2164 filtered through the check function referenced by the
2165 appropriate element of this array. The new op is passed in as
2166 the sole argument to the check function, and the check function
2167 returns the completed op. The check function may (as the name
2168 suggests) check the op for validity and signal errors. It may
2169 also initialise or modify parts of the ops, or perform more
2170 radical surgery such as adding or removing child ops, or even
2171 throw the op away and return a different op in its place.
2172 This array of function pointers is a convenient place to hook
2174 into the compilation process. An XS module can put its own
2175 custom check function in place of any of the standard ones, to
2176 influence the compilation of a particular type of op. However,
2177 a custom check function must never fully replace a standard
2178 check function (or even a custom check function from another
2179 module). A module modifying checking must instead wrap the
2180 preexisting check function. A custom check function must be
2181 selective about when to apply its custom behaviour. In the
2182 usual case where it decides not to do anything special with an
2183 op, it must chain the preexisting op function. Check functions
2184 are thus linked in a chain, with the core's base checker at the
2185 end.
2186 For thread safety, modules should not write directly to this
2188 array. Instead, use the function "wrap_op_checker".
2189 PL_keyword_plugin
2191 NOTE: this function is experimental and may change or be
2192 removed without notice.
2193 Function pointer, pointing at a function used to handle
2195 extended keywords. The function should be declared as
2196 int keyword_plugin_function(pTHX_
2198 char *keyword_ptr, STRLEN keyword_len,
2199 OP **op_ptr)
2200 The function is called from the tokeniser, whenever a possible
2202 keyword is seen. "keyword_ptr" points at the word in the
2203 parser's input buffer, and "keyword_len" gives its length; it
2204 is not null-terminated. The function is expected to examine
2205 the word, and possibly other state such as %^H, to decide
2206 whether it wants to handle it as an extended keyword. If it
2207 does not, the function should return "KEYWORD_PLUGIN_DECLINE",
2208 and the normal parser process will continue.
2209 If the function wants to handle the keyword, it first must
2211 parse anything following the keyword that is part of the syntax
2212 introduced by the keyword. See "Lexer interface" for details.
2213 When a keyword is being handled, the plugin function must build
2215 a tree of "OP" structures, representing the code that was
2216 parsed. The root of the tree must be stored in *op_ptr. The
2217 function then returns a constant indicating the syntactic role
2218 of the construct that it has parsed: "KEYWORD_PLUGIN_STMT" if
2219 it is a complete statement, or "KEYWORD_PLUGIN_EXPR" if it is
2220 an expression. Note that a statement construct cannot be used
2221 inside an expression (except via "do BLOCK" and similar), and
2222 an expression is not a complete statement (it requires at least
2223 a terminating semicolon).
2224 When a keyword is handled, the plugin function may also have
2226 (compile-time) side effects. It may modify "%^H", define
2227 functions, and so on. Typically, if side effects are the main
2228 purpose of a handler, it does not wish to generate any ops to
2229 be included in the normal compilation. In this case it is
2230 still required to supply an op tree, but it suffices to
2231 generate a single null op.
2232 That's how the *PL_keyword_plugin function needs to behave
2234 overall. Conventionally, however, one does not completely
2235 replace the existing handler function. Instead, take a copy of
2236 "PL_keyword_plugin" before assigning your own function pointer
2237 to it. Your handler function should look for keywords that it
2238 is interested in and handle those. Where it is not interested,
2239 it should call the saved plugin function, passing on the
2240 arguments it received. Thus "PL_keyword_plugin" actually
2241 points at a chain of handler functions, all of which have an
2242 opportunity to handle keywords, and only the last function in
2243 the chain (built into the Perl core) will normally return
2244 "KEYWORD_PLUGIN_DECLINE".
2245
2247 A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
2248 It is a structure that holds a pointer to a scalar, an array, a hash
2249 etc, corresponding to $foo, @foo, %foo.
2250 GVs are usually found as values in stashes (symbol table hashes) where
2252 Perl stores its global variables.
2253 GvAV Return the AV from the GV.
2255 AV* GvAV(GV* gv)
2257 gv_const_sv
2259 If "gv" is a typeglob whose subroutine entry is a constant sub
2260 eligible for inlining, or "gv" is a placeholder reference that
2261 would be promoted to such a typeglob, then returns the value
2262 returned by the sub. Otherwise, returns "NULL".
2263 SV* gv_const_sv(GV* gv)
2265 GvCV Return the CV from the GV.
2267 CV* GvCV(GV* gv)
2269 gv_fetchmeth
2271 Like "gv_fetchmeth_pvn", but lacks a flags parameter.
2272 GV* gv_fetchmeth(HV* stash, const char* name,
2274 STRLEN len, I32 level)
2275 gv_fetchmethod_autoload
2277 Returns the glob which contains the subroutine to call to
2278 invoke the method on the "stash". In fact in the presence of
2279 autoloading this may be the glob for "AUTOLOAD". In this case
2280 the corresponding variable $AUTOLOAD is already setup.
2281 The third parameter of "gv_fetchmethod_autoload" determines
2283 whether AUTOLOAD lookup is performed if the given method is not
2284 present: non-zero means yes, look for AUTOLOAD; zero means no,
2285 don't look for AUTOLOAD. Calling "gv_fetchmethod" is
2286 equivalent to calling "gv_fetchmethod_autoload" with a non-zero
2287 "autoload" parameter.
2288 These functions grant "SUPER" token as a prefix of the method
2290 name. Note that if you want to keep the returned glob for a
2291 long time, you need to check for it being "AUTOLOAD", since at
2292 the later time the call may load a different subroutine due to
2293 $AUTOLOAD changing its value. Use the glob created as a side
2294 effect to do this.
2295 These functions have the same side-effects as "gv_fetchmeth"
2297 with "level==0". The warning against passing the GV returned
2298 by "gv_fetchmeth" to "call_sv" applies equally to these
2299 functions.
2300 GV* gv_fetchmethod_autoload(HV* stash,
2302 const char* name,
2303 I32 autoload)
2304 gv_fetchmeth_autoload
2306 This is the old form of "gv_fetchmeth_pvn_autoload", which has
2307 no flags parameter.
2308 GV* gv_fetchmeth_autoload(HV* stash,
2310 const char* name,
2311 STRLEN len, I32 level)
2312 gv_fetchmeth_pv
2314 Exactly like "gv_fetchmeth_pvn", but takes a nul-terminated
2315 string instead of a string/length pair.
2316 GV* gv_fetchmeth_pv(HV* stash, const char* name,
2318 I32 level, U32 flags)
2319 gv_fetchmeth_pvn
2321 Returns the glob with the given "name" and a defined subroutine
2322 or "NULL". The glob lives in the given "stash", or in the
2323 stashes accessible via @ISA and "UNIVERSAL::".
2324 The argument "level" should be either 0 or -1. If "level==0",
2326 as a side-effect creates a glob with the given "name" in the
2327 given "stash" which in the case of success contains an alias
2328 for the subroutine, and sets up caching info for this glob.
2329 The only significant values for "flags" are "GV_SUPER" and
2331 "SVf_UTF8".
2332 "GV_SUPER" indicates that we want to look up the method in the
2334 superclasses of the "stash".
2335 The GV returned from "gv_fetchmeth" may be a method cache
2337 entry, which is not visible to Perl code. So when calling
2338 "call_sv", you should not use the GV directly; instead, you
2339 should use the method's CV, which can be obtained from the GV
2340 with the "GvCV" macro.
2341 GV* gv_fetchmeth_pvn(HV* stash, const char* name,
2343 STRLEN len, I32 level,
2344 U32 flags)
2345 gv_fetchmeth_pvn_autoload
2347 Same as "gv_fetchmeth_pvn()", but looks for autoloaded
2348 subroutines too. Returns a glob for the subroutine.
2349 For an autoloaded subroutine without a GV, will create a GV
2351 even if "level < 0". For an autoloaded subroutine without a
2352 stub, "GvCV()" of the result may be zero.
2353 Currently, the only significant value for "flags" is
2355 "SVf_UTF8".
2356 GV* gv_fetchmeth_pvn_autoload(HV* stash,
2358 const char* name,
2359 STRLEN len, I32 level,
2360 U32 flags)
2361 gv_fetchmeth_pv_autoload
2363 Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-
2364 terminated string instead of a string/length pair.
2365 GV* gv_fetchmeth_pv_autoload(HV* stash,
2367 const char* name,
2368 I32 level, U32 flags)
2369 gv_fetchmeth_sv
2371 Exactly like "gv_fetchmeth_pvn", but takes the name string in
2372 the form of an SV instead of a string/length pair.
2373 GV* gv_fetchmeth_sv(HV* stash, SV* namesv,
2375 I32 level, U32 flags)
2376 gv_fetchmeth_sv_autoload
2378 Exactly like "gv_fetchmeth_pvn_autoload", but takes the name
2379 string in the form of an SV instead of a string/length pair.
2380 GV* gv_fetchmeth_sv_autoload(HV* stash, SV* namesv,
2382 I32 level, U32 flags)
2383 GvHV Return the HV from the GV.
2385 HV* GvHV(GV* gv)
2387 gv_init The old form of "gv_init_pvn()". It does not work with UTF-8
2389 strings, as it has no flags parameter. If the "multi"
2390 parameter is set, the "GV_ADDMULTI" flag will be passed to
2391 "gv_init_pvn()".
2392 void gv_init(GV* gv, HV* stash, const char* name,
2394 STRLEN len, int multi)
2395 gv_init_pv
2397 Same as "gv_init_pvn()", but takes a nul-terminated string for
2398 the name instead of separate char * and length parameters.
2399 void gv_init_pv(GV* gv, HV* stash, const char* name,
2401 U32 flags)
2402 gv_init_pvn
2404 Converts a scalar into a typeglob. This is an incoercible
2405 typeglob; assigning a reference to it will assign to one of its
2406 slots, instead of overwriting it as happens with typeglobs
2407 created by "SvSetSV". Converting any scalar that is "SvOK()"
2408 may produce unpredictable results and is reserved for perl's
2409 internal use.
2410 "gv" is the scalar to be converted.
2412 "stash" is the parent stash/package, if any.
2414 "name" and "len" give the name. The name must be unqualified;
2416 that is, it must not include the package name. If "gv" is a
2417 stash element, it is the caller's responsibility to ensure that
2418 the name passed to this function matches the name of the
2419 element. If it does not match, perl's internal bookkeeping
2420 will get out of sync.
2421 "flags" can be set to "SVf_UTF8" if "name" is a UTF-8 string,
2423 or the return value of SvUTF8(sv). It can also take the
2424 "GV_ADDMULTI" flag, which means to pretend that the GV has been
2425 seen before (i.e., suppress "Used once" warnings).
2426 void gv_init_pvn(GV* gv, HV* stash, const char* name,
2428 STRLEN len, U32 flags)
2429 gv_init_sv
2431 Same as "gv_init_pvn()", but takes an SV * for the name instead
2432 of separate char * and length parameters. "flags" is currently
2433 unused.
2434 void gv_init_sv(GV* gv, HV* stash, SV* namesv,
2436 U32 flags)
2437 gv_stashpv
2439 Returns a pointer to the stash for a specified package. Uses
2440 "strlen" to determine the length of "name", then calls
2441 "gv_stashpvn()".
2442 HV* gv_stashpv(const char* name, I32 flags)
2444 gv_stashpvn
2446 Returns a pointer to the stash for a specified package. The
2447 "namelen" parameter indicates the length of the "name", in
2448 bytes. "flags" is passed to "gv_fetchpvn_flags()", so if set
2449 to "GV_ADD" then the package will be created if it does not
2450 already exist. If the package does not exist and "flags" is 0
2451 (or any other setting that does not create packages) then
2452 "NULL" is returned.
2453 Flags may be one of:
2455 GV_ADD
2457 SVf_UTF8
2458 GV_NOADD_NOINIT
2459 GV_NOINIT
2460 GV_NOEXPAND
2461 GV_ADDMG
2462 The most important of which are probably "GV_ADD" and
2464 "SVf_UTF8".
2465 Note, use of "gv_stashsv" instead of "gv_stashpvn" where
2467 possible is strongly recommended for performance reasons.
2468 HV* gv_stashpvn(const char* name, U32 namelen,
2470 I32 flags)
2471 gv_stashpvs
2473 Like "gv_stashpvn", but takes a "NUL"-terminated literal string
2474 instead of a string/length pair.
2475 HV* gv_stashpvs(const char* name, I32 create)
2477 gv_stashsv
2479 Returns a pointer to the stash for a specified package. See
2480 "gv_stashpvn".
2481 Note this interface is strongly preferred over "gv_stashpvn"
2483 for performance reasons.
2484 HV* gv_stashsv(SV* sv, I32 flags)
2486 GvSV Return the SV from the GV.
2488 SV* GvSV(GV* gv)
2490 setdefout
2492 Sets "PL_defoutgv", the default file handle for output, to the
2493 passed in typeglob. As "PL_defoutgv" "owns" a reference on its
2494 typeglob, the reference count of the passed in typeglob is
2495 increased by one, and the reference count of the typeglob that
2496 "PL_defoutgv" points to is decreased by one.
2497 void setdefout(GV* gv)
2499
2501 Nullav Null AV pointer.
2502 (deprecated - use "(AV *)NULL" instead)
2504 Nullch Null character pointer. (No longer available when "PERL_CORE"
2506 is defined.)
2507 Nullcv Null CV pointer.
2509 (deprecated - use "(CV *)NULL" instead)
2511 Nullhv Null HV pointer.
2513 (deprecated - use "(HV *)NULL" instead)
2515 Nullsv Null SV pointer. (No longer available when "PERL_CORE" is
2517 defined.)
2518
2520 A HV structure represents a Perl hash. It consists mainly of an array
2521 of pointers, each of which points to a linked list of HE structures.
2522 The array is indexed by the hash function of the key, so each linked
2523 list represents all the hash entries with the same hash value. Each HE
2524 contains a pointer to the actual value, plus a pointer to a HEK
2525 structure which holds the key and hash value.
2526 cop_fetch_label
2528 NOTE: this function is experimental and may change or be
2529 removed without notice.
2530 Returns the label attached to a cop. The flags pointer may be
2532 set to "SVf_UTF8" or 0.
2533 const char * cop_fetch_label(COP *const cop,
2535 STRLEN *len, U32 *flags)
2536 cop_store_label
2538 NOTE: this function is experimental and may change or be
2539 removed without notice.
2540 Save a label into a "cop_hints_hash". You need to set flags to
2542 "SVf_UTF8" for a UTF-8 label.
2543 void cop_store_label(COP *const cop,
2545 const char *label, STRLEN len,
2546 U32 flags)
2547 get_hv Returns the HV of the specified Perl hash. "flags" are passed
2549 to "gv_fetchpv". If "GV_ADD" is set and the Perl variable does
2550 not exist then it will be created. If "flags" is zero and the
2551 variable does not exist then "NULL" is returned.
2552 NOTE: the perl_ form of this function is deprecated.
2554 HV* get_hv(const char *name, I32 flags)
2556 HEf_SVKEY
2558 This flag, used in the length slot of hash entries and magic
2559 structures, specifies the structure contains an "SV*" pointer
2560 where a "char*" pointer is to be expected. (For information
2561 only--not to be used).
2562 HeHASH Returns the computed hash stored in the hash entry.
2564 U32 HeHASH(HE* he)
2566 HeKEY Returns the actual pointer stored in the key slot of the hash
2568 entry. The pointer may be either "char*" or "SV*", depending
2569 on the value of "HeKLEN()". Can be assigned to. The "HePV()"
2570 or "HeSVKEY()" macros are usually preferable for finding the
2571 value of a key.
2572 void* HeKEY(HE* he)
2574 HeKLEN If this is negative, and amounts to "HEf_SVKEY", it indicates
2576 the entry holds an "SV*" key. Otherwise, holds the actual
2577 length of the key. Can be assigned to. The "HePV()" macro is
2578 usually preferable for finding key lengths.
2579 STRLEN HeKLEN(HE* he)
2581 HePV Returns the key slot of the hash entry as a "char*" value,
2583 doing any necessary dereferencing of possibly "SV*" keys. The
2584 length of the string is placed in "len" (this is a macro, so do
2585 not use &len). If you do not care about what the length of the
2586 key is, you may use the global variable "PL_na", though this is
2587 rather less efficient than using a local variable. Remember
2588 though, that hash keys in perl are free to contain embedded
2589 nulls, so using "strlen()" or similar is not a good way to find
2590 the length of hash keys. This is very similar to the "SvPV()"
2591 macro described elsewhere in this document. See also "HeUTF8".
2592 If you are using "HePV" to get values to pass to "newSVpvn()"
2594 to create a new SV, you should consider using
2595 "newSVhek(HeKEY_hek(he))" as it is more efficient.
2596 char* HePV(HE* he, STRLEN len)
2598 HeSVKEY Returns the key as an "SV*", or "NULL" if the hash entry does
2600 not contain an "SV*" key.
2601 SV* HeSVKEY(HE* he)
2603 HeSVKEY_force
2605 Returns the key as an "SV*". Will create and return a
2606 temporary mortal "SV*" if the hash entry contains only a
2607 "char*" key.
2608 SV* HeSVKEY_force(HE* he)
2610 HeSVKEY_set
2612 Sets the key to a given "SV*", taking care to set the
2613 appropriate flags to indicate the presence of an "SV*" key, and
2614 returns the same "SV*".
2615 SV* HeSVKEY_set(HE* he, SV* sv)
2617 HeUTF8 Returns whether the "char *" value returned by "HePV" is
2619 encoded in UTF-8, doing any necessary dereferencing of possibly
2620 "SV*" keys. The value returned will be 0 or non-0, not
2621 necessarily 1 (or even a value with any low bits set), so do
2622 not blindly assign this to a "bool" variable, as "bool" may be
2623 a typedef for "char".
2624 U32 HeUTF8(HE* he)
2626 HeVAL Returns the value slot (type "SV*") stored in the hash entry.
2628 Can be assigned to.
2629 SV *foo= HeVAL(hv);
2631 HeVAL(hv)= sv;
2632 SV* HeVAL(HE* he)
2635 hv_assert
2637 Check that a hash is in an internally consistent state.
2638 void hv_assert(HV *hv)
2640 hv_bucket_ratio
2642 NOTE: this function is experimental and may change or be
2643 removed without notice.
2644 If the hash is tied dispatches through to the SCALAR tied
2646 method, otherwise if the hash contains no keys returns 0,
2647 otherwise returns a mortal sv containing a string specifying
2648 the number of used buckets, followed by a slash, followed by
2649 the number of available buckets.
2650 This function is expensive, it must scan all of the buckets to
2652 determine which are used, and the count is NOT cached. In a
2653 large hash this could be a lot of buckets.
2654 SV* hv_bucket_ratio(HV *hv)
2656 hv_clear
2658 Frees the all the elements of a hash, leaving it empty. The XS
2659 equivalent of "%hash = ()". See also "hv_undef".
2660 See "av_clear" for a note about the hash possibly being invalid
2662 on return.
2663 void hv_clear(HV *hv)
2665 hv_clear_placeholders
2667 Clears any placeholders from a hash. If a restricted hash has
2668 any of its keys marked as readonly and the key is subsequently
2669 deleted, the key is not actually deleted but is marked by
2670 assigning it a value of &PL_sv_placeholder. This tags it so it
2671 will be ignored by future operations such as iterating over the
2672 hash, but will still allow the hash to have a value reassigned
2673 to the key at some future point. This function clears any such
2674 placeholder keys from the hash. See "Hash::Util::lock_keys()"
2675 for an example of its use.
2676 void hv_clear_placeholders(HV *hv)
2678 hv_copy_hints_hv
2680 A specialised version of "newHVhv" for copying "%^H". "ohv"
2681 must be a pointer to a hash (which may have "%^H" magic, but
2682 should be generally non-magical), or "NULL" (interpreted as an
2683 empty hash). The content of "ohv" is copied to a new hash,
2684 which has the "%^H"-specific magic added to it. A pointer to
2685 the new hash is returned.
2686 HV * hv_copy_hints_hv(HV *ohv)
2688 hv_delete
2690 Deletes a key/value pair in the hash. The value's SV is
2691 removed from the hash, made mortal, and returned to the caller.
2692 The absolute value of "klen" is the length of the key. If
2693 "klen" is negative the key is assumed to be in UTF-8-encoded
2694 Unicode. The "flags" value will normally be zero; if set to
2695 "G_DISCARD" then "NULL" will be returned. "NULL" will also be
2696 returned if the key is not found.
2697 SV* hv_delete(HV *hv, const char *key, I32 klen,
2699 I32 flags)
2700 hv_delete_ent
2702 Deletes a key/value pair in the hash. The value SV is removed
2703 from the hash, made mortal, and returned to the caller. The
2704 "flags" value will normally be zero; if set to "G_DISCARD" then
2705 "NULL" will be returned. "NULL" will also be returned if the
2706 key is not found. "hash" can be a valid precomputed hash
2707 value, or 0 to ask for it to be computed.
2708 SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags,
2710 U32 hash)
2711 HvENAME Returns the effective name of a stash, or NULL if there is
2713 none. The effective name represents a location in the symbol
2714 table where this stash resides. It is updated automatically
2715 when packages are aliased or deleted. A stash that is no
2716 longer in the symbol table has no effective name. This name is
2717 preferable to "HvNAME" for use in MRO linearisations and isa
2718 caches.
2719 char* HvENAME(HV* stash)
2721 HvENAMELEN
2723 Returns the length of the stash's effective name.
2724 STRLEN HvENAMELEN(HV *stash)
2726 HvENAMEUTF8
2728 Returns true if the effective name is in UTF-8 encoding.
2729 unsigned char HvENAMEUTF8(HV *stash)
2731 hv_exists
2733 Returns a boolean indicating whether the specified hash key
2734 exists. The absolute value of "klen" is the length of the key.
2735 If "klen" is negative the key is assumed to be in UTF-8-encoded
2736 Unicode.
2737 bool hv_exists(HV *hv, const char *key, I32 klen)
2739 hv_exists_ent
2741 Returns a boolean indicating whether the specified hash key
2742 exists. "hash" can be a valid precomputed hash value, or 0 to
2743 ask for it to be computed.
2744 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
2746 hv_fetch
2748 Returns the SV which corresponds to the specified key in the
2749 hash. The absolute value of "klen" is the length of the key.
2750 If "klen" is negative the key is assumed to be in UTF-8-encoded
2751 Unicode. If "lval" is set then the fetch will be part of a
2752 store. This means that if there is no value in the hash
2753 associated with the given key, then one is created and a
2754 pointer to it is returned. The "SV*" it points to can be
2755 assigned to. But always check that the return value is non-
2756 null before dereferencing it to an "SV*".
2757 See "Understanding the Magic of Tied Hashes and Arrays" in
2759 perlguts for more information on how to use this function on
2760 tied hashes.
2761 SV** hv_fetch(HV *hv, const char *key, I32 klen,
2763 I32 lval)
2764 hv_fetchs
2766 Like "hv_fetch", but takes a "NUL"-terminated literal string
2767 instead of a string/length pair.
2768 SV** hv_fetchs(HV* tb, const char* key, I32 lval)
2770 hv_fetch_ent
2772 Returns the hash entry which corresponds to the specified key
2773 in the hash. "hash" must be a valid precomputed hash number
2774 for the given "key", or 0 if you want the function to compute
2775 it. IF "lval" is set then the fetch will be part of a store.
2776 Make sure the return value is non-null before accessing it.
2777 The return value when "hv" is a tied hash is a pointer to a
2778 static location, so be sure to make a copy of the structure if
2779 you need to store it somewhere.
2780 See "Understanding the Magic of Tied Hashes and Arrays" in
2782 perlguts for more information on how to use this function on
2783 tied hashes.
2784 HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval,
2786 U32 hash)
2787 hv_fill Returns the number of hash buckets that happen to be in use.
2789 This function is wrapped by the macro "HvFILL".
2791 As of perl 5.25 this function is used only for debugging
2793 purposes, and the number of used hash buckets is not in any way
2794 cached, thus this function can be costly to execute as it must
2795 iterate over all the buckets in the hash.
2796 STRLEN hv_fill(HV *const hv)
2798 hv_iterinit
2800 Prepares a starting point to traverse a hash table. Returns
2801 the number of keys in the hash, including placeholders (i.e.
2802 the same as "HvTOTALKEYS(hv)"). The return value is currently
2803 only meaningful for hashes without tie magic.
2804 NOTE: Before version 5.004_65, "hv_iterinit" used to return the
2806 number of hash buckets that happen to be in use. If you still
2807 need that esoteric value, you can get it through the macro
2808 "HvFILL(hv)".
2809 I32 hv_iterinit(HV *hv)
2811 hv_iterkey
2813 Returns the key from the current position of the hash iterator.
2814 See "hv_iterinit".
2815 char* hv_iterkey(HE* entry, I32* retlen)
2817 hv_iterkeysv
2819 Returns the key as an "SV*" from the current position of the
2820 hash iterator. The return value will always be a mortal copy
2821 of the key. Also see "hv_iterinit".
2822 SV* hv_iterkeysv(HE* entry)
2824 hv_iternext
2826 Returns entries from a hash iterator. See "hv_iterinit".
2827 You may call "hv_delete" or "hv_delete_ent" on the hash entry
2829 that the iterator currently points to, without losing your
2830 place or invalidating your iterator. Note that in this case
2831 the current entry is deleted from the hash with your iterator
2832 holding the last reference to it. Your iterator is flagged to
2833 free the entry on the next call to "hv_iternext", so you must
2834 not discard your iterator immediately else the entry will leak
2835 - call "hv_iternext" to trigger the resource deallocation.
2836 HE* hv_iternext(HV *hv)
2838 hv_iternextsv
2840 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in
2841 one operation.
2842 SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
2844 hv_iternext_flags
2846 NOTE: this function is experimental and may change or be
2847 removed without notice.
2848 Returns entries from a hash iterator. See "hv_iterinit" and
2850 "hv_iternext". The "flags" value will normally be zero; if
2851 "HV_ITERNEXT_WANTPLACEHOLDERS" is set the placeholders keys
2852 (for restricted hashes) will be returned in addition to normal
2853 keys. By default placeholders are automatically skipped over.
2854 Currently a placeholder is implemented with a value that is
2855 &PL_sv_placeholder. Note that the implementation of
2856 placeholders and restricted hashes may change, and the
2857 implementation currently is insufficiently abstracted for any
2858 change to be tidy.
2859 HE* hv_iternext_flags(HV *hv, I32 flags)
2861 hv_iterval
2863 Returns the value from the current position of the hash
2864 iterator. See "hv_iterkey".
2865 SV* hv_iterval(HV *hv, HE *entry)
2867 hv_magic
2869 Adds magic to a hash. See "sv_magic".
2870 void hv_magic(HV *hv, GV *gv, int how)
2872 HvNAME Returns the package name of a stash, or "NULL" if "stash" isn't
2874 a stash. See "SvSTASH", "CvSTASH".
2875 char* HvNAME(HV* stash)
2877 HvNAMELEN
2879 Returns the length of the stash's name.
2880 STRLEN HvNAMELEN(HV *stash)
2882 HvNAMEUTF8
2884 Returns true if the name is in UTF-8 encoding.
2885 unsigned char HvNAMEUTF8(HV *stash)
2887 hv_scalar
2889 Evaluates the hash in scalar context and returns the result.
2890 When the hash is tied dispatches through to the SCALAR method,
2892 otherwise returns a mortal SV containing the number of keys in
2893 the hash.
2894 Note, prior to 5.25 this function returned what is now returned
2896 by the hv_bucket_ratio() function.
2897 SV* hv_scalar(HV *hv)
2899 hv_store
2901 Stores an SV in a hash. The hash key is specified as "key" and
2902 the absolute value of "klen" is the length of the key. If
2903 "klen" is negative the key is assumed to be in UTF-8-encoded
2904 Unicode. The "hash" parameter is the precomputed hash value;
2905 if it is zero then Perl will compute it.
2906 The return value will be "NULL" if the operation failed or if
2908 the value did not need to be actually stored within the hash
2909 (as in the case of tied hashes). Otherwise it can be
2910 dereferenced to get the original "SV*". Note that the caller
2911 is responsible for suitably incrementing the reference count of
2912 "val" before the call, and decrementing it if the function
2913 returned "NULL". Effectively a successful "hv_store" takes
2914 ownership of one reference to "val". This is usually what you
2915 want; a newly created SV has a reference count of one, so if
2916 all your code does is create SVs then store them in a hash,
2917 "hv_store" will own the only reference to the new SV, and your
2918 code doesn't need to do anything further to tidy up.
2919 "hv_store" is not implemented as a call to "hv_store_ent", and
2920 does not create a temporary SV for the key, so if your key data
2921 is not already in SV form then use "hv_store" in preference to
2922 "hv_store_ent".
2923 See "Understanding the Magic of Tied Hashes and Arrays" in
2925 perlguts for more information on how to use this function on
2926 tied hashes.
2927 SV** hv_store(HV *hv, const char *key, I32 klen,
2929 SV *val, U32 hash)
2930 hv_stores
2932 Like "hv_store", but takes a "NUL"-terminated literal string
2933 instead of a string/length pair and omits the hash parameter.
2934 SV** hv_stores(HV* tb, const char* key,
2936 NULLOK SV* val)
2937 hv_store_ent
2939 Stores "val" in a hash. The hash key is specified as "key".
2940 The "hash" parameter is the precomputed hash value; if it is
2941 zero then Perl will compute it. The return value is the new
2942 hash entry so created. It will be "NULL" if the operation
2943 failed or if the value did not need to be actually stored
2944 within the hash (as in the case of tied hashes). Otherwise the
2945 contents of the return value can be accessed using the "He?"
2946 macros described here. Note that the caller is responsible for
2947 suitably incrementing the reference count of "val" before the
2948 call, and decrementing it if the function returned NULL.
2949 Effectively a successful "hv_store_ent" takes ownership of one
2950 reference to "val". This is usually what you want; a newly
2951 created SV has a reference count of one, so if all your code
2952 does is create SVs then store them in a hash, "hv_store" will
2953 own the only reference to the new SV, and your code doesn't
2954 need to do anything further to tidy up. Note that
2955 "hv_store_ent" only reads the "key"; unlike "val" it does not
2956 take ownership of it, so maintaining the correct reference
2957 count on "key" is entirely the caller's responsibility.
2958 "hv_store" is not implemented as a call to "hv_store_ent", and
2959 does not create a temporary SV for the key, so if your key data
2960 is not already in SV form then use "hv_store" in preference to
2961 "hv_store_ent".
2962 See "Understanding the Magic of Tied Hashes and Arrays" in
2964 perlguts for more information on how to use this function on
2965 tied hashes.
2966 HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
2968 hv_undef
2970 Undefines the hash. The XS equivalent of "undef(%hash)".
2971 As well as freeing all the elements of the hash (like
2973 "hv_clear()"), this also frees any auxiliary data and storage
2974 associated with the hash.
2975 See "av_clear" for a note about the hash possibly being invalid
2977 on return.
2978 void hv_undef(HV *hv)
2980 newHV Creates a new HV. The reference count is set to 1.
2982 HV* newHV()
2984
2986 These functions provide convenient and thread-safe means of
2987 manipulating hook variables.
2988 wrap_op_checker
2990 Puts a C function into the chain of check functions for a
2991 specified op type. This is the preferred way to manipulate the
2992 "PL_check" array. "opcode" specifies which type of op is to be
2993 affected. "new_checker" is a pointer to the C function that is
2994 to be added to that opcode's check chain, and "old_checker_p"
2995 points to the storage location where a pointer to the next
2996 function in the chain will be stored. The value of
2997 "new_pointer" is written into the "PL_check" array, while the
2998 value previously stored there is written to *old_checker_p.
2999 The function should be defined like this:
3001 static OP *new_checker(pTHX_ OP *op) { ... }
3003 It is intended to be called in this manner:
3005 new_checker(aTHX_ op)
3007 "old_checker_p" should be defined like this:
3009 static Perl_check_t old_checker_p;
3011 "PL_check" is global to an entire process, and a module wishing
3013 to hook op checking may find itself invoked more than once per
3014 process, typically in different threads. To handle that
3015 situation, this function is idempotent. The location
3016 *old_checker_p must initially (once per process) contain a null
3017 pointer. A C variable of static duration (declared at file
3018 scope, typically also marked "static" to give it internal
3019 linkage) will be implicitly initialised appropriately, if it
3020 does not have an explicit initialiser. This function will only
3021 actually modify the check chain if it finds *old_checker_p to
3022 be null. This function is also thread safe on the small scale.
3023 It uses appropriate locking to avoid race conditions in
3024 accessing "PL_check".
3025 When this function is called, the function referenced by
3027 "new_checker" must be ready to be called, except for
3028 *old_checker_p being unfilled. In a threading situation,
3029 "new_checker" may be called immediately, even before this
3030 function has returned. *old_checker_p will always be
3031 appropriately set before "new_checker" is called. If
3032 "new_checker" decides not to do anything special with an op
3033 that it is given (which is the usual case for most uses of op
3034 check hooking), it must chain the check function referenced by
3035 *old_checker_p.
3036 If you want to influence compilation of calls to a specific
3038 subroutine, then use "cv_set_call_checker" rather than hooking
3039 checking of all "entersub" ops.
3040 void wrap_op_checker(Optype opcode,
3042 Perl_check_t new_checker,
3043 Perl_check_t *old_checker_p)
3044
3046 This is the lower layer of the Perl parser, managing characters and
3047 tokens.
3048 lex_bufutf8
3050 NOTE: this function is experimental and may change or be
3051 removed without notice.
3052 Indicates whether the octets in the lexer buffer
3054 ("PL_parser->linestr") should be interpreted as the UTF-8
3055 encoding of Unicode characters. If not, they should be
3056 interpreted as Latin-1 characters. This is analogous to the
3057 "SvUTF8" flag for scalars.
3058 In UTF-8 mode, it is not guaranteed that the lexer buffer
3060 actually contains valid UTF-8. Lexing code must be robust in
3061 the face of invalid encoding.
3062 The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
3064 significant, but not the whole story regarding the input
3065 character encoding. Normally, when a file is being read, the
3066 scalar contains octets and its "SvUTF8" flag is off, but the
3067 octets should be interpreted as UTF-8 if the "use utf8" pragma
3068 is in effect. During a string eval, however, the scalar may
3069 have the "SvUTF8" flag on, and in this case its octets should
3070 be interpreted as UTF-8 unless the "use bytes" pragma is in
3071 effect. This logic may change in the future; use this function
3072 instead of implementing the logic yourself.
3073 bool lex_bufutf8()
3075 lex_discard_to
3077 NOTE: this function is experimental and may change or be
3078 removed without notice.
3079 Discards the first part of the "PL_parser->linestr" buffer, up
3081 to "ptr". The remaining content of the buffer will be moved,
3082 and all pointers into the buffer updated appropriately. "ptr"
3083 must not be later in the buffer than the position of
3084 "PL_parser->bufptr": it is not permitted to discard text that
3085 has yet to be lexed.
3086 Normally it is not necessarily to do this directly, because it
3088 suffices to use the implicit discarding behaviour of
3089 "lex_next_chunk" and things based on it. However, if a token
3090 stretches across multiple lines, and the lexing code has kept
3091 multiple lines of text in the buffer for that purpose, then
3092 after completion of the token it would be wise to explicitly
3093 discard the now-unneeded earlier lines, to avoid future multi-
3094 line tokens growing the buffer without bound.
3095 void lex_discard_to(char *ptr)
3097 lex_grow_linestr
3099 NOTE: this function is experimental and may change or be
3100 removed without notice.
3101 Reallocates the lexer buffer ("PL_parser->linestr") to
3103 accommodate at least "len" octets (including terminating
3104 "NUL"). Returns a pointer to the reallocated buffer. This is
3105 necessary before making any direct modification of the buffer
3106 that would increase its length. "lex_stuff_pvn" provides a
3107 more convenient way to insert text into the buffer.
3108 Do not use "SvGROW" or "sv_grow" directly on
3110 "PL_parser->linestr"; this function updates all of the lexer's
3111 variables that point directly into the buffer.
3112 char * lex_grow_linestr(STRLEN len)
3114 lex_next_chunk
3116 NOTE: this function is experimental and may change or be
3117 removed without notice.
3118 Reads in the next chunk of text to be lexed, appending it to
3120 "PL_parser->linestr". This should be called when lexing code
3121 has looked to the end of the current chunk and wants to know
3122 more. It is usual, but not necessary, for lexing to have
3123 consumed the entirety of the current chunk at this time.
3124 If "PL_parser->bufptr" is pointing to the very end of the
3126 current chunk (i.e., the current chunk has been entirely
3127 consumed), normally the current chunk will be discarded at the
3128 same time that the new chunk is read in. If "flags" has the
3129 "LEX_KEEP_PREVIOUS" bit set, the current chunk will not be
3130 discarded. If the current chunk has not been entirely
3131 consumed, then it will not be discarded regardless of the flag.
3132 Returns true if some new text was added to the buffer, or false
3134 if the buffer has reached the end of the input text.
3135 bool lex_next_chunk(U32 flags)
3137 lex_peek_unichar
3139 NOTE: this function is experimental and may change or be
3140 removed without notice.
3141 Looks ahead one (Unicode) character in the text currently being
3143 lexed. Returns the codepoint (unsigned integer value) of the
3144 next character, or -1 if lexing has reached the end of the
3145 input text. To consume the peeked character, use
3146 "lex_read_unichar".
3147 If the next character is in (or extends into) the next chunk of
3149 input text, the next chunk will be read in. Normally the
3150 current chunk will be discarded at the same time, but if
3151 "flags" has the "LEX_KEEP_PREVIOUS" bit set, then the current
3152 chunk will not be discarded.
3153 If the input is being interpreted as UTF-8 and a UTF-8 encoding
3155 error is encountered, an exception is generated.
3156 I32 lex_peek_unichar(U32 flags)
3158 lex_read_space
3160 NOTE: this function is experimental and may change or be
3161 removed without notice.
3162 Reads optional spaces, in Perl style, in the text currently
3164 being lexed. The spaces may include ordinary whitespace
3165 characters and Perl-style comments. "#line" directives are
3166 processed if encountered. "PL_parser->bufptr" is moved past
3167 the spaces, so that it points at a non-space character (or the
3168 end of the input text).
3169 If spaces extend into the next chunk of input text, the next
3171 chunk will be read in. Normally the current chunk will be
3172 discarded at the same time, but if "flags" has the
3173 "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
3174 discarded.
3175 void lex_read_space(U32 flags)
3177 lex_read_to
3179 NOTE: this function is experimental and may change or be
3180 removed without notice.
3181 Consume text in the lexer buffer, from "PL_parser->bufptr" up
3183 to "ptr". This advances "PL_parser->bufptr" to match "ptr",
3184 performing the correct bookkeeping whenever a newline character
3185 is passed. This is the normal way to consume lexed text.
3186 Interpretation of the buffer's octets can be abstracted out by
3188 using the slightly higher-level functions "lex_peek_unichar"
3189 and "lex_read_unichar".
3190 void lex_read_to(char *ptr)
3192 lex_read_unichar
3194 NOTE: this function is experimental and may change or be
3195 removed without notice.
3196 Reads the next (Unicode) character in the text currently being
3198 lexed. Returns the codepoint (unsigned integer value) of the
3199 character read, and moves "PL_parser->bufptr" past the
3200 character, or returns -1 if lexing has reached the end of the
3201 input text. To non-destructively examine the next character,
3202 use "lex_peek_unichar" instead.
3203 If the next character is in (or extends into) the next chunk of
3205 input text, the next chunk will be read in. Normally the
3206 current chunk will be discarded at the same time, but if
3207 "flags" has the "LEX_KEEP_PREVIOUS" bit set, then the current
3208 chunk will not be discarded.
3209 If the input is being interpreted as UTF-8 and a UTF-8 encoding
3211 error is encountered, an exception is generated.
3212 I32 lex_read_unichar(U32 flags)
3214 lex_start
3216 NOTE: this function is experimental and may change or be
3217 removed without notice.
3218 Creates and initialises a new lexer/parser state object,
3220 supplying a context in which to lex and parse from a new source
3221 of Perl code. A pointer to the new state object is placed in
3222 "PL_parser". An entry is made on the save stack so that upon
3223 unwinding, the new state object will be destroyed and the
3224 former value of "PL_parser" will be restored. Nothing else
3225 need be done to clean up the parsing context.
3226 The code to be parsed comes from "line" and "rsfp". "line", if
3228 non-null, provides a string (in SV form) containing code to be
3229 parsed. A copy of the string is made, so subsequent
3230 modification of "line" does not affect parsing. "rsfp", if
3231 non-null, provides an input stream from which code will be read
3232 to be parsed. If both are non-null, the code in "line" comes
3233 first and must consist of complete lines of input, and "rsfp"
3234 supplies the remainder of the source.
3235 The "flags" parameter is reserved for future use. Currently it
3237 is only used by perl internally, so extensions should always
3238 pass zero.
3239 void lex_start(SV *line, PerlIO *rsfp, U32 flags)
3241 lex_stuff_pv
3243 NOTE: this function is experimental and may change or be
3244 removed without notice.
3245 Insert characters into the lexer buffer ("PL_parser->linestr"),
3247 immediately after the current lexing point
3248 ("PL_parser->bufptr"), reallocating the buffer if necessary.
3249 This means that lexing code that runs later will see the
3250 characters as if they had appeared in the input. It is not
3251 recommended to do this as part of normal parsing, and most uses
3252 of this facility run the risk of the inserted characters being
3253 interpreted in an unintended manner.
3254 The string to be inserted is represented by octets starting at
3256 "pv" and continuing to the first nul. These octets are
3257 interpreted as either UTF-8 or Latin-1, according to whether
3258 the "LEX_STUFF_UTF8" flag is set in "flags". The characters
3259 are recoded for the lexer buffer, according to how the buffer
3260 is currently being interpreted ("lex_bufutf8"). If it is not
3261 convenient to nul-terminate a string to be inserted, the
3262 "lex_stuff_pvn" function is more appropriate.
3263 void lex_stuff_pv(const char *pv, U32 flags)
3265 lex_stuff_pvn
3267 NOTE: this function is experimental and may change or be
3268 removed without notice.
3269 Insert characters into the lexer buffer ("PL_parser->linestr"),
3271 immediately after the current lexing point
3272 ("PL_parser->bufptr"), reallocating the buffer if necessary.
3273 This means that lexing code that runs later will see the
3274 characters as if they had appeared in the input. It is not
3275 recommended to do this as part of normal parsing, and most uses
3276 of this facility run the risk of the inserted characters being
3277 interpreted in an unintended manner.
3278 The string to be inserted is represented by "len" octets
3280 starting at "pv". These octets are interpreted as either UTF-8
3281 or Latin-1, according to whether the "LEX_STUFF_UTF8" flag is
3282 set in "flags". The characters are recoded for the lexer
3283 buffer, according to how the buffer is currently being
3284 interpreted ("lex_bufutf8"). If a string to be inserted is
3285 available as a Perl scalar, the "lex_stuff_sv" function is more
3286 convenient.
3287 void lex_stuff_pvn(const char *pv, STRLEN len,
3289 U32 flags)
3290 lex_stuff_pvs
3292 NOTE: this function is experimental and may change or be
3293 removed without notice.
3294 Like "lex_stuff_pvn", but takes a "NUL"-terminated literal
3296 string instead of a string/length pair.
3297 void lex_stuff_pvs(const char *pv, U32 flags)
3299 lex_stuff_sv
3301 NOTE: this function is experimental and may change or be
3302 removed without notice.
3303 Insert characters into the lexer buffer ("PL_parser->linestr"),
3305 immediately after the current lexing point
3306 ("PL_parser->bufptr"), reallocating the buffer if necessary.
3307 This means that lexing code that runs later will see the
3308 characters as if they had appeared in the input. It is not
3309 recommended to do this as part of normal parsing, and most uses
3310 of this facility run the risk of the inserted characters being
3311 interpreted in an unintended manner.
3312 The string to be inserted is the string value of "sv". The
3314 characters are recoded for the lexer buffer, according to how
3315 the buffer is currently being interpreted ("lex_bufutf8"). If
3316 a string to be inserted is not already a Perl scalar, the
3317 "lex_stuff_pvn" function avoids the need to construct a scalar.
3318 void lex_stuff_sv(SV *sv, U32 flags)
3320 lex_unstuff
3322 NOTE: this function is experimental and may change or be
3323 removed without notice.
3324 Discards text about to be lexed, from "PL_parser->bufptr" up to
3326 "ptr". Text following "ptr" will be moved, and the buffer
3327 shortened. This hides the discarded text from any lexing code
3328 that runs later, as if the text had never appeared.
3329 This is not the normal way to consume lexed text. For that,
3331 use "lex_read_to".
3332 void lex_unstuff(char *ptr)
3334 parse_arithexpr
3336 NOTE: this function is experimental and may change or be
3337 removed without notice.
3338 Parse a Perl arithmetic expression. This may contain operators
3340 of precedence down to the bit shift operators. The expression
3341 must be followed (and thus terminated) either by a comparison
3342 or lower-precedence operator or by something that would
3343 normally terminate an expression such as semicolon. If "flags"
3344 has the "PARSE_OPTIONAL" bit set, then the expression is
3345 optional, otherwise it is mandatory. It is up to the caller to
3346 ensure that the dynamic parser state ("PL_parser" et al) is
3347 correctly set to reflect the source of the code to be parsed
3348 and the lexical context for the expression.
3349 The op tree representing the expression is returned. If an
3351 optional expression is absent, a null pointer is returned,
3352 otherwise the pointer will be non-null.
3353 If an error occurs in parsing or compilation, in most cases a
3355 valid op tree is returned anyway. The error is reflected in
3356 the parser state, normally resulting in a single exception at
3357 the top level of parsing which covers all the compilation
3358 errors that occurred. Some compilation errors, however, will
3359 throw an exception immediately.
3360 OP * parse_arithexpr(U32 flags)
3362 parse_barestmt
3364 NOTE: this function is experimental and may change or be
3365 removed without notice.
3366 Parse a single unadorned Perl statement. This may be a normal
3368 imperative statement or a declaration that has compile-time
3369 effect. It does not include any label or other affixture. It
3370 is up to the caller to ensure that the dynamic parser state
3371 ("PL_parser" et al) is correctly set to reflect the source of
3372 the code to be parsed and the lexical context for the
3373 statement.
3374 The op tree representing the statement is returned. This may
3376 be a null pointer if the statement is null, for example if it
3377 was actually a subroutine definition (which has compile-time
3378 side effects). If not null, it will be ops directly
3379 implementing the statement, suitable to pass to "newSTATEOP".
3380 It will not normally include a "nextstate" or equivalent op
3381 (except for those embedded in a scope contained entirely within
3382 the statement).
3383 If an error occurs in parsing or compilation, in most cases a
3385 valid op tree (most likely null) is returned anyway. The error
3386 is reflected in the parser state, normally resulting in a
3387 single exception at the top level of parsing which covers all
3388 the compilation errors that occurred. Some compilation errors,
3389 however, will throw an exception immediately.
3390 The "flags" parameter is reserved for future use, and must
3392 always be zero.
3393 OP * parse_barestmt(U32 flags)
3395 parse_block
3397 NOTE: this function is experimental and may change or be
3398 removed without notice.
3399 Parse a single complete Perl code block. This consists of an
3401 opening brace, a sequence of statements, and a closing brace.
3402 The block constitutes a lexical scope, so "my" variables and
3403 various compile-time effects can be contained within it. It is
3404 up to the caller to ensure that the dynamic parser state
3405 ("PL_parser" et al) is correctly set to reflect the source of
3406 the code to be parsed and the lexical context for the
3407 statement.
3408 The op tree representing the code block is returned. This is
3410 always a real op, never a null pointer. It will normally be a
3411 "lineseq" list, including "nextstate" or equivalent ops. No
3412 ops to construct any kind of runtime scope are included by
3413 virtue of it being a block.
3414 If an error occurs in parsing or compilation, in most cases a
3416 valid op tree (most likely null) is returned anyway. The error
3417 is reflected in the parser state, normally resulting in a
3418 single exception at the top level of parsing which covers all
3419 the compilation errors that occurred. Some compilation errors,
3420 however, will throw an exception immediately.
3421 The "flags" parameter is reserved for future use, and must
3423 always be zero.
3424 OP * parse_block(U32 flags)
3426 parse_fullexpr
3428 NOTE: this function is experimental and may change or be
3429 removed without notice.
3430 Parse a single complete Perl expression. This allows the full
3432 expression grammar, including the lowest-precedence operators
3433 such as "or". The expression must be followed (and thus
3434 terminated) by a token that an expression would normally be
3435 terminated by: end-of-file, closing bracketing punctuation,
3436 semicolon, or one of the keywords that signals a postfix
3437 expression-statement modifier. If "flags" has the
3438 "PARSE_OPTIONAL" bit set, then the expression is optional,
3439 otherwise it is mandatory. It is up to the caller to ensure
3440 that the dynamic parser state ("PL_parser" et al) is correctly
3441 set to reflect the source of the code to be parsed and the
3442 lexical context for the expression.
3443 The op tree representing the expression is returned. If an
3445 optional expression is absent, a null pointer is returned,
3446 otherwise the pointer will be non-null.
3447 If an error occurs in parsing or compilation, in most cases a
3449 valid op tree is returned anyway. The error is reflected in
3450 the parser state, normally resulting in a single exception at
3451 the top level of parsing which covers all the compilation
3452 errors that occurred. Some compilation errors, however, will
3453 throw an exception immediately.
3454 OP * parse_fullexpr(U32 flags)
3456 parse_fullstmt
3458 NOTE: this function is experimental and may change or be
3459 removed without notice.
3460 Parse a single complete Perl statement. This may be a normal
3462 imperative statement or a declaration that has compile-time
3463 effect, and may include optional labels. It is up to the
3464 caller to ensure that the dynamic parser state ("PL_parser" et
3465 al) is correctly set to reflect the source of the code to be
3466 parsed and the lexical context for the statement.
3467 The op tree representing the statement is returned. This may
3469 be a null pointer if the statement is null, for example if it
3470 was actually a subroutine definition (which has compile-time
3471 side effects). If not null, it will be the result of a
3472 "newSTATEOP" call, normally including a "nextstate" or
3473 equivalent op.
3474 If an error occurs in parsing or compilation, in most cases a
3476 valid op tree (most likely null) is returned anyway. The error
3477 is reflected in the parser state, normally resulting in a
3478 single exception at the top level of parsing which covers all
3479 the compilation errors that occurred. Some compilation errors,
3480 however, will throw an exception immediately.
3481 The "flags" parameter is reserved for future use, and must
3483 always be zero.
3484 OP * parse_fullstmt(U32 flags)
3486 parse_label
3488 NOTE: this function is experimental and may change or be
3489 removed without notice.
3490 Parse a single label, possibly optional, of the type that may
3492 prefix a Perl statement. It is up to the caller to ensure that
3493 the dynamic parser state ("PL_parser" et al) is correctly set
3494 to reflect the source of the code to be parsed. If "flags" has
3495 the "PARSE_OPTIONAL" bit set, then the label is optional,
3496 otherwise it is mandatory.
3497 The name of the label is returned in the form of a fresh
3499 scalar. If an optional label is absent, a null pointer is
3500 returned.
3501 If an error occurs in parsing, which can only occur if the
3503 label is mandatory, a valid label is returned anyway. The
3504 error is reflected in the parser state, normally resulting in a
3505 single exception at the top level of parsing which covers all
3506 the compilation errors that occurred.
3507 SV * parse_label(U32 flags)
3509 parse_listexpr
3511 NOTE: this function is experimental and may change or be
3512 removed without notice.
3513 Parse a Perl list expression. This may contain operators of
3515 precedence down to the comma operator. The expression must be
3516 followed (and thus terminated) either by a low-precedence logic
3517 operator such as "or" or by something that would normally
3518 terminate an expression such as semicolon. If "flags" has the
3519 "PARSE_OPTIONAL" bit set, then the expression is optional,
3520 otherwise it is mandatory. It is up to the caller to ensure
3521 that the dynamic parser state ("PL_parser" et al) is correctly
3522 set to reflect the source of the code to be parsed and the
3523 lexical context for the expression.
3524 The op tree representing the expression is returned. If an
3526 optional expression is absent, a null pointer is returned,
3527 otherwise the pointer will be non-null.
3528 If an error occurs in parsing or compilation, in most cases a
3530 valid op tree is returned anyway. The error is reflected in
3531 the parser state, normally resulting in a single exception at
3532 the top level of parsing which covers all the compilation
3533 errors that occurred. Some compilation errors, however, will
3534 throw an exception immediately.
3535 OP * parse_listexpr(U32 flags)
3537 parse_stmtseq
3539 NOTE: this function is experimental and may change or be
3540 removed without notice.
3541 Parse a sequence of zero or more Perl statements. These may be
3543 normal imperative statements, including optional labels, or
3544 declarations that have compile-time effect, or any mixture
3545 thereof. The statement sequence ends when a closing brace or
3546 end-of-file is encountered in a place where a new statement
3547 could have validly started. It is up to the caller to ensure
3548 that the dynamic parser state ("PL_parser" et al) is correctly
3549 set to reflect the source of the code to be parsed and the
3550 lexical context for the statements.
3551 The op tree representing the statement sequence is returned.
3553 This may be a null pointer if the statements were all null, for
3554 example if there were no statements or if there were only
3555 subroutine definitions (which have compile-time side effects).
3556 If not null, it will be a "lineseq" list, normally including
3557 "nextstate" or equivalent ops.
3558 If an error occurs in parsing or compilation, in most cases a
3560 valid op tree is returned anyway. The error is reflected in
3561 the parser state, normally resulting in a single exception at
3562 the top level of parsing which covers all the compilation
3563 errors that occurred. Some compilation errors, however, will
3564 throw an exception immediately.
3565 The "flags" parameter is reserved for future use, and must
3567 always be zero.
3568 OP * parse_stmtseq(U32 flags)
3570 parse_termexpr
3572 NOTE: this function is experimental and may change or be
3573 removed without notice.
3574 Parse a Perl term expression. This may contain operators of
3576 precedence down to the assignment operators. The expression
3577 must be followed (and thus terminated) either by a comma or
3578 lower-precedence operator or by something that would normally
3579 terminate an expression such as semicolon. If "flags" has the
3580 "PARSE_OPTIONAL" bit set, then the expression is optional,
3581 otherwise it is mandatory. It is up to the caller to ensure
3582 that the dynamic parser state ("PL_parser" et al) is correctly
3583 set to reflect the source of the code to be parsed and the
3584 lexical context for the expression.
3585 The op tree representing the expression is returned. If an
3587 optional expression is absent, a null pointer is returned,
3588 otherwise the pointer will be non-null.
3589 If an error occurs in parsing or compilation, in most cases a
3591 valid op tree is returned anyway. The error is reflected in
3592 the parser state, normally resulting in a single exception at
3593 the top level of parsing which covers all the compilation
3594 errors that occurred. Some compilation errors, however, will
3595 throw an exception immediately.
3596 OP * parse_termexpr(U32 flags)
3598 PL_parser
3600 Pointer to a structure encapsulating the state of the parsing
3601 operation currently in progress. The pointer can be locally
3602 changed to perform a nested parse without interfering with the
3603 state of an outer parse. Individual members of "PL_parser"
3604 have their own documentation.
3605 PL_parser->bufend
3607 NOTE: this function is experimental and may change or be
3608 removed without notice.
3609 Direct pointer to the end of the chunk of text currently being
3611 lexed, the end of the lexer buffer. This is equal to
3612 "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)". A
3613 "NUL" character (zero octet) is always located at the end of
3614 the buffer, and does not count as part of the buffer's
3615 contents.
3616 PL_parser->bufptr
3618 NOTE: this function is experimental and may change or be
3619 removed without notice.
3620 Points to the current position of lexing inside the lexer
3622 buffer. Characters around this point may be freely examined,
3623 within the range delimited by "SvPVX("PL_parser->linestr")" and
3624 "PL_parser->bufend". The octets of the buffer may be intended
3625 to be interpreted as either UTF-8 or Latin-1, as indicated by
3626 "lex_bufutf8".
3627 Lexing code (whether in the Perl core or not) moves this
3629 pointer past the characters that it consumes. It is also
3630 expected to perform some bookkeeping whenever a newline
3631 character is consumed. This movement can be more conveniently
3632 performed by the function "lex_read_to", which handles newlines
3633 appropriately.
3634 Interpretation of the buffer's octets can be abstracted out by
3636 using the slightly higher-level functions "lex_peek_unichar"
3637 and "lex_read_unichar".
3638 PL_parser->linestart
3640 NOTE: this function is experimental and may change or be
3641 removed without notice.
3642 Points to the start of the current line inside the lexer
3644 buffer. This is useful for indicating at which column an error
3645 occurred, and not much else. This must be updated by any
3646 lexing code that consumes a newline; the function "lex_read_to"
3647 handles this detail.
3648 PL_parser->linestr
3650 NOTE: this function is experimental and may change or be
3651 removed without notice.
3652 Buffer scalar containing the chunk currently under
3654 consideration of the text currently being lexed. This is
3655 always a plain string scalar (for which "SvPOK" is true). It
3656 is not intended to be used as a scalar by normal scalar means;
3657 instead refer to the buffer directly by the pointer variables
3658 described below.
3659 The lexer maintains various "char*" pointers to things in the
3661 "PL_parser->linestr" buffer. If "PL_parser->linestr" is ever
3662 reallocated, all of these pointers must be updated. Don't
3663 attempt to do this manually, but rather use "lex_grow_linestr"
3664 if you need to reallocate the buffer.
3665 The content of the text chunk in the buffer is commonly exactly
3667 one complete line of input, up to and including a newline
3668 terminator, but there are situations where it is otherwise.
3669 The octets of the buffer may be intended to be interpreted as
3670 either UTF-8 or Latin-1. The function "lex_bufutf8" tells you
3671 which. Do not use the "SvUTF8" flag on this scalar, which may
3672 disagree with it.
3673 For direct examination of the buffer, the variable
3675 "PL_parser->bufend" points to the end of the buffer. The
3676 current lexing position is pointed to by "PL_parser->bufptr".
3677 Direct use of these pointers is usually preferable to
3678 examination of the scalar through normal scalar means.
3679
3681 DECLARATION_FOR_LC_NUMERIC_MANIPULATION
3682 This macro should be used as a statement. It declares a
3683 private variable (whose name begins with an underscore) that is
3684 needed by the other macros in this section. Failing to include
3685 this correctly should lead to a syntax error. For
3686 compatibility with C89 C compilers it should be placed in a
3687 block before any executable statements.
3688 void DECLARATION_FOR_LC_NUMERIC_MANIPULATION
3690 RESTORE_LC_NUMERIC
3692 This is used in conjunction with one of the macros
3693 "STORE_LC_NUMERIC_SET_TO_NEEDED" and
3694 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
3695 to properly restore the "LC_NUMERIC" state.
3697 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
3699 been made to declare at compile time a private variable used by
3700 this macro and the two "STORE" ones. This macro should be
3701 called as a single statement, not an expression, but with an
3702 empty argument list, like this:
3703 {
3705 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
3706 ...
3707 RESTORE_LC_NUMERIC();
3708 ...
3709 }
3710 void RESTORE_LC_NUMERIC()
3712 STORE_LC_NUMERIC_FORCE_TO_UNDERLYING
3714 This is used by XS code that that is "LC_NUMERIC" locale-aware
3715 to force the locale for category "LC_NUMERIC" to be what perl
3716 thinks is the current underlying locale. (The perl interpreter
3717 could be wrong about what the underlying locale actually is if
3718 some C or XS code has called the C library function
3719 setlocale(3) behind its back; calling "sync_locale" before
3720 calling this macro will update perl's records.)
3721 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
3723 been made to declare at compile time a private variable used by
3724 this macro. This macro should be called as a single statement,
3725 not an expression, but with an empty argument list, like this:
3726 {
3728 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
3729 ...
3730 STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
3731 ...
3732 RESTORE_LC_NUMERIC();
3733 ...
3734 }
3735 The private variable is used to save the current locale state,
3737 so that the requisite matching call to "RESTORE_LC_NUMERIC" can
3738 restore it.
3739 void STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
3741 STORE_LC_NUMERIC_SET_TO_NEEDED
3743 This is used to help wrap XS or C code that that is
3744 "LC_NUMERIC" locale-aware. This locale category is generally
3745 kept set to the C locale by Perl for backwards compatibility,
3746 and because most XS code that reads floating point values can
3747 cope only with the decimal radix character being a dot.
3748 This macro makes sure the current "LC_NUMERIC" state is set
3750 properly, to be aware of locale if the call to the XS or C code
3751 from the Perl program is from within the scope of a
3752 "use locale"; or to ignore locale if the call is instead from
3753 outside such scope.
3754 This macro is the start of wrapping the C or XS code; the wrap
3756 ending is done by calling the "RESTORE_LC_NUMERIC" macro after
3757 the operation. Otherwise the state can be changed that will
3758 adversely affect other XS code.
3759 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
3761 been made to declare at compile time a private variable used by
3762 this macro. This macro should be called as a single statement,
3763 not an expression, but with an empty argument list, like this:
3764 {
3766 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
3767 ...
3768 STORE_LC_NUMERIC_SET_TO_NEEDED();
3769 ...
3770 RESTORE_LC_NUMERIC();
3771 ...
3772 }
3773 void STORE_LC_NUMERIC_SET_TO_NEEDED()
3775 sync_locale
3777 Changing the program's locale should be avoided by XS code.
3778 Nevertheless, certain non-Perl libraries called from XS, such
3779 as "Gtk" do so. When this happens, Perl needs to be told that
3780 the locale has changed. Use this function to do so, before
3781 returning to Perl.
3782 void sync_locale()
3784
3786 mg_clear
3787 Clear something magical that the SV represents. See
3788 "sv_magic".
3789 int mg_clear(SV* sv)
3791 mg_copy Copies the magic from one SV to another. See "sv_magic".
3793 int mg_copy(SV *sv, SV *nsv, const char *key,
3795 I32 klen)
3796 mg_find Finds the magic pointer for "type" matching the SV. See
3798 "sv_magic".
3799 MAGIC* mg_find(const SV* sv, int type)
3801 mg_findext
3803 Finds the magic pointer of "type" with the given "vtbl" for the
3804 "SV". See "sv_magicext".
3805 MAGIC* mg_findext(const SV* sv, int type,
3807 const MGVTBL *vtbl)
3808 mg_free Free any magic storage used by the SV. See "sv_magic".
3810 int mg_free(SV* sv)
3812 mg_free_type
3814 Remove any magic of type "how" from the SV "sv". See
3815 "sv_magic".
3816 void mg_free_type(SV *sv, int how)
3818 mg_get Do magic before a value is retrieved from the SV. The type of
3820 SV must be >= "SVt_PVMG". See "sv_magic".
3821 int mg_get(SV* sv)
3823 mg_length
3825 DEPRECATED! It is planned to remove this function from a
3826 future release of Perl. Do not use it for new code; remove it
3827 from existing code.
3828 Reports on the SV's length in bytes, calling length magic if
3830 available, but does not set the UTF8 flag on "sv". It will
3831 fall back to 'get' magic if there is no 'length' magic, but
3832 with no indication as to whether it called 'get' magic. It
3833 assumes "sv" is a "PVMG" or higher. Use "sv_len()" instead.
3834 U32 mg_length(SV* sv)
3836 mg_magical
3838 Turns on the magical status of an SV. See "sv_magic".
3839 void mg_magical(SV* sv)
3841 mg_set Do magic after a value is assigned to the SV. See "sv_magic".
3843 int mg_set(SV* sv)
3845 SvGETMAGIC
3847 Invokes "mg_get" on an SV if it has 'get' magic. For example,
3848 this will call "FETCH" on a tied variable. This macro
3849 evaluates its argument more than once.
3850 void SvGETMAGIC(SV* sv)
3852 SvLOCK Arranges for a mutual exclusion lock to be obtained on "sv" if
3854 a suitable module has been loaded.
3855 void SvLOCK(SV* sv)
3857 SvSETMAGIC
3859 Invokes "mg_set" on an SV if it has 'set' magic. This is
3860 necessary after modifying a scalar, in case it is a magical
3861 variable like $| or a tied variable (it calls "STORE"). This
3862 macro evaluates its argument more than once.
3863 void SvSETMAGIC(SV* sv)
3865 SvSetMagicSV
3867 Like "SvSetSV", but does any set magic required afterwards.
3868 void SvSetMagicSV(SV* dsv, SV* ssv)
3870 SvSetMagicSV_nosteal
3872 Like "SvSetSV_nosteal", but does any set magic required
3873 afterwards.
3874 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
3876 SvSetSV Calls "sv_setsv" if "dsv" is not the same as "ssv". May
3878 evaluate arguments more than once. Does not handle 'set' magic
3879 on the destination SV.
3880 void SvSetSV(SV* dsv, SV* ssv)
3882 SvSetSV_nosteal
3884 Calls a non-destructive version of "sv_setsv" if "dsv" is not
3885 the same as "ssv". May evaluate arguments more than once.
3886 void SvSetSV_nosteal(SV* dsv, SV* ssv)
3888 SvSHARE Arranges for "sv" to be shared between threads if a suitable
3890 module has been loaded.
3891 void SvSHARE(SV* sv)
3893 SvUNLOCK
3895 Releases a mutual exclusion lock on "sv" if a suitable module
3896 has been loaded.
3897 void SvUNLOCK(SV* sv)
3899
3901 Copy The XSUB-writer's interface to the C "memcpy" function. The
3902 "src" is the source, "dest" is the destination, "nitems" is the
3903 number of items, and "type" is the type. May fail on
3904 overlapping copies. See also "Move".
3905 void Copy(void* src, void* dest, int nitems, type)
3907 CopyD Like "Copy" but returns "dest". Useful for encouraging
3909 compilers to tail-call optimise.
3910 void * CopyD(void* src, void* dest, int nitems, type)
3912 Move The XSUB-writer's interface to the C "memmove" function. The
3914 "src" is the source, "dest" is the destination, "nitems" is the
3915 number of items, and "type" is the type. Can do overlapping
3916 moves. See also "Copy".
3917 void Move(void* src, void* dest, int nitems, type)
3919 MoveD Like "Move" but returns "dest". Useful for encouraging
3921 compilers to tail-call optimise.
3922 void * MoveD(void* src, void* dest, int nitems, type)
3924 Newx The XSUB-writer's interface to the C "malloc" function.
3926 Memory obtained by this should ONLY be freed with "Safefree".
3928 In 5.9.3, Newx() and friends replace the older New() API, and
3930 drops the first parameter, x, a debug aid which allowed callers
3931 to identify themselves. This aid has been superseded by a new
3932 build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in
3933 perlhacktips). The older API is still there for use in XS
3934 modules supporting older perls.
3935 void Newx(void* ptr, int nitems, type)
3937 Newxc The XSUB-writer's interface to the C "malloc" function, with
3939 cast. See also "Newx".
3940 Memory obtained by this should ONLY be freed with "Safefree".
3942 void Newxc(void* ptr, int nitems, type, cast)
3944 Newxz The XSUB-writer's interface to the C "malloc" function. The
3946 allocated memory is zeroed with "memzero". See also "Newx".
3947 Memory obtained by this should ONLY be freed with "Safefree".
3949 void Newxz(void* ptr, int nitems, type)
3951 Poison PoisonWith(0xEF) for catching access to freed memory.
3953 void Poison(void* dest, int nitems, type)
3955 PoisonFree
3957 PoisonWith(0xEF) for catching access to freed memory.
3958 void PoisonFree(void* dest, int nitems, type)
3960 PoisonNew
3962 PoisonWith(0xAB) for catching access to allocated but
3963 uninitialized memory.
3964 void PoisonNew(void* dest, int nitems, type)
3966 PoisonWith
3968 Fill up memory with a byte pattern (a byte repeated over and
3969 over again) that hopefully catches attempts to access
3970 uninitialized memory.
3971 void PoisonWith(void* dest, int nitems, type,
3973 U8 byte)
3974 Renew The XSUB-writer's interface to the C "realloc" function.
3976 Memory obtained by this should ONLY be freed with "Safefree".
3978 void Renew(void* ptr, int nitems, type)
3980 Renewc The XSUB-writer's interface to the C "realloc" function, with
3982 cast.
3983 Memory obtained by this should ONLY be freed with "Safefree".
3985 void Renewc(void* ptr, int nitems, type, cast)
3987 Safefree
3989 The XSUB-writer's interface to the C "free" function.
3990 This should ONLY be used on memory obtained using "Newx" and
3992 friends.
3993 void Safefree(void* ptr)
3995 savepv Perl's version of "strdup()". Returns a pointer to a newly
3997 allocated string which is a duplicate of "pv". The size of the
3998 string is determined by "strlen()", which means it may not
3999 contain embedded "NUL" characters and must have a trailing
4000 "NUL". The memory allocated for the new string can be freed
4001 with the "Safefree()" function.
4002 On some platforms, Windows for example, all allocated memory
4004 owned by a thread is deallocated when that thread ends. So if
4005 you need that not to happen, you need to use the shared memory
4006 functions, such as "savesharedpv".
4007 char* savepv(const char* pv)
4009 savepvn Perl's version of what "strndup()" would be if it existed.
4011 Returns a pointer to a newly allocated string which is a
4012 duplicate of the first "len" bytes from "pv", plus a trailing
4013 "NUL" byte. The memory allocated for the new string can be
4014 freed with the "Safefree()" function.
4015 On some platforms, Windows for example, all allocated memory
4017 owned by a thread is deallocated when that thread ends. So if
4018 you need that not to happen, you need to use the shared memory
4019 functions, such as "savesharedpvn".
4020 char* savepvn(const char* pv, I32 len)
4022 savepvs Like "savepvn", but takes a "NUL"-terminated literal string
4024 instead of a string/length pair.
4025 char* savepvs(const char* s)
4027 savesharedpv
4029 A version of "savepv()" which allocates the duplicate string in
4030 memory which is shared between threads.
4031 char* savesharedpv(const char* pv)
4033 savesharedpvn
4035 A version of "savepvn()" which allocates the duplicate string
4036 in memory which is shared between threads. (With the specific
4037 difference that a "NULL" pointer is not acceptable)
4038 char* savesharedpvn(const char *const pv,
4040 const STRLEN len)
4041 savesharedpvs
4043 A version of "savepvs()" which allocates the duplicate string
4044 in memory which is shared between threads.
4045 char* savesharedpvs(const char* s)
4047 savesharedsvpv
4049 A version of "savesharedpv()" which allocates the duplicate
4050 string in memory which is shared between threads.
4051 char* savesharedsvpv(SV *sv)
4053 savesvpv
4055 A version of "savepv()"/"savepvn()" which gets the string to
4056 duplicate from the passed in SV using "SvPV()"
4057 On some platforms, Windows for example, all allocated memory
4059 owned by a thread is deallocated when that thread ends. So if
4060 you need that not to happen, you need to use the shared memory
4061 functions, such as "savesharedsvpv".
4062 char* savesvpv(SV* sv)
4064 StructCopy
4066 This is an architecture-independent macro to copy one structure
4067 to another.
4068 void StructCopy(type *src, type *dest, type)
4070 Zero The XSUB-writer's interface to the C "memzero" function. The
4072 "dest" is the destination, "nitems" is the number of items, and
4073 "type" is the type.
4074 void Zero(void* dest, int nitems, type)
4076 ZeroD Like "Zero" but returns dest. Useful for encouraging compilers
4078 to tail-call optimise.
4079 void * ZeroD(void* dest, int nitems, type)
4081
4083 dump_c_backtrace
4084 Dumps the C backtrace to the given "fp".
4085 Returns true if a backtrace could be retrieved, false if not.
4087 bool dump_c_backtrace(PerlIO* fp, int max_depth,
4089 int skip)
4090 fbm_compile
4092 Analyses the string in order to make fast searches on it using
4093 "fbm_instr()" -- the Boyer-Moore algorithm.
4094 void fbm_compile(SV* sv, U32 flags)
4096 fbm_instr
4098 Returns the location of the SV in the string delimited by "big"
4099 and "bigend" ("bigend") is the char following the last char).
4100 It returns "NULL" if the string can't be found. The "sv" does
4101 not have to be "fbm_compiled", but the search will not be as
4102 fast then.
4103 char* fbm_instr(unsigned char* big,
4105 unsigned char* bigend, SV* littlestr,
4106 U32 flags)
4107 foldEQ Returns true if the leading "len" bytes of the strings "s1" and
4109 "s2" are the same case-insensitively; false otherwise.
4110 Uppercase and lowercase ASCII range bytes match themselves and
4111 their opposite case counterparts. Non-cased and non-ASCII
4112 range bytes match only themselves.
4113 I32 foldEQ(const char* a, const char* b, I32 len)
4115 foldEQ_locale
4117 Returns true if the leading "len" bytes of the strings "s1" and
4118 "s2" are the same case-insensitively in the current locale;
4119 false otherwise.
4120 I32 foldEQ_locale(const char* a, const char* b,
4122 I32 len)
4123 form Takes a sprintf-style format pattern and conventional (non-SV)
4125 arguments and returns the formatted string.
4126 (char *) Perl_form(pTHX_ const char* pat, ...)
4128 can be used any place a string (char *) is required:
4130 char * s = Perl_form("%d.%d",major,minor);
4132 Uses a single private buffer so if you want to format several
4134 strings you must explicitly copy the earlier strings away (and
4135 free the copies when you are done).
4136 char* form(const char* pat, ...)
4138 getcwd_sv
4140 Fill "sv" with current working directory
4141 int getcwd_sv(SV* sv)
4143 get_c_backtrace_dump
4145 Returns a SV containing a dump of "depth" frames of the call
4146 stack, skipping the "skip" innermost ones. "depth" of 20 is
4147 usually enough.
4148 The appended output looks like:
4150 ... 1 10e004812:0082 Perl_croak util.c:1716
4152 /usr/bin/perl 2 10df8d6d2:1d72 perl_parse perl.c:3975
4153 /usr/bin/perl ...
4154 The fields are tab-separated. The first column is the depth
4156 (zero being the innermost non-skipped frame). In the
4157 hex:offset, the hex is where the program counter was in
4158 "S_parse_body", and the :offset (might be missing) tells how
4159 much inside the "S_parse_body" the program counter was.
4160 The "util.c:1716" is the source code file and line number.
4162 The /usr/bin/perl is obvious (hopefully).
4164 Unknowns are "-". Unknowns can happen unfortunately quite
4166 easily: if the platform doesn't support retrieving the
4167 information; if the binary is missing the debug information; if
4168 the optimizer has transformed the code by for example inlining.
4169 SV* get_c_backtrace_dump(int max_depth, int skip)
4171 ibcmp This is a synonym for "(! foldEQ())"
4173 I32 ibcmp(const char* a, const char* b, I32 len)
4175 ibcmp_locale
4177 This is a synonym for "(! foldEQ_locale())"
4178 I32 ibcmp_locale(const char* a, const char* b,
4180 I32 len)
4181 is_safe_syscall
4183 Test that the given "pv" doesn't contain any internal "NUL"
4184 characters. If it does, set "errno" to "ENOENT", optionally
4185 warn, and return FALSE.
4186 Return TRUE if the name is safe.
4188 Used by the "IS_SAFE_SYSCALL()" macro.
4190 bool is_safe_syscall(const char *pv, STRLEN len,
4192 const char *what,
4193 const char *op_name)
4194 memEQ Test two buffers (which may contain embedded "NUL" characters,
4196 to see if they are equal. The "len" parameter indicates the
4197 number of bytes to compare. Returns zero if equal, or non-zero
4198 if non-equal.
4199 bool memEQ(char* s1, char* s2, STRLEN len)
4201 memNE Test two buffers (which may contain embedded "NUL" characters,
4203 to see if they are not equal. The "len" parameter indicates
4204 the number of bytes to compare. Returns zero if non-equal, or
4205 non-zero if equal.
4206 bool memNE(char* s1, char* s2, STRLEN len)
4208 mess Take a sprintf-style format pattern and argument list. These
4210 are used to generate a string message. If the message does not
4211 end with a newline, then it will be extended with some
4212 indication of the current location in the code, as described
4213 for "mess_sv".
4214 Normally, the resulting message is returned in a new mortal SV.
4216 During global destruction a single SV may be shared between
4217 uses of this function.
4218 SV * mess(const char *pat, ...)
4220 mess_sv Expands a message, intended for the user, to include an
4222 indication of the current location in the code, if the message
4223 does not already appear to be complete.
4224 "basemsg" is the initial message or object. If it is a
4226 reference, it will be used as-is and will be the result of this
4227 function. Otherwise it is used as a string, and if it already
4228 ends with a newline, it is taken to be complete, and the result
4229 of this function will be the same string. If the message does
4230 not end with a newline, then a segment such as "at foo.pl line
4231 37" will be appended, and possibly other clauses indicating the
4232 current state of execution. The resulting message will end
4233 with a dot and a newline.
4234 Normally, the resulting message is returned in a new mortal SV.
4236 During global destruction a single SV may be shared between
4237 uses of this function. If "consume" is true, then the function
4238 is permitted (but not required) to modify and return "basemsg"
4239 instead of allocating a new SV.
4240 SV * mess_sv(SV *basemsg, bool consume)
4242 my_snprintf
4244 The C library "snprintf" functionality, if available and
4245 standards-compliant (uses "vsnprintf", actually). However, if
4246 the "vsnprintf" is not available, will unfortunately use the
4247 unsafe "vsprintf" which can overrun the buffer (there is an
4248 overrun check, but that may be too late). Consider using
4249 "sv_vcatpvf" instead, or getting "vsnprintf".
4250 int my_snprintf(char *buffer, const Size_t len,
4252 const char *format, ...)
4253 my_sprintf
4255 The C library "sprintf", wrapped if necessary, to ensure that
4256 it will return the length of the string written to the buffer.
4257 Only rare pre-ANSI systems need the wrapper function - usually
4258 this is a direct call to "sprintf".
4259 int my_sprintf(char *buffer, const char *pat, ...)
4261 my_strlcat
4263 The C library "strlcat" if available, or a Perl implementation
4264 of it. This operates on C "NUL"-terminated strings.
4265 "my_strlcat()" appends string "src" to the end of "dst". It
4267 will append at most "size - strlen(dst) - 1" characters. It
4268 will then "NUL"-terminate, unless "size" is 0 or the original
4269 "dst" string was longer than "size" (in practice this should
4270 not happen as it means that either "size" is incorrect or that
4271 "dst" is not a proper "NUL"-terminated string).
4272 Note that "size" is the full size of the destination buffer and
4274 the result is guaranteed to be "NUL"-terminated if there is
4275 room. Note that room for the "NUL" should be included in
4276 "size".
4277 The return value is the total length that "dst" would have if
4279 "size" is sufficiently large. Thus it is the initial length of
4280 "dst" plus the length of "src". If "size" is smaller than the
4281 return, the excess was not appended.
4282 Size_t my_strlcat(char *dst, const char *src,
4284 Size_t size)
4285 my_strlcpy
4287 The C library "strlcpy" if available, or a Perl implementation
4288 of it. This operates on C "NUL"-terminated strings.
4289 "my_strlcpy()" copies up to "size - 1" characters from the
4291 string "src" to "dst", "NUL"-terminating the result if "size"
4292 is not 0.
4293 The return value is the total length "src" would be if the copy
4295 completely succeeded. If it is larger than "size", the excess
4296 was not copied.
4297 Size_t my_strlcpy(char *dst, const char *src,
4299 Size_t size)
4300 my_vsnprintf
4302 The C library "vsnprintf" if available and standards-compliant.
4303 However, if if the "vsnprintf" is not available, will
4304 unfortunately use the unsafe "vsprintf" which can overrun the
4305 buffer (there is an overrun check, but that may be too late).
4306 Consider using "sv_vcatpvf" instead, or getting "vsnprintf".
4307 int my_vsnprintf(char *buffer, const Size_t len,
4309 const char *format, va_list ap)
4310 ninstr Find the first (leftmost) occurrence of a sequence of bytes
4312 within another sequence. This is the Perl version of
4313 "strstr()", extended to handle arbitrary sequences, potentially
4314 containing embedded "NUL" characters ("NUL" is what the initial
4315 "n" in the function name stands for; some systems have an
4316 equivalent, "memmem()", but with a somewhat different API).
4317 Another way of thinking about this function is finding a needle
4319 in a haystack. "big" points to the first byte in the haystack.
4320 "big_end" points to one byte beyond the final byte in the
4321 haystack. "little" points to the first byte in the needle.
4322 "little_end" points to one byte beyond the final byte in the
4323 needle. All the parameters must be non-"NULL".
4324 The function returns "NULL" if there is no occurrence of
4326 "little" within "big". If "little" is the empty string, "big"
4327 is returned.
4328 Because this function operates at the byte level, and because
4330 of the inherent characteristics of UTF-8 (or UTF-EBCDIC), it
4331 will work properly if both the needle and the haystack are
4332 strings with the same UTF-8ness, but not if the UTF-8ness
4333 differs.
4334 char * ninstr(char * big, char * bigend, char * little,
4336 char * little_end)
4337 PERL_SYS_INIT
4339 Provides system-specific tune up of the C runtime environment
4340 necessary to run Perl interpreters. This should be called only
4341 once, before creating any Perl interpreters.
4342 void PERL_SYS_INIT(int *argc, char*** argv)
4344 PERL_SYS_INIT3
4346 Provides system-specific tune up of the C runtime environment
4347 necessary to run Perl interpreters. This should be called only
4348 once, before creating any Perl interpreters.
4349 void PERL_SYS_INIT3(int *argc, char*** argv,
4351 char*** env)
4352 PERL_SYS_TERM
4354 Provides system-specific clean up of the C runtime environment
4355 after running Perl interpreters. This should be called only
4356 once, after freeing any remaining Perl interpreters.
4357 void PERL_SYS_TERM()
4359 quadmath_format_needed
4361 "quadmath_format_needed()" returns true if the "format" string
4362 seems to contain at least one non-Q-prefixed "%[efgaEFGA]"
4363 format specifier, or returns false otherwise.
4364 The format specifier detection is not complete printf-syntax
4366 detection, but it should catch most common cases.
4367 If true is returned, those arguments should in theory be
4369 processed with "quadmath_snprintf()", but in case there is more
4370 than one such format specifier (see "quadmath_format_single"),
4371 and if there is anything else beyond that one (even just a
4372 single byte), they cannot be processed because
4373 "quadmath_snprintf()" is very strict, accepting only one format
4374 spec, and nothing else. In this case, the code should probably
4375 fail.
4376 bool quadmath_format_needed(const char* format)
4378 quadmath_format_single
4380 "quadmath_snprintf()" is very strict about its "format" string
4381 and will fail, returning -1, if the format is invalid. It
4382 accepts exactly one format spec.
4383 "quadmath_format_single()" checks that the intended single spec
4385 looks sane: begins with "%", has only one "%", ends with
4386 "[efgaEFGA]", and has "Q" before it. This is not a full
4387 "printf syntax check", just the basics.
4388 Returns the format if it is valid, NULL if not.
4390 "quadmath_format_single()" can and will actually patch in the
4392 missing "Q", if necessary. In this case it will return the
4393 modified copy of the format, which the caller will need to
4394 free.
4395 See also "quadmath_format_needed".
4397 const char* quadmath_format_single(const char* format)
4399 READ_XDIGIT
4401 Returns the value of an ASCII-range hex digit and advances the
4402 string pointer. Behaviour is only well defined when
4403 isXDIGIT(*str) is true.
4404 U8 READ_XDIGIT(char str*)
4406 rninstr Like "ninstr", but instead finds the final (rightmost)
4408 occurrence of a sequence of bytes within another sequence,
4409 returning "NULL" if there is no such occurrence.
4410 char * rninstr(char * big, char * bigend,
4412 char * little, char * little_end)
4413 strEQ Test two "NUL"-terminated strings to see if they are equal.
4415 Returns true or false.
4416 bool strEQ(char* s1, char* s2)
4418 strGE Test two "NUL"-terminated strings to see if the first, "s1", is
4420 greater than or equal to the second, "s2". Returns true or
4421 false.
4422 bool strGE(char* s1, char* s2)
4424 strGT Test two "NUL"-terminated strings to see if the first, "s1", is
4426 greater than the second, "s2". Returns true or false.
4427 bool strGT(char* s1, char* s2)
4429 strLE Test two "NUL"-terminated strings to see if the first, "s1", is
4431 less than or equal to the second, "s2". Returns true or false.
4432 bool strLE(char* s1, char* s2)
4434 strLT Test two "NUL"-terminated strings to see if the first, "s1", is
4436 less than the second, "s2". Returns true or false.
4437 bool strLT(char* s1, char* s2)
4439 strNE Test two "NUL"-terminated strings to see if they are different.
4441 Returns true or false.
4442 bool strNE(char* s1, char* s2)
4444 strnEQ Test two "NUL"-terminated strings to see if they are equal.
4446 The "len" parameter indicates the number of bytes to compare.
4447 Returns true or false. (A wrapper for "strncmp").
4448 bool strnEQ(char* s1, char* s2, STRLEN len)
4450 strnNE Test two "NUL"-terminated strings to see if they are different.
4452 The "len" parameter indicates the number of bytes to compare.
4453 Returns true or false. (A wrapper for "strncmp").
4454 bool strnNE(char* s1, char* s2, STRLEN len)
4456 sv_destroyable
4458 Dummy routine which reports that object can be destroyed when
4459 there is no sharing module present. It ignores its single SV
4460 argument, and returns 'true'. Exists to avoid test for a
4461 "NULL" function pointer and because it could potentially warn
4462 under some level of strict-ness.
4463 bool sv_destroyable(SV *sv)
4465 sv_nosharing
4467 Dummy routine which "shares" an SV when there is no sharing
4468 module present. Or "locks" it. Or "unlocks" it. In other
4469 words, ignores its single SV argument. Exists to avoid test
4470 for a "NULL" function pointer and because it could potentially
4471 warn under some level of strict-ness.
4472 void sv_nosharing(SV *sv)
4474 vmess "pat" and "args" are a sprintf-style format pattern and
4476 encapsulated argument list, respectively. These are used to
4477 generate a string message. If the message does not end with a
4478 newline, then it will be extended with some indication of the
4479 current location in the code, as described for "mess_sv".
4480 Normally, the resulting message is returned in a new mortal SV.
4482 During global destruction a single SV may be shared between
4483 uses of this function.
4484 SV * vmess(const char *pat, va_list *args)
4486
4488 These functions are related to the method resolution order of perl
4489 classes
4490 mro_get_linear_isa
4492 Returns the mro linearisation for the given stash. By default,
4493 this will be whatever "mro_get_linear_isa_dfs" returns unless
4494 some other MRO is in effect for the stash. The return value is
4495 a read-only AV*.
4496 You are responsible for "SvREFCNT_inc()" on the return value if
4498 you plan to store it anywhere semi-permanently (otherwise it
4499 might be deleted out from under you the next time the cache is
4500 invalidated).
4501 AV* mro_get_linear_isa(HV* stash)
4503 mro_method_changed_in
4505 Invalidates method caching on any child classes of the given
4506 stash, so that they might notice the changes in this one.
4507 Ideally, all instances of "PL_sub_generation++" in perl source
4509 outside of mro.c should be replaced by calls to this.
4510 Perl automatically handles most of the common ways a method
4512 might be redefined. However, there are a few ways you could
4513 change a method in a stash without the cache code noticing, in
4514 which case you need to call this method afterwards:
4515 1) Directly manipulating the stash HV entries from XS code.
4517 2) Assigning a reference to a readonly scalar constant into a
4519 stash entry in order to create a constant subroutine (like
4520 constant.pm does).
4521 This same method is available from pure perl via,
4523 "mro::method_changed_in(classname)".
4524 void mro_method_changed_in(HV* stash)
4526 mro_register
4528 Registers a custom mro plugin. See perlmroapi for details.
4529 void mro_register(const struct mro_alg *mro)
4531
4533 dMULTICALL
4534 Declare local variables for a multicall. See "LIGHTWEIGHT
4535 CALLBACKS" in perlcall.
4536 dMULTICALL;
4538 MULTICALL
4540 Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in
4541 perlcall.
4542 MULTICALL;
4544 POP_MULTICALL
4546 Closing bracket for a lightweight callback. See "LIGHTWEIGHT
4547 CALLBACKS" in perlcall.
4548 POP_MULTICALL;
4550 PUSH_MULTICALL
4552 Opening bracket for a lightweight callback. See "LIGHTWEIGHT
4553 CALLBACKS" in perlcall.
4554 PUSH_MULTICALL;
4556
4558 grok_bin
4559 converts a string representing a binary number to numeric form.
4560 On entry "start" and *len give the string to scan, *flags gives
4562 conversion flags, and "result" should be "NULL" or a pointer to
4563 an NV. The scan stops at the end of the string, or the first
4564 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
4565 in *flags, encountering an invalid character will also trigger
4566 a warning. On return *len is set to the length of the scanned
4567 string, and *flags gives output flags.
4568 If the value is <= "UV_MAX" it is returned as a UV, the output
4570 flags are clear, and nothing is written to *result. If the
4571 value is > "UV_MAX", "grok_bin" returns "UV_MAX", sets
4572 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
4573 the value to *result (or the value is discarded if "result" is
4574 NULL).
4575 The binary number may optionally be prefixed with "0b" or "b"
4577 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
4578 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the
4579 binary number may use "_" characters to separate digits.
4580 UV grok_bin(const char* start, STRLEN* len_p,
4582 I32* flags, NV *result)
4583 grok_hex
4585 converts a string representing a hex number to numeric form.
4586 On entry "start" and *len_p give the string to scan, *flags
4588 gives conversion flags, and "result" should be "NULL" or a
4589 pointer to an NV. The scan stops at the end of the string, or
4590 the first invalid character. Unless
4591 "PERL_SCAN_SILENT_ILLDIGIT" is set in *flags, encountering an
4592 invalid character will also trigger a warning. On return *len
4593 is set to the length of the scanned string, and *flags gives
4594 output flags.
4595 If the value is <= "UV_MAX" it is returned as a UV, the output
4597 flags are clear, and nothing is written to *result. If the
4598 value is > "UV_MAX", "grok_hex" returns "UV_MAX", sets
4599 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
4600 the value to *result (or the value is discarded if "result" is
4601 "NULL").
4602 The hex number may optionally be prefixed with "0x" or "x"
4604 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
4605 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the hex
4606 number may use "_" characters to separate digits.
4607 UV grok_hex(const char* start, STRLEN* len_p,
4609 I32* flags, NV *result)
4610 grok_infnan
4612 Helper for "grok_number()", accepts various ways of spelling
4613 "infinity" or "not a number", and returns one of the following
4614 flag combinations:
4615 IS_NUMBER_INFINITE
4617 IS_NUMBER_NAN
4618 IS_NUMBER_INFINITE | IS_NUMBER_NEG
4619 IS_NUMBER_NAN | IS_NUMBER_NEG
4620 0
4621 possibly |-ed with "IS_NUMBER_TRAILING".
4623 If an infinity or a not-a-number is recognized, *sp will point
4625 to one byte past the end of the recognized string. If the
4626 recognition fails, zero is returned, and *sp will not move.
4627 int grok_infnan(const char** sp, const char *send)
4629 grok_number
4631 Identical to "grok_number_flags()" with "flags" set to zero.
4632 int grok_number(const char *pv, STRLEN len,
4634 UV *valuep)
4635 grok_number_flags
4637 Recognise (or not) a number. The type of the number is
4638 returned (0 if unrecognised), otherwise it is a bit-ORed
4639 combination of "IS_NUMBER_IN_UV",
4640 "IS_NUMBER_GREATER_THAN_UV_MAX", "IS_NUMBER_NOT_INT",
4641 "IS_NUMBER_NEG", "IS_NUMBER_INFINITY", "IS_NUMBER_NAN" (defined
4642 in perl.h).
4643 If the value of the number can fit in a UV, it is returned in
4645 *valuep. "IS_NUMBER_IN_UV" will be set to indicate that
4646 *valuep is valid, "IS_NUMBER_IN_UV" will never be set unless
4647 *valuep is valid, but *valuep may have been assigned to during
4648 processing even though "IS_NUMBER_IN_UV" is not set on return.
4649 If "valuep" is "NULL", "IS_NUMBER_IN_UV" will be set for the
4650 same cases as when "valuep" is non-"NULL", but no actual
4651 assignment (or SEGV) will occur.
4652 "IS_NUMBER_NOT_INT" will be set with "IS_NUMBER_IN_UV" if
4654 trailing decimals were seen (in which case *valuep gives the
4655 true value truncated to an integer), and "IS_NUMBER_NEG" if the
4656 number is negative (in which case *valuep holds the absolute
4657 value). "IS_NUMBER_IN_UV" is not set if e notation was used or
4658 the number is larger than a UV.
4659 "flags" allows only "PERL_SCAN_TRAILING", which allows for
4661 trailing non-numeric text on an otherwise successful grok,
4662 setting "IS_NUMBER_TRAILING" on the result.
4663 int grok_number_flags(const char *pv, STRLEN len,
4665 UV *valuep, U32 flags)
4666 grok_numeric_radix
4668 Scan and skip for a numeric decimal separator (radix).
4669 bool grok_numeric_radix(const char **sp,
4671 const char *send)
4672 grok_oct
4674 converts a string representing an octal number to numeric form.
4675 On entry "start" and *len give the string to scan, *flags gives
4677 conversion flags, and "result" should be "NULL" or a pointer to
4678 an NV. The scan stops at the end of the string, or the first
4679 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
4680 in *flags, encountering an 8 or 9 will also trigger a warning.
4681 On return *len is set to the length of the scanned string, and
4682 *flags gives output flags.
4683 If the value is <= "UV_MAX" it is returned as a UV, the output
4685 flags are clear, and nothing is written to *result. If the
4686 value is > "UV_MAX", "grok_oct" returns "UV_MAX", sets
4687 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
4688 the value to *result (or the value is discarded if "result" is
4689 "NULL").
4690 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the
4692 octal number may use "_" characters to separate digits.
4693 UV grok_oct(const char* start, STRLEN* len_p,
4695 I32* flags, NV *result)
4696 isinfnan
4698 "Perl_isinfnan()" is utility function that returns true if the
4699 NV argument is either an infinity or a "NaN", false otherwise.
4700 To test in more detail, use "Perl_isinf()" and "Perl_isnan()".
4701 This is also the logical inverse of Perl_isfinite().
4703 bool isinfnan(NV nv)
4705 Perl_signbit
4707 NOTE: this function is experimental and may change or be
4708 removed without notice.
4709 Return a non-zero integer if the sign bit on an NV is set, and
4711 0 if it is not.
4712 If Configure detects this system has a "signbit()" that will
4714 work with our NVs, then we just use it via the "#define" in
4715 perl.h. Otherwise, fall back on this implementation. The main
4716 use of this function is catching "-0.0".
4717 "Configure" notes: This function is called 'Perl_signbit'
4719 instead of a plain 'signbit' because it is easy to imagine a
4720 system having a "signbit()" function or macro that doesn't
4721 happen to work with our particular choice of NVs. We shouldn't
4722 just re-"#define" "signbit" as "Perl_signbit" and expect the
4723 standard system headers to be happy. Also, this is a no-
4724 context function (no "pTHX_") because "Perl_signbit()" is
4725 usually re-"#defined" in perl.h as a simple macro call to the
4726 system's "signbit()". Users should just always call
4727 "Perl_signbit()".
4728 int Perl_signbit(NV f)
4730 scan_bin
4732 For backwards compatibility. Use "grok_bin" instead.
4733 NV scan_bin(const char* start, STRLEN len,
4735 STRLEN* retlen)
4736 scan_hex
4738 For backwards compatibility. Use "grok_hex" instead.
4739 NV scan_hex(const char* start, STRLEN len,
4741 STRLEN* retlen)
4742 scan_oct
4744 For backwards compatibility. Use "grok_oct" instead.
4745 NV scan_oct(const char* start, STRLEN len,
4747 STRLEN* retlen)
4748
4750 Some of these are also deprecated. You can exclude these from your
4751 compiled Perl by adding this option to Configure:
4752 "-Accflags='-DNO_MATHOMS'"
4753 custom_op_desc
4755 Return the description of a given custom op. This was once
4756 used by the "OP_DESC" macro, but is no longer: it has only been
4757 kept for compatibility, and should not be used.
4758 const char * custom_op_desc(const OP *o)
4760 custom_op_name
4762 Return the name for a given custom op. This was once used by
4763 the "OP_NAME" macro, but is no longer: it has only been kept
4764 for compatibility, and should not be used.
4765 const char * custom_op_name(const OP *o)
4767 gv_fetchmethod
4769 See "gv_fetchmethod_autoload".
4770 GV* gv_fetchmethod(HV* stash, const char* name)
4772 is_utf8_char
4774 DEPRECATED! It is planned to remove this function from a
4775 future release of Perl. Do not use it for new code; remove it
4776 from existing code.
4777 Tests if some arbitrary number of bytes begins in a valid UTF-8
4779 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC
4780 machines) character is a valid UTF-8 character. The actual
4781 number of bytes in the UTF-8 character will be returned if it
4782 is valid, otherwise 0.
4783 This function is deprecated due to the possibility that
4785 malformed input could cause reading beyond the end of the input
4786 buffer. Use "isUTF8_CHAR" instead.
4787 STRLEN is_utf8_char(const U8 *s)
4789 is_utf8_char_buf
4791 This is identical to the macro "isUTF8_CHAR".
4792 STRLEN is_utf8_char_buf(const U8 *buf,
4794 const U8 *buf_end)
4795 pack_cat
4797 The engine implementing "pack()" Perl function. Note:
4798 parameters "next_in_list" and "flags" are not used. This call
4799 should not be used; use "packlist" instead.
4800 void pack_cat(SV *cat, const char *pat,
4802 const char *patend, SV **beglist,
4803 SV **endlist, SV ***next_in_list,
4804 U32 flags)
4805 pad_compname_type
4807 Looks up the type of the lexical variable at position "po" in
4808 the currently-compiling pad. If the variable is typed, the
4809 stash of the class to which it is typed is returned. If not,
4810 "NULL" is returned.
4811 HV * pad_compname_type(PADOFFSET po)
4813 sv_2pvbyte_nolen
4815 Return a pointer to the byte-encoded representation of the SV.
4816 May cause the SV to be downgraded from UTF-8 as a side-effect.
4817 Usually accessed via the "SvPVbyte_nolen" macro.
4819 char* sv_2pvbyte_nolen(SV* sv)
4821 sv_2pvutf8_nolen
4823 Return a pointer to the UTF-8-encoded representation of the SV.
4824 May cause the SV to be upgraded to UTF-8 as a side-effect.
4825 Usually accessed via the "SvPVutf8_nolen" macro.
4827 char* sv_2pvutf8_nolen(SV* sv)
4829 sv_2pv_nolen
4831 Like "sv_2pv()", but doesn't return the length too. You should
4832 usually use the macro wrapper "SvPV_nolen(sv)" instead.
4833 char* sv_2pv_nolen(SV* sv)
4835 sv_catpvn_mg
4837 Like "sv_catpvn", but also handles 'set' magic.
4838 void sv_catpvn_mg(SV *sv, const char *ptr,
4840 STRLEN len)
4841 sv_catsv_mg
4843 Like "sv_catsv", but also handles 'set' magic.
4844 void sv_catsv_mg(SV *dsv, SV *ssv)
4846 sv_force_normal
4848 Undo various types of fakery on an SV: if the PV is a shared
4849 string, make a private copy; if we're a ref, stop refing; if
4850 we're a glob, downgrade to an "xpvmg". See also
4851 "sv_force_normal_flags".
4852 void sv_force_normal(SV *sv)
4854 sv_iv A private implementation of the "SvIVx" macro for compilers
4856 which can't cope with complex macro expressions. Always use
4857 the macro instead.
4858 IV sv_iv(SV* sv)
4860 sv_nolocking
4862 Dummy routine which "locks" an SV when there is no locking
4863 module present. Exists to avoid test for a "NULL" function
4864 pointer and because it could potentially warn under some level
4865 of strict-ness.
4866 "Superseded" by "sv_nosharing()".
4868 void sv_nolocking(SV *sv)
4870 sv_nounlocking
4872 Dummy routine which "unlocks" an SV when there is no locking
4873 module present. Exists to avoid test for a "NULL" function
4874 pointer and because it could potentially warn under some level
4875 of strict-ness.
4876 "Superseded" by "sv_nosharing()".
4878 void sv_nounlocking(SV *sv)
4880 sv_nv A private implementation of the "SvNVx" macro for compilers
4882 which can't cope with complex macro expressions. Always use
4883 the macro instead.
4884 NV sv_nv(SV* sv)
4886 sv_pv Use the "SvPV_nolen" macro instead
4888 char* sv_pv(SV *sv)
4890 sv_pvbyte
4892 Use "SvPVbyte_nolen" instead.
4893 char* sv_pvbyte(SV *sv)
4895 sv_pvbyten
4897 A private implementation of the "SvPVbyte" macro for compilers
4898 which can't cope with complex macro expressions. Always use
4899 the macro instead.
4900 char* sv_pvbyten(SV *sv, STRLEN *lp)
4902 sv_pvn A private implementation of the "SvPV" macro for compilers
4904 which can't cope with complex macro expressions. Always use
4905 the macro instead.
4906 char* sv_pvn(SV *sv, STRLEN *lp)
4908 sv_pvutf8
4910 Use the "SvPVutf8_nolen" macro instead
4911 char* sv_pvutf8(SV *sv)
4913 sv_pvutf8n
4915 A private implementation of the "SvPVutf8" macro for compilers
4916 which can't cope with complex macro expressions. Always use
4917 the macro instead.
4918 char* sv_pvutf8n(SV *sv, STRLEN *lp)
4920 sv_taint
4922 Taint an SV. Use "SvTAINTED_on" instead.
4923 void sv_taint(SV* sv)
4925 sv_unref
4927 Unsets the RV status of the SV, and decrements the reference
4928 count of whatever was being referenced by the RV. This can
4929 almost be thought of as a reversal of "newSVrv". This is
4930 "sv_unref_flags" with the "flag" being zero. See "SvROK_off".
4931 void sv_unref(SV* sv)
4933 sv_usepvn
4935 Tells an SV to use "ptr" to find its string value. Implemented
4936 by calling "sv_usepvn_flags" with "flags" of 0, hence does not
4937 handle 'set' magic. See "sv_usepvn_flags".
4938 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
4940 sv_usepvn_mg
4942 Like "sv_usepvn", but also handles 'set' magic.
4943 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
4945 sv_uv A private implementation of the "SvUVx" macro for compilers
4947 which can't cope with complex macro expressions. Always use
4948 the macro instead.
4949 UV sv_uv(SV* sv)
4951 unpack_str
4953 The engine implementing "unpack()" Perl function. Note:
4954 parameters "strbeg", "new_s" and "ocnt" are not used. This
4955 call should not be used, use "unpackstring" instead.
4956 I32 unpack_str(const char *pat, const char *patend,
4958 const char *s, const char *strbeg,
4959 const char *strend, char **new_s,
4960 I32 ocnt, U32 flags)
4961 utf8_to_uvchr
4963 DEPRECATED! It is planned to remove this function from a
4964 future release of Perl. Do not use it for new code; remove it
4965 from existing code.
4966 Returns the native code point of the first character in the
4968 string "s" which is assumed to be in UTF-8 encoding; "retlen"
4969 will be set to the length, in bytes, of that character.
4970 Some, but not all, UTF-8 malformations are detected, and in
4972 fact, some malformed input could cause reading beyond the end
4973 of the input buffer, which is why this function is deprecated.
4974 Use "utf8_to_uvchr_buf" instead.
4975 If "s" points to one of the detected malformations, and UTF8
4977 warnings are enabled, zero is returned and *retlen is set (if
4978 "retlen" isn't "NULL") to -1. If those warnings are off, the
4979 computed value if well-defined (or the Unicode REPLACEMENT
4980 CHARACTER, if not) is silently returned, and *retlen is set (if
4981 "retlen" isn't NULL) so that ("s" + *retlen) is the next
4982 possible position in "s" that could begin a non-malformed
4983 character. See "utf8n_to_uvchr" for details on when the
4984 REPLACEMENT CHARACTER is returned.
4985 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
4987 utf8_to_uvuni
4989 DEPRECATED! It is planned to remove this function from a
4990 future release of Perl. Do not use it for new code; remove it
4991 from existing code.
4992 Returns the Unicode code point of the first character in the
4994 string "s" which is assumed to be in UTF-8 encoding; "retlen"
4995 will be set to the length, in bytes, of that character.
4996 Some, but not all, UTF-8 malformations are detected, and in
4998 fact, some malformed input could cause reading beyond the end
4999 of the input buffer, which is one reason why this function is
5000 deprecated. The other is that only in extremely limited
5001 circumstances should the Unicode versus native code point be of
5002 any interest to you. See "utf8_to_uvuni_buf" for alternatives.
5003 If "s" points to one of the detected malformations, and UTF8
5005 warnings are enabled, zero is returned and *retlen is set (if
5006 "retlen" doesn't point to NULL) to -1. If those warnings are
5007 off, the computed value if well-defined (or the Unicode
5008 REPLACEMENT CHARACTER, if not) is silently returned, and
5009 *retlen is set (if "retlen" isn't NULL) so that ("s" + *retlen)
5010 is the next possible position in "s" that could begin a non-
5011 malformed character. See "utf8n_to_uvchr" for details on when
5012 the REPLACEMENT CHARACTER is returned.
5013 UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
5015
5017 newASSIGNOP
5018 Constructs, checks, and returns an assignment op. "left" and
5019 "right" supply the parameters of the assignment; they are
5020 consumed by this function and become part of the constructed op
5021 tree.
5022 If "optype" is "OP_ANDASSIGN", "OP_ORASSIGN", or
5024 "OP_DORASSIGN", then a suitable conditional optree is
5025 constructed. If "optype" is the opcode of a binary operator,
5026 such as "OP_BIT_OR", then an op is constructed that performs
5027 the binary operation and assigns the result to the left
5028 argument. Either way, if "optype" is non-zero then "flags" has
5029 no effect.
5030 If "optype" is zero, then a plain scalar or list assignment is
5032 constructed. Which type of assignment it is is automatically
5033 determined. "flags" gives the eight bits of "op_flags", except
5034 that "OPf_KIDS" will be set automatically, and, shifted up
5035 eight bits, the eight bits of "op_private", except that the bit
5036 with value 1 or 2 is automatically set as required.
5037 OP * newASSIGNOP(I32 flags, OP *left, I32 optype,
5039 OP *right)
5040 newBINOP
5042 Constructs, checks, and returns an op of any binary type.
5043 "type" is the opcode. "flags" gives the eight bits of
5044 "op_flags", except that "OPf_KIDS" will be set automatically,
5045 and, shifted up eight bits, the eight bits of "op_private",
5046 except that the bit with value 1 or 2 is automatically set as
5047 required. "first" and "last" supply up to two ops to be the
5048 direct children of the binary op; they are consumed by this
5049 function and become part of the constructed op tree.
5050 OP * newBINOP(I32 type, I32 flags, OP *first,
5052 OP *last)
5053 newCONDOP
5055 Constructs, checks, and returns a conditional-expression
5056 ("cond_expr") op. "flags" gives the eight bits of "op_flags",
5057 except that "OPf_KIDS" will be set automatically, and, shifted
5058 up eight bits, the eight bits of "op_private", except that the
5059 bit with value 1 is automatically set. "first" supplies the
5060 expression selecting between the two branches, and "trueop" and
5061 "falseop" supply the branches; they are consumed by this
5062 function and become part of the constructed op tree.
5063 OP * newCONDOP(I32 flags, OP *first, OP *trueop,
5065 OP *falseop)
5066 newDEFSVOP
5068 Constructs and returns an op to access $_.
5069 OP * newDEFSVOP()
5071 newFOROP
5073 Constructs, checks, and returns an op tree expressing a
5074 "foreach" loop (iteration through a list of values). This is a
5075 heavyweight loop, with structure that allows exiting the loop
5076 by "last" and suchlike.
5077 "sv" optionally supplies the variable that will be aliased to
5079 each item in turn; if null, it defaults to $_. "expr" supplies
5080 the list of values to iterate over. "block" supplies the main
5081 body of the loop, and "cont" optionally supplies a "continue"
5082 block that operates as a second half of the body. All of these
5083 optree inputs are consumed by this function and become part of
5084 the constructed op tree.
5085 "flags" gives the eight bits of "op_flags" for the "leaveloop"
5087 op and, shifted up eight bits, the eight bits of "op_private"
5088 for the "leaveloop" op, except that (in both cases) some bits
5089 will be set automatically.
5090 OP * newFOROP(I32 flags, OP *sv, OP *expr, OP *block,
5092 OP *cont)
5093 newGIVENOP
5095 Constructs, checks, and returns an op tree expressing a "given"
5096 block. "cond" supplies the expression that will be locally
5097 assigned to a lexical variable, and "block" supplies the body
5098 of the "given" construct; they are consumed by this function
5099 and become part of the constructed op tree. "defsv_off" must
5100 be zero (it used to identity the pad slot of lexical $_).
5101 OP * newGIVENOP(OP *cond, OP *block,
5103 PADOFFSET defsv_off)
5104 newGVOP Constructs, checks, and returns an op of any type that involves
5106 an embedded reference to a GV. "type" is the opcode. "flags"
5107 gives the eight bits of "op_flags". "gv" identifies the GV
5108 that the op should reference; calling this function does not
5109 transfer ownership of any reference to it.
5110 OP * newGVOP(I32 type, I32 flags, GV *gv)
5112 newLISTOP
5114 Constructs, checks, and returns an op of any list type. "type"
5115 is the opcode. "flags" gives the eight bits of "op_flags",
5116 except that "OPf_KIDS" will be set automatically if required.
5117 "first" and "last" supply up to two ops to be direct children
5118 of the list op; they are consumed by this function and become
5119 part of the constructed op tree.
5120 For most list operators, the check function expects all the kid
5122 ops to be present already, so calling "newLISTOP(OP_JOIN, ...)"
5123 (e.g.) is not appropriate. What you want to do in that case is
5124 create an op of type "OP_LIST", append more children to it, and
5125 then call "op_convert_list". See "op_convert_list" for more
5126 information.
5127 OP * newLISTOP(I32 type, I32 flags, OP *first,
5129 OP *last)
5130 newLOGOP
5132 Constructs, checks, and returns a logical (flow control) op.
5133 "type" is the opcode. "flags" gives the eight bits of
5134 "op_flags", except that "OPf_KIDS" will be set automatically,
5135 and, shifted up eight bits, the eight bits of "op_private",
5136 except that the bit with value 1 is automatically set. "first"
5137 supplies the expression controlling the flow, and "other"
5138 supplies the side (alternate) chain of ops; they are consumed
5139 by this function and become part of the constructed op tree.
5140 OP * newLOGOP(I32 type, I32 flags, OP *first,
5142 OP *other)
5143 newLOOPEX
5145 Constructs, checks, and returns a loop-exiting op (such as
5146 "goto" or "last"). "type" is the opcode. "label" supplies the
5147 parameter determining the target of the op; it is consumed by
5148 this function and becomes part of the constructed op tree.
5149 OP * newLOOPEX(I32 type, OP *label)
5151 newLOOPOP
5153 Constructs, checks, and returns an op tree expressing a loop.
5154 This is only a loop in the control flow through the op tree; it
5155 does not have the heavyweight loop structure that allows
5156 exiting the loop by "last" and suchlike. "flags" gives the
5157 eight bits of "op_flags" for the top-level op, except that some
5158 bits will be set automatically as required. "expr" supplies
5159 the expression controlling loop iteration, and "block" supplies
5160 the body of the loop; they are consumed by this function and
5161 become part of the constructed op tree. "debuggable" is
5162 currently unused and should always be 1.
5163 OP * newLOOPOP(I32 flags, I32 debuggable, OP *expr,
5165 OP *block)
5166 newMETHOP
5168 Constructs, checks, and returns an op of method type with a
5169 method name evaluated at runtime. "type" is the opcode.
5170 "flags" gives the eight bits of "op_flags", except that
5171 "OPf_KIDS" will be set automatically, and, shifted up eight
5172 bits, the eight bits of "op_private", except that the bit with
5173 value 1 is automatically set. "dynamic_meth" supplies an op
5174 which evaluates method name; it is consumed by this function
5175 and become part of the constructed op tree. Supported optypes:
5176 "OP_METHOD".
5177 OP * newMETHOP(I32 type, I32 flags, OP *first)
5179 newMETHOP_named
5181 Constructs, checks, and returns an op of method type with a
5182 constant method name. "type" is the opcode. "flags" gives the
5183 eight bits of "op_flags", and, shifted up eight bits, the eight
5184 bits of "op_private". "const_meth" supplies a constant method
5185 name; it must be a shared COW string. Supported optypes:
5186 "OP_METHOD_NAMED".
5187 OP * newMETHOP_named(I32 type, I32 flags,
5189 SV *const_meth)
5190 newNULLLIST
5192 Constructs, checks, and returns a new "stub" op, which
5193 represents an empty list expression.
5194 OP * newNULLLIST()
5196 newOP Constructs, checks, and returns an op of any base type (any
5198 type that has no extra fields). "type" is the opcode. "flags"
5199 gives the eight bits of "op_flags", and, shifted up eight bits,
5200 the eight bits of "op_private".
5201 OP * newOP(I32 type, I32 flags)
5203 newPADOP
5205 Constructs, checks, and returns an op of any type that involves
5206 a reference to a pad element. "type" is the opcode. "flags"
5207 gives the eight bits of "op_flags". A pad slot is
5208 automatically allocated, and is populated with "sv"; this
5209 function takes ownership of one reference to it.
5210 This function only exists if Perl has been compiled to use
5212 ithreads.
5213 OP * newPADOP(I32 type, I32 flags, SV *sv)
5215 newPMOP Constructs, checks, and returns an op of any pattern matching
5217 type. "type" is the opcode. "flags" gives the eight bits of
5218 "op_flags" and, shifted up eight bits, the eight bits of
5219 "op_private".
5220 OP * newPMOP(I32 type, I32 flags)
5222 newPVOP Constructs, checks, and returns an op of any type that involves
5224 an embedded C-level pointer (PV). "type" is the opcode.
5225 "flags" gives the eight bits of "op_flags". "pv" supplies the
5226 C-level pointer, which must have been allocated using
5227 "PerlMemShared_malloc"; the memory will be freed when the op is
5228 destroyed.
5229 OP * newPVOP(I32 type, I32 flags, char *pv)
5231 newRANGE
5233 Constructs and returns a "range" op, with subordinate "flip"
5234 and "flop" ops. "flags" gives the eight bits of "op_flags" for
5235 the "flip" op and, shifted up eight bits, the eight bits of
5236 "op_private" for both the "flip" and "range" ops, except that
5237 the bit with value 1 is automatically set. "left" and "right"
5238 supply the expressions controlling the endpoints of the range;
5239 they are consumed by this function and become part of the
5240 constructed op tree.
5241 OP * newRANGE(I32 flags, OP *left, OP *right)
5243 newSLICEOP
5245 Constructs, checks, and returns an "lslice" (list slice) op.
5246 "flags" gives the eight bits of "op_flags", except that
5247 "OPf_KIDS" will be set automatically, and, shifted up eight
5248 bits, the eight bits of "op_private", except that the bit with
5249 value 1 or 2 is automatically set as required. "listval" and
5250 "subscript" supply the parameters of the slice; they are
5251 consumed by this function and become part of the constructed op
5252 tree.
5253 OP * newSLICEOP(I32 flags, OP *subscript,
5255 OP *listval)
5256 newSTATEOP
5258 Constructs a state op (COP). The state op is normally a
5259 "nextstate" op, but will be a "dbstate" op if debugging is
5260 enabled for currently-compiled code. The state op is populated
5261 from "PL_curcop" (or "PL_compiling"). If "label" is non-null,
5262 it supplies the name of a label to attach to the state op; this
5263 function takes ownership of the memory pointed at by "label",
5264 and will free it. "flags" gives the eight bits of "op_flags"
5265 for the state op.
5266 If "o" is null, the state op is returned. Otherwise the state
5268 op is combined with "o" into a "lineseq" list op, which is
5269 returned. "o" is consumed by this function and becomes part of
5270 the returned op tree.
5271 OP * newSTATEOP(I32 flags, char *label, OP *o)
5273 newSVOP Constructs, checks, and returns an op of any type that involves
5275 an embedded SV. "type" is the opcode. "flags" gives the eight
5276 bits of "op_flags". "sv" gives the SV to embed in the op; this
5277 function takes ownership of one reference to it.
5278 OP * newSVOP(I32 type, I32 flags, SV *sv)
5280 newUNOP Constructs, checks, and returns an op of any unary type.
5282 "type" is the opcode. "flags" gives the eight bits of
5283 "op_flags", except that "OPf_KIDS" will be set automatically if
5284 required, and, shifted up eight bits, the eight bits of
5285 "op_private", except that the bit with value 1 is automatically
5286 set. "first" supplies an optional op to be the direct child of
5287 the unary op; it is consumed by this function and become part
5288 of the constructed op tree.
5289 OP * newUNOP(I32 type, I32 flags, OP *first)
5291 newUNOP_AUX
5293 Similar to "newUNOP", but creates an "UNOP_AUX" struct instead,
5294 with "op_aux" initialised to "aux"
5295 OP* newUNOP_AUX(I32 type, I32 flags, OP* first,
5297 UNOP_AUX_item *aux)
5298 newWHENOP
5300 Constructs, checks, and returns an op tree expressing a "when"
5301 block. "cond" supplies the test expression, and "block"
5302 supplies the block that will be executed if the test evaluates
5303 to true; they are consumed by this function and become part of
5304 the constructed op tree. "cond" will be interpreted
5305 DWIMically, often as a comparison against $_, and may be null
5306 to generate a "default" block.
5307 OP * newWHENOP(OP *cond, OP *block)
5309 newWHILEOP
5311 Constructs, checks, and returns an op tree expressing a "while"
5312 loop. This is a heavyweight loop, with structure that allows
5313 exiting the loop by "last" and suchlike.
5314 "loop" is an optional preconstructed "enterloop" op to use in
5316 the loop; if it is null then a suitable op will be constructed
5317 automatically. "expr" supplies the loop's controlling
5318 expression. "block" supplies the main body of the loop, and
5319 "cont" optionally supplies a "continue" block that operates as
5320 a second half of the body. All of these optree inputs are
5321 consumed by this function and become part of the constructed op
5322 tree.
5323 "flags" gives the eight bits of "op_flags" for the "leaveloop"
5325 op and, shifted up eight bits, the eight bits of "op_private"
5326 for the "leaveloop" op, except that (in both cases) some bits
5327 will be set automatically. "debuggable" is currently unused
5328 and should always be 1. "has_my" can be supplied as true to
5329 force the loop body to be enclosed in its own scope.
5330 OP * newWHILEOP(I32 flags, I32 debuggable,
5332 LOOP *loop, OP *expr, OP *block,
5333 OP *cont, I32 has_my)
5334
5336 alloccopstash
5337 NOTE: this function is experimental and may change or be
5338 removed without notice.
5339 Available only under threaded builds, this function allocates
5341 an entry in "PL_stashpad" for the stash passed to it.
5342 PADOFFSET alloccopstash(HV *hv)
5344 block_end
5346 Handles compile-time scope exit. "floor" is the savestack
5347 index returned by "block_start", and "seq" is the body of the
5348 block. Returns the block, possibly modified.
5349 OP * block_end(I32 floor, OP *seq)
5351 block_start
5353 Handles compile-time scope entry. Arranges for hints to be
5354 restored on block exit and also handles pad sequence numbers to
5355 make lexical variables scope right. Returns a savestack index
5356 for use with "block_end".
5357 int block_start(int full)
5359 ck_entersub_args_list
5361 Performs the default fixup of the arguments part of an
5362 "entersub" op tree. This consists of applying list context to
5363 each of the argument ops. This is the standard treatment used
5364 on a call marked with "&", or a method call, or a call through
5365 a subroutine reference, or any other call where the callee
5366 can't be identified at compile time, or a call where the callee
5367 has no prototype.
5368 OP * ck_entersub_args_list(OP *entersubop)
5370 ck_entersub_args_proto
5372 Performs the fixup of the arguments part of an "entersub" op
5373 tree based on a subroutine prototype. This makes various
5374 modifications to the argument ops, from applying context up to
5375 inserting "refgen" ops, and checking the number and syntactic
5376 types of arguments, as directed by the prototype. This is the
5377 standard treatment used on a subroutine call, not marked with
5378 "&", where the callee can be identified at compile time and has
5379 a prototype.
5380 "protosv" supplies the subroutine prototype to be applied to
5382 the call. It may be a normal defined scalar, of which the
5383 string value will be used. Alternatively, for convenience, it
5384 may be a subroutine object (a "CV*" that has been cast to
5385 "SV*") which has a prototype. The prototype supplied, in
5386 whichever form, does not need to match the actual callee
5387 referenced by the op tree.
5388 If the argument ops disagree with the prototype, for example by
5390 having an unacceptable number of arguments, a valid op tree is
5391 returned anyway. The error is reflected in the parser state,
5392 normally resulting in a single exception at the top level of
5393 parsing which covers all the compilation errors that occurred.
5394 In the error message, the callee is referred to by the name
5395 defined by the "namegv" parameter.
5396 OP * ck_entersub_args_proto(OP *entersubop,
5398 GV *namegv, SV *protosv)
5399 ck_entersub_args_proto_or_list
5401 Performs the fixup of the arguments part of an "entersub" op
5402 tree either based on a subroutine prototype or using default
5403 list-context processing. This is the standard treatment used
5404 on a subroutine call, not marked with "&", where the callee can
5405 be identified at compile time.
5406 "protosv" supplies the subroutine prototype to be applied to
5408 the call, or indicates that there is no prototype. It may be a
5409 normal scalar, in which case if it is defined then the string
5410 value will be used as a prototype, and if it is undefined then
5411 there is no prototype. Alternatively, for convenience, it may
5412 be a subroutine object (a "CV*" that has been cast to "SV*"),
5413 of which the prototype will be used if it has one. The
5414 prototype (or lack thereof) supplied, in whichever form, does
5415 not need to match the actual callee referenced by the op tree.
5416 If the argument ops disagree with the prototype, for example by
5418 having an unacceptable number of arguments, a valid op tree is
5419 returned anyway. The error is reflected in the parser state,
5420 normally resulting in a single exception at the top level of
5421 parsing which covers all the compilation errors that occurred.
5422 In the error message, the callee is referred to by the name
5423 defined by the "namegv" parameter.
5424 OP * ck_entersub_args_proto_or_list(OP *entersubop,
5426 GV *namegv,
5427 SV *protosv)
5428 cv_const_sv
5430 If "cv" is a constant sub eligible for inlining, returns the
5431 constant value returned by the sub. Otherwise, returns "NULL".
5432 Constant subs can be created with "newCONSTSUB" or as described
5434 in "Constant Functions" in perlsub.
5435 SV* cv_const_sv(const CV *const cv)
5437 cv_get_call_checker
5439 Retrieves the function that will be used to fix up a call to
5440 "cv". Specifically, the function is applied to an "entersub"
5441 op tree for a subroutine call, not marked with "&", where the
5442 callee can be identified at compile time as "cv".
5443 The C-level function pointer is returned in *ckfun_p, and an SV
5445 argument for it is returned in *ckobj_p. The function is
5446 intended to be called in this manner:
5447 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
5449 In this call, "entersubop" is a pointer to the "entersub" op,
5451 which may be replaced by the check function, and "namegv" is a
5452 GV supplying the name that should be used by the check function
5453 to refer to the callee of the "entersub" op if it needs to emit
5454 any diagnostics. It is permitted to apply the check function
5455 in non-standard situations, such as to a call to a different
5456 subroutine or to a method call.
5457 By default, the function is
5459 Perl_ck_entersub_args_proto_or_list, and the SV parameter is
5460 "cv" itself. This implements standard prototype processing.
5461 It can be changed, for a particular subroutine, by
5462 "cv_set_call_checker".
5463 void cv_get_call_checker(CV *cv,
5465 Perl_call_checker *ckfun_p,
5466 SV **ckobj_p)
5467 cv_set_call_checker
5469 The original form of "cv_set_call_checker_flags", which passes
5470 it the "CALL_CHECKER_REQUIRE_GV" flag for backward-
5471 compatibility.
5472 void cv_set_call_checker(CV *cv,
5474 Perl_call_checker ckfun,
5475 SV *ckobj)
5476 cv_set_call_checker_flags
5478 Sets the function that will be used to fix up a call to "cv".
5479 Specifically, the function is applied to an "entersub" op tree
5480 for a subroutine call, not marked with "&", where the callee
5481 can be identified at compile time as "cv".
5482 The C-level function pointer is supplied in "ckfun", and an SV
5484 argument for it is supplied in "ckobj". The function should be
5485 defined like this:
5486 STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
5488 It is intended to be called in this manner:
5490 entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
5492 In this call, "entersubop" is a pointer to the "entersub" op,
5494 which may be replaced by the check function, and "namegv"
5495 supplies the name that should be used by the check function to
5496 refer to the callee of the "entersub" op if it needs to emit
5497 any diagnostics. It is permitted to apply the check function
5498 in non-standard situations, such as to a call to a different
5499 subroutine or to a method call.
5500 "namegv" may not actually be a GV. For efficiency, perl may
5502 pass a CV or other SV instead. Whatever is passed can be used
5503 as the first argument to "cv_name". You can force perl to pass
5504 a GV by including "CALL_CHECKER_REQUIRE_GV" in the "flags".
5505 The current setting for a particular CV can be retrieved by
5507 "cv_get_call_checker".
5508 void cv_set_call_checker_flags(
5510 CV *cv, Perl_call_checker ckfun, SV *ckobj,
5511 U32 flags
5512 )
5513 LINKLIST
5515 Given the root of an optree, link the tree in execution order
5516 using the "op_next" pointers and return the first op executed.
5517 If this has already been done, it will not be redone, and
5518 "o->op_next" will be returned. If "o->op_next" is not already
5519 set, "o" should be at least an "UNOP".
5520 OP* LINKLIST(OP *o)
5522 newCONSTSUB
5524 See "newCONSTSUB_flags".
5525 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
5527 newCONSTSUB_flags
5529 Creates a constant sub equivalent to Perl "sub FOO () { 123 }"
5530 which is eligible for inlining at compile-time.
5531 Currently, the only useful value for "flags" is "SVf_UTF8".
5533 The newly created subroutine takes ownership of a reference to
5535 the passed in SV.
5536 Passing "NULL" for SV creates a constant sub equivalent to
5538 "sub BAR () {}", which won't be called if used as a destructor,
5539 but will suppress the overhead of a call to "AUTOLOAD". (This
5540 form, however, isn't eligible for inlining at compile time.)
5541 CV* newCONSTSUB_flags(HV* stash, const char* name,
5543 STRLEN len, U32 flags, SV* sv)
5544 newXS Used by "xsubpp" to hook up XSUBs as Perl subs. "filename"
5546 needs to be static storage, as it is used directly as CvFILE(),
5547 without a copy being made.
5548 op_append_elem
5550 Append an item to the list of ops contained directly within a
5551 list-type op, returning the lengthened list. "first" is the
5552 list-type op, and "last" is the op to append to the list.
5553 "optype" specifies the intended opcode for the list. If
5554 "first" is not already a list of the right type, it will be
5555 upgraded into one. If either "first" or "last" is null, the
5556 other is returned unchanged.
5557 OP * op_append_elem(I32 optype, OP *first, OP *last)
5559 op_append_list
5561 Concatenate the lists of ops contained directly within two
5562 list-type ops, returning the combined list. "first" and "last"
5563 are the list-type ops to concatenate. "optype" specifies the
5564 intended opcode for the list. If either "first" or "last" is
5565 not already a list of the right type, it will be upgraded into
5566 one. If either "first" or "last" is null, the other is
5567 returned unchanged.
5568 OP * op_append_list(I32 optype, OP *first, OP *last)
5570 OP_CLASS
5572 Return the class of the provided OP: that is, which of the *OP
5573 structures it uses. For core ops this currently gets the
5574 information out of "PL_opargs", which does not always
5575 accurately reflect the type used; in v5.26 onwards, see also
5576 the function "op_class" which can do a better job of
5577 determining the used type.
5578 For custom ops the type is returned from the registration, and
5580 it is up to the registree to ensure it is accurate. The value
5581 returned will be one of the "OA_"* constants from op.h.
5582 U32 OP_CLASS(OP *o)
5584 op_contextualize
5586 Applies a syntactic context to an op tree representing an
5587 expression. "o" is the op tree, and "context" must be
5588 "G_SCALAR", "G_ARRAY", or "G_VOID" to specify the context to
5589 apply. The modified op tree is returned.
5590 OP * op_contextualize(OP *o, I32 context)
5592 op_convert_list
5594 Converts "o" into a list op if it is not one already, and then
5595 converts it into the specified "type", calling its check
5596 function, allocating a target if it needs one, and folding
5597 constants.
5598 A list-type op is usually constructed one kid at a time via
5600 "newLISTOP", "op_prepend_elem" and "op_append_elem". Then
5601 finally it is passed to "op_convert_list" to make it the right
5602 type.
5603 OP * op_convert_list(I32 type, I32 flags, OP *o)
5605 OP_DESC Return a short description of the provided OP.
5607 const char * OP_DESC(OP *o)
5609 op_free Free an op. Only use this when an op is no longer linked to
5611 from any optree.
5612 void op_free(OP *o)
5614 OpHAS_SIBLING
5616 Returns true if "o" has a sibling
5617 bool OpHAS_SIBLING(OP *o)
5619 OpLASTSIB_set
5621 Marks "o" as having no further siblings. On "PERL_OP_PARENT"
5622 builds, marks o as having the specified parent. See also
5623 "OpMORESIB_set" and "OpMAYBESIB_set". For a higher-level
5624 interface, see "op_sibling_splice".
5625 void OpLASTSIB_set(OP *o, OP *parent)
5627 op_linklist
5629 This function is the implementation of the "LINKLIST" macro.
5630 It should not be called directly.
5631 OP* op_linklist(OP *o)
5633 op_lvalue
5635 NOTE: this function is experimental and may change or be
5636 removed without notice.
5637 Propagate lvalue ("modifiable") context to an op and its
5639 children. "type" represents the context type, roughly based on
5640 the type of op that would do the modifying, although "local()"
5641 is represented by "OP_NULL", because it has no op type of its
5642 own (it is signalled by a flag on the lvalue op).
5643 This function detects things that can't be modified, such as
5645 "$x+1", and generates errors for them. For example, "$x+1 = 2"
5646 would cause it to be called with an op of type "OP_ADD" and a
5647 "type" argument of "OP_SASSIGN".
5648 It also flags things that need to behave specially in an lvalue
5650 context, such as "$$x = 5" which might have to vivify a
5651 reference in $x.
5652 OP * op_lvalue(OP *o, I32 type)
5654 OpMAYBESIB_set
5656 Conditionally does "OpMORESIB_set" or "OpLASTSIB_set" depending
5657 on whether "sib" is non-null. For a higher-level interface, see
5658 "op_sibling_splice".
5659 void OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
5661 OpMORESIB_set
5663 Sets the sibling of "o" to the non-zero value "sib". See also
5664 "OpLASTSIB_set" and "OpMAYBESIB_set". For a higher-level
5665 interface, see "op_sibling_splice".
5666 void OpMORESIB_set(OP *o, OP *sib)
5668 OP_NAME Return the name of the provided OP. For core ops this looks up
5670 the name from the op_type; for custom ops from the op_ppaddr.
5671 const char * OP_NAME(OP *o)
5673 op_null Neutralizes an op when it is no longer needed, but is still
5675 linked to from other ops.
5676 void op_null(OP *o)
5678 op_parent
5680 Returns the parent OP of "o", if it has a parent. Returns
5681 "NULL" otherwise. This function is only available on perls
5682 built with "-DPERL_OP_PARENT".
5683 OP* op_parent(OP *o)
5685 op_prepend_elem
5687 Prepend an item to the list of ops contained directly within a
5688 list-type op, returning the lengthened list. "first" is the op
5689 to prepend to the list, and "last" is the list-type op.
5690 "optype" specifies the intended opcode for the list. If "last"
5691 is not already a list of the right type, it will be upgraded
5692 into one. If either "first" or "last" is null, the other is
5693 returned unchanged.
5694 OP * op_prepend_elem(I32 optype, OP *first, OP *last)
5696 op_scope
5698 NOTE: this function is experimental and may change or be
5699 removed without notice.
5700 Wraps up an op tree with some additional ops so that at runtime
5702 a dynamic scope will be created. The original ops run in the
5703 new dynamic scope, and then, provided that they exit normally,
5704 the scope will be unwound. The additional ops used to create
5705 and unwind the dynamic scope will normally be an
5706 "enter"/"leave" pair, but a "scope" op may be used instead if
5707 the ops are simple enough to not need the full dynamic scope
5708 structure.
5709 OP * op_scope(OP *o)
5711 OpSIBLING
5713 Returns the sibling of "o", or "NULL" if there is no sibling
5714 OP* OpSIBLING(OP *o)
5716 op_sibling_splice
5718 A general function for editing the structure of an existing
5719 chain of op_sibling nodes. By analogy with the perl-level
5720 "splice()" function, allows you to delete zero or more
5721 sequential nodes, replacing them with zero or more different
5722 nodes. Performs the necessary op_first/op_last housekeeping on
5723 the parent node and op_sibling manipulation on the children.
5724 The last deleted node will be marked as as the last node by
5725 updating the op_sibling/op_sibparent or op_moresib field as
5726 appropriate.
5727 Note that op_next is not manipulated, and nodes are not freed;
5729 that is the responsibility of the caller. It also won't create
5730 a new list op for an empty list etc; use higher-level functions
5731 like op_append_elem() for that.
5732 "parent" is the parent node of the sibling chain. It may passed
5734 as "NULL" if the splicing doesn't affect the first or last op
5735 in the chain.
5736 "start" is the node preceding the first node to be spliced.
5738 Node(s) following it will be deleted, and ops will be inserted
5739 after it. If it is "NULL", the first node onwards is deleted,
5740 and nodes are inserted at the beginning.
5741 "del_count" is the number of nodes to delete. If zero, no
5743 nodes are deleted. If -1 or greater than or equal to the
5744 number of remaining kids, all remaining kids are deleted.
5745 "insert" is the first of a chain of nodes to be inserted in
5747 place of the nodes. If "NULL", no nodes are inserted.
5748 The head of the chain of deleted ops is returned, or "NULL" if
5750 no ops were deleted.
5751 For example:
5753 action before after returns
5755 ------ ----- ----- -------
5756 P P
5758 splice(P, A, 2, X-Y-Z) | | B-C
5759 A-B-C-D A-X-Y-Z-D
5760 P P
5762 splice(P, NULL, 1, X-Y) | | A
5763 A-B-C-D X-Y-B-C-D
5764 P P
5766 splice(P, NULL, 3, NULL) | | A-B-C
5767 A-B-C-D D
5768 P P
5770 splice(P, B, 0, X-Y) | | NULL
5771 A-B-C-D A-B-X-Y-C-D
5772 For lower-level direct manipulation of "op_sibparent" and
5774 "op_moresib", see "OpMORESIB_set", "OpLASTSIB_set",
5775 "OpMAYBESIB_set".
5776 OP* op_sibling_splice(OP *parent, OP *start,
5778 int del_count, OP* insert)
5779 OP_TYPE_IS
5781 Returns true if the given OP is not a "NULL" pointer and if it
5782 is of the given type.
5783 The negation of this macro, "OP_TYPE_ISNT" is also available as
5785 well as "OP_TYPE_IS_NN" and "OP_TYPE_ISNT_NN" which elide the
5786 NULL pointer check.
5787 bool OP_TYPE_IS(OP *o, Optype type)
5789 OP_TYPE_IS_OR_WAS
5791 Returns true if the given OP is not a NULL pointer and if it is
5792 of the given type or used to be before being replaced by an OP
5793 of type OP_NULL.
5794 The negation of this macro, "OP_TYPE_ISNT_AND_WASNT" is also
5796 available as well as "OP_TYPE_IS_OR_WAS_NN" and
5797 "OP_TYPE_ISNT_AND_WASNT_NN" which elide the "NULL" pointer
5798 check.
5799 bool OP_TYPE_IS_OR_WAS(OP *o, Optype type)
5801 rv2cv_op_cv
5803 Examines an op, which is expected to identify a subroutine at
5804 runtime, and attempts to determine at compile time which
5805 subroutine it identifies. This is normally used during Perl
5806 compilation to determine whether a prototype can be applied to
5807 a function call. "cvop" is the op being considered, normally
5808 an "rv2cv" op. A pointer to the identified subroutine is
5809 returned, if it could be determined statically, and a null
5810 pointer is returned if it was not possible to determine
5811 statically.
5812 Currently, the subroutine can be identified statically if the
5814 RV that the "rv2cv" is to operate on is provided by a suitable
5815 "gv" or "const" op. A "gv" op is suitable if the GV's CV slot
5816 is populated. A "const" op is suitable if the constant value
5817 must be an RV pointing to a CV. Details of this process may
5818 change in future versions of Perl. If the "rv2cv" op has the
5819 "OPpENTERSUB_AMPER" flag set then no attempt is made to
5820 identify the subroutine statically: this flag is used to
5821 suppress compile-time magic on a subroutine call, forcing it to
5822 use default runtime behaviour.
5823 If "flags" has the bit "RV2CVOPCV_MARK_EARLY" set, then the
5825 handling of a GV reference is modified. If a GV was examined
5826 and its CV slot was found to be empty, then the "gv" op has the
5827 "OPpEARLY_CV" flag set. If the op is not optimised away, and
5828 the CV slot is later populated with a subroutine having a
5829 prototype, that flag eventually triggers the warning "called
5830 too early to check prototype".
5831 If "flags" has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then
5833 instead of returning a pointer to the subroutine it returns a
5834 pointer to the GV giving the most appropriate name for the
5835 subroutine in this context. Normally this is just the "CvGV"
5836 of the subroutine, but for an anonymous ("CvANON") subroutine
5837 that is referenced through a GV it will be the referencing GV.
5838 The resulting "GV*" is cast to "CV*" to be returned. A null
5839 pointer is returned as usual if there is no statically-
5840 determinable subroutine.
5841 CV * rv2cv_op_cv(OP *cvop, U32 flags)
5843
5845 packlist
5846 The engine implementing "pack()" Perl function.
5847 void packlist(SV *cat, const char *pat,
5849 const char *patend, SV **beglist,
5850 SV **endlist)
5851 unpackstring
5853 The engine implementing the "unpack()" Perl function.
5854 Using the template "pat..patend", this function unpacks the
5856 string "s..strend" into a number of mortal SVs, which it pushes
5857 onto the perl argument (@_) stack (so you will need to issue a
5858 "PUTBACK" before and "SPAGAIN" after the call to this
5859 function). It returns the number of pushed elements.
5860 The "strend" and "patend" pointers should point to the byte
5862 following the last character of each string.
5863 Although this function returns its values on the perl argument
5865 stack, it doesn't take any parameters from that stack (and thus
5866 in particular there's no need to do a "PUSHMARK" before calling
5867 it, unlike "call_pv" for example).
5868 I32 unpackstring(const char *pat,
5870 const char *patend, const char *s,
5871 const char *strend, U32 flags)
5872
5874 CvPADLIST
5875 NOTE: this function is experimental and may change or be
5876 removed without notice.
5877 CV's can have CvPADLIST(cv) set to point to a PADLIST. This is
5879 the CV's scratchpad, which stores lexical variables and opcode
5880 temporary and per-thread values.
5881 For these purposes "formats" are a kind-of CV; eval""s are too
5883 (except they're not callable at will and are always thrown away
5884 after the eval"" is done executing). Require'd files are
5885 simply evals without any outer lexical scope.
5886 XSUBs do not have a "CvPADLIST". "dXSTARG" fetches values from
5888 "PL_curpad", but that is really the callers pad (a slot of
5889 which is allocated by every entersub). Do not get or set
5890 "CvPADLIST" if a CV is an XSUB (as determined by "CvISXSUB()"),
5891 "CvPADLIST" slot is reused for a different internal purpose in
5892 XSUBs.
5893 The PADLIST has a C array where pads are stored.
5895 The 0th entry of the PADLIST is a PADNAMELIST which represents
5897 the "names" or rather the "static type information" for
5898 lexicals. The individual elements of a PADNAMELIST are
5899 PADNAMEs. Future refactorings might stop the PADNAMELIST from
5900 being stored in the PADLIST's array, so don't rely on it. See
5901 "PadlistNAMES".
5902 The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the
5904 stack frame at that depth of recursion into the CV. The 0th
5905 slot of a frame AV is an AV which is @_. Other entries are
5906 storage for variables and op targets.
5907 Iterating over the PADNAMELIST iterates over all possible pad
5909 items. Pad slots for targets ("SVs_PADTMP") and GVs end up
5910 having &PL_padname_undef "names", while slots for constants
5911 have &PL_padname_const "names" (see "pad_alloc"). That
5912 &PL_padname_undef and &PL_padname_const are used is an
5913 implementation detail subject to change. To test for them, use
5914 "!PadnamePV(name)" and "PadnamePV(name) && !PadnameLEN(name)",
5915 respectively.
5916 Only "my"/"our" variable slots get valid names. The rest are
5918 op targets/GVs/constants which are statically allocated or
5919 resolved at compile time. These don't have names by which they
5920 can be looked up from Perl code at run time through eval"" the
5921 way "my"/"our" variables can be. Since they can't be looked up
5922 by "name" but only by their index allocated at compile time
5923 (which is usually in "PL_op-"op_targ>), wasting a name SV for
5924 them doesn't make sense.
5925 The pad names in the PADNAMELIST have their PV holding the name
5927 of the variable. The "COP_SEQ_RANGE_LOW" and "_HIGH" fields
5928 form a range (low+1..high inclusive) of cop_seq numbers for
5929 which the name is valid. During compilation, these fields may
5930 hold the special value PERL_PADSEQ_INTRO to indicate various
5931 stages:
5932 COP_SEQ_RANGE_LOW _HIGH
5934 ----------------- -----
5935 PERL_PADSEQ_INTRO 0 variable not yet introduced:
5936 { my ($x
5937 valid-seq# PERL_PADSEQ_INTRO variable in scope:
5938 { my ($x);
5939 valid-seq# valid-seq# compilation of scope complete:
5940 { my ($x); .... }
5941 When a lexical var hasn't yet been introduced, it already
5943 exists from the perspective of duplicate declarations, but not
5944 for variable lookups, e.g.
5945 my ($x, $x); # '"my" variable $x masks earlier declaration'
5947 my $x = $x; # equal to my $x = $::x;
5948 For typed lexicals "PadnameTYPE" points at the type stash. For
5950 "our" lexicals, "PadnameOURSTASH" points at the stash of the
5951 associated global (so that duplicate "our" declarations in the
5952 same package can be detected). "PadnameGEN" is sometimes used
5953 to store the generation number during compilation.
5954 If "PadnameOUTER" is set on the pad name, then that slot in the
5956 frame AV is a REFCNT'ed reference to a lexical from "outside".
5957 Such entries are sometimes referred to as 'fake'. In this
5958 case, the name does not use 'low' and 'high' to store a cop_seq
5959 range, since it is in scope throughout. Instead 'high' stores
5960 some flags containing info about the real lexical (is it
5961 declared in an anon, and is it capable of being instantiated
5962 multiple times?), and for fake ANONs, 'low' contains the index
5963 within the parent's pad where the lexical's value is stored, to
5964 make cloning quicker.
5965 If the 'name' is "&" the corresponding entry in the PAD is a CV
5967 representing a possible closure.
5968 Note that formats are treated as anon subs, and are cloned each
5970 time write is called (if necessary).
5971 The flag "SVs_PADSTALE" is cleared on lexicals each time the
5973 "my()" is executed, and set on scope exit. This allows the
5974 "Variable $x is not available" warning to be generated in
5975 evals, such as
5976 { my $x = 1; sub f { eval '$x'} } f();
5978 For state vars, "SVs_PADSTALE" is overloaded to mean 'not yet
5980 initialised', but this internal state is stored in a separate
5981 pad entry.
5982 PADLIST * CvPADLIST(CV *cv)
5984 pad_add_name_pvs
5986 Exactly like "pad_add_name_pvn", but takes a "NUL"-terminated
5987 literal string instead of a string/length pair.
5988 PADOFFSET pad_add_name_pvs(const char *name, U32 flags,
5990 HV *typestash, HV *ourstash)
5991 PadARRAY
5993 NOTE: this function is experimental and may change or be
5994 removed without notice.
5995 The C array of pad entries.
5997 SV ** PadARRAY(PAD pad)
5999 pad_findmy_pvs
6001 Exactly like "pad_findmy_pvn", but takes a "NUL"-terminated
6002 literal string instead of a string/length pair.
6003 PADOFFSET pad_findmy_pvs(const char *name, U32 flags)
6005 PadlistARRAY
6007 NOTE: this function is experimental and may change or be
6008 removed without notice.
6009 The C array of a padlist, containing the pads. Only subscript
6011 it with numbers >= 1, as the 0th entry is not guaranteed to
6012 remain usable.
6013 PAD ** PadlistARRAY(PADLIST padlist)
6015 PadlistMAX
6017 NOTE: this function is experimental and may change or be
6018 removed without notice.
6019 The index of the last allocated space in the padlist. Note
6021 that the last pad may be in an earlier slot. Any entries
6022 following it will be "NULL" in that case.
6023 SSize_t PadlistMAX(PADLIST padlist)
6025 PadlistNAMES
6027 NOTE: this function is experimental and may change or be
6028 removed without notice.
6029 The names associated with pad entries.
6031 PADNAMELIST * PadlistNAMES(PADLIST padlist)
6033 PadlistNAMESARRAY
6035 NOTE: this function is experimental and may change or be
6036 removed without notice.
6037 The C array of pad names.
6039 PADNAME ** PadlistNAMESARRAY(PADLIST padlist)
6041 PadlistNAMESMAX
6043 NOTE: this function is experimental and may change or be
6044 removed without notice.
6045 The index of the last pad name.
6047 SSize_t PadlistNAMESMAX(PADLIST padlist)
6049 PadlistREFCNT
6051 NOTE: this function is experimental and may change or be
6052 removed without notice.
6053 The reference count of the padlist. Currently this is always
6055 1.
6056 U32 PadlistREFCNT(PADLIST padlist)
6058 PadMAX NOTE: this function is experimental and may change or be
6060 removed without notice.
6061 The index of the last pad entry.
6063 SSize_t PadMAX(PAD pad)
6065 PadnameLEN
6067 NOTE: this function is experimental and may change or be
6068 removed without notice.
6069 The length of the name.
6071 STRLEN PadnameLEN(PADNAME pn)
6073 PadnamelistARRAY
6075 NOTE: this function is experimental and may change or be
6076 removed without notice.
6077 The C array of pad names.
6079 PADNAME ** PadnamelistARRAY(PADNAMELIST pnl)
6081 PadnamelistMAX
6083 NOTE: this function is experimental and may change or be
6084 removed without notice.
6085 The index of the last pad name.
6087 SSize_t PadnamelistMAX(PADNAMELIST pnl)
6089 PadnamelistREFCNT
6091 NOTE: this function is experimental and may change or be
6092 removed without notice.
6093 The reference count of the pad name list.
6095 SSize_t PadnamelistREFCNT(PADNAMELIST pnl)
6097 PadnamelistREFCNT_dec
6099 NOTE: this function is experimental and may change or be
6100 removed without notice.
6101 Lowers the reference count of the pad name list.
6103 void PadnamelistREFCNT_dec(PADNAMELIST pnl)
6105 PadnamePV
6107 NOTE: this function is experimental and may change or be
6108 removed without notice.
6109 The name stored in the pad name struct. This returns "NULL"
6111 for a target slot.
6112 char * PadnamePV(PADNAME pn)
6114 PadnameREFCNT
6116 NOTE: this function is experimental and may change or be
6117 removed without notice.
6118 The reference count of the pad name.
6120 SSize_t PadnameREFCNT(PADNAME pn)
6122 PadnameREFCNT_dec
6124 NOTE: this function is experimental and may change or be
6125 removed without notice.
6126 Lowers the reference count of the pad name.
6128 void PadnameREFCNT_dec(PADNAME pn)
6130 PadnameSV
6132 NOTE: this function is experimental and may change or be
6133 removed without notice.
6134 Returns the pad name as a mortal SV.
6136 SV * PadnameSV(PADNAME pn)
6138 PadnameUTF8
6140 NOTE: this function is experimental and may change or be
6141 removed without notice.
6142 Whether PadnamePV is in UTF-8. Currently, this is always true.
6144 bool PadnameUTF8(PADNAME pn)
6146 pad_new Create a new padlist, updating the global variables for the
6148 currently-compiling padlist to point to the new padlist. The
6149 following flags can be OR'ed together:
6150 padnew_CLONE this pad is for a cloned CV
6152 padnew_SAVE save old globals on the save stack
6153 padnew_SAVESUB also save extra stuff for start of sub
6154 PADLIST * pad_new(int flags)
6156 PL_comppad
6158 NOTE: this function is experimental and may change or be
6159 removed without notice.
6160 During compilation, this points to the array containing the
6162 values part of the pad for the currently-compiling code. (At
6163 runtime a CV may have many such value arrays; at compile time
6164 just one is constructed.) At runtime, this points to the array
6165 containing the currently-relevant values for the pad for the
6166 currently-executing code.
6167 PL_comppad_name
6169 NOTE: this function is experimental and may change or be
6170 removed without notice.
6171 During compilation, this points to the array containing the
6173 names part of the pad for the currently-compiling code.
6174 PL_curpad
6176 NOTE: this function is experimental and may change or be
6177 removed without notice.
6178 Points directly to the body of the "PL_comppad" array. (I.e.,
6180 this is "PAD_ARRAY(PL_comppad)".)
6181
6183 PL_modglobal
6184 "PL_modglobal" is a general purpose, interpreter global HV for
6185 use by extensions that need to keep information on a per-
6186 interpreter basis. In a pinch, it can also be used as a symbol
6187 table for extensions to share data among each other. It is a
6188 good idea to use keys prefixed by the package name of the
6189 extension that owns the data.
6190 HV* PL_modglobal
6192 PL_na A convenience variable which is typically used with "SvPV" when
6194 one doesn't care about the length of the string. It is usually
6195 more efficient to either declare a local variable and use that
6196 instead or to use the "SvPV_nolen" macro.
6197 STRLEN PL_na
6199 PL_opfreehook
6201 When non-"NULL", the function pointed by this variable will be
6202 called each time an OP is freed with the corresponding OP as
6203 the argument. This allows extensions to free any extra
6204 attribute they have locally attached to an OP. It is also
6205 assured to first fire for the parent OP and then for its kids.
6206 When you replace this variable, it is considered a good
6208 practice to store the possibly previously installed hook and
6209 that you recall it inside your own.
6210 Perl_ophook_t PL_opfreehook
6212 PL_peepp
6214 Pointer to the per-subroutine peephole optimiser. This is a
6215 function that gets called at the end of compilation of a Perl
6216 subroutine (or equivalently independent piece of Perl code) to
6217 perform fixups of some ops and to perform small-scale
6218 optimisations. The function is called once for each subroutine
6219 that is compiled, and is passed, as sole parameter, a pointer
6220 to the op that is the entry point to the subroutine. It
6221 modifies the op tree in place.
6222 The peephole optimiser should never be completely replaced.
6224 Rather, add code to it by wrapping the existing optimiser. The
6225 basic way to do this can be seen in "Compile pass 3: peephole
6226 optimization" in perlguts. If the new code wishes to operate
6227 on ops throughout the subroutine's structure, rather than just
6228 at the top level, it is likely to be more convenient to wrap
6229 the "PL_rpeepp" hook.
6230 peep_t PL_peepp
6232 PL_rpeepp
6234 Pointer to the recursive peephole optimiser. This is a
6235 function that gets called at the end of compilation of a Perl
6236 subroutine (or equivalently independent piece of Perl code) to
6237 perform fixups of some ops and to perform small-scale
6238 optimisations. The function is called once for each chain of
6239 ops linked through their "op_next" fields; it is recursively
6240 called to handle each side chain. It is passed, as sole
6241 parameter, a pointer to the op that is at the head of the
6242 chain. It modifies the op tree in place.
6243 The peephole optimiser should never be completely replaced.
6245 Rather, add code to it by wrapping the existing optimiser. The
6246 basic way to do this can be seen in "Compile pass 3: peephole
6247 optimization" in perlguts. If the new code wishes to operate
6248 only on ops at a subroutine's top level, rather than throughout
6249 the structure, it is likely to be more convenient to wrap the
6250 "PL_peepp" hook.
6251 peep_t PL_rpeepp
6253 PL_sv_no
6255 This is the "false" SV. See "PL_sv_yes". Always refer to this
6256 as &PL_sv_no.
6257 SV PL_sv_no
6259 PL_sv_undef
6261 This is the "undef" SV. Always refer to this as &PL_sv_undef.
6262 SV PL_sv_undef
6264 PL_sv_yes
6266 This is the "true" SV. See "PL_sv_no". Always refer to this
6267 as &PL_sv_yes.
6268 SV PL_sv_yes
6270
6272 SvRX Convenience macro to get the REGEXP from a SV. This is
6273 approximately equivalent to the following snippet:
6274 if (SvMAGICAL(sv))
6276 mg_get(sv);
6277 if (SvROK(sv))
6278 sv = MUTABLE_SV(SvRV(sv));
6279 if (SvTYPE(sv) == SVt_REGEXP)
6280 return (REGEXP*) sv;
6281 "NULL" will be returned if a REGEXP* is not found.
6283 REGEXP * SvRX(SV *sv)
6285 SvRXOK Returns a boolean indicating whether the SV (or the one it
6287 references) is a REGEXP.
6288 If you want to do something with the REGEXP* later use SvRX
6290 instead and check for NULL.
6291 bool SvRXOK(SV* sv)
6293
6295 dMARK Declare a stack marker variable, "mark", for the XSUB. See
6296 "MARK" and "dORIGMARK".
6297 dMARK;
6299 dORIGMARK
6301 Saves the original stack mark for the XSUB. See "ORIGMARK".
6302 dORIGMARK;
6304 dSP Declares a local copy of perl's stack pointer for the XSUB,
6306 available via the "SP" macro. See "SP".
6307 dSP;
6309 EXTEND Used to extend the argument stack for an XSUB's return values.
6311 Once used, guarantees that there is room for at least "nitems"
6312 to be pushed onto the stack.
6313 void EXTEND(SP, SSize_t nitems)
6315 MARK Stack marker variable for the XSUB. See "dMARK".
6317 mPUSHi Push an integer onto the stack. The stack must have room for
6319 this element. Does not use "TARG". See also "PUSHi",
6320 "mXPUSHi" and "XPUSHi".
6321 void mPUSHi(IV iv)
6323 mPUSHn Push a double onto the stack. The stack must have room for
6325 this element. Does not use "TARG". See also "PUSHn",
6326 "mXPUSHn" and "XPUSHn".
6327 void mPUSHn(NV nv)
6329 mPUSHp Push a string onto the stack. The stack must have room for
6331 this element. The "len" indicates the length of the string.
6332 Does not use "TARG". See also "PUSHp", "mXPUSHp" and "XPUSHp".
6333 void mPUSHp(char* str, STRLEN len)
6335 mPUSHs Push an SV onto the stack and mortalizes the SV. The stack
6337 must have room for this element. Does not use "TARG". See
6338 also "PUSHs" and "mXPUSHs".
6339 void mPUSHs(SV* sv)
6341 mPUSHu Push an unsigned integer onto the stack. The stack must have
6343 room for this element. Does not use "TARG". See also "PUSHu",
6344 "mXPUSHu" and "XPUSHu".
6345 void mPUSHu(UV uv)
6347 mXPUSHi Push an integer onto the stack, extending the stack if
6349 necessary. Does not use "TARG". See also "XPUSHi", "mPUSHi"
6350 and "PUSHi".
6351 void mXPUSHi(IV iv)
6353 mXPUSHn Push a double onto the stack, extending the stack if necessary.
6355 Does not use "TARG". See also "XPUSHn", "mPUSHn" and "PUSHn".
6356 void mXPUSHn(NV nv)
6358 mXPUSHp Push a string onto the stack, extending the stack if necessary.
6360 The "len" indicates the length of the string. Does not use
6361 "TARG". See also "XPUSHp", "mPUSHp" and "PUSHp".
6362 void mXPUSHp(char* str, STRLEN len)
6364 mXPUSHs Push an SV onto the stack, extending the stack if necessary and
6366 mortalizes the SV. Does not use "TARG". See also "XPUSHs" and
6367 "mPUSHs".
6368 void mXPUSHs(SV* sv)
6370 mXPUSHu Push an unsigned integer onto the stack, extending the stack if
6372 necessary. Does not use "TARG". See also "XPUSHu", "mPUSHu"
6373 and "PUSHu".
6374 void mXPUSHu(UV uv)
6376 ORIGMARK
6378 The original stack mark for the XSUB. See "dORIGMARK".
6379 POPi Pops an integer off the stack.
6381 IV POPi
6383 POPl Pops a long off the stack.
6385 long POPl
6387 POPn Pops a double off the stack.
6389 NV POPn
6391 POPp Pops a string off the stack.
6393 char* POPp
6395 POPpbytex
6397 Pops a string off the stack which must consist of bytes i.e.
6398 characters < 256.
6399 char* POPpbytex
6401 POPpx Pops a string off the stack. Identical to POPp. There are two
6403 names for historical reasons.
6404 char* POPpx
6406 POPs Pops an SV off the stack.
6408 SV* POPs
6410 POPu Pops an unsigned integer off the stack.
6412 UV POPu
6414 POPul Pops an unsigned long off the stack.
6416 long POPul
6418 PUSHi Push an integer onto the stack. The stack must have room for
6420 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
6421 or "dXSTARG" should be called to declare it. Do not call
6422 multiple "TARG"-oriented macros to return lists from XSUB's -
6423 see "mPUSHi" instead. See also "XPUSHi" and "mXPUSHi".
6424 void PUSHi(IV iv)
6426 PUSHMARK
6428 Opening bracket for arguments on a callback. See "PUTBACK" and
6429 perlcall.
6430 void PUSHMARK(SP)
6432 PUSHmortal
6434 Push a new mortal SV onto the stack. The stack must have room
6435 for this element. Does not use "TARG". See also "PUSHs",
6436 "XPUSHmortal" and "XPUSHs".
6437 void PUSHmortal()
6439 PUSHn Push a double onto the stack. The stack must have room for
6441 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
6442 or "dXSTARG" should be called to declare it. Do not call
6443 multiple "TARG"-oriented macros to return lists from XSUB's -
6444 see "mPUSHn" instead. See also "XPUSHn" and "mXPUSHn".
6445 void PUSHn(NV nv)
6447 PUSHp Push a string onto the stack. The stack must have room for
6449 this element. The "len" indicates the length of the string.
6450 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
6451 should be called to declare it. Do not call multiple
6452 "TARG"-oriented macros to return lists from XSUB's - see
6453 "mPUSHp" instead. See also "XPUSHp" and "mXPUSHp".
6454 void PUSHp(char* str, STRLEN len)
6456 PUSHs Push an SV onto the stack. The stack must have room for this
6458 element. Does not handle 'set' magic. Does not use "TARG".
6459 See also "PUSHmortal", "XPUSHs", and "XPUSHmortal".
6460 void PUSHs(SV* sv)
6462 PUSHu Push an unsigned integer onto the stack. The stack must have
6464 room for this element. Handles 'set' magic. Uses "TARG", so
6465 "dTARGET" or "dXSTARG" should be called to declare it. Do not
6466 call multiple "TARG"-oriented macros to return lists from
6467 XSUB's - see "mPUSHu" instead. See also "XPUSHu" and
6468 "mXPUSHu".
6469 void PUSHu(UV uv)
6471 PUTBACK Closing bracket for XSUB arguments. This is usually handled by
6473 "xsubpp". See "PUSHMARK" and perlcall for other uses.
6474 PUTBACK;
6476 SP Stack pointer. This is usually handled by "xsubpp". See "dSP"
6478 and "SPAGAIN".
6479 SPAGAIN Refetch the stack pointer. Used after a callback. See
6481 perlcall.
6482 SPAGAIN;
6484 XPUSHi Push an integer onto the stack, extending the stack if
6486 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
6487 "dXSTARG" should be called to declare it. Do not call multiple
6488 "TARG"-oriented macros to return lists from XSUB's - see
6489 "mXPUSHi" instead. See also "PUSHi" and "mPUSHi".
6490 void XPUSHi(IV iv)
6492 XPUSHmortal
6494 Push a new mortal SV onto the stack, extending the stack if
6495 necessary. Does not use "TARG". See also "XPUSHs",
6496 "PUSHmortal" and "PUSHs".
6497 void XPUSHmortal()
6499 XPUSHn Push a double onto the stack, extending the stack if necessary.
6501 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
6502 should be called to declare it. Do not call multiple
6503 "TARG"-oriented macros to return lists from XSUB's - see
6504 "mXPUSHn" instead. See also "PUSHn" and "mPUSHn".
6505 void XPUSHn(NV nv)
6507 XPUSHp Push a string onto the stack, extending the stack if necessary.
6509 The "len" indicates the length of the string. Handles 'set'
6510 magic. Uses "TARG", so "dTARGET" or "dXSTARG" should be called
6511 to declare it. Do not call multiple "TARG"-oriented macros to
6512 return lists from XSUB's - see "mXPUSHp" instead. See also
6513 "PUSHp" and "mPUSHp".
6514 void XPUSHp(char* str, STRLEN len)
6516 XPUSHs Push an SV onto the stack, extending the stack if necessary.
6518 Does not handle 'set' magic. Does not use "TARG". See also
6519 "XPUSHmortal", "PUSHs" and "PUSHmortal".
6520 void XPUSHs(SV* sv)
6522 XPUSHu Push an unsigned integer onto the stack, extending the stack if
6524 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
6525 "dXSTARG" should be called to declare it. Do not call multiple
6526 "TARG"-oriented macros to return lists from XSUB's - see
6527 "mXPUSHu" instead. See also "PUSHu" and "mPUSHu".
6528 void XPUSHu(UV uv)
6530 XSRETURN
6532 Return from XSUB, indicating number of items on the stack.
6533 This is usually handled by "xsubpp".
6534 void XSRETURN(int nitems)
6536 XSRETURN_EMPTY
6538 Return an empty list from an XSUB immediately.
6539 XSRETURN_EMPTY;
6541 XSRETURN_IV
6543 Return an integer from an XSUB immediately. Uses "XST_mIV".
6544 void XSRETURN_IV(IV iv)
6546 XSRETURN_NO
6548 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
6549 XSRETURN_NO;
6551 XSRETURN_NV
6553 Return a double from an XSUB immediately. Uses "XST_mNV".
6554 void XSRETURN_NV(NV nv)
6556 XSRETURN_PV
6558 Return a copy of a string from an XSUB immediately. Uses
6559 "XST_mPV".
6560 void XSRETURN_PV(char* str)
6562 XSRETURN_UNDEF
6564 Return &PL_sv_undef from an XSUB immediately. Uses
6565 "XST_mUNDEF".
6566 XSRETURN_UNDEF;
6568 XSRETURN_UV
6570 Return an integer from an XSUB immediately. Uses "XST_mUV".
6571 void XSRETURN_UV(IV uv)
6573 XSRETURN_YES
6575 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
6576 XSRETURN_YES;
6578 XST_mIV Place an integer into the specified position "pos" on the
6580 stack. The value is stored in a new mortal SV.
6581 void XST_mIV(int pos, IV iv)
6583 XST_mNO Place &PL_sv_no into the specified position "pos" on the stack.
6585 void XST_mNO(int pos)
6587 XST_mNV Place a double into the specified position "pos" on the stack.
6589 The value is stored in a new mortal SV.
6590 void XST_mNV(int pos, NV nv)
6592 XST_mPV Place a copy of a string into the specified position "pos" on
6594 the stack. The value is stored in a new mortal SV.
6595 void XST_mPV(int pos, char* str)
6597 XST_mUNDEF
6599 Place &PL_sv_undef into the specified position "pos" on the
6600 stack.
6601 void XST_mUNDEF(int pos)
6603 XST_mYES
6605 Place &PL_sv_yes into the specified position "pos" on the
6606 stack.
6607 void XST_mYES(int pos)
6609
6611 looks_like_number
6612 Test if the content of an SV looks like a number (or is a
6613 number). "Inf" and "Infinity" are treated as numbers (so will
6614 not issue a non-numeric warning), even if your "atof()" doesn't
6615 grok them. Get-magic is ignored.
6616 I32 looks_like_number(SV *const sv)
6618 newRV_noinc
6620 Creates an RV wrapper for an SV. The reference count for the
6621 original SV is not incremented.
6622 SV* newRV_noinc(SV *const tmpRef)
6624 newSV Creates a new SV. A non-zero "len" parameter indicates the
6626 number of bytes of preallocated string space the SV should
6627 have. An extra byte for a trailing "NUL" is also reserved.
6628 ("SvPOK" is not set for the SV even if string space is
6629 allocated.) The reference count for the new SV is set to 1.
6630 In 5.9.3, "newSV()" replaces the older "NEWSV()" API, and drops
6632 the first parameter, x, a debug aid which allowed callers to
6633 identify themselves. This aid has been superseded by a new
6634 build option, "PERL_MEM_LOG" (see "PERL_MEM_LOG" in
6635 perlhacktips). The older API is still there for use in XS
6636 modules supporting older perls.
6637 SV* newSV(const STRLEN len)
6639 newSVhek
6641 Creates a new SV from the hash key structure. It will generate
6642 scalars that point to the shared string table where possible.
6643 Returns a new (undefined) SV if "hek" is NULL.
6644 SV* newSVhek(const HEK *const hek)
6646 newSViv Creates a new SV and copies an integer into it. The reference
6648 count for the SV is set to 1.
6649 SV* newSViv(const IV i)
6651 newSVnv Creates a new SV and copies a floating point value into it.
6653 The reference count for the SV is set to 1.
6654 SV* newSVnv(const NV n)
6656 newSVpv Creates a new SV and copies a string (which may contain "NUL"
6658 ("\0") characters) into it. The reference count for the SV is
6659 set to 1. If "len" is zero, Perl will compute the length using
6660 "strlen()", (which means if you use this option, that "s" can't
6661 have embedded "NUL" characters and has to have a terminating
6662 "NUL" byte).
6663 This function can cause reliability issues if you are likely to
6665 pass in empty strings that are not null terminated, because it
6666 will run strlen on the string and potentially run past valid
6667 memory.
6668 Using "newSVpvn" is a safer alternative for non "NUL"
6670 terminated strings. For string literals use "newSVpvs"
6671 instead. This function will work fine for "NUL" terminated
6672 strings, but if you want to avoid the if statement on whether
6673 to call "strlen" use "newSVpvn" instead (calling "strlen"
6674 yourself).
6675 SV* newSVpv(const char *const s, const STRLEN len)
6677 newSVpvf
6679 Creates a new SV and initializes it with the string formatted
6680 like "sv_catpvf".
6681 SV* newSVpvf(const char *const pat, ...)
6683 newSVpvn
6685 Creates a new SV and copies a string into it, which may contain
6686 "NUL" characters ("\0") and other binary data. The reference
6687 count for the SV is set to 1. Note that if "len" is zero, Perl
6688 will create a zero length (Perl) string. You are responsible
6689 for ensuring that the source buffer is at least "len" bytes
6690 long. If the "buffer" argument is NULL the new SV will be
6691 undefined.
6692 SV* newSVpvn(const char *const s, const STRLEN len)
6694 newSVpvn_flags
6696 Creates a new SV and copies a string (which may contain "NUL"
6697 ("\0") characters) into it. The reference count for the SV is
6698 set to 1. Note that if "len" is zero, Perl will create a zero
6699 length string. You are responsible for ensuring that the
6700 source string is at least "len" bytes long. If the "s"
6701 argument is NULL the new SV will be undefined. Currently the
6702 only flag bits accepted are "SVf_UTF8" and "SVs_TEMP". If
6703 "SVs_TEMP" is set, then "sv_2mortal()" is called on the result
6704 before returning. If "SVf_UTF8" is set, "s" is considered to
6705 be in UTF-8 and the "SVf_UTF8" flag will be set on the new SV.
6706 "newSVpvn_utf8()" is a convenience wrapper for this function,
6707 defined as
6708 #define newSVpvn_utf8(s, len, u) \
6710 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
6711 SV* newSVpvn_flags(const char *const s,
6713 const STRLEN len,
6714 const U32 flags)
6715 newSVpvn_share
6717 Creates a new SV with its "SvPVX_const" pointing to a shared
6718 string in the string table. If the string does not already
6719 exist in the table, it is created first. Turns on the
6720 "SvIsCOW" flag (or "READONLY" and "FAKE" in 5.16 and earlier).
6721 If the "hash" parameter is non-zero, that value is used;
6722 otherwise the hash is computed. The string's hash can later be
6723 retrieved from the SV with the "SvSHARED_HASH()" macro. The
6724 idea here is that as the string table is used for shared hash
6725 keys these strings will have "SvPVX_const == HeKEY" and hash
6726 lookup will avoid string compare.
6727 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
6729 newSVpvs
6731 Like "newSVpvn", but takes a "NUL"-terminated literal string
6732 instead of a string/length pair.
6733 SV* newSVpvs(const char* s)
6735 newSVpvs_flags
6737 Like "newSVpvn_flags", but takes a "NUL"-terminated literal
6738 string instead of a string/length pair.
6739 SV* newSVpvs_flags(const char* s, U32 flags)
6741 newSVpv_share
6743 Like "newSVpvn_share", but takes a "NUL"-terminated string
6744 instead of a string/length pair.
6745 SV* newSVpv_share(const char* s, U32 hash)
6747 newSVpvs_share
6749 Like "newSVpvn_share", but takes a "NUL"-terminated literal
6750 string instead of a string/length pair and omits the hash
6751 parameter.
6752 SV* newSVpvs_share(const char* s)
6754 newSVrv Creates a new SV for the existing RV, "rv", to point to. If
6756 "rv" is not an RV then it will be upgraded to one. If
6757 "classname" is non-null then the new SV will be blessed in the
6758 specified package. The new SV is returned and its reference
6759 count is 1. The reference count 1 is owned by "rv".
6760 SV* newSVrv(SV *const rv,
6762 const char *const classname)
6763 newSVsv Creates a new SV which is an exact duplicate of the original
6765 SV. (Uses "sv_setsv".)
6766 SV* newSVsv(SV *const old)
6768 newSV_type
6770 Creates a new SV, of the type specified. The reference count
6771 for the new SV is set to 1.
6772 SV* newSV_type(const svtype type)
6774 newSVuv Creates a new SV and copies an unsigned integer into it. The
6776 reference count for the SV is set to 1.
6777 SV* newSVuv(const UV u)
6779 sv_2bool
6781 This macro is only used by "sv_true()" or its macro equivalent,
6782 and only if the latter's argument is neither "SvPOK", "SvIOK"
6783 nor "SvNOK". It calls "sv_2bool_flags" with the "SV_GMAGIC"
6784 flag.
6785 bool sv_2bool(SV *const sv)
6787 sv_2bool_flags
6789 This function is only used by "sv_true()" and friends, and
6790 only if the latter's argument is neither "SvPOK", "SvIOK" nor
6791 "SvNOK". If the flags contain "SV_GMAGIC", then it does an
6792 "mg_get()" first.
6793 bool sv_2bool_flags(SV *sv, I32 flags)
6795 sv_2cv Using various gambits, try to get a CV from an SV; in addition,
6797 try if possible to set *st and *gvp to the stash and GV
6798 associated with it. The flags in "lref" are passed to
6799 "gv_fetchsv".
6800 CV* sv_2cv(SV* sv, HV **const st, GV **const gvp,
6802 const I32 lref)
6803 sv_2io Using various gambits, try to get an IO from an SV: the IO slot
6805 if its a GV; or the recursive result if we're an RV; or the IO
6806 slot of the symbol named after the PV if we're a string.
6807 'Get' magic is ignored on the "sv" passed in, but will be
6809 called on "SvRV(sv)" if "sv" is an RV.
6810 IO* sv_2io(SV *const sv)
6812 sv_2iv_flags
6814 Return the integer value of an SV, doing any necessary string
6815 conversion. If "flags" has the "SV_GMAGIC" bit set, does an
6816 "mg_get()" first. Normally used via the "SvIV(sv)" and
6817 "SvIVx(sv)" macros.
6818 IV sv_2iv_flags(SV *const sv, const I32 flags)
6820 sv_2mortal
6822 Marks an existing SV as mortal. The SV will be destroyed
6823 "soon", either by an explicit call to "FREETMPS", or by an
6824 implicit call at places such as statement boundaries.
6825 "SvTEMP()" is turned on which means that the SV's string buffer
6826 can be "stolen" if this SV is copied. See also "sv_newmortal"
6827 and "sv_mortalcopy".
6828 SV* sv_2mortal(SV *const sv)
6830 sv_2nv_flags
6832 Return the num value of an SV, doing any necessary string or
6833 integer conversion. If "flags" has the "SV_GMAGIC" bit set,
6834 does an "mg_get()" first. Normally used via the "SvNV(sv)" and
6835 "SvNVx(sv)" macros.
6836 NV sv_2nv_flags(SV *const sv, const I32 flags)
6838 sv_2pvbyte
6840 Return a pointer to the byte-encoded representation of the SV,
6841 and set *lp to its length. May cause the SV to be downgraded
6842 from UTF-8 as a side-effect.
6843 Usually accessed via the "SvPVbyte" macro.
6845 char* sv_2pvbyte(SV *sv, STRLEN *const lp)
6847 sv_2pvutf8
6849 Return a pointer to the UTF-8-encoded representation of the SV,
6850 and set *lp to its length. May cause the SV to be upgraded to
6851 UTF-8 as a side-effect.
6852 Usually accessed via the "SvPVutf8" macro.
6854 char* sv_2pvutf8(SV *sv, STRLEN *const lp)
6856 sv_2pv_flags
6858 Returns a pointer to the string value of an SV, and sets *lp to
6859 its length. If flags has the "SV_GMAGIC" bit set, does an
6860 "mg_get()" first. Coerces "sv" to a string if necessary.
6861 Normally invoked via the "SvPV_flags" macro. "sv_2pv()" and
6862 "sv_2pv_nomg" usually end up here too.
6863 char* sv_2pv_flags(SV *const sv, STRLEN *const lp,
6865 const I32 flags)
6866 sv_2uv_flags
6868 Return the unsigned integer value of an SV, doing any necessary
6869 string conversion. If "flags" has the "SV_GMAGIC" bit set,
6870 does an "mg_get()" first. Normally used via the "SvUV(sv)" and
6871 "SvUVx(sv)" macros.
6872 UV sv_2uv_flags(SV *const sv, const I32 flags)
6874 sv_backoff
6876 Remove any string offset. You should normally use the
6877 "SvOOK_off" macro wrapper instead.
6878 void sv_backoff(SV *const sv)
6880 sv_bless
6882 Blesses an SV into a specified package. The SV must be an RV.
6883 The package must be designated by its stash (see "gv_stashpv").
6884 The reference count of the SV is unaffected.
6885 SV* sv_bless(SV *const sv, HV *const stash)
6887 sv_catpv
6889 Concatenates the "NUL"-terminated string onto the end of the
6890 string which is in the SV. If the SV has the UTF-8 status set,
6891 then the bytes appended should be valid UTF-8. Handles 'get'
6892 magic, but not 'set' magic. See "sv_catpv_mg".
6893 void sv_catpv(SV *const sv, const char* ptr)
6895 sv_catpvf
6897 Processes its arguments like "sv_catpvfn", and appends the
6898 formatted output to an SV. As with "sv_catpvfn" called with a
6899 non-null C-style variable argument list, argument reordering is
6900 not supported. If the appended data contains "wide" characters
6901 (including, but not limited to, SVs with a UTF-8 PV formatted
6902 with %s, and characters >255 formatted with %c), the original
6903 SV might get upgraded to UTF-8. Handles 'get' magic, but not
6904 'set' magic. See "sv_catpvf_mg". If the original SV was
6905 UTF-8, the pattern should be valid UTF-8; if the original SV
6906 was bytes, the pattern should be too.
6907 void sv_catpvf(SV *const sv, const char *const pat,
6909 ...)
6910 sv_catpvf_mg
6912 Like "sv_catpvf", but also handles 'set' magic.
6913 void sv_catpvf_mg(SV *const sv,
6915 const char *const pat, ...)
6916 sv_catpvn
6918 Concatenates the string onto the end of the string which is in
6919 the SV. "len" indicates number of bytes to copy. If the SV
6920 has the UTF-8 status set, then the bytes appended should be
6921 valid UTF-8. Handles 'get' magic, but not 'set' magic. See
6922 "sv_catpvn_mg".
6923 void sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
6925 sv_catpvn_flags
6927 Concatenates the string onto the end of the string which is in
6928 the SV. The "len" indicates number of bytes to copy.
6929 By default, the string appended is assumed to be valid UTF-8 if
6931 the SV has the UTF-8 status set, and a string of bytes
6932 otherwise. One can force the appended string to be interpreted
6933 as UTF-8 by supplying the "SV_CATUTF8" flag, and as bytes by
6934 supplying the "SV_CATBYTES" flag; the SV or the string appended
6935 will be upgraded to UTF-8 if necessary.
6936 If "flags" has the "SV_SMAGIC" bit set, will "mg_set" on "dsv"
6938 afterwards if appropriate. "sv_catpvn" and "sv_catpvn_nomg"
6939 are implemented in terms of this function.
6940 void sv_catpvn_flags(SV *const dstr,
6942 const char *sstr,
6943 const STRLEN len,
6944 const I32 flags)
6945 sv_catpvs
6947 Like "sv_catpvn", but takes a "NUL"-terminated literal string
6948 instead of a string/length pair.
6949 void sv_catpvs(SV* sv, const char* s)
6951 sv_catpvs_flags
6953 Like "sv_catpvn_flags", but takes a "NUL"-terminated literal
6954 string instead of a string/length pair.
6955 void sv_catpvs_flags(SV* sv, const char* s,
6957 I32 flags)
6958 sv_catpvs_mg
6960 Like "sv_catpvn_mg", but takes a "NUL"-terminated literal
6961 string instead of a string/length pair.
6962 void sv_catpvs_mg(SV* sv, const char* s)
6964 sv_catpvs_nomg
6966 Like "sv_catpvn_nomg", but takes a "NUL"-terminated literal
6967 string instead of a string/length pair.
6968 void sv_catpvs_nomg(SV* sv, const char* s)
6970 sv_catpv_flags
6972 Concatenates the "NUL"-terminated string onto the end of the
6973 string which is in the SV. If the SV has the UTF-8 status set,
6974 then the bytes appended should be valid UTF-8. If "flags" has
6975 the "SV_SMAGIC" bit set, will "mg_set" on the modified SV if
6976 appropriate.
6977 void sv_catpv_flags(SV *dstr, const char *sstr,
6979 const I32 flags)
6980 sv_catpv_mg
6982 Like "sv_catpv", but also handles 'set' magic.
6983 void sv_catpv_mg(SV *const sv, const char *const ptr)
6985 sv_catsv
6987 Concatenates the string from SV "ssv" onto the end of the
6988 string in SV "dsv". If "ssv" is null, does nothing; otherwise
6989 modifies only "dsv". Handles 'get' magic on both SVs, but no
6990 'set' magic. See "sv_catsv_mg" and "sv_catsv_nomg".
6991 void sv_catsv(SV *dstr, SV *sstr)
6993 sv_catsv_flags
6995 Concatenates the string from SV "ssv" onto the end of the
6996 string in SV "dsv". If "ssv" is null, does nothing; otherwise
6997 modifies only "dsv". If "flags" has the "SV_GMAGIC" bit set,
6998 will call "mg_get" on both SVs if appropriate. If "flags" has
6999 the "SV_SMAGIC" bit set, "mg_set" will be called on the
7000 modified SV afterward, if appropriate. "sv_catsv",
7001 "sv_catsv_nomg", and "sv_catsv_mg" are implemented in terms of
7002 this function.
7003 void sv_catsv_flags(SV *const dsv, SV *const ssv,
7005 const I32 flags)
7006 sv_chop Efficient removal of characters from the beginning of the
7008 string buffer. "SvPOK(sv)", or at least "SvPOKp(sv)", must be
7009 true and "ptr" must be a pointer to somewhere inside the string
7010 buffer. "ptr" becomes the first character of the adjusted
7011 string. Uses the "OOK" hack. On return, only "SvPOK(sv)" and
7012 "SvPOKp(sv)" among the "OK" flags will be true.
7013 Beware: after this function returns, "ptr" and SvPVX_const(sv)
7015 may no longer refer to the same chunk of data.
7016 The unfortunate similarity of this function's name to that of
7018 Perl's "chop" operator is strictly coincidental. This function
7019 works from the left; "chop" works from the right.
7020 void sv_chop(SV *const sv, const char *const ptr)
7022 sv_clear
7024 Clear an SV: call any destructors, free up any memory used by
7025 the body, and free the body itself. The SV's head is not
7026 freed, although its type is set to all 1's so that it won't
7027 inadvertently be assumed to be live during global destruction
7028 etc. This function should only be called when "REFCNT" is
7029 zero. Most of the time you'll want to call "sv_free()" (or its
7030 macro wrapper "SvREFCNT_dec") instead.
7031 void sv_clear(SV *const orig_sv)
7033 sv_cmp Compares the strings in two SVs. Returns -1, 0, or 1
7035 indicating whether the string in "sv1" is less than, equal to,
7036 or greater than the string in "sv2". Is UTF-8 and 'use bytes'
7037 aware, handles get magic, and will coerce its args to strings
7038 if necessary. See also "sv_cmp_locale".
7039 I32 sv_cmp(SV *const sv1, SV *const sv2)
7041 sv_cmp_flags
7043 Compares the strings in two SVs. Returns -1, 0, or 1
7044 indicating whether the string in "sv1" is less than, equal to,
7045 or greater than the string in "sv2". Is UTF-8 and 'use bytes'
7046 aware and will coerce its args to strings if necessary. If the
7047 flags has the "SV_GMAGIC" bit set, it handles get magic. See
7048 also "sv_cmp_locale_flags".
7049 I32 sv_cmp_flags(SV *const sv1, SV *const sv2,
7051 const U32 flags)
7052 sv_cmp_locale
7054 Compares the strings in two SVs in a locale-aware manner. Is
7055 UTF-8 and 'use bytes' aware, handles get magic, and will coerce
7056 its args to strings if necessary. See also "sv_cmp".
7057 I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
7059 sv_cmp_locale_flags
7061 Compares the strings in two SVs in a locale-aware manner. Is
7062 UTF-8 and 'use bytes' aware and will coerce its args to strings
7063 if necessary. If the flags contain "SV_GMAGIC", it handles get
7064 magic. See also "sv_cmp_flags".
7065 I32 sv_cmp_locale_flags(SV *const sv1,
7067 SV *const sv2,
7068 const U32 flags)
7069 sv_collxfrm
7071 This calls "sv_collxfrm_flags" with the SV_GMAGIC flag. See
7072 "sv_collxfrm_flags".
7073 char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
7075 sv_collxfrm_flags
7077 Add Collate Transform magic to an SV if it doesn't already have
7078 it. If the flags contain "SV_GMAGIC", it handles get-magic.
7079 Any scalar variable may carry "PERL_MAGIC_collxfrm" magic that
7081 contains the scalar data of the variable, but transformed to
7082 such a format that a normal memory comparison can be used to
7083 compare the data according to the locale settings.
7084 char* sv_collxfrm_flags(SV *const sv,
7086 STRLEN *const nxp,
7087 I32 const flags)
7088 sv_copypv
7090 Copies a stringified representation of the source SV into the
7091 destination SV. Automatically performs any necessary "mg_get"
7092 and coercion of numeric values into strings. Guaranteed to
7093 preserve "UTF8" flag even from overloaded objects. Similar in
7094 nature to "sv_2pv[_flags]" but operates directly on an SV
7095 instead of just the string. Mostly uses "sv_2pv_flags" to do
7096 its work, except when that would lose the UTF-8'ness of the PV.
7097 void sv_copypv(SV *const dsv, SV *const ssv)
7099 sv_copypv_flags
7101 Implementation of "sv_copypv" and "sv_copypv_nomg". Calls get
7102 magic iff flags has the "SV_GMAGIC" bit set.
7103 void sv_copypv_flags(SV *const dsv, SV *const ssv,
7105 const I32 flags)
7106 sv_copypv_nomg
7108 Like "sv_copypv", but doesn't invoke get magic first.
7109 void sv_copypv_nomg(SV *const dsv, SV *const ssv)
7111 sv_dec Auto-decrement of the value in the SV, doing string to numeric
7113 conversion if necessary. Handles 'get' magic and operator
7114 overloading.
7115 void sv_dec(SV *const sv)
7117 sv_dec_nomg
7119 Auto-decrement of the value in the SV, doing string to numeric
7120 conversion if necessary. Handles operator overloading. Skips
7121 handling 'get' magic.
7122 void sv_dec_nomg(SV *const sv)
7124 sv_eq Returns a boolean indicating whether the strings in the two SVs
7126 are identical. Is UTF-8 and 'use bytes' aware, handles get
7127 magic, and will coerce its args to strings if necessary.
7128 I32 sv_eq(SV* sv1, SV* sv2)
7130 sv_eq_flags
7132 Returns a boolean indicating whether the strings in the two SVs
7133 are identical. Is UTF-8 and 'use bytes' aware and coerces its
7134 args to strings if necessary. If the flags has the "SV_GMAGIC"
7135 bit set, it handles get-magic, too.
7136 I32 sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)
7138 sv_force_normal_flags
7140 Undo various types of fakery on an SV, where fakery means "more
7141 than" a string: if the PV is a shared string, make a private
7142 copy; if we're a ref, stop refing; if we're a glob, downgrade
7143 to an "xpvmg"; if we're a copy-on-write scalar, this is the on-
7144 write time when we do the copy, and is also used locally; if
7145 this is a vstring, drop the vstring magic. If "SV_COW_DROP_PV"
7146 is set then a copy-on-write scalar drops its PV buffer (if any)
7147 and becomes "SvPOK_off" rather than making a copy. (Used where
7148 this scalar is about to be set to some other value.) In
7149 addition, the "flags" parameter gets passed to
7150 "sv_unref_flags()" when unreffing. "sv_force_normal" calls
7151 this function with flags set to 0.
7152 This function is expected to be used to signal to perl that
7154 this SV is about to be written to, and any extra book-keeping
7155 needs to be taken care of. Hence, it croaks on read-only
7156 values.
7157 void sv_force_normal_flags(SV *const sv,
7159 const U32 flags)
7160 sv_free Decrement an SV's reference count, and if it drops to zero,
7162 call "sv_clear" to invoke destructors and free up any memory
7163 used by the body; finally, deallocating the SV's head itself.
7164 Normally called via a wrapper macro "SvREFCNT_dec".
7165 void sv_free(SV *const sv)
7167 sv_gets Get a line from the filehandle and store it into the SV,
7169 optionally appending to the currently-stored string. If
7170 "append" is not 0, the line is appended to the SV instead of
7171 overwriting it. "append" should be set to the byte offset that
7172 the appended string should start at in the SV (typically,
7173 "SvCUR(sv)" is a suitable choice).
7174 char* sv_gets(SV *const sv, PerlIO *const fp,
7176 I32 append)
7177 sv_get_backrefs
7179 NOTE: this function is experimental and may change or be
7180 removed without notice.
7181 If "sv" is the target of a weak reference then it returns the
7183 back references structure associated with the sv; otherwise
7184 return "NULL".
7185 When returning a non-null result the type of the return is
7187 relevant. If it is an AV then the elements of the AV are the
7188 weak reference RVs which point at this item. If it is any other
7189 type then the item itself is the weak reference.
7190 See also "Perl_sv_add_backref()", "Perl_sv_del_backref()",
7192 "Perl_sv_kill_backrefs()"
7193 SV* sv_get_backrefs(SV *const sv)
7195 sv_grow Expands the character buffer in the SV. If necessary, uses
7197 "sv_unref" and upgrades the SV to "SVt_PV". Returns a pointer
7198 to the character buffer. Use the "SvGROW" wrapper instead.
7199 char* sv_grow(SV *const sv, STRLEN newlen)
7201 sv_inc Auto-increment of the value in the SV, doing string to numeric
7203 conversion if necessary. Handles 'get' magic and operator
7204 overloading.
7205 void sv_inc(SV *const sv)
7207 sv_inc_nomg
7209 Auto-increment of the value in the SV, doing string to numeric
7210 conversion if necessary. Handles operator overloading. Skips
7211 handling 'get' magic.
7212 void sv_inc_nomg(SV *const sv)
7214 sv_insert
7216 Inserts a string at the specified offset/length within the SV.
7217 Similar to the Perl "substr()" function. Handles get magic.
7218 void sv_insert(SV *const bigstr, const STRLEN offset,
7220 const STRLEN len,
7221 const char *const little,
7222 const STRLEN littlelen)
7223 sv_insert_flags
7225 Same as "sv_insert", but the extra "flags" are passed to the
7226 "SvPV_force_flags" that applies to "bigstr".
7227 void sv_insert_flags(SV *const bigstr,
7229 const STRLEN offset,
7230 const STRLEN len,
7231 const char *little,
7232 const STRLEN littlelen,
7233 const U32 flags)
7234 sv_isa Returns a boolean indicating whether the SV is blessed into the
7236 specified class. This does not check for subtypes; use
7237 "sv_derived_from" to verify an inheritance relationship.
7238 int sv_isa(SV* sv, const char *const name)
7240 sv_isobject
7242 Returns a boolean indicating whether the SV is an RV pointing
7243 to a blessed object. If the SV is not an RV, or if the object
7244 is not blessed, then this will return false.
7245 int sv_isobject(SV* sv)
7247 sv_len Returns the length of the string in the SV. Handles magic and
7249 type coercion and sets the UTF8 flag appropriately. See also
7250 "SvCUR", which gives raw access to the "xpv_cur" slot.
7251 STRLEN sv_len(SV *const sv)
7253 sv_len_utf8
7255 Returns the number of characters in the string in an SV,
7256 counting wide UTF-8 bytes as a single character. Handles magic
7257 and type coercion.
7258 STRLEN sv_len_utf8(SV *const sv)
7260 sv_magic
7262 Adds magic to an SV. First upgrades "sv" to type "SVt_PVMG" if
7263 necessary, then adds a new magic item of type "how" to the head
7264 of the magic list.
7265 See "sv_magicext" (which "sv_magic" now calls) for a
7267 description of the handling of the "name" and "namlen"
7268 arguments.
7269 You need to use "sv_magicext" to add magic to "SvREADONLY" SVs
7271 and also to add more than one instance of the same "how".
7272 void sv_magic(SV *const sv, SV *const obj,
7274 const int how, const char *const name,
7275 const I32 namlen)
7276 sv_magicext
7278 Adds magic to an SV, upgrading it if necessary. Applies the
7279 supplied "vtable" and returns a pointer to the magic added.
7280 Note that "sv_magicext" will allow things that "sv_magic" will
7282 not. In particular, you can add magic to "SvREADONLY" SVs, and
7283 add more than one instance of the same "how".
7284 If "namlen" is greater than zero then a "savepvn" copy of
7286 "name" is stored, if "namlen" is zero then "name" is stored as-
7287 is and - as another special case - if "(name && namlen ==
7288 HEf_SVKEY)" then "name" is assumed to contain an SV* and is
7289 stored as-is with its "REFCNT" incremented.
7290 (This is now used as a subroutine by "sv_magic".)
7292 MAGIC * sv_magicext(SV *const sv, SV *const obj,
7294 const int how,
7295 const MGVTBL *const vtbl,
7296 const char *const name,
7297 const I32 namlen)
7298 sv_mortalcopy
7300 Creates a new SV which is a copy of the original SV (using
7301 "sv_setsv"). The new SV is marked as mortal. It will be
7302 destroyed "soon", either by an explicit call to "FREETMPS", or
7303 by an implicit call at places such as statement boundaries.
7304 See also "sv_newmortal" and "sv_2mortal".
7305 SV* sv_mortalcopy(SV *const oldsv)
7307 sv_newmortal
7309 Creates a new null SV which is mortal. The reference count of
7310 the SV is set to 1. It will be destroyed "soon", either by an
7311 explicit call to "FREETMPS", or by an implicit call at places
7312 such as statement boundaries. See also "sv_mortalcopy" and
7313 "sv_2mortal".
7314 SV* sv_newmortal()
7316 sv_newref
7318 Increment an SV's reference count. Use the "SvREFCNT_inc()"
7319 wrapper instead.
7320 SV* sv_newref(SV *const sv)
7322 sv_pos_b2u
7324 Converts the value pointed to by "offsetp" from a count of
7325 bytes from the start of the string, to a count of the
7326 equivalent number of UTF-8 chars. Handles magic and type
7327 coercion.
7328 Use "sv_pos_b2u_flags" in preference, which correctly handles
7330 strings longer than 2Gb.
7331 void sv_pos_b2u(SV *const sv, I32 *const offsetp)
7333 sv_pos_b2u_flags
7335 Converts "offset" from a count of bytes from the start of the
7336 string, to a count of the equivalent number of UTF-8 chars.
7337 Handles type coercion. "flags" is passed to "SvPV_flags", and
7338 usually should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
7339 STRLEN sv_pos_b2u_flags(SV *const sv,
7341 STRLEN const offset, U32 flags)
7342 sv_pos_u2b
7344 Converts the value pointed to by "offsetp" from a count of
7345 UTF-8 chars from the start of the string, to a count of the
7346 equivalent number of bytes; if "lenp" is non-zero, it does the
7347 same to "lenp", but this time starting from the offset, rather
7348 than from the start of the string. Handles magic and type
7349 coercion.
7350 Use "sv_pos_u2b_flags" in preference, which correctly handles
7352 strings longer than 2Gb.
7353 void sv_pos_u2b(SV *const sv, I32 *const offsetp,
7355 I32 *const lenp)
7356 sv_pos_u2b_flags
7358 Converts the offset from a count of UTF-8 chars from the start
7359 of the string, to a count of the equivalent number of bytes; if
7360 "lenp" is non-zero, it does the same to "lenp", but this time
7361 starting from "offset", rather than from the start of the
7362 string. Handles type coercion. "flags" is passed to
7363 "SvPV_flags", and usually should be "SV_GMAGIC|SV_CONST_RETURN"
7364 to handle magic.
7365 STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
7367 STRLEN *const lenp, U32 flags)
7368 sv_pvbyten_force
7370 The backend for the "SvPVbytex_force" macro. Always use the
7371 macro instead.
7372 char* sv_pvbyten_force(SV *const sv, STRLEN *const lp)
7374 sv_pvn_force
7376 Get a sensible string out of the SV somehow. A private
7377 implementation of the "SvPV_force" macro for compilers which
7378 can't cope with complex macro expressions. Always use the
7379 macro instead.
7380 char* sv_pvn_force(SV* sv, STRLEN* lp)
7382 sv_pvn_force_flags
7384 Get a sensible string out of the SV somehow. If "flags" has
7385 the "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate,
7386 else not. "sv_pvn_force" and "sv_pvn_force_nomg" are
7387 implemented in terms of this function. You normally want to
7388 use the various wrapper macros instead: see "SvPV_force" and
7389 "SvPV_force_nomg".
7390 char* sv_pvn_force_flags(SV *const sv,
7392 STRLEN *const lp,
7393 const I32 flags)
7394 sv_pvutf8n_force
7396 The backend for the "SvPVutf8x_force" macro. Always use the
7397 macro instead.
7398 char* sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
7400 sv_ref Returns a SV describing what the SV passed in is a reference
7402 to.
7403 dst can be a SV to be set to the description or NULL, in which
7405 case a mortal SV is returned.
7406 If ob is true and the SV is blessed, the description is the
7408 class name, otherwise it is the type of the SV, "SCALAR",
7409 "ARRAY" etc.
7410 SV* sv_ref(SV *dst, const SV *const sv,
7412 const int ob)
7413 sv_reftype
7415 Returns a string describing what the SV is a reference to.
7416 If ob is true and the SV is blessed, the string is the class
7418 name, otherwise it is the type of the SV, "SCALAR", "ARRAY"
7419 etc.
7420 const char* sv_reftype(const SV *const sv, const int ob)
7422 sv_replace
7424 Make the first argument a copy of the second, then delete the
7425 original. The target SV physically takes over ownership of the
7426 body of the source SV and inherits its flags; however, the
7427 target keeps any magic it owns, and any magic in the source is
7428 discarded. Note that this is a rather specialist SV copying
7429 operation; most of the time you'll want to use "sv_setsv" or
7430 one of its many macro front-ends.
7431 void sv_replace(SV *const sv, SV *const nsv)
7433 sv_reset
7435 Underlying implementation for the "reset" Perl function. Note
7436 that the perl-level function is vaguely deprecated.
7437 void sv_reset(const char* s, HV *const stash)
7439 sv_rvweaken
7441 Weaken a reference: set the "SvWEAKREF" flag on this RV; give
7442 the referred-to SV "PERL_MAGIC_backref" magic if it hasn't
7443 already; and push a back-reference to this RV onto the array of
7444 backreferences associated with that magic. If the RV is
7445 magical, set magic will be called after the RV is cleared.
7446 SV* sv_rvweaken(SV *const sv)
7448 sv_setiv
7450 Copies an integer into the given SV, upgrading first if
7451 necessary. Does not handle 'set' magic. See also
7452 "sv_setiv_mg".
7453 void sv_setiv(SV *const sv, const IV num)
7455 sv_setiv_mg
7457 Like "sv_setiv", but also handles 'set' magic.
7458 void sv_setiv_mg(SV *const sv, const IV i)
7460 sv_setnv
7462 Copies a double into the given SV, upgrading first if
7463 necessary. Does not handle 'set' magic. See also
7464 "sv_setnv_mg".
7465 void sv_setnv(SV *const sv, const NV num)
7467 sv_setnv_mg
7469 Like "sv_setnv", but also handles 'set' magic.
7470 void sv_setnv_mg(SV *const sv, const NV num)
7472 sv_setpv
7474 Copies a string into an SV. The string must be terminated with
7475 a "NUL" character, and not contain embeded "NUL"'s. Does not
7476 handle 'set' magic. See "sv_setpv_mg".
7477 void sv_setpv(SV *const sv, const char *const ptr)
7479 sv_setpvf
7481 Works like "sv_catpvf" but copies the text into the SV instead
7482 of appending it. Does not handle 'set' magic. See
7483 "sv_setpvf_mg".
7484 void sv_setpvf(SV *const sv, const char *const pat,
7486 ...)
7487 sv_setpvf_mg
7489 Like "sv_setpvf", but also handles 'set' magic.
7490 void sv_setpvf_mg(SV *const sv,
7492 const char *const pat, ...)
7493 sv_setpviv
7495 Copies an integer into the given SV, also updating its string
7496 value. Does not handle 'set' magic. See "sv_setpviv_mg".
7497 void sv_setpviv(SV *const sv, const IV num)
7499 sv_setpviv_mg
7501 Like "sv_setpviv", but also handles 'set' magic.
7502 void sv_setpviv_mg(SV *const sv, const IV iv)
7504 sv_setpvn
7506 Copies a string (possibly containing embedded "NUL" characters)
7507 into an SV. The "len" parameter indicates the number of bytes
7508 to be copied. If the "ptr" argument is NULL the SV will become
7509 undefined. Does not handle 'set' magic. See "sv_setpvn_mg".
7510 void sv_setpvn(SV *const sv, const char *const ptr,
7512 const STRLEN len)
7513 sv_setpvn_mg
7515 Like "sv_setpvn", but also handles 'set' magic.
7516 void sv_setpvn_mg(SV *const sv,
7518 const char *const ptr,
7519 const STRLEN len)
7520 sv_setpvs
7522 Like "sv_setpvn", but takes a "NUL"-terminated literal string
7523 instead of a string/length pair.
7524 void sv_setpvs(SV* sv, const char* s)
7526 sv_setpvs_mg
7528 Like "sv_setpvn_mg", but takes a "NUL"-terminated literal
7529 string instead of a string/length pair.
7530 void sv_setpvs_mg(SV* sv, const char* s)
7532 sv_setpv_bufsize
7534 Sets the SV to be a string of cur bytes length, with at least
7535 len bytes available. Ensures that there is a null byte at
7536 SvEND. Returns a char * pointer to the SvPV buffer.
7537 char * sv_setpv_bufsize(SV *const sv, const STRLEN cur,
7539 const STRLEN len)
7540 sv_setpv_mg
7542 Like "sv_setpv", but also handles 'set' magic.
7543 void sv_setpv_mg(SV *const sv, const char *const ptr)
7545 sv_setref_iv
7547 Copies an integer into a new SV, optionally blessing the SV.
7548 The "rv" argument will be upgraded to an RV. That RV will be
7549 modified to point to the new SV. The "classname" argument
7550 indicates the package for the blessing. Set "classname" to
7551 "NULL" to avoid the blessing. The new SV will have a reference
7552 count of 1, and the RV will be returned.
7553 SV* sv_setref_iv(SV *const rv,
7555 const char *const classname,
7556 const IV iv)
7557 sv_setref_nv
7559 Copies a double into a new SV, optionally blessing the SV. The
7560 "rv" argument will be upgraded to an RV. That RV will be
7561 modified to point to the new SV. The "classname" argument
7562 indicates the package for the blessing. Set "classname" to
7563 "NULL" to avoid the blessing. The new SV will have a reference
7564 count of 1, and the RV will be returned.
7565 SV* sv_setref_nv(SV *const rv,
7567 const char *const classname,
7568 const NV nv)
7569 sv_setref_pv
7571 Copies a pointer into a new SV, optionally blessing the SV.
7572 The "rv" argument will be upgraded to an RV. That RV will be
7573 modified to point to the new SV. If the "pv" argument is
7574 "NULL", then "PL_sv_undef" will be placed into the SV. The
7575 "classname" argument indicates the package for the blessing.
7576 Set "classname" to "NULL" to avoid the blessing. The new SV
7577 will have a reference count of 1, and the RV will be returned.
7578 Do not use with other Perl types such as HV, AV, SV, CV,
7580 because those objects will become corrupted by the pointer copy
7581 process.
7582 Note that "sv_setref_pvn" copies the string while this copies
7584 the pointer.
7585 SV* sv_setref_pv(SV *const rv,
7587 const char *const classname,
7588 void *const pv)
7589 sv_setref_pvn
7591 Copies a string into a new SV, optionally blessing the SV. The
7592 length of the string must be specified with "n". The "rv"
7593 argument will be upgraded to an RV. That RV will be modified
7594 to point to the new SV. The "classname" argument indicates the
7595 package for the blessing. Set "classname" to "NULL" to avoid
7596 the blessing. The new SV will have a reference count of 1, and
7597 the RV will be returned.
7598 Note that "sv_setref_pv" copies the pointer while this copies
7600 the string.
7601 SV* sv_setref_pvn(SV *const rv,
7603 const char *const classname,
7604 const char *const pv,
7605 const STRLEN n)
7606 sv_setref_pvs
7608 Like "sv_setref_pvn", but takes a "NUL"-terminated literal
7609 string instead of a string/length pair.
7610 SV * sv_setref_pvs(const char* s)
7612 sv_setref_uv
7614 Copies an unsigned integer into a new SV, optionally blessing
7615 the SV. The "rv" argument will be upgraded to an RV. That RV
7616 will be modified to point to the new SV. The "classname"
7617 argument indicates the package for the blessing. Set
7618 "classname" to "NULL" to avoid the blessing. The new SV will
7619 have a reference count of 1, and the RV will be returned.
7620 SV* sv_setref_uv(SV *const rv,
7622 const char *const classname,
7623 const UV uv)
7624 sv_setsv
7626 Copies the contents of the source SV "ssv" into the destination
7627 SV "dsv". The source SV may be destroyed if it is mortal, so
7628 don't use this function if the source SV needs to be reused.
7629 Does not handle 'set' magic on destination SV. Calls 'get'
7630 magic on source SV. Loosely speaking, it performs a copy-by-
7631 value, obliterating any previous content of the destination.
7632 You probably want to use one of the assortment of wrappers,
7634 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
7635 "SvSetMagicSV_nosteal".
7636 void sv_setsv(SV *dstr, SV *sstr)
7638 sv_setsv_flags
7640 Copies the contents of the source SV "ssv" into the destination
7641 SV "dsv". The source SV may be destroyed if it is mortal, so
7642 don't use this function if the source SV needs to be reused.
7643 Does not handle 'set' magic. Loosely speaking, it performs a
7644 copy-by-value, obliterating any previous content of the
7645 destination. If the "flags" parameter has the "SV_GMAGIC" bit
7646 set, will "mg_get" on "ssv" if appropriate, else not. If the
7647 "flags" parameter has the "SV_NOSTEAL" bit set then the buffers
7648 of temps will not be stolen. "sv_setsv" and "sv_setsv_nomg"
7649 are implemented in terms of this function.
7650 You probably want to use one of the assortment of wrappers,
7652 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
7653 "SvSetMagicSV_nosteal".
7654 This is the primary function for copying scalars, and most
7656 other copy-ish functions and macros use this underneath.
7657 void sv_setsv_flags(SV *dstr, SV *sstr,
7659 const I32 flags)
7660 sv_setsv_mg
7662 Like "sv_setsv", but also handles 'set' magic.
7663 void sv_setsv_mg(SV *const dstr, SV *const sstr)
7665 sv_setuv
7667 Copies an unsigned integer into the given SV, upgrading first
7668 if necessary. Does not handle 'set' magic. See also
7669 "sv_setuv_mg".
7670 void sv_setuv(SV *const sv, const UV num)
7672 sv_setuv_mg
7674 Like "sv_setuv", but also handles 'set' magic.
7675 void sv_setuv_mg(SV *const sv, const UV u)
7677 sv_set_undef
7679 Equivalent to "sv_setsv(sv, &PL_sv_undef)", but more efficient.
7680 Doesn't handle set magic.
7681 The perl equivalent is "$sv = undef;". Note that it doesn't
7683 free any string buffer, unlike "undef $sv".
7684 Introduced in perl 5.26.0.
7686 void sv_set_undef(SV *sv)
7688 sv_tainted
7690 Test an SV for taintedness. Use "SvTAINTED" instead.
7691 bool sv_tainted(SV *const sv)
7693 sv_true Returns true if the SV has a true value by Perl's rules. Use
7695 the "SvTRUE" macro instead, which may call "sv_true()" or may
7696 instead use an in-line version.
7697 I32 sv_true(SV *const sv)
7699 sv_unmagic
7701 Removes all magic of type "type" from an SV.
7702 int sv_unmagic(SV *const sv, const int type)
7704 sv_unmagicext
7706 Removes all magic of type "type" with the specified "vtbl" from
7707 an SV.
7708 int sv_unmagicext(SV *const sv, const int type,
7710 MGVTBL *vtbl)
7711 sv_unref_flags
7713 Unsets the RV status of the SV, and decrements the reference
7714 count of whatever was being referenced by the RV. This can
7715 almost be thought of as a reversal of "newSVrv". The "cflags"
7716 argument can contain "SV_IMMEDIATE_UNREF" to force the
7717 reference count to be decremented (otherwise the decrementing
7718 is conditional on the reference count being different from one
7719 or the reference being a readonly SV). See "SvROK_off".
7720 void sv_unref_flags(SV *const ref, const U32 flags)
7722 sv_untaint
7724 Untaint an SV. Use "SvTAINTED_off" instead.
7725 void sv_untaint(SV *const sv)
7727 sv_upgrade
7729 Upgrade an SV to a more complex form. Generally adds a new
7730 body type to the SV, then copies across as much information as
7731 possible from the old body. It croaks if the SV is already in
7732 a more complex form than requested. You generally want to use
7733 the "SvUPGRADE" macro wrapper, which checks the type before
7734 calling "sv_upgrade", and hence does not croak. See also
7735 "svtype".
7736 void sv_upgrade(SV *const sv, svtype new_type)
7738 sv_usepvn_flags
7740 Tells an SV to use "ptr" to find its string value. Normally
7741 the string is stored inside the SV, but sv_usepvn allows the SV
7742 to use an outside string. "ptr" should point to memory that
7743 was allocated by "Newx". It must be the start of a "Newx"-ed
7744 block of memory, and not a pointer to the middle of it (beware
7745 of "OOK" and copy-on-write), and not be from a non-"Newx"
7746 memory allocator like "malloc". The string length, "len", must
7747 be supplied. By default this function will "Renew" (i.e.
7748 realloc, move) the memory pointed to by "ptr", so that pointer
7749 should not be freed or used by the programmer after giving it
7750 to "sv_usepvn", and neither should any pointers from "behind"
7751 that pointer (e.g. ptr + 1) be used.
7752 If "flags & SV_SMAGIC" is true, will call "SvSETMAGIC". If
7754 "flags" & SV_HAS_TRAILING_NUL> is true, then "ptr[len]" must be
7755 "NUL", and the realloc will be skipped (i.e. the buffer is
7756 actually at least 1 byte longer than "len", and already meets
7757 the requirements for storing in "SvPVX").
7758 void sv_usepvn_flags(SV *const sv, char* ptr,
7760 const STRLEN len,
7761 const U32 flags)
7762 sv_utf8_decode
7764 NOTE: this function is experimental and may change or be
7765 removed without notice.
7766 If the PV of the SV is an octet sequence in Perl's extended
7768 UTF-8 and contains a multiple-byte character, the "SvUTF8" flag
7769 is turned on so that it looks like a character. If the PV
7770 contains only single-byte characters, the "SvUTF8" flag stays
7771 off. Scans PV for validity and returns FALSE if the PV is
7772 invalid UTF-8.
7773 bool sv_utf8_decode(SV *const sv)
7775 sv_utf8_downgrade
7777 NOTE: this function is experimental and may change or be
7778 removed without notice.
7779 Attempts to convert the PV of an SV from characters to bytes.
7781 If the PV contains a character that cannot fit in a byte, this
7782 conversion will fail; in this case, either returns false or, if
7783 "fail_ok" is not true, croaks.
7784 This is not a general purpose Unicode to byte encoding
7786 interface: use the "Encode" extension for that.
7787 bool sv_utf8_downgrade(SV *const sv,
7789 const bool fail_ok)
7790 sv_utf8_encode
7792 Converts the PV of an SV to UTF-8, but then turns the "SvUTF8"
7793 flag off so that it looks like octets again.
7794 void sv_utf8_encode(SV *const sv)
7796 sv_utf8_upgrade
7798 Converts the PV of an SV to its UTF-8-encoded form. Forces the
7799 SV to string form if it is not already. Will "mg_get" on "sv"
7800 if appropriate. Always sets the "SvUTF8" flag to avoid future
7801 validity checks even if the whole string is the same in UTF-8
7802 as not. Returns the number of bytes in the converted string
7803 This is not a general purpose byte encoding to Unicode
7805 interface: use the Encode extension for that.
7806 STRLEN sv_utf8_upgrade(SV *sv)
7808 sv_utf8_upgrade_flags
7810 Converts the PV of an SV to its UTF-8-encoded form. Forces the
7811 SV to string form if it is not already. Always sets the SvUTF8
7812 flag to avoid future validity checks even if all the bytes are
7813 invariant in UTF-8. If "flags" has "SV_GMAGIC" bit set, will
7814 "mg_get" on "sv" if appropriate, else not.
7815 If "flags" has "SV_FORCE_UTF8_UPGRADE" set, this function
7817 assumes that the PV will expand when converted to UTF-8, and
7818 skips the extra work of checking for that. Typically this flag
7819 is used by a routine that has already parsed the string and
7820 found such characters, and passes this information on so that
7821 the work doesn't have to be repeated.
7822 Returns the number of bytes in the converted string.
7824 This is not a general purpose byte encoding to Unicode
7826 interface: use the Encode extension for that.
7827 STRLEN sv_utf8_upgrade_flags(SV *const sv,
7829 const I32 flags)
7830 sv_utf8_upgrade_flags_grow
7832 Like "sv_utf8_upgrade_flags", but has an additional parameter
7833 "extra", which is the number of unused bytes the string of "sv"
7834 is guaranteed to have free after it upon return. This allows
7835 the caller to reserve extra space that it intends to fill, to
7836 avoid extra grows.
7837 "sv_utf8_upgrade", "sv_utf8_upgrade_nomg", and
7839 "sv_utf8_upgrade_flags" are implemented in terms of this
7840 function.
7841 Returns the number of bytes in the converted string (not
7843 including the spares).
7844 STRLEN sv_utf8_upgrade_flags_grow(SV *const sv,
7846 const I32 flags,
7847 STRLEN extra)
7848 sv_utf8_upgrade_nomg
7850 Like "sv_utf8_upgrade", but doesn't do magic on "sv".
7851 STRLEN sv_utf8_upgrade_nomg(SV *sv)
7853 sv_vcatpvf
7855 Processes its arguments like "sv_catpvfn" called with a non-
7856 null C-style variable argument list, and appends the formatted
7857 output to an SV. Does not handle 'set' magic. See
7858 "sv_vcatpvf_mg".
7859 Usually used via its frontend "sv_catpvf".
7861 void sv_vcatpvf(SV *const sv, const char *const pat,
7863 va_list *const args)
7864 sv_vcatpvfn
7866 void sv_vcatpvfn(SV *const sv, const char *const pat,
7867 const STRLEN patlen,
7868 va_list *const args,
7869 SV **const svargs, const I32 svmax,
7870 bool *const maybe_tainted)
7871 sv_vcatpvfn_flags
7873 Processes its arguments like "vsprintf" and appends the
7874 formatted output to an SV. Uses an array of SVs if the C-style
7875 variable argument list is missing ("NULL"). Argument reordering
7876 (using format specifiers like "%2$d" or "%*2$d") is supported
7877 only when using an array of SVs; using a C-style "va_list"
7878 argument list with a format string that uses argument
7879 reordering will yield an exception.
7880 When running with taint checks enabled, indicates via
7882 "maybe_tainted" if results are untrustworthy (often due to the
7883 use of locales).
7884 If called as "sv_vcatpvfn" or flags has the "SV_GMAGIC" bit
7886 set, calls get magic.
7887 Usually used via one of its frontends "sv_vcatpvf" and
7889 "sv_vcatpvf_mg".
7890 void sv_vcatpvfn_flags(SV *const sv,
7892 const char *const pat,
7893 const STRLEN patlen,
7894 va_list *const args,
7895 SV **const svargs,
7896 const I32 svmax,
7897 bool *const maybe_tainted,
7898 const U32 flags)
7899 sv_vcatpvf_mg
7901 Like "sv_vcatpvf", but also handles 'set' magic.
7902 Usually used via its frontend "sv_catpvf_mg".
7904 void sv_vcatpvf_mg(SV *const sv,
7906 const char *const pat,
7907 va_list *const args)
7908 sv_vsetpvf
7910 Works like "sv_vcatpvf" but copies the text into the SV instead
7911 of appending it. Does not handle 'set' magic. See
7912 "sv_vsetpvf_mg".
7913 Usually used via its frontend "sv_setpvf".
7915 void sv_vsetpvf(SV *const sv, const char *const pat,
7917 va_list *const args)
7918 sv_vsetpvfn
7920 Works like "sv_vcatpvfn" but copies the text into the SV
7921 instead of appending it.
7922 Usually used via one of its frontends "sv_vsetpvf" and
7924 "sv_vsetpvf_mg".
7925 void sv_vsetpvfn(SV *const sv, const char *const pat,
7927 const STRLEN patlen,
7928 va_list *const args,
7929 SV **const svargs, const I32 svmax,
7930 bool *const maybe_tainted)
7931 sv_vsetpvf_mg
7933 Like "sv_vsetpvf", but also handles 'set' magic.
7934 Usually used via its frontend "sv_setpvf_mg".
7936 void sv_vsetpvf_mg(SV *const sv,
7938 const char *const pat,
7939 va_list *const args)
7940
7942 SVt_INVLIST
7943 Type flag for scalars. See "svtype".
7944 SVt_IV Type flag for scalars. See "svtype".
7946 SVt_NULL
7948 Type flag for scalars. See "svtype".
7949 SVt_NV Type flag for scalars. See "svtype".
7951 SVt_PV Type flag for scalars. See "svtype".
7953 SVt_PVAV
7955 Type flag for arrays. See "svtype".
7956 SVt_PVCV
7958 Type flag for subroutines. See "svtype".
7959 SVt_PVFM
7961 Type flag for formats. See "svtype".
7962 SVt_PVGV
7964 Type flag for typeglobs. See "svtype".
7965 SVt_PVHV
7967 Type flag for hashes. See "svtype".
7968 SVt_PVIO
7970 Type flag for I/O objects. See "svtype".
7971 SVt_PVIV
7973 Type flag for scalars. See "svtype".
7974 SVt_PVLV
7976 Type flag for scalars. See "svtype".
7977 SVt_PVMG
7979 Type flag for scalars. See "svtype".
7980 SVt_PVNV
7982 Type flag for scalars. See "svtype".
7983 SVt_REGEXP
7985 Type flag for regular expressions. See "svtype".
7986 svtype An enum of flags for Perl types. These are found in the file
7988 sv.h in the "svtype" enum. Test these flags with the "SvTYPE"
7989 macro.
7990 The types are:
7992 SVt_NULL
7994 SVt_IV
7995 SVt_NV
7996 SVt_RV
7997 SVt_PV
7998 SVt_PVIV
7999 SVt_PVNV
8000 SVt_PVMG
8001 SVt_INVLIST
8002 SVt_REGEXP
8003 SVt_PVGV
8004 SVt_PVLV
8005 SVt_PVAV
8006 SVt_PVHV
8007 SVt_PVCV
8008 SVt_PVFM
8009 SVt_PVIO
8010 These are most easily explained from the bottom up.
8012 "SVt_PVIO" is for I/O objects, "SVt_PVFM" for formats,
8014 "SVt_PVCV" for subroutines, "SVt_PVHV" for hashes and
8015 "SVt_PVAV" for arrays.
8016 All the others are scalar types, that is, things that can be
8018 bound to a "$" variable. For these, the internal types are
8019 mostly orthogonal to types in the Perl language.
8020 Hence, checking "SvTYPE(sv) < SVt_PVAV" is the best way to see
8022 whether something is a scalar.
8023 "SVt_PVGV" represents a typeglob. If "!SvFAKE(sv)", then it is
8025 a real, incoercible typeglob. If "SvFAKE(sv)", then it is a
8026 scalar to which a typeglob has been assigned. Assigning to it
8027 again will stop it from being a typeglob. "SVt_PVLV"
8028 represents a scalar that delegates to another scalar behind the
8029 scenes. It is used, e.g., for the return value of "substr" and
8030 for tied hash and array elements. It can hold any scalar
8031 value, including a typeglob. "SVt_REGEXP" is for regular
8032 expressions. "SVt_INVLIST" is for Perl core internal use only.
8033 "SVt_PVMG" represents a "normal" scalar (not a typeglob,
8035 regular expression, or delegate). Since most scalars do not
8036 need all the internal fields of a PVMG, we save memory by
8037 allocating smaller structs when possible. All the other types
8038 are just simpler forms of "SVt_PVMG", with fewer internal
8039 fields. "SVt_NULL" can only hold undef. "SVt_IV" can hold
8040 undef, an integer, or a reference. ("SVt_RV" is an alias for
8041 "SVt_IV", which exists for backward compatibility.) "SVt_NV"
8042 can hold any of those or a double. "SVt_PV" can only hold
8043 "undef" or a string. "SVt_PVIV" is a superset of "SVt_PV" and
8044 "SVt_IV". "SVt_PVNV" is similar. "SVt_PVMG" can hold anything
8045 "SVt_PVNV" can hold, but it can, but does not have to, be
8046 blessed or magical.
8047
8049 boolSV Returns a true SV if "b" is a true value, or a false SV if "b"
8050 is 0.
8051 See also "PL_sv_yes" and "PL_sv_no".
8053 SV * boolSV(bool b)
8055 croak_xs_usage
8057 A specialised variant of "croak()" for emitting the usage
8058 message for xsubs
8059 croak_xs_usage(cv, "eee_yow");
8061 works out the package name and subroutine name from "cv", and
8063 then calls "croak()". Hence if "cv" is &ouch::awk, it would
8064 call "croak" as:
8065 Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
8067 "eee_yow");
8068 void croak_xs_usage(const CV *const cv,
8070 const char *const params)
8071 get_sv Returns the SV of the specified Perl scalar. "flags" are
8073 passed to "gv_fetchpv". If "GV_ADD" is set and the Perl
8074 variable does not exist then it will be created. If "flags" is
8075 zero and the variable does not exist then NULL is returned.
8076 NOTE: the perl_ form of this function is deprecated.
8078 SV* get_sv(const char *name, I32 flags)
8080 newRV_inc
8082 Creates an RV wrapper for an SV. The reference count for the
8083 original SV is incremented.
8084 SV* newRV_inc(SV* sv)
8086 newSVpadname
8088 NOTE: this function is experimental and may change or be
8089 removed without notice.
8090 Creates a new SV containing the pad name.
8092 SV* newSVpadname(PADNAME *pn)
8094 newSVpvn_utf8
8096 Creates a new SV and copies a string (which may contain "NUL"
8097 ("\0") characters) into it. If "utf8" is true, calls
8098 "SvUTF8_on" on the new SV. Implemented as a wrapper around
8099 "newSVpvn_flags".
8100 SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len,
8102 U32 utf8)
8103 sv_catpvn_nomg
8105 Like "sv_catpvn" but doesn't process magic.
8106 void sv_catpvn_nomg(SV* sv, const char* ptr,
8108 STRLEN len)
8109 sv_catpv_nomg
8111 Like "sv_catpv" but doesn't process magic.
8112 void sv_catpv_nomg(SV* sv, const char* ptr)
8114 sv_catsv_nomg
8116 Like "sv_catsv" but doesn't process magic.
8117 void sv_catsv_nomg(SV* dsv, SV* ssv)
8119 SvCUR Returns the length of the string which is in the SV. See
8121 "SvLEN".
8122 STRLEN SvCUR(SV* sv)
8124 SvCUR_set
8126 Set the current length of the string which is in the SV. See
8127 "SvCUR" and "SvIV_set">.
8128 void SvCUR_set(SV* sv, STRLEN len)
8130 sv_derived_from
8132 Exactly like "sv_derived_from_pv", but doesn't take a "flags"
8133 parameter.
8134 bool sv_derived_from(SV* sv, const char *const name)
8136 sv_derived_from_pv
8138 Exactly like "sv_derived_from_pvn", but takes a nul-terminated
8139 string instead of a string/length pair.
8140 bool sv_derived_from_pv(SV* sv,
8142 const char *const name,
8143 U32 flags)
8144 sv_derived_from_pvn
8146 Returns a boolean indicating whether the SV is derived from the
8147 specified class at the C level. To check derivation at the
8148 Perl level, call "isa()" as a normal Perl method.
8149 Currently, the only significant value for "flags" is SVf_UTF8.
8151 bool sv_derived_from_pvn(SV* sv,
8153 const char *const name,
8154 const STRLEN len, U32 flags)
8155 sv_derived_from_sv
8157 Exactly like "sv_derived_from_pvn", but takes the name string
8158 in the form of an SV instead of a string/length pair.
8159 bool sv_derived_from_sv(SV* sv, SV *namesv,
8161 U32 flags)
8162 sv_does Like "sv_does_pv", but doesn't take a "flags" parameter.
8164 bool sv_does(SV* sv, const char *const name)
8166 sv_does_pv
8168 Like "sv_does_sv", but takes a nul-terminated string instead of
8169 an SV.
8170 bool sv_does_pv(SV* sv, const char *const name,
8172 U32 flags)
8173 sv_does_pvn
8175 Like "sv_does_sv", but takes a string/length pair instead of an
8176 SV.
8177 bool sv_does_pvn(SV* sv, const char *const name,
8179 const STRLEN len, U32 flags)
8180 sv_does_sv
8182 Returns a boolean indicating whether the SV performs a
8183 specific, named role. The SV can be a Perl object or the name
8184 of a Perl class.
8185 bool sv_does_sv(SV* sv, SV* namesv, U32 flags)
8187 SvEND Returns a pointer to the spot just after the last character in
8189 the string which is in the SV, where there is usually a
8190 trailing "NUL" character (even though Perl scalars do not
8191 strictly require it). See "SvCUR". Access the character as
8192 "*(SvEND(sv))".
8193 Warning: If "SvCUR" is equal to "SvLEN", then "SvEND" points to
8195 unallocated memory.
8196 char* SvEND(SV* sv)
8198 SvGAMAGIC
8200 Returns true if the SV has get magic or overloading. If either
8201 is true then the scalar is active data, and has the potential
8202 to return a new value every time it is accessed. Hence you
8203 must be careful to only read it once per user logical operation
8204 and work with that returned value. If neither is true then the
8205 scalar's value cannot change unless written to.
8206 U32 SvGAMAGIC(SV* sv)
8208 SvGROW Expands the character buffer in the SV so that it has room for
8210 the indicated number of bytes (remember to reserve space for an
8211 extra trailing "NUL" character). Calls "sv_grow" to perform
8212 the expansion if necessary. Returns a pointer to the character
8213 buffer. SV must be of type >= "SVt_PV". One alternative is to
8214 call "sv_grow" if you are not sure of the type of SV.
8215 You might mistakenly think that "len" is the number of bytes to
8217 add to the existing size, but instead it is the total size "sv"
8218 should be.
8219 char * SvGROW(SV* sv, STRLEN len)
8221 SvIOK Returns a U32 value indicating whether the SV contains an
8223 integer.
8224 U32 SvIOK(SV* sv)
8226 SvIOK_notUV
8228 Returns a boolean indicating whether the SV contains a signed
8229 integer.
8230 bool SvIOK_notUV(SV* sv)
8232 SvIOK_off
8234 Unsets the IV status of an SV.
8235 void SvIOK_off(SV* sv)
8237 SvIOK_on
8239 Tells an SV that it is an integer.
8240 void SvIOK_on(SV* sv)
8242 SvIOK_only
8244 Tells an SV that it is an integer and disables all other "OK"
8245 bits.
8246 void SvIOK_only(SV* sv)
8248 SvIOK_only_UV
8250 Tells an SV that it is an unsigned integer and disables all
8251 other "OK" bits.
8252 void SvIOK_only_UV(SV* sv)
8254 SvIOKp Returns a U32 value indicating whether the SV contains an
8256 integer. Checks the private setting. Use "SvIOK" instead.
8257 U32 SvIOKp(SV* sv)
8259 SvIOK_UV
8261 Returns a boolean indicating whether the SV contains an integer
8262 that must be interpreted as unsigned. A non-negative integer
8263 whose value is within the range of both an IV and a UV may be
8264 be flagged as either "SvUOK" or "SVIOK".
8265 bool SvIOK_UV(SV* sv)
8267 SvIsCOW Returns a U32 value indicating whether the SV is Copy-On-Write
8269 (either shared hash key scalars, or full Copy On Write scalars
8270 if 5.9.0 is configured for COW).
8271 U32 SvIsCOW(SV* sv)
8273 SvIsCOW_shared_hash
8275 Returns a boolean indicating whether the SV is Copy-On-Write
8276 shared hash key scalar.
8277 bool SvIsCOW_shared_hash(SV* sv)
8279 SvIV Coerces the given SV to IV and returns it. The returned value
8281 in many circumstances will get stored in "sv"'s IV slot, but
8282 not in all cases. (Use "sv_setiv" to make sure it does).
8283 See "SvIVx" for a version which guarantees to evaluate "sv"
8285 only once.
8286 IV SvIV(SV* sv)
8288 SvIV_nomg
8290 Like "SvIV" but doesn't process magic.
8291 IV SvIV_nomg(SV* sv)
8293 SvIV_set
8295 Set the value of the IV pointer in sv to val. It is possible
8296 to perform the same function of this macro with an lvalue
8297 assignment to "SvIVX". With future Perls, however, it will be
8298 more efficient to use "SvIV_set" instead of the lvalue
8299 assignment to "SvIVX".
8300 void SvIV_set(SV* sv, IV val)
8302 SvIVX Returns the raw value in the SV's IV slot, without checks or
8304 conversions. Only use when you are sure "SvIOK" is true. See
8305 also "SvIV".
8306 IV SvIVX(SV* sv)
8308 SvIVx Coerces the given SV to IV and returns it. The returned value
8310 in many circumstances will get stored in "sv"'s IV slot, but
8311 not in all cases. (Use "sv_setiv" to make sure it does).
8312 This form guarantees to evaluate "sv" only once. Only use this
8314 if "sv" is an expression with side effects, otherwise use the
8315 more efficient "SvIV".
8316 IV SvIVx(SV* sv)
8318 SvLEN Returns the size of the string buffer in the SV, not including
8320 any part attributable to "SvOOK". See "SvCUR".
8321 STRLEN SvLEN(SV* sv)
8323 SvLEN_set
8325 Set the size of the string buffer for the SV. See "SvLEN".
8326 void SvLEN_set(SV* sv, STRLEN len)
8328 SvMAGIC_set
8330 Set the value of the MAGIC pointer in "sv" to val. See
8331 "SvIV_set".
8332 void SvMAGIC_set(SV* sv, MAGIC* val)
8334 SvNIOK Returns a U32 value indicating whether the SV contains a
8336 number, integer or double.
8337 U32 SvNIOK(SV* sv)
8339 SvNIOK_off
8341 Unsets the NV/IV status of an SV.
8342 void SvNIOK_off(SV* sv)
8344 SvNIOKp Returns a U32 value indicating whether the SV contains a
8346 number, integer or double. Checks the private setting. Use
8347 "SvNIOK" instead.
8348 U32 SvNIOKp(SV* sv)
8350 SvNOK Returns a U32 value indicating whether the SV contains a
8352 double.
8353 U32 SvNOK(SV* sv)
8355 SvNOK_off
8357 Unsets the NV status of an SV.
8358 void SvNOK_off(SV* sv)
8360 SvNOK_on
8362 Tells an SV that it is a double.
8363 void SvNOK_on(SV* sv)
8365 SvNOK_only
8367 Tells an SV that it is a double and disables all other OK bits.
8368 void SvNOK_only(SV* sv)
8370 SvNOKp Returns a U32 value indicating whether the SV contains a
8372 double. Checks the private setting. Use "SvNOK" instead.
8373 U32 SvNOKp(SV* sv)
8375 SvNV Coerces the given SV to NV and returns it. The returned value
8377 in many circumstances will get stored in "sv"'s NV slot, but
8378 not in all cases. (Use "sv_setnv" to make sure it does).
8379 See "SvNVx" for a version which guarantees to evaluate "sv"
8381 only once.
8382 NV SvNV(SV* sv)
8384 SvNV_nomg
8386 Like "SvNV" but doesn't process magic.
8387 NV SvNV_nomg(SV* sv)
8389 SvNV_set
8391 Set the value of the NV pointer in "sv" to val. See
8392 "SvIV_set".
8393 void SvNV_set(SV* sv, NV val)
8395 SvNVX Returns the raw value in the SV's NV slot, without checks or
8397 conversions. Only use when you are sure "SvNOK" is true. See
8398 also "SvNV".
8399 NV SvNVX(SV* sv)
8401 SvNVx Coerces the given SV to NV and returns it. The returned value
8403 in many circumstances will get stored in "sv"'s NV slot, but
8404 not in all cases. (Use "sv_setnv" to make sure it does).
8405 This form guarantees to evaluate "sv" only once. Only use this
8407 if "sv" is an expression with side effects, otherwise use the
8408 more efficient "SvNV".
8409 NV SvNVx(SV* sv)
8411 SvOK Returns a U32 value indicating whether the value is defined.
8413 This is only meaningful for scalars.
8414 U32 SvOK(SV* sv)
8416 SvOOK Returns a U32 indicating whether the pointer to the string
8418 buffer is offset. This hack is used internally to speed up
8419 removal of characters from the beginning of a "SvPV". When
8420 "SvOOK" is true, then the start of the allocated string buffer
8421 is actually "SvOOK_offset()" bytes before "SvPVX". This offset
8422 used to be stored in "SvIVX", but is now stored within the
8423 spare part of the buffer.
8424 U32 SvOOK(SV* sv)
8426 SvOOK_offset
8428 Reads into "len" the offset from "SvPVX" back to the true start
8429 of the allocated buffer, which will be non-zero if "sv_chop"
8430 has been used to efficiently remove characters from start of
8431 the buffer. Implemented as a macro, which takes the address of
8432 "len", which must be of type "STRLEN". Evaluates "sv" more
8433 than once. Sets "len" to 0 if "SvOOK(sv)" is false.
8434 void SvOOK_offset(NN SV*sv, STRLEN len)
8436 SvPOK Returns a U32 value indicating whether the SV contains a
8438 character string.
8439 U32 SvPOK(SV* sv)
8441 SvPOK_off
8443 Unsets the PV status of an SV.
8444 void SvPOK_off(SV* sv)
8446 SvPOK_on
8448 Tells an SV that it is a string.
8449 void SvPOK_on(SV* sv)
8451 SvPOK_only
8453 Tells an SV that it is a string and disables all other "OK"
8454 bits. Will also turn off the UTF-8 status.
8455 void SvPOK_only(SV* sv)
8457 SvPOK_only_UTF8
8459 Tells an SV that it is a string and disables all other "OK"
8460 bits, and leaves the UTF-8 status as it was.
8461 void SvPOK_only_UTF8(SV* sv)
8463 SvPOKp Returns a U32 value indicating whether the SV contains a
8465 character string. Checks the private setting. Use "SvPOK"
8466 instead.
8467 U32 SvPOKp(SV* sv)
8469 SvPV Returns a pointer to the string in the SV, or a stringified
8471 form of the SV if the SV does not contain a string. The SV may
8472 cache the stringified version becoming "SvPOK". Handles 'get'
8473 magic. The "len" variable will be set to the length of the
8474 string (this is a macro, so don't use &len). See also "SvPVx"
8475 for a version which guarantees to evaluate "sv" only once.
8476 Note that there is no guarantee that the return value of
8478 "SvPV()" is equal to "SvPVX(sv)", or that "SvPVX(sv)" contains
8479 valid data, or that successive calls to "SvPV(sv)" will return
8480 the same pointer value each time. This is due to the way that
8481 things like overloading and Copy-On-Write are handled. In
8482 these cases, the return value may point to a temporary buffer
8483 or similar. If you absolutely need the "SvPVX" field to be
8484 valid (for example, if you intend to write to it), then see
8485 "SvPV_force".
8486 char* SvPV(SV* sv, STRLEN len)
8488 SvPVbyte
8490 Like "SvPV", but converts "sv" to byte representation first if
8491 necessary.
8492 char* SvPVbyte(SV* sv, STRLEN len)
8494 SvPVbyte_force
8496 Like "SvPV_force", but converts "sv" to byte representation
8497 first if necessary.
8498 char* SvPVbyte_force(SV* sv, STRLEN len)
8500 SvPVbyte_nolen
8502 Like "SvPV_nolen", but converts "sv" to byte representation
8503 first if necessary.
8504 char* SvPVbyte_nolen(SV* sv)
8506 SvPVbytex
8508 Like "SvPV", but converts "sv" to byte representation first if
8509 necessary. Guarantees to evaluate "sv" only once; use the more
8510 efficient "SvPVbyte" otherwise.
8511 char* SvPVbytex(SV* sv, STRLEN len)
8513 SvPVbytex_force
8515 Like "SvPV_force", but converts "sv" to byte representation
8516 first if necessary. Guarantees to evaluate "sv" only once; use
8517 the more efficient "SvPVbyte_force" otherwise.
8518 char* SvPVbytex_force(SV* sv, STRLEN len)
8520 SvPVCLEAR
8522 Ensures that sv is a SVt_PV and that its SvCUR is 0, and that
8523 it is properly null terminated. Equivalent to sv_setpvs(""),
8524 but more efficient.
8525 char * SvPVCLEAR(SV* sv)
8527 SvPV_force
8529 Like "SvPV" but will force the SV into containing a string
8530 ("SvPOK"), and only a string ("SvPOK_only"), by hook or by
8531 crook. You need force if you are going to update the "SvPVX"
8532 directly. Processes get magic.
8533 Note that coercing an arbitrary scalar into a plain PV will
8535 potentially strip useful data from it. For example if the SV
8536 was "SvROK", then the referent will have its reference count
8537 decremented, and the SV itself may be converted to an "SvPOK"
8538 scalar with a string buffer containing a value such as
8539 "ARRAY(0x1234)".
8540 char* SvPV_force(SV* sv, STRLEN len)
8542 SvPV_force_nomg
8544 Like "SvPV_force", but doesn't process get magic.
8545 char* SvPV_force_nomg(SV* sv, STRLEN len)
8547 SvPV_nolen
8549 Like "SvPV" but doesn't set a length variable.
8550 char* SvPV_nolen(SV* sv)
8552 SvPV_nomg
8554 Like "SvPV" but doesn't process magic.
8555 char* SvPV_nomg(SV* sv, STRLEN len)
8557 SvPV_nomg_nolen
8559 Like "SvPV_nolen" but doesn't process magic.
8560 char* SvPV_nomg_nolen(SV* sv)
8562 SvPV_set
8564 This is probably not what you want to use, you probably wanted
8565 "sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
8566 Set the value of the PV pointer in "sv" to the Perl allocated
8568 "NUL"-terminated string "val". See also "SvIV_set".
8569 Remember to free the previous PV buffer. There are many things
8571 to check. Beware that the existing pointer may be involved in
8572 copy-on-write or other mischief, so do "SvOOK_off(sv)" and use
8573 "sv_force_normal" or "SvPV_force" (or check the "SvIsCOW" flag)
8574 first to make sure this modification is safe. Then finally, if
8575 it is not a COW, call "SvPV_free" to free the previous PV
8576 buffer.
8577 void SvPV_set(SV* sv, char* val)
8579 SvPVutf8
8581 Like "SvPV", but converts "sv" to UTF-8 first if necessary.
8582 char* SvPVutf8(SV* sv, STRLEN len)
8584 SvPVutf8x
8586 Like "SvPV", but converts "sv" to UTF-8 first if necessary.
8587 Guarantees to evaluate "sv" only once; use the more efficient
8588 "SvPVutf8" otherwise.
8589 char* SvPVutf8x(SV* sv, STRLEN len)
8591 SvPVutf8x_force
8593 Like "SvPV_force", but converts "sv" to UTF-8 first if
8594 necessary. Guarantees to evaluate "sv" only once; use the more
8595 efficient "SvPVutf8_force" otherwise.
8596 char* SvPVutf8x_force(SV* sv, STRLEN len)
8598 SvPVutf8_force
8600 Like "SvPV_force", but converts "sv" to UTF-8 first if
8601 necessary.
8602 char* SvPVutf8_force(SV* sv, STRLEN len)
8604 SvPVutf8_nolen
8606 Like "SvPV_nolen", but converts "sv" to UTF-8 first if
8607 necessary.
8608 char* SvPVutf8_nolen(SV* sv)
8610 SvPVX Returns a pointer to the physical string in the SV. The SV
8612 must contain a string. Prior to 5.9.3 it is not safe to
8613 execute this macro unless the SV's type >= "SVt_PV".
8614 This is also used to store the name of an autoloaded subroutine
8616 in an XS AUTOLOAD routine. See "Autoloading with XSUBs" in
8617 perlguts.
8618 char* SvPVX(SV* sv)
8620 SvPVx A version of "SvPV" which guarantees to evaluate "sv" only
8622 once. Only use this if "sv" is an expression with side
8623 effects, otherwise use the more efficient "SvPV".
8624 char* SvPVx(SV* sv, STRLEN len)
8626 SvREADONLY
8628 Returns true if the argument is readonly, otherwise returns
8629 false. Exposed to to perl code via Internals::SvREADONLY().
8630 U32 SvREADONLY(SV* sv)
8632 SvREADONLY_off
8634 Mark an object as not-readonly. Exactly what this mean depends
8635 on the object type. Exposed to perl code via
8636 Internals::SvREADONLY().
8637 U32 SvREADONLY_off(SV* sv)
8639 SvREADONLY_on
8641 Mark an object as readonly. Exactly what this means depends on
8642 the object type. Exposed to perl code via
8643 Internals::SvREADONLY().
8644 U32 SvREADONLY_on(SV* sv)
8646 SvREFCNT
8648 Returns the value of the object's reference count. Exposed to
8649 perl code via Internals::SvREFCNT().
8650 U32 SvREFCNT(SV* sv)
8652 SvREFCNT_dec
8654 Decrements the reference count of the given SV. "sv" may be
8655 "NULL".
8656 void SvREFCNT_dec(SV* sv)
8658 SvREFCNT_dec_NN
8660 Same as "SvREFCNT_dec", but can only be used if you know "sv"
8661 is not "NULL". Since we don't have to check the NULLness, it's
8662 faster and smaller.
8663 void SvREFCNT_dec_NN(SV* sv)
8665 SvREFCNT_inc
8667 Increments the reference count of the given SV, returning the
8668 SV.
8669 All of the following "SvREFCNT_inc"* macros are optimized
8671 versions of "SvREFCNT_inc", and can be replaced with
8672 "SvREFCNT_inc".
8673 SV* SvREFCNT_inc(SV* sv)
8675 SvREFCNT_inc_NN
8677 Same as "SvREFCNT_inc", but can only be used if you know "sv"
8678 is not "NULL". Since we don't have to check the NULLness, it's
8679 faster and smaller.
8680 SV* SvREFCNT_inc_NN(SV* sv)
8682 SvREFCNT_inc_simple
8684 Same as "SvREFCNT_inc", but can only be used with expressions
8685 without side effects. Since we don't have to store a temporary
8686 value, it's faster.
8687 SV* SvREFCNT_inc_simple(SV* sv)
8689 SvREFCNT_inc_simple_NN
8691 Same as "SvREFCNT_inc_simple", but can only be used if you know
8692 "sv" is not "NULL". Since we don't have to check the NULLness,
8693 it's faster and smaller.
8694 SV* SvREFCNT_inc_simple_NN(SV* sv)
8696 SvREFCNT_inc_simple_void
8698 Same as "SvREFCNT_inc_simple", but can only be used if you
8699 don't need the return value. The macro doesn't need to return
8700 a meaningful value.
8701 void SvREFCNT_inc_simple_void(SV* sv)
8703 SvREFCNT_inc_simple_void_NN
8705 Same as "SvREFCNT_inc", but can only be used if you don't need
8706 the return value, and you know that "sv" is not "NULL". The
8707 macro doesn't need to return a meaningful value, or check for
8708 NULLness, so it's smaller and faster.
8709 void SvREFCNT_inc_simple_void_NN(SV* sv)
8711 SvREFCNT_inc_void
8713 Same as "SvREFCNT_inc", but can only be used if you don't need
8714 the return value. The macro doesn't need to return a
8715 meaningful value.
8716 void SvREFCNT_inc_void(SV* sv)
8718 SvREFCNT_inc_void_NN
8720 Same as "SvREFCNT_inc", but can only be used if you don't need
8721 the return value, and you know that "sv" is not "NULL". The
8722 macro doesn't need to return a meaningful value, or check for
8723 NULLness, so it's smaller and faster.
8724 void SvREFCNT_inc_void_NN(SV* sv)
8726 sv_report_used
8728 Dump the contents of all SVs not yet freed (debugging aid).
8729 void sv_report_used()
8731 SvROK Tests if the SV is an RV.
8733 U32 SvROK(SV* sv)
8735 SvROK_off
8737 Unsets the RV status of an SV.
8738 void SvROK_off(SV* sv)
8740 SvROK_on
8742 Tells an SV that it is an RV.
8743 void SvROK_on(SV* sv)
8745 SvRV Dereferences an RV to return the SV.
8747 SV* SvRV(SV* sv)
8749 SvRV_set
8751 Set the value of the RV pointer in "sv" to val. See
8752 "SvIV_set".
8753 void SvRV_set(SV* sv, SV* val)
8755 sv_setsv_nomg
8757 Like "sv_setsv" but doesn't process magic.
8758 void sv_setsv_nomg(SV* dsv, SV* ssv)
8760 SvSTASH Returns the stash of the SV.
8762 HV* SvSTASH(SV* sv)
8764 SvSTASH_set
8766 Set the value of the STASH pointer in "sv" to val. See
8767 "SvIV_set".
8768 void SvSTASH_set(SV* sv, HV* val)
8770 SvTAINT Taints an SV if tainting is enabled, and if some input to the
8772 current expression is tainted--usually a variable, but possibly
8773 also implicit inputs such as locale settings. "SvTAINT"
8774 propagates that taintedness to the outputs of an expression in
8775 a pessimistic fashion; i.e., without paying attention to
8776 precisely which outputs are influenced by which inputs.
8777 void SvTAINT(SV* sv)
8779 SvTAINTED
8781 Checks to see if an SV is tainted. Returns TRUE if it is,
8782 FALSE if not.
8783 bool SvTAINTED(SV* sv)
8785 SvTAINTED_off
8787 Untaints an SV. Be very careful with this routine, as it
8788 short-circuits some of Perl's fundamental security features.
8789 XS module authors should not use this function unless they
8790 fully understand all the implications of unconditionally
8791 untainting the value. Untainting should be done in the
8792 standard perl fashion, via a carefully crafted regexp, rather
8793 than directly untainting variables.
8794 void SvTAINTED_off(SV* sv)
8796 SvTAINTED_on
8798 Marks an SV as tainted if tainting is enabled.
8799 void SvTAINTED_on(SV* sv)
8801 SvTRUE Returns a boolean indicating whether Perl would evaluate the SV
8803 as true or false. See "SvOK" for a defined/undefined test.
8804 Handles 'get' magic unless the scalar is already "SvPOK",
8805 "SvIOK" or "SvNOK" (the public, not the private flags).
8806 bool SvTRUE(SV* sv)
8808 SvTRUE_nomg
8810 Returns a boolean indicating whether Perl would evaluate the SV
8811 as true or false. See "SvOK" for a defined/undefined test.
8812 Does not handle 'get' magic.
8813 bool SvTRUE_nomg(SV* sv)
8815 SvTYPE Returns the type of the SV. See "svtype".
8817 svtype SvTYPE(SV* sv)
8819 SvUOK Returns a boolean indicating whether the SV contains an integer
8821 that must be interpreted as unsigned. A non-negative integer
8822 whose value is within the range of both an IV and a UV may be
8823 be flagged as either "SvUOK" or "SVIOK".
8824 bool SvUOK(SV* sv)
8826 SvUPGRADE
8828 Used to upgrade an SV to a more complex form. Uses
8829 "sv_upgrade" to perform the upgrade if necessary. See
8830 "svtype".
8831 void SvUPGRADE(SV* sv, svtype type)
8833 SvUTF8 Returns a U32 value indicating the UTF-8 status of an SV. If
8835 things are set-up properly, this indicates whether or not the
8836 SV contains UTF-8 encoded data. You should use this after a
8837 call to "SvPV()" or one of its variants, in case any call to
8838 string overloading updates the internal flag.
8839 If you want to take into account the bytes pragma, use
8841 "DO_UTF8" instead.
8842 U32 SvUTF8(SV* sv)
8844 sv_utf8_upgrade_nomg
8846 Like "sv_utf8_upgrade", but doesn't do magic on "sv".
8847 STRLEN sv_utf8_upgrade_nomg(NN SV *sv)
8849 SvUTF8_off
8851 Unsets the UTF-8 status of an SV (the data is not changed, just
8852 the flag). Do not use frivolously.
8853 void SvUTF8_off(SV *sv)
8855 SvUTF8_on
8857 Turn on the UTF-8 status of an SV (the data is not changed,
8858 just the flag). Do not use frivolously.
8859 void SvUTF8_on(SV *sv)
8861 SvUV Coerces the given SV to UV and returns it. The returned value
8863 in many circumstances will get stored in "sv"'s UV slot, but
8864 not in all cases. (Use "sv_setuv" to make sure it does).
8865 See "SvUVx" for a version which guarantees to evaluate "sv"
8867 only once.
8868 UV SvUV(SV* sv)
8870 SvUV_nomg
8872 Like "SvUV" but doesn't process magic.
8873 UV SvUV_nomg(SV* sv)
8875 SvUV_set
8877 Set the value of the UV pointer in "sv" to val. See
8878 "SvIV_set".
8879 void SvUV_set(SV* sv, UV val)
8881 SvUVX Returns the raw value in the SV's UV slot, without checks or
8883 conversions. Only use when you are sure "SvIOK" is true. See
8884 also "SvUV".
8885 UV SvUVX(SV* sv)
8887 SvUVx Coerces the given SV to UV and returns it. The returned value
8889 in many circumstances will get stored in "sv"'s UV slot, but
8890 not in all cases. (Use "sv_setuv" to make sure it does).
8891 This form guarantees to evaluate "sv" only once. Only use this
8893 if "sv" is an expression with side effects, otherwise use the
8894 more efficient "SvUV".
8895 UV SvUVx(SV* sv)
8897 SvVOK Returns a boolean indicating whether the SV contains a
8899 v-string.
8900 bool SvVOK(SV* sv)
8902
8904 "Unicode Support" in perlguts has an introduction to this API.
8905 See also "Character classification", and "Character case changing".
8907 Various functions outside this section also work specially with
8908 Unicode. Search for the string "utf8" in this document.
8909 BOM_UTF8
8911 This is a macro that evaluates to a string constant of the
8912 UTF-8 bytes that define the Unicode BYTE ORDER MARK (U+FEFF)
8913 for the platform that perl is compiled on. This allows code to
8914 use a mnemonic for this character that works on both ASCII and
8915 EBCDIC platforms. "sizeof(BOM_UTF8) - 1" can be used to get
8916 its length in bytes.
8917 bytes_cmp_utf8
8919 Compares the sequence of characters (stored as octets) in "b",
8920 "blen" with the sequence of characters (stored as UTF-8) in
8921 "u", "ulen". Returns 0 if they are equal, -1 or -2 if the
8922 first string is less than the second string, +1 or +2 if the
8923 first string is greater than the second string.
8924 -1 or +1 is returned if the shorter string was identical to the
8926 start of the longer string. -2 or +2 is returned if there was
8927 a difference between characters within the strings.
8928 int bytes_cmp_utf8(const U8 *b, STRLEN blen,
8930 const U8 *u, STRLEN ulen)
8931 bytes_from_utf8
8933 NOTE: this function is experimental and may change or be
8934 removed without notice.
8935 Converts a string "s" of length "len" from UTF-8 into native
8937 byte encoding. Unlike "utf8_to_bytes" but like
8938 "bytes_to_utf8", returns a pointer to the newly-created string,
8939 and updates "len" to contain the new length. Returns the
8940 original string if no conversion occurs, "len" is unchanged.
8941 Do nothing if "is_utf8" points to 0. Sets "is_utf8" to 0 if
8942 "s" is converted or consisted entirely of characters that are
8943 invariant in UTF-8 (i.e., US-ASCII on non-EBCDIC machines).
8944 U8* bytes_from_utf8(const U8 *s, STRLEN *len,
8946 bool *is_utf8)
8947 bytes_to_utf8
8949 NOTE: this function is experimental and may change or be
8950 removed without notice.
8951 Converts a string "s" of length "len" bytes from the native
8953 encoding into UTF-8. Returns a pointer to the newly-created
8954 string, and sets "len" to reflect the new length in bytes.
8955 A "NUL" character will be written after the end of the string.
8957 If you want to convert to UTF-8 from encodings other than the
8959 native (Latin1 or EBCDIC), see "sv_recode_to_utf8"().
8960 U8* bytes_to_utf8(const U8 *s, STRLEN *len)
8962 DO_UTF8 Returns a bool giving whether or not the PV in "sv" is to be
8964 treated as being encoded in UTF-8.
8965 You should use this after a call to "SvPV()" or one of its
8967 variants, in case any call to string overloading updates the
8968 internal UTF-8 encoding flag.
8969 bool DO_UTF8(SV* sv)
8971 foldEQ_utf8
8973 Returns true if the leading portions of the strings "s1" and
8974 "s2" (either or both of which may be in UTF-8) are the same
8975 case-insensitively; false otherwise. How far into the strings
8976 to compare is determined by other input parameters.
8977 If "u1" is true, the string "s1" is assumed to be in
8979 UTF-8-encoded Unicode; otherwise it is assumed to be in native
8980 8-bit encoding. Correspondingly for "u2" with respect to "s2".
8981 If the byte length "l1" is non-zero, it says how far into "s1"
8983 to check for fold equality. In other words, "s1"+"l1" will be
8984 used as a goal to reach. The scan will not be considered to be
8985 a match unless the goal is reached, and scanning won't continue
8986 past that goal. Correspondingly for "l2" with respect to "s2".
8987 If "pe1" is non-"NULL" and the pointer it points to is not
8989 "NULL", that pointer is considered an end pointer to the
8990 position 1 byte past the maximum point in "s1" beyond which
8991 scanning will not continue under any circumstances. (This
8992 routine assumes that UTF-8 encoded input strings are not
8993 malformed; malformed input can cause it to read past "pe1").
8994 This means that if both "l1" and "pe1" are specified, and "pe1"
8995 is less than "s1"+"l1", the match will never be successful
8996 because it can never get as far as its goal (and in fact is
8997 asserted against). Correspondingly for "pe2" with respect to
8998 "s2".
8999 At least one of "s1" and "s2" must have a goal (at least one of
9001 "l1" and "l2" must be non-zero), and if both do, both have to
9002 be reached for a successful match. Also, if the fold of a
9003 character is multiple characters, all of them must be matched
9004 (see tr21 reference below for 'folding').
9005 Upon a successful match, if "pe1" is non-"NULL", it will be set
9007 to point to the beginning of the next character of "s1" beyond
9008 what was matched. Correspondingly for "pe2" and "s2".
9009 For case-insensitiveness, the "casefolding" of Unicode is used
9011 instead of upper/lowercasing both the characters, see
9012 <http://www.unicode.org/unicode/reports/tr21/> (Case Mappings).
9013 I32 foldEQ_utf8(const char *s1, char **pe1, UV l1,
9015 bool u1, const char *s2, char **pe2,
9016 UV l2, bool u2)
9017 is_ascii_string
9019 This is a misleadingly-named synonym for
9020 "is_utf8_invariant_string". On ASCII-ish platforms, the name
9021 isn't misleading: the ASCII-range characters are exactly the
9022 UTF-8 invariants. But EBCDIC machines have more invariants
9023 than just the ASCII characters, so "is_utf8_invariant_string"
9024 is preferred.
9025 bool is_ascii_string(const U8* const s,
9027 const STRLEN len)
9028 is_c9strict_utf8_string
9030 Returns TRUE if the first "len" bytes of string "s" form a
9031 valid UTF-8-encoded string that conforms to Unicode Corrigendum
9032 #9 <http://www.unicode.org/versions/corrigendum9.html>;
9033 otherwise it returns FALSE. If "len" is 0, it will be
9034 calculated using strlen(s) (which means if you use this option,
9035 that "s" can't have embedded "NUL" characters and has to have a
9036 terminating "NUL" byte). Note that all characters being ASCII
9037 constitute 'a valid UTF-8 string'.
9038 This function returns FALSE for strings containing any code
9040 points above the Unicode max of 0x10FFFF or surrogate code
9041 points, but accepts non-character code points per Corrigendum
9042 #9 <http://www.unicode.org/versions/corrigendum9.html>.
9043 See also "is_utf8_invariant_string", "is_utf8_string",
9045 "is_utf8_string_flags", "is_utf8_string_loc",
9046 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
9047 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
9048 "is_utf8_fixed_width_buf_loc_flags",
9049 "is_utf8_fixed_width_buf_loclen_flags",
9050 "is_strict_utf8_string", "is_strict_utf8_string_loc",
9051 "is_strict_utf8_string_loclen", "is_c9strict_utf8_string_loc",
9052 and "is_c9strict_utf8_string_loclen".
9053 bool is_c9strict_utf8_string(const U8 *s,
9055 const STRLEN len)
9056 is_c9strict_utf8_string_loc
9058 Like "is_c9strict_utf8_string" but stores the location of the
9059 failure (in the case of "utf8ness failure") or the location
9060 "s"+"len" (in the case of "utf8ness success") in the "ep"
9061 pointer.
9062 See also "is_c9strict_utf8_string_loclen".
9064 bool is_c9strict_utf8_string_loc(const U8 *s,
9066 const STRLEN len,
9067 const U8 **ep)
9068 is_c9strict_utf8_string_loclen
9070 Like "is_c9strict_utf8_string" but stores the location of the
9071 failure (in the case of "utf8ness failure") or the location
9072 "s"+"len" (in the case of "utf8ness success") in the "ep"
9073 pointer, and the number of UTF-8 encoded characters in the "el"
9074 pointer.
9075 See also "is_c9strict_utf8_string_loc".
9077 bool is_c9strict_utf8_string_loclen(
9079 const U8 *s, const STRLEN len,
9080 const U8 **ep, STRLEN *el
9081 )
9082 isC9_STRICT_UTF8_CHAR
9084 Evaluates to non-zero if the first few bytes of the string
9085 starting at "s" and looking no further than "e - 1" are well-
9086 formed UTF-8 that represents some Unicode non-surrogate code
9087 point; otherwise it evaluates to 0. If non-zero, the value
9088 gives how many bytes starting at "s" comprise the code point's
9089 representation. Any bytes remaining before "e", but beyond the
9090 ones needed to form the first code point in "s", are not
9091 examined.
9092 The largest acceptable code point is the Unicode maximum
9094 0x10FFFF. This differs from "isSTRICT_UTF8_CHAR" only in that
9095 it accepts non-character code points. This corresponds to
9096 Unicode Corrigendum #9
9097 <http://www.unicode.org/versions/corrigendum9.html>. which
9098 said that non-character code points are merely discouraged
9099 rather than completely forbidden in open interchange. See
9100 "Noncharacter code points" in perlunicode.
9101 Use "isUTF8_CHAR" to check for Perl's extended UTF-8; and
9103 "isUTF8_CHAR_flags" for a more customized definition.
9104 Use "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc",
9106 and "is_c9strict_utf8_string_loclen" to check entire strings.
9107 STRLEN isC9_STRICT_UTF8_CHAR(const U8 *s, const U8 *e)
9109 is_invariant_string
9111 This is a somewhat misleadingly-named synonym for
9112 "is_utf8_invariant_string". "is_utf8_invariant_string" is
9113 preferred, as it indicates under what conditions the string is
9114 invariant.
9115 bool is_invariant_string(const U8* const s,
9117 const STRLEN len)
9118 isSTRICT_UTF8_CHAR
9120 Evaluates to non-zero if the first few bytes of the string
9121 starting at "s" and looking no further than "e - 1" are well-
9122 formed UTF-8 that represents some Unicode code point completely
9123 acceptable for open interchange between all applications;
9124 otherwise it evaluates to 0. If non-zero, the value gives how
9125 many bytes starting at "s" comprise the code point's
9126 representation. Any bytes remaining before "e", but beyond the
9127 ones needed to form the first code point in "s", are not
9128 examined.
9129 The largest acceptable code point is the Unicode maximum
9131 0x10FFFF, and must not be a surrogate nor a non-character code
9132 point. Thus this excludes any code point from Perl's extended
9133 UTF-8.
9134 This is used to efficiently decide if the next few bytes in "s"
9136 is legal Unicode-acceptable UTF-8 for a single character.
9137 Use "isC9_STRICT_UTF8_CHAR" to use the Unicode Corrigendum #9
9139 <http://www.unicode.org/versions/corrigendum9.html> definition
9140 of allowable code points; "isUTF8_CHAR" to check for Perl's
9141 extended UTF-8; and "isUTF8_CHAR_flags" for a more customized
9142 definition.
9143 Use "is_strict_utf8_string", "is_strict_utf8_string_loc", and
9145 "is_strict_utf8_string_loclen" to check entire strings.
9146 STRLEN isSTRICT_UTF8_CHAR(const U8 *s, const U8 *e)
9148 is_strict_utf8_string
9150 Returns TRUE if the first "len" bytes of string "s" form a
9151 valid UTF-8-encoded string that is fully interchangeable by any
9152 application using Unicode rules; otherwise it returns FALSE.
9153 If "len" is 0, it will be calculated using strlen(s) (which
9154 means if you use this option, that "s" can't have embedded
9155 "NUL" characters and has to have a terminating "NUL" byte).
9156 Note that all characters being ASCII constitute 'a valid UTF-8
9157 string'.
9158 This function returns FALSE for strings containing any code
9160 points above the Unicode max of 0x10FFFF, surrogate code
9161 points, or non-character code points.
9162 See also "is_utf8_invariant_string", "is_utf8_string",
9164 "is_utf8_string_flags", "is_utf8_string_loc",
9165 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
9166 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
9167 "is_utf8_fixed_width_buf_loc_flags",
9168 "is_utf8_fixed_width_buf_loclen_flags",
9169 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
9170 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
9171 "is_c9strict_utf8_string_loclen".
9172 bool is_strict_utf8_string(const U8 *s,
9174 const STRLEN len)
9175 is_strict_utf8_string_loc
9177 Like "is_strict_utf8_string" but stores the location of the
9178 failure (in the case of "utf8ness failure") or the location
9179 "s"+"len" (in the case of "utf8ness success") in the "ep"
9180 pointer.
9181 See also "is_strict_utf8_string_loclen".
9183 bool is_strict_utf8_string_loc(const U8 *s,
9185 const STRLEN len,
9186 const U8 **ep)
9187 is_strict_utf8_string_loclen
9189 Like "is_strict_utf8_string" but stores the location of the
9190 failure (in the case of "utf8ness failure") or the location
9191 "s"+"len" (in the case of "utf8ness success") in the "ep"
9192 pointer, and the number of UTF-8 encoded characters in the "el"
9193 pointer.
9194 See also "is_strict_utf8_string_loc".
9196 bool is_strict_utf8_string_loclen(const U8 *s,
9198 const STRLEN len,
9199 const U8 **ep,
9200 STRLEN *el)
9201 is_utf8_fixed_width_buf_flags
9203 Returns TRUE if the fixed-width buffer starting at "s" with
9204 length "len" is entirely valid UTF-8, subject to the
9205 restrictions given by "flags"; otherwise it returns FALSE.
9206 If "flags" is 0, any well-formed UTF-8, as extended by Perl, is
9208 accepted without restriction. If the final few bytes of the
9209 buffer do not form a complete code point, this will return TRUE
9210 anyway, provided that "is_utf8_valid_partial_char_flags"
9211 returns TRUE for them.
9212 If "flags" in non-zero, it can be any combination of the
9214 "UTF8_DISALLOW_foo" flags accepted by "utf8n_to_uvchr", and
9215 with the same meanings.
9216 This function differs from "is_utf8_string_flags" only in that
9218 the latter returns FALSE if the final few bytes of the string
9219 don't form a complete code point.
9220 bool is_utf8_fixed_width_buf_flags(
9222 const U8 * const s, const STRLEN len,
9223 const U32 flags
9224 )
9225 is_utf8_fixed_width_buf_loclen_flags
9227 Like "is_utf8_fixed_width_buf_loc_flags" but stores the number
9228 of complete, valid characters found in the "el" pointer.
9229 bool is_utf8_fixed_width_buf_loclen_flags(
9231 const U8 * const s, const STRLEN len,
9232 const U8 **ep, STRLEN *el, const U32 flags
9233 )
9234 is_utf8_fixed_width_buf_loc_flags
9236 Like "is_utf8_fixed_width_buf_flags" but stores the location of
9237 the failure in the "ep" pointer. If the function returns TRUE,
9238 *ep will point to the beginning of any partial character at the
9239 end of the buffer; if there is no partial character *ep will
9240 contain "s"+"len".
9241 See also "is_utf8_fixed_width_buf_loclen_flags".
9243 bool is_utf8_fixed_width_buf_loc_flags(
9245 const U8 * const s, const STRLEN len,
9246 const U8 **ep, const U32 flags
9247 )
9248 is_utf8_invariant_string
9250 Returns TRUE if the first "len" bytes of the string "s" are the
9251 same regardless of the UTF-8 encoding of the string (or UTF-
9252 EBCDIC encoding on EBCDIC machines); otherwise it returns
9253 FALSE. That is, it returns TRUE if they are UTF-8 invariant.
9254 On ASCII-ish machines, all the ASCII characters and only the
9255 ASCII characters fit this definition. On EBCDIC machines, the
9256 ASCII-range characters are invariant, but so also are the C1
9257 controls.
9258 If "len" is 0, it will be calculated using strlen(s), (which
9260 means if you use this option, that "s" can't have embedded
9261 "NUL" characters and has to have a terminating "NUL" byte).
9262 See also "is_utf8_string", "is_utf8_string_flags",
9264 "is_utf8_string_loc", "is_utf8_string_loc_flags",
9265 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
9266 "is_utf8_fixed_width_buf_flags",
9267 "is_utf8_fixed_width_buf_loc_flags",
9268 "is_utf8_fixed_width_buf_loclen_flags",
9269 "is_strict_utf8_string", "is_strict_utf8_string_loc",
9270 "is_strict_utf8_string_loclen", "is_c9strict_utf8_string",
9271 "is_c9strict_utf8_string_loc", and
9272 "is_c9strict_utf8_string_loclen".
9273 bool is_utf8_invariant_string(const U8* const s,
9275 STRLEN const len)
9276 is_utf8_string
9278 Returns TRUE if the first "len" bytes of string "s" form a
9279 valid Perl-extended-UTF-8 string; returns FALSE otherwise. If
9280 "len" is 0, it will be calculated using strlen(s) (which means
9281 if you use this option, that "s" can't have embedded "NUL"
9282 characters and has to have a terminating "NUL" byte). Note
9283 that all characters being ASCII constitute 'a valid UTF-8
9284 string'.
9285 This function considers Perl's extended UTF-8 to be valid.
9287 That means that code points above Unicode, surrogates, and non-
9288 character code points are considered valid by this function.
9289 Use "is_strict_utf8_string", "is_c9strict_utf8_string", or
9290 "is_utf8_string_flags" to restrict what code points are
9291 considered valid.
9292 See also "is_utf8_invariant_string", "is_utf8_string_loc",
9294 "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags",
9295 "is_utf8_fixed_width_buf_loc_flags",
9296 "is_utf8_fixed_width_buf_loclen_flags",
9297 bool is_utf8_string(const U8 *s, const STRLEN len)
9299 is_utf8_string_flags
9301 Returns TRUE if the first "len" bytes of string "s" form a
9302 valid UTF-8 string, subject to the restrictions imposed by
9303 "flags"; returns FALSE otherwise. If "len" is 0, it will be
9304 calculated using strlen(s) (which means if you use this option,
9305 that "s" can't have embedded "NUL" characters and has to have a
9306 terminating "NUL" byte). Note that all characters being ASCII
9307 constitute 'a valid UTF-8 string'.
9308 If "flags" is 0, this gives the same results as
9310 "is_utf8_string"; if "flags" is
9311 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the same
9312 results as "is_strict_utf8_string"; and if "flags" is
9313 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same
9314 results as "is_c9strict_utf8_string". Otherwise "flags" may be
9315 any combination of the "UTF8_DISALLOW_foo" flags understood by
9316 "utf8n_to_uvchr", with the same meanings.
9317 See also "is_utf8_invariant_string", "is_utf8_string",
9319 "is_utf8_string_loc", "is_utf8_string_loc_flags",
9320 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
9321 "is_utf8_fixed_width_buf_flags",
9322 "is_utf8_fixed_width_buf_loc_flags",
9323 "is_utf8_fixed_width_buf_loclen_flags",
9324 "is_strict_utf8_string", "is_strict_utf8_string_loc",
9325 "is_strict_utf8_string_loclen", "is_c9strict_utf8_string",
9326 "is_c9strict_utf8_string_loc", and
9327 "is_c9strict_utf8_string_loclen".
9328 bool is_utf8_string_flags(const U8 *s,
9330 const STRLEN len,
9331 const U32 flags)
9332 is_utf8_string_loc
9334 Like "is_utf8_string" but stores the location of the failure
9335 (in the case of "utf8ness failure") or the location "s"+"len"
9336 (in the case of "utf8ness success") in the "ep" pointer.
9337 See also "is_utf8_string_loclen".
9339 bool is_utf8_string_loc(const U8 *s,
9341 const STRLEN len,
9342 const U8 **ep)
9343 is_utf8_string_loclen
9345 Like "is_utf8_string" but stores the location of the failure
9346 (in the case of "utf8ness failure") or the location "s"+"len"
9347 (in the case of "utf8ness success") in the "ep" pointer, and
9348 the number of UTF-8 encoded characters in the "el" pointer.
9349 See also "is_utf8_string_loc".
9351 bool is_utf8_string_loclen(const U8 *s,
9353 const STRLEN len,
9354 const U8 **ep, STRLEN *el)
9355 is_utf8_string_loclen_flags
9357 Like "is_utf8_string_flags" but stores the location of the
9358 failure (in the case of "utf8ness failure") or the location
9359 "s"+"len" (in the case of "utf8ness success") in the "ep"
9360 pointer, and the number of UTF-8 encoded characters in the "el"
9361 pointer.
9362 See also "is_utf8_string_loc_flags".
9364 bool is_utf8_string_loclen_flags(const U8 *s,
9366 const STRLEN len,
9367 const U8 **ep,
9368 STRLEN *el,
9369 const U32 flags)
9370 is_utf8_string_loc_flags
9372 Like "is_utf8_string_flags" but stores the location of the
9373 failure (in the case of "utf8ness failure") or the location
9374 "s"+"len" (in the case of "utf8ness success") in the "ep"
9375 pointer.
9376 See also "is_utf8_string_loclen_flags".
9378 bool is_utf8_string_loc_flags(const U8 *s,
9380 const STRLEN len,
9381 const U8 **ep,
9382 const U32 flags)
9383 is_utf8_valid_partial_char
9385 Returns 0 if the sequence of bytes starting at "s" and looking
9386 no further than "e - 1" is the UTF-8 encoding, as extended by
9387 Perl, for one or more code points. Otherwise, it returns 1 if
9388 there exists at least one non-empty sequence of bytes that when
9389 appended to sequence "s", starting at position "e" causes the
9390 entire sequence to be the well-formed UTF-8 of some code point;
9391 otherwise returns 0.
9392 In other words this returns TRUE if "s" points to a partial
9394 UTF-8-encoded code point.
9395 This is useful when a fixed-length buffer is being tested for
9397 being well-formed UTF-8, but the final few bytes in it don't
9398 comprise a full character; that is, it is split somewhere in
9399 the middle of the final code point's UTF-8 representation.
9400 (Presumably when the buffer is refreshed with the next chunk of
9401 data, the new first bytes will complete the partial code
9402 point.) This function is used to verify that the final bytes
9403 in the current buffer are in fact the legal beginning of some
9404 code point, so that if they aren't, the failure can be
9405 signalled without having to wait for the next read.
9406 bool is_utf8_valid_partial_char(const U8 * const s,
9408 const U8 * const e)
9409 is_utf8_valid_partial_char_flags
9411 Like "is_utf8_valid_partial_char", it returns a boolean giving
9412 whether or not the input is a valid UTF-8 encoded partial
9413 character, but it takes an extra parameter, "flags", which can
9414 further restrict which code points are considered valid.
9415 If "flags" is 0, this behaves identically to
9417 "is_utf8_valid_partial_char". Otherwise "flags" can be any
9418 combination of the "UTF8_DISALLOW_foo" flags accepted by
9419 "utf8n_to_uvchr". If there is any sequence of bytes that can
9420 complete the input partial character in such a way that a non-
9421 prohibited character is formed, the function returns TRUE;
9422 otherwise FALSE. Non character code points cannot be
9423 determined based on partial character input. But many of the
9424 other possible excluded types can be determined from just the
9425 first one or two bytes.
9426 bool is_utf8_valid_partial_char_flags(
9428 const U8 * const s, const U8 * const e,
9429 const U32 flags
9430 )
9431 isUTF8_CHAR
9433 Evaluates to non-zero if the first few bytes of the string
9434 starting at "s" and looking no further than "e - 1" are well-
9435 formed UTF-8, as extended by Perl, that represents some code
9436 point; otherwise it evaluates to 0. If non-zero, the value
9437 gives how many bytes starting at "s" comprise the code point's
9438 representation. Any bytes remaining before "e", but beyond the
9439 ones needed to form the first code point in "s", are not
9440 examined.
9441 The code point can be any that will fit in a UV on this
9443 machine, using Perl's extension to official UTF-8 to represent
9444 those higher than the Unicode maximum of 0x10FFFF. That means
9445 that this macro is used to efficiently decide if the next few
9446 bytes in "s" is legal UTF-8 for a single character.
9447 Use "isSTRICT_UTF8_CHAR" to restrict the acceptable code points
9449 to those defined by Unicode to be fully interchangeable across
9450 applications; "isC9_STRICT_UTF8_CHAR" to use the Unicode
9451 Corrigendum #9
9452 <http://www.unicode.org/versions/corrigendum9.html> definition
9453 of allowable code points; and "isUTF8_CHAR_flags" for a more
9454 customized definition.
9455 Use "is_utf8_string", "is_utf8_string_loc", and
9457 "is_utf8_string_loclen" to check entire strings.
9458 Note that it is deprecated to use code points higher than what
9460 will fit in an IV. This macro does not raise any warnings for
9461 such code points, treating them as valid.
9462 Note also that a UTF-8 INVARIANT character (i.e. ASCII on non-
9464 EBCDIC machines) is a valid UTF-8 character.
9465 STRLEN isUTF8_CHAR(const U8 *s, const U8 *e)
9467 isUTF8_CHAR_flags
9469 Evaluates to non-zero if the first few bytes of the string
9470 starting at "s" and looking no further than "e - 1" are well-
9471 formed UTF-8, as extended by Perl, that represents some code
9472 point, subject to the restrictions given by "flags"; otherwise
9473 it evaluates to 0. If non-zero, the value gives how many bytes
9474 starting at "s" comprise the code point's representation. Any
9475 bytes remaining before "e", but beyond the ones needed to form
9476 the first code point in "s", are not examined.
9477 If "flags" is 0, this gives the same results as "isUTF8_CHAR";
9479 if "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives
9480 the same results as "isSTRICT_UTF8_CHAR"; and if "flags" is
9481 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same
9482 results as "isC9_STRICT_UTF8_CHAR". Otherwise "flags" may be
9483 any combination of the "UTF8_DISALLOW_foo" flags understood by
9484 "utf8n_to_uvchr", with the same meanings.
9485 The three alternative macros are for the most commonly needed
9487 validations; they are likely to run somewhat faster than this
9488 more general one, as they can be inlined into your code.
9489 Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
9491 "is_utf8_string_loclen_flags" to check entire strings.
9492 STRLEN isUTF8_CHAR_flags(const U8 *s, const U8 *e,
9494 const U32 flags)
9495 pv_uni_display
9497 Build to the scalar "dsv" a displayable version of the string
9498 "spv", length "len", the displayable version being at most
9499 "pvlim" bytes long (if longer, the rest is truncated and "..."
9500 will be appended).
9501 The "flags" argument can have "UNI_DISPLAY_ISPRINT" set to
9503 display "isPRINT()"able characters as themselves,
9504 "UNI_DISPLAY_BACKSLASH" to display the "\\[nrfta\\]" as the
9505 backslashed versions (like "\n") ("UNI_DISPLAY_BACKSLASH" is
9506 preferred over "UNI_DISPLAY_ISPRINT" for "\\").
9507 "UNI_DISPLAY_QQ" (and its alias "UNI_DISPLAY_REGEX") have both
9508 "UNI_DISPLAY_BACKSLASH" and "UNI_DISPLAY_ISPRINT" turned on.
9509 The pointer to the PV of the "dsv" is returned.
9511 See also "sv_uni_display".
9513 char* pv_uni_display(SV *dsv, const U8 *spv,
9515 STRLEN len, STRLEN pvlim,
9516 UV flags)
9517 REPLACEMENT_CHARACTER_UTF8
9519 This is a macro that evaluates to a string constant of the
9520 UTF-8 bytes that define the Unicode REPLACEMENT CHARACTER
9521 (U+FFFD) for the platform that perl is compiled on. This
9522 allows code to use a mnemonic for this character that works on
9523 both ASCII and EBCDIC platforms.
9524 "sizeof(REPLACEMENT_CHARACTER_UTF8) - 1" can be used to get its
9525 length in bytes.
9526 sv_cat_decode
9528 "encoding" is assumed to be an "Encode" object, the PV of "ssv"
9529 is assumed to be octets in that encoding and decoding the input
9530 starts from the position which "(PV + *offset)" pointed to.
9531 "dsv" will be concatenated with the decoded UTF-8 string from
9532 "ssv". Decoding will terminate when the string "tstr" appears
9533 in decoding output or the input ends on the PV of "ssv". The
9534 value which "offset" points will be modified to the last input
9535 position on "ssv".
9536 Returns TRUE if the terminator was found, else returns FALSE.
9538 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv,
9540 int *offset, char* tstr, int tlen)
9541 sv_recode_to_utf8
9543 "encoding" is assumed to be an "Encode" object, on entry the PV
9544 of "sv" is assumed to be octets in that encoding, and "sv" will
9545 be converted into Unicode (and UTF-8).
9546 If "sv" already is UTF-8 (or if it is not "POK"), or if
9548 "encoding" is not a reference, nothing is done to "sv". If
9549 "encoding" is not an "Encode::XS" Encoding object, bad things
9550 will happen. (See cpan/Encode/encoding.pm and Encode.)
9551 The PV of "sv" is returned.
9553 char* sv_recode_to_utf8(SV* sv, SV *encoding)
9555 sv_uni_display
9557 Build to the scalar "dsv" a displayable version of the scalar
9558 "sv", the displayable version being at most "pvlim" bytes long
9559 (if longer, the rest is truncated and "..." will be appended).
9560 The "flags" argument is as in "pv_uni_display"().
9562 The pointer to the PV of the "dsv" is returned.
9564 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim,
9566 UV flags)
9567 to_utf8_case
9569 DEPRECATED! It is planned to remove this function from a
9570 future release of Perl. Do not use it for new code; remove it
9571 from existing code.
9572 Instead use the appropriate one of "toUPPER_utf8_safe",
9574 "toTITLE_utf8_safe", "toLOWER_utf8_safe", or
9575 "toFOLD_utf8_safe".
9576 This function will be removed in Perl v5.28.
9578 "p" contains the pointer to the UTF-8 string encoding the
9580 character that is being converted. This routine assumes that
9581 the character at "p" is well-formed.
9582 "ustrp" is a pointer to the character buffer to put the
9584 conversion result to. "lenp" is a pointer to the length of the
9585 result.
9586 "swashp" is a pointer to the swash to use.
9588 Both the special and normal mappings are stored in
9590 lib/unicore/To/Foo.pl, and loaded by "SWASHNEW", using
9591 lib/utf8_heavy.pl. "special" (usually, but not always, a
9592 multicharacter mapping), is tried first.
9593 "special" is a string, normally "NULL" or "". "NULL" means to
9595 not use any special mappings; "" means to use the special
9596 mappings. Values other than these two are treated as the name
9597 of the hash containing the special mappings, like
9598 "utf8::ToSpecLower".
9599 "normal" is a string like "ToLower" which means the swash
9601 %utf8::ToLower.
9602 Code points above the platform's "IV_MAX" will raise a
9604 deprecation warning, unless those are turned off.
9605 UV to_utf8_case(const U8 *p, U8* ustrp,
9607 STRLEN *lenp, SV **swashp,
9608 const char *normal,
9609 const char *special)
9610 to_utf8_fold
9612 DEPRECATED! It is planned to remove this function from a
9613 future release of Perl. Do not use it for new code; remove it
9614 from existing code.
9615 Instead use "toFOLD_utf8_safe".
9617 UV to_utf8_fold(const U8 *p, U8* ustrp,
9619 STRLEN *lenp)
9620 to_utf8_lower
9622 DEPRECATED! It is planned to remove this function from a
9623 future release of Perl. Do not use it for new code; remove it
9624 from existing code.
9625 Instead use "toLOWER_utf8_safe".
9627 UV to_utf8_lower(const U8 *p, U8* ustrp,
9629 STRLEN *lenp)
9630 to_utf8_title
9632 DEPRECATED! It is planned to remove this function from a
9633 future release of Perl. Do not use it for new code; remove it
9634 from existing code.
9635 Instead use "toTITLE_utf8_safe".
9637 UV to_utf8_title(const U8 *p, U8* ustrp,
9639 STRLEN *lenp)
9640 to_utf8_upper
9642 DEPRECATED! It is planned to remove this function from a
9643 future release of Perl. Do not use it for new code; remove it
9644 from existing code.
9645 Instead use "toUPPER_utf8_safe".
9647 UV to_utf8_upper(const U8 *p, U8* ustrp,
9649 STRLEN *lenp)
9650 utf8n_to_uvchr
9652 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
9653 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"()
9654 rather than call this directly.
9655 Bottom level UTF-8 decode routine. Returns the native code
9657 point value of the first character in the string "s", which is
9658 assumed to be in UTF-8 (or UTF-EBCDIC) encoding, and no longer
9659 than "curlen" bytes; *retlen (if "retlen" isn't NULL) will be
9660 set to the length, in bytes, of that character.
9661 The value of "flags" determines the behavior when "s" does not
9663 point to a well-formed UTF-8 character. If "flags" is 0,
9664 encountering a malformation causes zero to be returned and
9665 *retlen is set so that ("s" + *retlen) is the next possible
9666 position in "s" that could begin a non-malformed character.
9667 Also, if UTF-8 warnings haven't been lexically disabled, a
9668 warning is raised. Some UTF-8 input sequences may contain
9669 multiple malformations. This function tries to find every
9670 possible one in each call, so multiple warnings can be raised
9671 for each sequence.
9672 Various ALLOW flags can be set in "flags" to allow (and not
9674 warn on) individual types of malformations, such as the
9675 sequence being overlong (that is, when there is a shorter
9676 sequence that can express the same code point; overlong
9677 sequences are expressly forbidden in the UTF-8 standard due to
9678 potential security issues). Another malformation example is
9679 the first byte of a character not being a legal first byte.
9680 See utf8.h for the list of such flags. Even if allowed, this
9681 function generally returns the Unicode REPLACEMENT CHARACTER
9682 when it encounters a malformation. There are flags in utf8.h
9683 to override this behavior for the overlong malformations, but
9684 don't do that except for very specialized purposes.
9685 The "UTF8_CHECK_ONLY" flag overrides the behavior when a non-
9687 allowed (by other flags) malformation is found. If this flag
9688 is set, the routine assumes that the caller will raise a
9689 warning, and this function will silently just set "retlen" to
9690 "-1" (cast to "STRLEN") and return zero.
9691 Note that this API requires disambiguation between successful
9693 decoding a "NUL" character, and an error return (unless the
9694 "UTF8_CHECK_ONLY" flag is set), as in both cases, 0 is
9695 returned, and, depending on the malformation, "retlen" may be
9696 set to 1. To disambiguate, upon a zero return, see if the
9697 first byte of "s" is 0 as well. If so, the input was a "NUL";
9698 if not, the input had an error. Or you can use
9699 "utf8n_to_uvchr_error".
9700 Certain code points are considered problematic. These are
9702 Unicode surrogates, Unicode non-characters, and code points
9703 above the Unicode maximum of 0x10FFFF. By default these are
9704 considered regular code points, but certain situations warrant
9705 special handling for them, which can be specified using the
9706 "flags" parameter. If "flags" contains
9707 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", all three classes are
9708 treated as malformations and handled as such. The flags
9709 "UTF8_DISALLOW_SURROGATE", "UTF8_DISALLOW_NONCHAR", and
9710 "UTF8_DISALLOW_SUPER" (meaning above the legal Unicode maximum)
9711 can be set to disallow these categories individually.
9712 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed
9713 inputs to the strict UTF-8 traditionally defined by Unicode.
9714 Use "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE" to use the
9715 strictness definition given by Unicode Corrigendum #9
9716 <http://www.unicode.org/versions/corrigendum9.html>. The
9717 difference between traditional strictness and C9 strictness is
9718 that the latter does not forbid non-character code points.
9719 (They are still discouraged, however.) For more discussion see
9720 "Noncharacter code points" in perlunicode.
9721 The flags "UTF8_WARN_ILLEGAL_INTERCHANGE",
9723 "UTF8_WARN_ILLEGAL_C9_INTERCHANGE", "UTF8_WARN_SURROGATE",
9724 "UTF8_WARN_NONCHAR", and "UTF8_WARN_SUPER" will cause warning
9725 messages to be raised for their respective categories, but
9726 otherwise the code points are considered valid (not
9727 malformations). To get a category to both be treated as a
9728 malformation and raise a warning, specify both the WARN and
9729 DISALLOW flags. (But note that warnings are not raised if
9730 lexically disabled nor if "UTF8_CHECK_ONLY" is also specified.)
9731 It is now deprecated to have very high code points (above
9733 "IV_MAX" on the platforms) and this function will raise a
9734 deprecation warning for these (unless such warnings are turned
9735 off). This value is typically 0x7FFF_FFFF (2**31 -1) in a
9736 32-bit word.
9737 Code points above 0x7FFF_FFFF (2**31 - 1) were never specified
9739 in any standard, so using them is more problematic than other
9740 above-Unicode code points. Perl invented an extension to UTF-8
9741 to represent the ones above 2**36-1, so it is likely that non-
9742 Perl languages will not be able to read files that contain
9743 these; nor would Perl understand files written by something
9744 that uses a different extension. For these reasons, there is a
9745 separate set of flags that can warn and/or disallow these
9746 extremely high code points, even if other above-Unicode ones
9747 are accepted. These are the "UTF8_WARN_ABOVE_31_BIT" and
9748 "UTF8_DISALLOW_ABOVE_31_BIT" flags. These are entirely
9749 independent from the deprecation warning for code points above
9750 "IV_MAX". On 32-bit machines, it will eventually be forbidden
9751 to have any code point that needs more than 31 bits to
9752 represent. When that happens, effectively the
9753 "UTF8_DISALLOW_ABOVE_31_BIT" flag will always be set on 32-bit
9754 machines. (Of course "UTF8_DISALLOW_SUPER" will treat all
9755 above-Unicode code points, including these, as malformations;
9756 and "UTF8_WARN_SUPER" warns on these.)
9757 On EBCDIC platforms starting in Perl v5.24, the Perl extension
9759 for representing extremely high code points kicks in at
9760 0x3FFF_FFFF (2**30 -1), which is lower than on ASCII. Prior to
9761 that, code points 2**31 and higher were simply unrepresentable,
9762 and a different, incompatible method was used to represent code
9763 points between 2**30 and 2**31 - 1. The flags
9764 "UTF8_WARN_ABOVE_31_BIT" and "UTF8_DISALLOW_ABOVE_31_BIT" have
9765 the same function as on ASCII platforms, warning and
9766 disallowing 2**31 and higher.
9767 All other code points corresponding to Unicode characters,
9769 including private use and those yet to be assigned, are never
9770 considered malformed and never warn.
9771 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen,
9773 STRLEN *retlen, const U32 flags)
9774 utf8n_to_uvchr_error
9776 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
9777 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"()
9778 rather than call this directly.
9779 This function is for code that needs to know what the precise
9781 malformation(s) are when an error is found.
9782 It is like "utf8n_to_uvchr" but it takes an extra parameter
9784 placed after all the others, "errors". If this parameter is 0,
9785 this function behaves identically to "utf8n_to_uvchr".
9786 Otherwise, "errors" should be a pointer to a "U32" variable,
9787 which this function sets to indicate any errors found. Upon
9788 return, if *errors is 0, there were no errors found.
9789 Otherwise, *errors is the bit-wise "OR" of the bits described
9790 in the list below. Some of these bits will be set if a
9791 malformation is found, even if the input "flags" parameter
9792 indicates that the given malformation is allowed; those
9793 exceptions are noted:
9794 "UTF8_GOT_ABOVE_31_BIT"
9796 The code point represented by the input UTF-8 sequence
9797 occupies more than 31 bits. This bit is set only if the
9798 input "flags" parameter contains either the
9799 "UTF8_DISALLOW_ABOVE_31_BIT" or the
9800 "UTF8_WARN_ABOVE_31_BIT" flags.
9801 "UTF8_GOT_CONTINUATION"
9803 The input sequence was malformed in that the first byte was
9804 a a UTF-8 continuation byte.
9805 "UTF8_GOT_EMPTY"
9807 The input "curlen" parameter was 0.
9808 "UTF8_GOT_LONG"
9810 The input sequence was malformed in that there is some
9811 other sequence that evaluates to the same code point, but
9812 that sequence is shorter than this one.
9813 "UTF8_GOT_NONCHAR"
9815 The code point represented by the input UTF-8 sequence is
9816 for a Unicode non-character code point. This bit is set
9817 only if the input "flags" parameter contains either the
9818 "UTF8_DISALLOW_NONCHAR" or the "UTF8_WARN_NONCHAR" flags.
9819 "UTF8_GOT_NON_CONTINUATION"
9821 The input sequence was malformed in that a non-continuation
9822 type byte was found in a position where only a continuation
9823 type one should be.
9824 "UTF8_GOT_OVERFLOW"
9826 The input sequence was malformed in that it is for a code
9827 point that is not representable in the number of bits
9828 available in a UV on the current platform.
9829 "UTF8_GOT_SHORT"
9831 The input sequence was malformed in that "curlen" is
9832 smaller than required for a complete sequence. In other
9833 words, the input is for a partial character sequence.
9834 "UTF8_GOT_SUPER"
9836 The input sequence was malformed in that it is for a non-
9837 Unicode code point; that is, one above the legal Unicode
9838 maximum. This bit is set only if the input "flags"
9839 parameter contains either the "UTF8_DISALLOW_SUPER" or the
9840 "UTF8_WARN_SUPER" flags.
9841 "UTF8_GOT_SURROGATE"
9843 The input sequence was malformed in that it is for a
9844 -Unicode UTF-16 surrogate code point. This bit is set only
9845 if the input "flags" parameter contains either the
9846 "UTF8_DISALLOW_SURROGATE" or the "UTF8_WARN_SURROGATE"
9847 flags.
9848 To do your own error handling, call this function with the
9850 "UTF8_CHECK_ONLY" flag to suppress any warnings, and then
9851 examine the *errors return.
9852 UV utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
9854 STRLEN *retlen,
9855 const U32 flags,
9856 U32 * errors)
9857 utf8n_to_uvuni
9859 Instead use "utf8_to_uvchr_buf", or rarely, "utf8n_to_uvchr".
9860 This function was useful for code that wanted to handle both
9862 EBCDIC and ASCII platforms with Unicode properties, but
9863 starting in Perl v5.20, the distinctions between the platforms
9864 have mostly been made invisible to most code, so this function
9865 is quite unlikely to be what you want. If you do need this
9866 precise functionality, use instead
9867 "NATIVE_TO_UNI(utf8_to_uvchr_buf(...))" or
9868 "NATIVE_TO_UNI(utf8n_to_uvchr(...))".
9869 UV utf8n_to_uvuni(const U8 *s, STRLEN curlen,
9871 STRLEN *retlen, U32 flags)
9872 UTF8SKIP
9874 returns the number of bytes in the UTF-8 encoded character
9875 whose first (perhaps only) byte is pointed to by "s".
9876 STRLEN UTF8SKIP(char* s)
9878 utf8_distance
9880 Returns the number of UTF-8 characters between the UTF-8
9881 pointers "a" and "b".
9882 WARNING: use only if you *know* that the pointers point inside
9884 the same UTF-8 buffer.
9885 IV utf8_distance(const U8 *a, const U8 *b)
9887 utf8_hop
9889 Return the UTF-8 pointer "s" displaced by "off" characters,
9890 either forward or backward.
9891 WARNING: do not use the following unless you *know* "off" is
9893 within the UTF-8 data pointed to by "s" *and* that on entry "s"
9894 is aligned on the first byte of character or just after the
9895 last byte of a character.
9896 U8* utf8_hop(const U8 *s, SSize_t off)
9898 utf8_hop_back
9900 Return the UTF-8 pointer "s" displaced by up to "off"
9901 characters, backward.
9902 "off" must be non-positive.
9904 "s" must be after or equal to "start".
9906 When moving backward it will not move before "start".
9908 Will not exceed this limit even if the string is not valid
9910 "UTF-8".
9911 U8* utf8_hop_back(const U8 *s, SSize_t off,
9913 const U8 *start)
9914 utf8_hop_forward
9916 Return the UTF-8 pointer "s" displaced by up to "off"
9917 characters, forward.
9918 "off" must be non-negative.
9920 "s" must be before or equal to "end".
9922 When moving forward it will not move beyond "end".
9924 Will not exceed this limit even if the string is not valid
9926 "UTF-8".
9927 U8* utf8_hop_forward(const U8 *s, SSize_t off,
9929 const U8 *end)
9930 utf8_hop_safe
9932 Return the UTF-8 pointer "s" displaced by up to "off"
9933 characters, either forward or backward.
9934 When moving backward it will not move before "start".
9936 When moving forward it will not move beyond "end".
9938 Will not exceed those limits even if the string is not valid
9940 "UTF-8".
9941 U8* utf8_hop_safe(const U8 *s, SSize_t off,
9943 const U8 *start, const U8 *end)
9944 UTF8_IS_INVARIANT
9946 Evaluates to 1 if the byte "c" represents the same character
9947 when encoded in UTF-8 as when not; otherwise evaluates to 0.
9948 UTF-8 invariant characters can be copied as-is when converting
9949 to/from UTF-8, saving time.
9950 In spite of the name, this macro gives the correct result if
9952 the input string from which "c" comes is not encoded in UTF-8.
9953 See "UVCHR_IS_INVARIANT" for checking if a UV is invariant.
9955 bool UTF8_IS_INVARIANT(char c)
9957 UTF8_IS_NONCHAR
9959 Evaluates to non-zero if the first few bytes of the string
9960 starting at "s" and looking no further than "e - 1" are well-
9961 formed UTF-8 that represents one of the Unicode non-character
9962 code points; otherwise it evaluates to 0. If non-zero, the
9963 value gives how many bytes starting at "s" comprise the code
9964 point's representation.
9965 bool UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
9967 UTF8_IS_SUPER
9969 Recall that Perl recognizes an extension to UTF-8 that can
9970 encode code points larger than the ones defined by Unicode,
9971 which are 0..0x10FFFF.
9972 This macro evaluates to non-zero if the first few bytes of the
9974 string starting at "s" and looking no further than "e - 1" are
9975 from this UTF-8 extension; otherwise it evaluates to 0. If
9976 non-zero, the value gives how many bytes starting at "s"
9977 comprise the code point's representation.
9978 0 is returned if the bytes are not well-formed extended UTF-8,
9980 or if they represent a code point that cannot fit in a UV on
9981 the current platform. Hence this macro can give different
9982 results when run on a 64-bit word machine than on one with a
9983 32-bit word size.
9984 Note that it is deprecated to have code points that are larger
9986 than what can fit in an IV on the current machine.
9987 bool UTF8_IS_SUPER(const U8 *s, const U8 *e)
9989 UTF8_IS_SURROGATE
9991 Evaluates to non-zero if the first few bytes of the string
9992 starting at "s" and looking no further than "e - 1" are well-
9993 formed UTF-8 that represents one of the Unicode surrogate code
9994 points; otherwise it evaluates to 0. If non-zero, the value
9995 gives how many bytes starting at "s" comprise the code point's
9996 representation.
9997 bool UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
9999 utf8_length
10001 Return the length of the UTF-8 char encoded string "s" in
10002 characters. Stops at "e" (inclusive). If "e < s" or if the
10003 scan would end up past "e", croaks.
10004 STRLEN utf8_length(const U8* s, const U8 *e)
10006 utf8_to_bytes
10008 NOTE: this function is experimental and may change or be
10009 removed without notice.
10010 Converts a string "s" of length "len" from UTF-8 into native
10012 byte encoding. Unlike "bytes_to_utf8", this over-writes the
10013 original string, and updates "len" to contain the new length.
10014 Returns zero on failure, setting "len" to -1.
10015 If you need a copy of the string, see "bytes_from_utf8".
10017 U8* utf8_to_bytes(U8 *s, STRLEN *len)
10019 utf8_to_uvchr_buf
10021 Returns the native code point of the first character in the
10022 string "s" which is assumed to be in UTF-8 encoding; "send"
10023 points to 1 beyond the end of "s". *retlen will be set to the
10024 length, in bytes, of that character.
10025 If "s" does not point to a well-formed UTF-8 character and UTF8
10027 warnings are enabled, zero is returned and *retlen is set (if
10028 "retlen" isn't "NULL") to -1. If those warnings are off, the
10029 computed value, if well-defined (or the Unicode REPLACEMENT
10030 CHARACTER if not), is silently returned, and *retlen is set (if
10031 "retlen" isn't "NULL") so that ("s" + *retlen) is the next
10032 possible position in "s" that could begin a non-malformed
10033 character. See "utf8n_to_uvchr" for details on when the
10034 REPLACEMENT CHARACTER is returned.
10035 Code points above the platform's "IV_MAX" will raise a
10037 deprecation warning, unless those are turned off.
10038 UV utf8_to_uvchr_buf(const U8 *s, const U8 *send,
10040 STRLEN *retlen)
10041 utf8_to_uvuni_buf
10043 DEPRECATED! It is planned to remove this function from a
10044 future release of Perl. Do not use it for new code; remove it
10045 from existing code.
10046 Only in very rare circumstances should code need to be dealing
10048 in Unicode (as opposed to native) code points. In those few
10049 cases, use "NATIVE_TO_UNI(utf8_to_uvchr_buf(...))" instead.
10050 Returns the Unicode (not-native) code point of the first
10052 character in the string "s" which is assumed to be in UTF-8
10053 encoding; "send" points to 1 beyond the end of "s". "retlen"
10054 will be set to the length, in bytes, of that character.
10055 If "s" does not point to a well-formed UTF-8 character and UTF8
10057 warnings are enabled, zero is returned and *retlen is set (if
10058 "retlen" isn't NULL) to -1. If those warnings are off, the
10059 computed value if well-defined (or the Unicode REPLACEMENT
10060 CHARACTER, if not) is silently returned, and *retlen is set (if
10061 "retlen" isn't NULL) so that ("s" + *retlen) is the next
10062 possible position in "s" that could begin a non-malformed
10063 character. See "utf8n_to_uvchr" for details on when the
10064 REPLACEMENT CHARACTER is returned.
10065 Code points above the platform's "IV_MAX" will raise a
10067 deprecation warning, unless those are turned off.
10068 UV utf8_to_uvuni_buf(const U8 *s, const U8 *send,
10070 STRLEN *retlen)
10071 UVCHR_IS_INVARIANT
10073 Evaluates to 1 if the representation of code point "cp" is the
10074 same whether or not it is encoded in UTF-8; otherwise evaluates
10075 to 0. UTF-8 invariant characters can be copied as-is when
10076 converting to/from UTF-8, saving time. "cp" is Unicode if
10077 above 255; otherwise is platform-native.
10078 bool UVCHR_IS_INVARIANT(UV cp)
10080 UVCHR_SKIP
10082 returns the number of bytes required to represent the code
10083 point "cp" when encoded as UTF-8. "cp" is a native (ASCII or
10084 EBCDIC) code point if less than 255; a Unicode code point
10085 otherwise.
10086 STRLEN UVCHR_SKIP(UV cp)
10088 uvchr_to_utf8
10090 Adds the UTF-8 representation of the native code point "uv" to
10091 the end of the string "d"; "d" should have at least
10092 "UVCHR_SKIP(uv)+1" (up to "UTF8_MAXBYTES+1") free bytes
10093 available. The return value is the pointer to the byte after
10094 the end of the new character. In other words,
10095 d = uvchr_to_utf8(d, uv);
10097 is the recommended wide native character-aware way of saying
10099 *(d++) = uv;
10101 This function accepts any UV as input, but very high code
10103 points (above "IV_MAX" on the platform) will raise a
10104 deprecation warning. This is typically 0x7FFF_FFFF in a 32-bit
10105 word.
10106 It is possible to forbid or warn on non-Unicode code points, or
10108 those that may be problematic by using "uvchr_to_utf8_flags".
10109 U8* uvchr_to_utf8(U8 *d, UV uv)
10111 uvchr_to_utf8_flags
10113 Adds the UTF-8 representation of the native code point "uv" to
10114 the end of the string "d"; "d" should have at least
10115 "UVCHR_SKIP(uv)+1" (up to "UTF8_MAXBYTES+1") free bytes
10116 available. The return value is the pointer to the byte after
10117 the end of the new character. In other words,
10118 d = uvchr_to_utf8_flags(d, uv, flags);
10120 or, in most cases,
10122 d = uvchr_to_utf8_flags(d, uv, 0);
10124 This is the Unicode-aware way of saying
10126 *(d++) = uv;
10128 If "flags" is 0, this function accepts any UV as input, but
10130 very high code points (above "IV_MAX" for the platform) will
10131 raise a deprecation warning. This is typically 0x7FFF_FFFF in
10132 a 32-bit word.
10133 Specifying "flags" can further restrict what is allowed and not
10135 warned on, as follows:
10136 If "uv" is a Unicode surrogate code point and
10138 "UNICODE_WARN_SURROGATE" is set, the function will raise a
10139 warning, provided UTF8 warnings are enabled. If instead
10140 "UNICODE_DISALLOW_SURROGATE" is set, the function will fail and
10141 return NULL. If both flags are set, the function will both
10142 warn and return NULL.
10143 Similarly, the "UNICODE_WARN_NONCHAR" and
10145 "UNICODE_DISALLOW_NONCHAR" flags affect how the function
10146 handles a Unicode non-character.
10147 And likewise, the "UNICODE_WARN_SUPER" and
10149 "UNICODE_DISALLOW_SUPER" flags affect the handling of code
10150 points that are above the Unicode maximum of 0x10FFFF.
10151 Languages other than Perl may not be able to accept files that
10152 contain these.
10153 The flag "UNICODE_WARN_ILLEGAL_INTERCHANGE" selects all three
10155 of the above WARN flags; and
10156 "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE" selects all three
10157 DISALLOW flags. "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE"
10158 restricts the allowed inputs to the strict UTF-8 traditionally
10159 defined by Unicode. Similarly,
10160 "UNICODE_WARN_ILLEGAL_C9_INTERCHANGE" and
10161 "UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE" are shortcuts to
10162 select the above-Unicode and surrogate flags, but not the non-
10163 character ones, as defined in Unicode Corrigendum #9
10164 <http://www.unicode.org/versions/corrigendum9.html>. See
10165 "Noncharacter code points" in perlunicode.
10166 Code points above 0x7FFF_FFFF (2**31 - 1) were never specified
10168 in any standard, so using them is more problematic than other
10169 above-Unicode code points. Perl invented an extension to UTF-8
10170 to represent the ones above 2**36-1, so it is likely that non-
10171 Perl languages will not be able to read files that contain
10172 these that written by the perl interpreter; nor would Perl
10173 understand files written by something that uses a different
10174 extension. For these reasons, there is a separate set of flags
10175 that can warn and/or disallow these extremely high code points,
10176 even if other above-Unicode ones are accepted. These are the
10177 "UNICODE_WARN_ABOVE_31_BIT" and "UNICODE_DISALLOW_ABOVE_31_BIT"
10178 flags. These are entirely independent from the deprecation
10179 warning for code points above "IV_MAX". On 32-bit machines, it
10180 will eventually be forbidden to have any code point that needs
10181 more than 31 bits to represent. When that happens, effectively
10182 the "UNICODE_DISALLOW_ABOVE_31_BIT" flag will always be set on
10183 32-bit machines. (Of course "UNICODE_DISALLOW_SUPER" will
10184 treat all above-Unicode code points, including these, as
10185 malformations; and "UNICODE_WARN_SUPER" warns on these.)
10186 On EBCDIC platforms starting in Perl v5.24, the Perl extension
10188 for representing extremely high code points kicks in at
10189 0x3FFF_FFFF (2**30 -1), which is lower than on ASCII. Prior to
10190 that, code points 2**31 and higher were simply unrepresentable,
10191 and a different, incompatible method was used to represent code
10192 points between 2**30 and 2**31 - 1. The flags
10193 "UNICODE_WARN_ABOVE_31_BIT" and "UNICODE_DISALLOW_ABOVE_31_BIT"
10194 have the same function as on ASCII platforms, warning and
10195 disallowing 2**31 and higher.
10196 U8* uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
10198 uvoffuni_to_utf8_flags
10200 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
10201 CIRCUMSTANCES. Instead, Almost all code should use
10202 "uvchr_to_utf8" or "uvchr_to_utf8_flags".
10203 This function is like them, but the input is a strict Unicode
10205 (as opposed to native) code point. Only in very rare
10206 circumstances should code not be using the native code point.
10207 For details, see the description for "uvchr_to_utf8_flags".
10209 U8* uvoffuni_to_utf8_flags(U8 *d, UV uv,
10211 const UV flags)
10212 uvuni_to_utf8_flags
10214 Instead you almost certainly want to use "uvchr_to_utf8" or
10215 "uvchr_to_utf8_flags".
10216 This function is a deprecated synonym for
10218 "uvoffuni_to_utf8_flags", which itself, while not deprecated,
10219 should be used only in isolated circumstances. These functions
10220 were useful for code that wanted to handle both EBCDIC and
10221 ASCII platforms with Unicode properties, but starting in Perl
10222 v5.20, the distinctions between the platforms have mostly been
10223 made invisible to most code, so this function is quite unlikely
10224 to be what you want.
10225 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
10227 valid_utf8_to_uvchr
10229 Like "utf8_to_uvchr_buf", but should only be called when it is
10230 known that the next character in the input UTF-8 string "s" is
10231 well-formed (e.g., it passes "isUTF8_CHAR". Surrogates, non-
10232 character code points, and non-Unicode code points are allowed.
10233 UV valid_utf8_to_uvchr(const U8 *s, STRLEN *retlen)
10235
10237 newXSproto
10238 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl
10239 prototypes to the subs.
10240 XS_APIVERSION_BOOTCHECK
10242 Macro to verify that the perl api version an XS module has been
10243 compiled against matches the api version of the perl
10244 interpreter it's being loaded into.
10245 XS_APIVERSION_BOOTCHECK;
10247 XS_VERSION
10249 The version identifier for an XS module. This is usually
10250 handled automatically by "ExtUtils::MakeMaker". See
10251 "XS_VERSION_BOOTCHECK".
10252 XS_VERSION_BOOTCHECK
10254 Macro to verify that a PM module's $VERSION variable matches
10255 the XS module's "XS_VERSION" variable. This is usually handled
10256 automatically by "xsubpp". See "The VERSIONCHECK: Keyword" in
10257 perlxs.
10258 XS_VERSION_BOOTCHECK;
10260
10262 ckWARN Returns a boolean as to whether or not warnings are enabled for
10263 the warning category "w". If the category is by default
10264 enabled even if not within the scope of "use warnings", instead
10265 use the "ckWARN_d" macro.
10266 bool ckWARN(U32 w)
10268 ckWARN2 Like "ckWARN", but takes two warnings categories as input, and
10270 returns TRUE if either is enabled. If either category is by
10271 default enabled even if not within the scope of "use warnings",
10272 instead use the "ckWARN2_d" macro. The categories must be
10273 completely independent, one may not be subclassed from the
10274 other.
10275 bool ckWARN2(U32 w1, U32 w2)
10277 ckWARN3 Like "ckWARN2", but takes three warnings categories as input,
10279 and returns TRUE if any is enabled. If any of the categories
10280 is by default enabled even if not within the scope of
10281 "use warnings", instead use the "ckWARN3_d" macro. The
10282 categories must be completely independent, one may not be
10283 subclassed from any other.
10284 bool ckWARN3(U32 w1, U32 w2, U32 w3)
10286 ckWARN4 Like "ckWARN3", but takes four warnings categories as input,
10288 and returns TRUE if any is enabled. If any of the categories
10289 is by default enabled even if not within the scope of
10290 "use warnings", instead use the "ckWARN4_d" macro. The
10291 categories must be completely independent, one may not be
10292 subclassed from any other.
10293 bool ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
10295 ckWARN_d
10297 Like "ckWARN", but for use if and only if the warning category
10298 is by default enabled even if not within the scope of
10299 "use warnings".
10300 bool ckWARN_d(U32 w)
10302 ckWARN2_d
10304 Like "ckWARN2", but for use if and only if either warning
10305 category is by default enabled even if not within the scope of
10306 "use warnings".
10307 bool ckWARN2_d(U32 w1, U32 w2)
10309 ckWARN3_d
10311 Like "ckWARN3", but for use if and only if any of the warning
10312 categories is by default enabled even if not within the scope
10313 of "use warnings".
10314 bool ckWARN3_d(U32 w1, U32 w2, U32 w3)
10316 ckWARN4_d
10318 Like "ckWARN4", but for use if and only if any of the warning
10319 categories is by default enabled even if not within the scope
10320 of "use warnings".
10321 bool ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
10323 croak This is an XS interface to Perl's "die" function.
10325 Take a sprintf-style format pattern and argument list. These
10327 are used to generate a string message. If the message does not
10328 end with a newline, then it will be extended with some
10329 indication of the current location in the code, as described
10330 for "mess_sv".
10331 The error message will be used as an exception, by default
10333 returning control to the nearest enclosing "eval", but subject
10334 to modification by a $SIG{__DIE__} handler. In any case, the
10335 "croak" function never returns normally.
10336 For historical reasons, if "pat" is null then the contents of
10338 "ERRSV" ($@) will be used as an error message or object instead
10339 of building an error message from arguments. If you want to
10340 throw a non-string object, or build an error message in an SV
10341 yourself, it is preferable to use the "croak_sv" function,
10342 which does not involve clobbering "ERRSV".
10343 void croak(const char *pat, ...)
10345 croak_no_modify
10347 Exactly equivalent to "Perl_croak(aTHX_ "%s", PL_no_modify)",
10348 but generates terser object code than using "Perl_croak". Less
10349 code used on exception code paths reduces CPU cache pressure.
10350 void croak_no_modify()
10352 croak_sv
10354 This is an XS interface to Perl's "die" function.
10355 "baseex" is the error message or object. If it is a reference,
10357 it will be used as-is. Otherwise it is used as a string, and
10358 if it does not end with a newline then it will be extended with
10359 some indication of the current location in the code, as
10360 described for "mess_sv".
10361 The error message or object will be used as an exception, by
10363 default returning control to the nearest enclosing "eval", but
10364 subject to modification by a $SIG{__DIE__} handler. In any
10365 case, the "croak_sv" function never returns normally.
10366 To die with a simple string message, the "croak" function may
10368 be more convenient.
10369 void croak_sv(SV *baseex)
10371 die Behaves the same as "croak", except for the return type. It
10373 should be used only where the "OP *" return type is required.
10374 The function never actually returns.
10375 OP * die(const char *pat, ...)
10377 die_sv Behaves the same as "croak_sv", except for the return type. It
10379 should be used only where the "OP *" return type is required.
10380 The function never actually returns.
10381 OP * die_sv(SV *baseex)
10383 vcroak This is an XS interface to Perl's "die" function.
10385 "pat" and "args" are a sprintf-style format pattern and
10387 encapsulated argument list. These are used to generate a
10388 string message. If the message does not end with a newline,
10389 then it will be extended with some indication of the current
10390 location in the code, as described for "mess_sv".
10391 The error message will be used as an exception, by default
10393 returning control to the nearest enclosing "eval", but subject
10394 to modification by a $SIG{__DIE__} handler. In any case, the
10395 "croak" function never returns normally.
10396 For historical reasons, if "pat" is null then the contents of
10398 "ERRSV" ($@) will be used as an error message or object instead
10399 of building an error message from arguments. If you want to
10400 throw a non-string object, or build an error message in an SV
10401 yourself, it is preferable to use the "croak_sv" function,
10402 which does not involve clobbering "ERRSV".
10403 void vcroak(const char *pat, va_list *args)
10405 vwarn This is an XS interface to Perl's "warn" function.
10407 "pat" and "args" are a sprintf-style format pattern and
10409 encapsulated argument list. These are used to generate a
10410 string message. If the message does not end with a newline,
10411 then it will be extended with some indication of the current
10412 location in the code, as described for "mess_sv".
10413 The error message or object will by default be written to
10415 standard error, but this is subject to modification by a
10416 $SIG{__WARN__} handler.
10417 Unlike with "vcroak", "pat" is not permitted to be null.
10419 void vwarn(const char *pat, va_list *args)
10421 warn This is an XS interface to Perl's "warn" function.
10423 Take a sprintf-style format pattern and argument list. These
10425 are used to generate a string message. If the message does not
10426 end with a newline, then it will be extended with some
10427 indication of the current location in the code, as described
10428 for "mess_sv".
10429 The error message or object will by default be written to
10431 standard error, but this is subject to modification by a
10432 $SIG{__WARN__} handler.
10433 Unlike with "croak", "pat" is not permitted to be null.
10435 void warn(const char *pat, ...)
10437 warn_sv This is an XS interface to Perl's "warn" function.
10439 "baseex" is the error message or object. If it is a reference,
10441 it will be used as-is. Otherwise it is used as a string, and
10442 if it does not end with a newline then it will be extended with
10443 some indication of the current location in the code, as
10444 described for "mess_sv".
10445 The error message or object will by default be written to
10447 standard error, but this is subject to modification by a
10448 $SIG{__WARN__} handler.
10449 To warn with a simple string message, the "warn" function may
10451 be more convenient.
10452 void warn_sv(SV *baseex)
10454
10456 The following functions have been flagged as part of the public API,
10457 but are currently undocumented. Use them at your own risk, as the
10458 interfaces are subject to change. Functions that are not listed in
10459 this document are not intended for public use, and should NOT be used
10460 under any circumstances.
10461 If you feel you need to use one of these functions, first send email to
10463 perl5-porters@perl.org <mailto:perl5-porters@perl.org>. It may be that
10464 there is a good reason for the function not being documented, and it
10465 should be removed from this list; or it may just be that no one has
10466 gotten around to documenting it. In the latter case, you will be asked
10467 to submit a patch to document the function. Once your patch is
10468 accepted, it will indicate that the interface is stable (unless it is
10469 explicitly marked otherwise) and usable by you.
10470 GetVars
10472 Gv_AMupdate
10473 PerlIO_clearerr
10474 PerlIO_close
10475 PerlIO_context_layers
10476 PerlIO_eof
10477 PerlIO_error
10478 PerlIO_fileno
10479 PerlIO_fill
10480 PerlIO_flush
10481 PerlIO_get_base
10482 PerlIO_get_bufsiz
10483 PerlIO_get_cnt
10484 PerlIO_get_ptr
10485 PerlIO_read
10486 PerlIO_seek
10487 PerlIO_set_cnt
10488 PerlIO_set_ptrcnt
10489 PerlIO_setlinebuf
10490 PerlIO_stderr
10491 PerlIO_stdin
10492 PerlIO_stdout
10493 PerlIO_tell
10494 PerlIO_unread
10495 PerlIO_write
10496 amagic_call
10497 amagic_deref_call
10498 any_dup
10499 atfork_lock
10500 atfork_unlock
10501 av_arylen_p
10502 av_iter_p
10503 block_gimme
10504 call_atexit
10505 call_list
10506 calloc
10507 cast_i32
10508 cast_iv
10509 cast_ulong
10510 cast_uv
10511 ck_warner
10512 ck_warner_d
10513 ckwarn
10514 ckwarn_d
10515 clear_defarray
10516 clone_params_del
10517 clone_params_new
10518 croak_memory_wrap
10519 croak_nocontext
10520 csighandler
10521 cx_dump
10522 cx_dup
10523 cxinc
10524 deb
10525 deb_nocontext
10526 debop
10527 debprofdump
10528 debstack
10529 debstackptrs
10530 delimcpy
10531 despatch_signals
10532 die_nocontext
10533 dirp_dup
10534 do_aspawn
10535 do_binmode
10536 do_close
10537 do_gv_dump
10538 do_gvgv_dump
10539 do_hv_dump
10540 do_join
10541 do_magic_dump
10542 do_op_dump
10543 do_open
10544 do_open9
10545 do_openn
10546 do_pmop_dump
10547 do_spawn
10548 do_spawn_nowait
10549 do_sprintf
10550 do_sv_dump
10551 doing_taint
10552 doref
10553 dounwind
10554 dowantarray
10555 dump_eval
10556 dump_form
10557 dump_indent
10558 dump_mstats
10559 dump_sub
10560 dump_vindent
10561 filter_add
10562 filter_del
10563 filter_read
10564 foldEQ_latin1
10565 form_nocontext
10566 fp_dup
10567 fprintf_nocontext
10568 free_global_struct
10569 free_tmps
10570 get_context
10571 get_mstats
10572 get_op_descs
10573 get_op_names
10574 get_ppaddr
10575 get_vtbl
10576 gp_dup
10577 gp_free
10578 gp_ref
10579 gv_AVadd
10580 gv_HVadd
10581 gv_IOadd
10582 gv_SVadd
10583 gv_add_by_type
10584 gv_autoload4
10585 gv_autoload_pv
10586 gv_autoload_pvn
10587 gv_autoload_sv
10588 gv_check
10589 gv_dump
10590 gv_efullname
10591 gv_efullname3
10592 gv_efullname4
10593 gv_fetchfile
10594 gv_fetchfile_flags
10595 gv_fetchpv
10596 gv_fetchpvn_flags
10597 gv_fetchsv
10598 gv_fullname
10599 gv_fullname3
10600 gv_fullname4
10601 gv_handler
10602 gv_name_set
10603 he_dup
10604 hek_dup
10605 hv_common
10606 hv_common_key_len
10607 hv_delayfree_ent
10608 hv_eiter_p
10609 hv_eiter_set
10610 hv_free_ent
10611 hv_ksplit
10612 hv_name_set
10613 hv_placeholders_get
10614 hv_placeholders_set
10615 hv_rand_set
10616 hv_riter_p
10617 hv_riter_set
10618 ibcmp_utf8
10619 init_global_struct
10620 init_stacks
10621 init_tm
10622 instr
10623 is_lvalue_sub
10624 leave_scope
10625 load_module_nocontext
10626 magic_dump
10627 malloc
10628 markstack_grow
10629 mess_nocontext
10630 mfree
10631 mg_dup
10632 mg_size
10633 mini_mktime
10634 moreswitches
10635 mro_get_from_name
10636 mro_get_private_data
10637 mro_set_mro
10638 mro_set_private_data
10639 my_atof
10640 my_atof2
10641 my_bcopy
10642 my_bzero
10643 my_chsize
10644 my_cxt_index
10645 my_cxt_init
10646 my_dirfd
10647 my_exit
10648 my_failure_exit
10649 my_fflush_all
10650 my_fork
10651 my_lstat
10652 my_memcmp
10653 my_memset
10654 my_pclose
10655 my_popen
10656 my_popen_list
10657 my_setenv
10658 my_socketpair
10659 my_stat
10660 my_strftime
10661 newANONATTRSUB
10662 newANONHASH
10663 newANONLIST
10664 newANONSUB
10665 newATTRSUB
10666 newAVREF
10667 newCVREF
10668 newFORM
10669 newGVREF
10670 newGVgen
10671 newGVgen_flags
10672 newHVREF
10673 newHVhv
10674 newIO
10675 newMYSUB
10676 newPROG
10677 newRV
10678 newSUB
10679 newSVREF
10680 newSVpvf_nocontext
10681 new_stackinfo
10682 op_refcnt_lock
10683 op_refcnt_unlock
10684 parser_dup
10685 perl_alloc_using
10686 perl_clone_using
10687 pmop_dump
10688 pop_scope
10689 pregcomp
10690 pregexec
10691 pregfree
10692 pregfree2
10693 printf_nocontext
10694 ptr_table_fetch
10695 ptr_table_free
10696 ptr_table_new
10697 ptr_table_split
10698 ptr_table_store
10699 push_scope
10700 re_compile
10701 re_dup_guts
10702 re_intuit_start
10703 re_intuit_string
10704 realloc
10705 reentrant_free
10706 reentrant_init
10707 reentrant_retry
10708 reentrant_size
10709 ref
10710 reg_named_buff_all
10711 reg_named_buff_exists
10712 reg_named_buff_fetch
10713 reg_named_buff_firstkey
10714 reg_named_buff_nextkey
10715 reg_named_buff_scalar
10716 regdump
10717 regdupe_internal
10718 regexec_flags
10719 regfree_internal
10720 reginitcolors
10721 regnext
10722 repeatcpy
10723 rsignal
10724 rsignal_state
10725 runops_debug
10726 runops_standard
10727 rvpv_dup
10728 safesyscalloc
10729 safesysfree
10730 safesysmalloc
10731 safesysrealloc
10732 save_I16
10733 save_I32
10734 save_I8
10735 save_adelete
10736 save_aelem
10737 save_aelem_flags
10738 save_alloc
10739 save_aptr
10740 save_ary
10741 save_bool
10742 save_clearsv
10743 save_delete
10744 save_destructor
10745 save_destructor_x
10746 save_freeop
10747 save_freepv
10748 save_freesv
10749 save_generic_pvref
10750 save_generic_svref
10751 save_hash
10752 save_hdelete
10753 save_helem
10754 save_helem_flags
10755 save_hints
10756 save_hptr
10757 save_int
10758 save_item
10759 save_iv
10760 save_list
10761 save_long
10762 save_mortalizesv
10763 save_nogv
10764 save_op
10765 save_padsv_and_mortalize
10766 save_pptr
10767 save_pushi32ptr
10768 save_pushptr
10769 save_pushptrptr
10770 save_re_context
10771 save_scalar
10772 save_set_svflags
10773 save_shared_pvref
10774 save_sptr
10775 save_svref
10776 save_vptr
10777 savestack_grow
10778 savestack_grow_cnt
10779 scan_num
10780 scan_vstring
10781 seed
10782 set_context
10783 set_numeric_local
10784 set_numeric_radix
10785 set_numeric_standard
10786 share_hek
10787 si_dup
10788 ss_dup
10789 stack_grow
10790 start_subparse
10791 str_to_version
10792 sv_2iv
10793 sv_2pv
10794 sv_2uv
10795 sv_catpvf_mg_nocontext
10796 sv_catpvf_nocontext
10797 sv_dup
10798 sv_dup_inc
10799 sv_peek
10800 sv_pvn_nomg
10801 sv_setpvf_mg_nocontext
10802 sv_setpvf_nocontext
10803 sys_init
10804 sys_init3
10805 sys_intern_clear
10806 sys_intern_dup
10807 sys_intern_init
10808 sys_term
10809 taint_env
10810 taint_proper
10811 unlnk
10812 unsharepvn
10813 utf16_to_utf8
10814 utf16_to_utf8_reversed
10815 uvuni_to_utf8
10816 vdeb
10817 vform
10818 vload_module
10819 vnewSVpvf
10820 vwarner
10821 warn_nocontext
10822 warner
10823 warner_nocontext
10824 whichsig
10825 whichsig_pv
10826 whichsig_pvn
10827 whichsig_sv
10828
10830 Until May 1997, this document was maintained by Jeff Okamoto
10831 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
10832 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
10834 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
10835 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
10836 Stephen McCamant, and Gurusamy Sarathy.
10837 API Listing originally by Dean Roehrich <roehrich@cray.com>.
10839 Updated to be autogenerated from comments in the source by Benjamin
10841 Stuhl.
10842
10844 perlguts, perlxs, perlxstut, perlintern
10845perl v5.26.3 2019-05-11 PERLAPI(1)