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. Any functions not listed here
14 are not part of the public API, and should not be used by extension
15 writers at all. For these reasons, blindly using functions listed in
16 proto.h is to be avoided when writing extensions.
17 Note that all Perl API global variables must be referenced with the
19 "PL_" prefix. Some macros are provided for compatibility with the
20 older, unadorned names, but this support may be disabled in a future
21 release.
22 Perl was originally written to handle US-ASCII only (that is characters
24 whose ordinal numbers are in the range 0 - 127). And documentation and
25 comments may still use the term ASCII, when sometimes in fact the
26 entire range from 0 - 255 is meant.
27 Note that Perl can be compiled and run under EBCDIC (See perlebcdic) or
29 ASCII. Most of the documentation (and even comments in the code)
30 ignore the EBCDIC possibility. For almost all purposes the differences
31 are transparent. As an example, under EBCDIC, instead of UTF-8, UTF-
32 EBCDIC is used to encode Unicode strings, and so whenever this
33 documentation refers to "utf8" (and variants of that name, including in
34 function names), it also (essentially transparently) means
35 "UTF-EBCDIC". But the ordinals of characters differ between ASCII,
36 EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may
37 occupy more bytes than in UTF-8.
38 Also, on some EBCDIC machines, functions that are documented as
40 operating on US-ASCII (or Basic Latin in Unicode terminology) may in
41 fact operate on all 256 characters in the EBCDIC range, not just the
42 subset corresponding to US-ASCII.
43 The listing below is alphabetical, case insensitive.
45
47 GIMME A backward-compatible version of "GIMME_V" which can only
48 return "G_SCALAR" or "G_ARRAY"; in a void context, it returns
49 "G_SCALAR". Deprecated. Use "GIMME_V" instead.
50 U32 GIMME
52 GIMME_V The XSUB-writer's equivalent to Perl's "wantarray". Returns
54 "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list
55 context, respectively. See perlcall for a usage example.
56 U32 GIMME_V
58 G_ARRAY Used to indicate list context. See "GIMME_V", "GIMME" and
60 perlcall.
61 G_DISCARD
63 Indicates that arguments returned from a callback should be
64 discarded. See perlcall.
65 G_EVAL Used to force a Perl "eval" wrapper around a callback. See
67 perlcall.
68 G_NOARGS
70 Indicates that no arguments are being sent to a callback. See
71 perlcall.
72 G_SCALAR
74 Used to indicate scalar context. See "GIMME_V", "GIMME", and
75 perlcall.
76 G_VOID Used to indicate void context. See "GIMME_V" and perlcall.
78
80 AvFILL Same as "av_len()". Deprecated, use "av_len()" instead.
81 int AvFILL(AV* av)
83 av_clear
85 Clears an array, making it empty. Does not free the memory the
86 av uses to store its list of scalars. If any destructors are
87 triggered as a result, the av itself may be freed when this
88 function returns.
89 Perl equivalent: "@myarray = ();".
91 void av_clear(AV *av)
93 av_create_and_push
95 Push an SV onto the end of the array, creating the array if
96 necessary. A small internal helper function to remove a
97 commonly duplicated idiom.
98 NOTE: this function is experimental and may change or be
100 removed without notice.
101 void av_create_and_push(AV **const avp,
103 SV *const val)
104 av_create_and_unshift_one
106 Unshifts an SV onto the beginning of the array, creating the
107 array if necessary. A small internal helper function to remove
108 a commonly duplicated idiom.
109 NOTE: this function is experimental and may change or be
111 removed without notice.
112 SV** av_create_and_unshift_one(AV **const avp,
114 SV *const val)
115 av_delete
117 Deletes the element indexed by "key" from the array, makes the
118 element mortal, and returns it. If "flags" equals "G_DISCARD",
119 the element is freed and null is returned. Perl equivalent:
120 "my $elem = delete($myarray[$idx]);" for the non-"G_DISCARD"
121 version and a void-context "delete($myarray[$idx]);" for the
122 "G_DISCARD" version.
123 SV* av_delete(AV *av, I32 key, I32 flags)
125 av_exists
127 Returns true if the element indexed by "key" has been
128 initialized.
129 This relies on the fact that uninitialized array elements are
131 set to &PL_sv_undef.
132 Perl equivalent: "exists($myarray[$key])".
134 bool av_exists(AV *av, I32 key)
136 av_extend
138 Pre-extend an array. The "key" is the index to which the array
139 should be extended.
140 void av_extend(AV *av, I32 key)
142 av_fetch
144 Returns the SV at the specified index in the array. The "key"
145 is the index. If lval is true, you are guaranteed to get a
146 real SV back (in case it wasn't real before), which you can
147 then modify. Check that the return value is non-null before
148 dereferencing it to a "SV*".
149 See "Understanding the Magic of Tied Hashes and Arrays" in
151 perlguts for more information on how to use this function on
152 tied arrays.
153 The rough perl equivalent is $myarray[$idx].
155 SV** av_fetch(AV *av, I32 key, I32 lval)
157 av_fill Set the highest index in the array to the given number,
159 equivalent to Perl's "$#array = $fill;".
160 The number of elements in the an array will be "fill + 1" after
162 av_fill() returns. If the array was previously shorter, then
163 the additional elements appended are set to "PL_sv_undef". If
164 the array was longer, then the excess elements are freed.
165 "av_fill(av, -1)" is the same as "av_clear(av)".
166 void av_fill(AV *av, I32 fill)
168 av_len Returns the highest index in the array. The number of elements
170 in the array is "av_len(av) + 1". Returns -1 if the array is
171 empty.
172 The Perl equivalent for this is $#myarray.
174 I32 av_len(AV *av)
176 av_make Creates a new AV and populates it with a list of SVs. The SVs
178 are copied into the array, so they may be freed after the call
179 to av_make. The new AV will have a reference count of 1.
180 Perl equivalent: "my @new_array = ($scalar1, $scalar2,
182 $scalar3...);"
183 AV* av_make(I32 size, SV **strp)
185 av_pop Pops an SV off the end of the array. Returns &PL_sv_undef if
187 the array is empty.
188 Perl equivalent: "pop(@myarray);"
190 SV* av_pop(AV *av)
192 av_push Pushes an SV onto the end of the array. The array will grow
194 automatically to accommodate the addition. This takes
195 ownership of one reference count.
196 Perl equivalent: "push @myarray, $elem;".
198 void av_push(AV *av, SV *val)
200 av_shift
202 Shifts an SV off the beginning of the array. Returns
203 &PL_sv_undef if the array is empty.
204 Perl equivalent: "shift(@myarray);"
206 SV* av_shift(AV *av)
208 av_store
210 Stores an SV in an array. The array index is specified as
211 "key". The return value will be NULL if the operation failed
212 or if the value did not need to be actually stored within the
213 array (as in the case of tied arrays). Otherwise, it can be
214 dereferenced to get the "SV*" that was stored there (= "val")).
215 Note that the caller is responsible for suitably incrementing
217 the reference count of "val" before the call, and decrementing
218 it if the function returned NULL.
219 Approximate Perl equivalent: "$myarray[$key] = $val;".
221 See "Understanding the Magic of Tied Hashes and Arrays" in
223 perlguts for more information on how to use this function on
224 tied arrays.
225 SV** av_store(AV *av, I32 key, SV *val)
227 av_undef
229 Undefines the array. Frees the memory used by the av to store
230 its list of scalars. If any destructors are triggered as a
231 result, the av itself may be freed.
232 void av_undef(AV *av)
234 av_unshift
236 Unshift the given number of "undef" values onto the beginning
237 of the array. The array will grow automatically to accommodate
238 the addition. You must then use "av_store" to assign values to
239 these new elements.
240 Perl equivalent: "unshift @myarray, ( (undef) x $n );"
242 void av_unshift(AV *av, I32 num)
244 get_av Returns the AV of the specified Perl global or package array
246 with the given name (so it won't work on lexical variables).
247 "flags" are passed to "gv_fetchpv". If "GV_ADD" is set and the
248 Perl variable does not exist then it will be created. If
249 "flags" is zero and the variable does not exist then NULL is
250 returned.
251 Perl equivalent: "@{"$name"}".
253 NOTE: the perl_ form of this function is deprecated.
255 AV* get_av(const char *name, I32 flags)
257 newAV Creates a new AV. The reference count is set to 1.
259 Perl equivalent: "my @array;".
261 AV* newAV()
263 sortsv Sort an array. Here is an example:
265 sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
267 Currently this always uses mergesort. See sortsv_flags for a
269 more flexible routine.
270 void sortsv(SV** array, size_t num_elts,
272 SVCOMPARE_t cmp)
273 sortsv_flags
275 Sort an array, with various options.
276 void sortsv_flags(SV** array, size_t num_elts,
278 SVCOMPARE_t cmp, U32 flags)
279
281 call_argv
282 Performs a callback to the specified named and package-scoped
283 Perl subroutine with "argv" (a NULL-terminated array of
284 strings) as arguments. See perlcall.
285 Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
287 NOTE: the perl_ form of this function is deprecated.
289 I32 call_argv(const char* sub_name, I32 flags,
291 char** argv)
292 call_method
294 Performs a callback to the specified Perl method. The blessed
295 object must be on the stack. See perlcall.
296 NOTE: the perl_ form of this function is deprecated.
298 I32 call_method(const char* methname, I32 flags)
300 call_pv Performs a callback to the specified Perl sub. See perlcall.
302 NOTE: the perl_ form of this function is deprecated.
304 I32 call_pv(const char* sub_name, I32 flags)
306 call_sv Performs a callback to the Perl sub whose name is in the SV.
308 See perlcall.
309 NOTE: the perl_ form of this function is deprecated.
311 I32 call_sv(SV* sv, VOL I32 flags)
313 ENTER Opening bracket on a callback. See "LEAVE" and perlcall.
315 ENTER;
317 eval_pv Tells Perl to "eval" the given string and return an SV* result.
319 NOTE: the perl_ form of this function is deprecated.
321 SV* eval_pv(const char* p, I32 croak_on_error)
323 eval_sv Tells Perl to "eval" the string in the SV. It supports the same
325 flags as "call_sv", with the obvious exception of G_EVAL. See
326 perlcall.
327 NOTE: the perl_ form of this function is deprecated.
329 I32 eval_sv(SV* sv, I32 flags)
331 FREETMPS
333 Closing bracket for temporaries on a callback. See "SAVETMPS"
334 and perlcall.
335 FREETMPS;
337 LEAVE Closing bracket on a callback. See "ENTER" and perlcall.
339 LEAVE;
341 SAVETMPS
343 Opening bracket for temporaries on a callback. See "FREETMPS"
344 and perlcall.
345 SAVETMPS;
347
349 toLOWER Converts the specified character to lowercase in the platform's
350 native character set, if possible; otherwise returns the input
351 character itself.
352 char toLOWER(char ch)
354 toUPPER Converts the specified character to uppercase in the platform's
356 native character set, if possible; otherwise returns the input
357 character itself.
358 char toUPPER(char ch)
360
362 There are three variants for all the functions in this section. The
363 base ones operate using the character set of the platform Perl is
364 running on. The ones with an "_A" suffix operate on the ASCII
365 character set, and the ones with an "_L1" suffix operate on the full
366 Latin1 character set. All are unaffected by locale and by "use bytes".
367 For ASCII platforms, the base function with no suffix and the one with
369 the "_A" suffix are identical. The function with the "_L1" suffix
370 imposes the Latin-1 character set onto the platform. That is, the code
371 points that are ASCII are unaffected, since ASCII is a subset of
372 Latin-1. But the non-ASCII code points are treated as if they are
373 Latin-1 characters. For example, "isSPACE_L1()" will return true when
374 called with the code point 0xA0, which is the Latin-1 NO-BREAK SPACE.
375 For EBCDIC platforms, the base function with no suffix and the one with
377 the "_L1" suffix should be identical, since, as of this writing, the
378 EBCDIC code pages that Perl knows about all are equivalent to Latin-1.
379 The function that ends in an "_A" suffix will not return true unless
380 the specified character also has an ASCII equivalent.
381 isALPHA Returns a boolean indicating whether the specified character is
383 an alphabetic character in the platform's native character set.
384 See the top of this section for an explanation of variants
385 "isALPHA_A" and "isALPHA_L1".
386 bool isALPHA(char ch)
388 isASCII Returns a boolean indicating whether the specified character is
390 one of the 128 characters in the ASCII character set. On non-
391 ASCII platforms, it is if this character corresponds to an
392 ASCII character. Variants "isASCII_A()" and "isASCII_L1()" are
393 identical to "isASCII()".
394 bool isASCII(char ch)
396 isDIGIT Returns a boolean indicating whether the specified character is
398 a digit in the platform's native character set. Variants
399 "isDIGIT_A" and "isDIGIT_L1" are identical to "isDIGIT".
400 bool isDIGIT(char ch)
402 isLOWER Returns a boolean indicating whether the specified character is
404 a lowercase character in the platform's native character set.
405 See the top of this section for an explanation of variants
406 "isLOWER_A" and "isLOWER_L1".
407 bool isLOWER(char ch)
409 isOCTAL Returns a boolean indicating whether the specified character is
411 an octal digit, [0-7] in the platform's native character set.
412 Variants "isOCTAL_A" and "isOCTAL_L1" are identical to
413 "isOCTAL".
414 bool isOCTAL(char ch)
416 isSPACE Returns a boolean indicating whether the specified character is
418 a whitespace character in the platform's native character set.
419 This is the same as what "\s" matches in a regular expression.
420 See the top of this section for an explanation of variants
421 "isSPACE_A" and "isSPACE_L1".
422 bool isSPACE(char ch)
424 isUPPER Returns a boolean indicating whether the specified character is
426 an uppercase character in the platform's native character set.
427 See the top of this section for an explanation of variants
428 "isUPPER_A" and "isUPPER_L1".
429 bool isUPPER(char ch)
431 isWORDCHAR
433 Returns a boolean indicating whether the specified character is
434 a character that is any of: alphabetic, numeric, or an
435 underscore. This is the same as what "\w" matches in a regular
436 expression. "isALNUM()" is a synonym provided for backward
437 compatibility. Note that it does not have the standard C
438 language meaning of alphanumeric, since it matches an
439 underscore and the standard meaning does not. See the top of
440 this section for an explanation of variants "isWORDCHAR_A" and
441 "isWORDCHAR_L1".
442 bool isWORDCHAR(char ch)
444 isXDIGIT
446 Returns a boolean indicating whether the specified character is
447 a hexadecimal digit, [0-9A-Fa-f]. Variants "isXDIGIT_A()" and
448 "isXDIGIT_L1()" are identical to "isXDIGIT()".
449 bool isXDIGIT(char ch)
451
453 perl_clone
454 Create and return a new interpreter by cloning the current one.
455 perl_clone takes these flags as parameters:
457 CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
459 without it we only clone the data and zero the stacks, with it
460 we copy the stacks and the new perl interpreter is ready to run
461 at the exact same point as the previous one. The pseudo-fork
462 code uses COPY_STACKS while the threads->create doesn't.
463 CLONEf_KEEP_PTR_TABLE - perl_clone keeps a ptr_table with the
465 pointer of the old variable as a key and the new variable as a
466 value, this allows it to check if something has been cloned and
467 not clone it again but rather just use the value and increase
468 the refcount. If KEEP_PTR_TABLE is not set then perl_clone
469 will kill the ptr_table using the function
470 "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;", reason to
471 keep it around is if you want to dup some of your own variable
472 who are outside the graph perl scans, example of this code is
473 in threads.xs create.
474 CLONEf_CLONE_HOST - This is a win32 thing, it is ignored on
476 unix, it tells perls win32host code (which is c++) to clone
477 itself, this is needed on win32 if you want to run two threads
478 at the same time, if you just want to do some stuff in a
479 separate perl interpreter and then throw it away and return to
480 the original one, you don't need to do anything.
481 PerlInterpreter* perl_clone(
483 PerlInterpreter *proto_perl,
484 UV flags
485 )
486
488 BhkDISABLE
489 Temporarily disable an entry in this BHK structure, by clearing
490 the appropriate flag. which is a preprocessor token indicating
491 which entry to disable.
492 NOTE: this function is experimental and may change or be
494 removed without notice.
495 void BhkDISABLE(BHK *hk, which)
497 BhkENABLE
499 Re-enable an entry in this BHK structure, by setting the
500 appropriate flag. which is a preprocessor token indicating
501 which entry to enable. This will assert (under -DDEBUGGING) if
502 the entry doesn't contain a valid pointer.
503 NOTE: this function is experimental and may change or be
505 removed without notice.
506 void BhkENABLE(BHK *hk, which)
508 BhkENTRY_set
510 Set an entry in the BHK structure, and set the flags to
511 indicate it is valid. which is a preprocessing token indicating
512 which entry to set. The type of ptr depends on the entry.
513 NOTE: this function is experimental and may change or be
515 removed without notice.
516 void BhkENTRY_set(BHK *hk, which, void *ptr)
518 blockhook_register
520 Register a set of hooks to be called when the Perl lexical
521 scope changes at compile time. See "Compile-time scope hooks"
522 in perlguts.
523 NOTE: this function is experimental and may change or be
525 removed without notice.
526 NOTE: this function must be explicitly called as
528 Perl_blockhook_register with an aTHX_ parameter.
529 void Perl_blockhook_register(pTHX_ BHK *hk)
531
533 cophh_2hv
534 Generates and returns a standard Perl hash representing the
535 full set of key/value pairs in the cop hints hash cophh. flags
536 is currently unused and must be zero.
537 NOTE: this function is experimental and may change or be
539 removed without notice.
540 HV * cophh_2hv(const COPHH *cophh, U32 flags)
542 cophh_copy
544 Make and return a complete copy of the cop hints hash cophh.
545 NOTE: this function is experimental and may change or be
547 removed without notice.
548 COPHH * cophh_copy(COPHH *cophh)
550 cophh_delete_pv
552 Like "cophh_delete_pvn", but takes a nul-terminated string
553 instead of a string/length pair.
554 NOTE: this function is experimental and may change or be
556 removed without notice.
557 COPHH * cophh_delete_pv(const COPHH *cophh,
559 const char *key, U32 hash,
560 U32 flags)
561 cophh_delete_pvn
563 Delete a key and its associated value from the cop hints hash
564 cophh, and returns the modified hash. The returned hash
565 pointer is in general not the same as the hash pointer that was
566 passed in. The input hash is consumed by the function, and the
567 pointer to it must not be subsequently used. Use "cophh_copy"
568 if you need both hashes.
569 The key is specified by keypv and keylen. If flags has the
571 "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
572 UTF-8, otherwise they are interpreted as Latin-1. hash is a
573 precomputed hash of the key string, or zero if it has not been
574 precomputed.
575 NOTE: this function is experimental and may change or be
577 removed without notice.
578 COPHH * cophh_delete_pvn(COPHH *cophh,
580 const char *keypv,
581 STRLEN keylen, U32 hash,
582 U32 flags)
583 cophh_delete_pvs
585 Like "cophh_delete_pvn", but takes a literal string instead of
586 a string/length pair, and no precomputed hash.
587 NOTE: this function is experimental and may change or be
589 removed without notice.
590 COPHH * cophh_delete_pvs(const COPHH *cophh,
592 const char *key, U32 flags)
593 cophh_delete_sv
595 Like "cophh_delete_pvn", but takes a Perl scalar instead of a
596 string/length pair.
597 NOTE: this function is experimental and may change or be
599 removed without notice.
600 COPHH * cophh_delete_sv(const COPHH *cophh, SV *key,
602 U32 hash, U32 flags)
603 cophh_fetch_pv
605 Like "cophh_fetch_pvn", but takes a nul-terminated string
606 instead of a string/length pair.
607 NOTE: this function is experimental and may change or be
609 removed without notice.
610 SV * cophh_fetch_pv(const COPHH *cophh,
612 const char *key, U32 hash,
613 U32 flags)
614 cophh_fetch_pvn
616 Look up the entry in the cop hints hash cophh with the key
617 specified by keypv and keylen. If flags has the
618 "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
619 UTF-8, otherwise they are interpreted as Latin-1. hash is a
620 precomputed hash of the key string, or zero if it has not been
621 precomputed. Returns a mortal scalar copy of the value
622 associated with the key, or &PL_sv_placeholder if there is no
623 value associated with the key.
624 NOTE: this function is experimental and may change or be
626 removed without notice.
627 SV * cophh_fetch_pvn(const COPHH *cophh,
629 const char *keypv,
630 STRLEN keylen, U32 hash,
631 U32 flags)
632 cophh_fetch_pvs
634 Like "cophh_fetch_pvn", but takes a literal string instead of a
635 string/length pair, and no precomputed hash.
636 NOTE: this function is experimental and may change or be
638 removed without notice.
639 SV * cophh_fetch_pvs(const COPHH *cophh,
641 const char *key, U32 flags)
642 cophh_fetch_sv
644 Like "cophh_fetch_pvn", but takes a Perl scalar instead of a
645 string/length pair.
646 NOTE: this function is experimental and may change or be
648 removed without notice.
649 SV * cophh_fetch_sv(const COPHH *cophh, SV *key,
651 U32 hash, U32 flags)
652 cophh_free
654 Discard the cop hints hash cophh, freeing all resources
655 associated with it.
656 NOTE: this function is experimental and may change or be
658 removed without notice.
659 void cophh_free(COPHH *cophh)
661 cophh_new_empty
663 Generate and return a fresh cop hints hash containing no
664 entries.
665 NOTE: this function is experimental and may change or be
667 removed without notice.
668 COPHH * cophh_new_empty()
670 cophh_store_pv
672 Like "cophh_store_pvn", but takes a nul-terminated string
673 instead of a string/length pair.
674 NOTE: this function is experimental and may change or be
676 removed without notice.
677 COPHH * cophh_store_pv(const COPHH *cophh,
679 const char *key, U32 hash,
680 SV *value, U32 flags)
681 cophh_store_pvn
683 Stores a value, associated with a key, in the cop hints hash
684 cophh, and returns the modified hash. The returned hash
685 pointer is in general not the same as the hash pointer that was
686 passed in. The input hash is consumed by the function, and the
687 pointer to it must not be subsequently used. Use "cophh_copy"
688 if you need both hashes.
689 The key is specified by keypv and keylen. If flags has the
691 "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
692 UTF-8, otherwise they are interpreted as Latin-1. hash is a
693 precomputed hash of the key string, or zero if it has not been
694 precomputed.
695 value is the scalar value to store for this key. value is
697 copied by this function, which thus does not take ownership of
698 any reference to it, and later changes to the scalar will not
699 be reflected in the value visible in the cop hints hash.
700 Complex types of scalar will not be stored with referential
701 integrity, but will be coerced to strings.
702 NOTE: this function is experimental and may change or be
704 removed without notice.
705 COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
707 STRLEN keylen, U32 hash,
708 SV *value, U32 flags)
709 cophh_store_pvs
711 Like "cophh_store_pvn", but takes a literal string instead of a
712 string/length pair, and no precomputed hash.
713 NOTE: this function is experimental and may change or be
715 removed without notice.
716 COPHH * cophh_store_pvs(const COPHH *cophh,
718 const char *key, SV *value,
719 U32 flags)
720 cophh_store_sv
722 Like "cophh_store_pvn", but takes a Perl scalar instead of a
723 string/length pair.
724 NOTE: this function is experimental and may change or be
726 removed without notice.
727 COPHH * cophh_store_sv(const COPHH *cophh, SV *key,
729 U32 hash, SV *value, U32 flags)
730
732 cop_hints_2hv
733 Generates and returns a standard Perl hash representing the
734 full set of hint entries in the cop cop. flags is currently
735 unused and must be zero.
736 HV * cop_hints_2hv(const COP *cop, U32 flags)
738 cop_hints_fetch_pv
740 Like "cop_hints_fetch_pvn", but takes a nul-terminated string
741 instead of a string/length pair.
742 SV * cop_hints_fetch_pv(const COP *cop,
744 const char *key, U32 hash,
745 U32 flags)
746 cop_hints_fetch_pvn
748 Look up the hint entry in the cop cop with the key specified by
749 keypv and keylen. If flags has the "COPHH_KEY_UTF8" bit set,
750 the key octets are interpreted as UTF-8, otherwise they are
751 interpreted as Latin-1. hash is a precomputed hash of the key
752 string, or zero if it has not been precomputed. Returns a
753 mortal scalar copy of the value associated with the key, or
754 &PL_sv_placeholder if there is no value associated with the
755 key.
756 SV * cop_hints_fetch_pvn(const COP *cop,
758 const char *keypv,
759 STRLEN keylen, U32 hash,
760 U32 flags)
761 cop_hints_fetch_pvs
763 Like "cop_hints_fetch_pvn", but takes a literal string instead
764 of a string/length pair, and no precomputed hash.
765 SV * cop_hints_fetch_pvs(const COP *cop,
767 const char *key, U32 flags)
768 cop_hints_fetch_sv
770 Like "cop_hints_fetch_pvn", but takes a Perl scalar instead of
771 a string/length pair.
772 SV * cop_hints_fetch_sv(const COP *cop, SV *key,
774 U32 hash, U32 flags)
775
777 custom_op_register
778 Register a custom op. See "Custom Operators" in perlguts.
779 NOTE: this function must be explicitly called as
781 Perl_custom_op_register with an aTHX_ parameter.
782 void Perl_custom_op_register(pTHX_
784 Perl_ppaddr_t ppaddr,
785 const XOP *xop)
786 custom_op_xop
788 Return the XOP structure for a given custom op. This function
789 should be considered internal to OP_NAME and the other access
790 macros: use them instead.
791 NOTE: this function must be explicitly called as
793 Perl_custom_op_xop with an aTHX_ parameter.
794 const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
796 XopDISABLE
798 Temporarily disable a member of the XOP, by clearing the
799 appropriate flag.
800 void XopDISABLE(XOP *xop, which)
802 XopENABLE
804 Reenable a member of the XOP which has been disabled.
805 void XopENABLE(XOP *xop, which)
807 XopENTRY
809 Return a member of the XOP structure. which is a cpp token
810 indicating which entry to return. If the member is not set this
811 will return a default value. The return type depends on which.
812 XopENTRY(XOP *xop, which)
814 XopENTRY_set
816 Set a member of the XOP structure. which is a cpp token
817 indicating which entry to set. See "Custom Operators" in
818 perlguts for details about the available members and how they
819 are used.
820 void XopENTRY_set(XOP *xop, which, value)
822 XopFLAGS
824 Return the XOP's flags.
825 U32 XopFLAGS(XOP *xop)
827
829 CvSTASH Returns the stash of the CV. A stash is the symbol table hash,
830 containing the package-scoped variables in the package where
831 the subroutine was defined. For more information, see
832 perlguts.
833 This also has a special use with XS AUTOLOAD subs. See
835 "Autoloading with XSUBs" in perlguts.
836 HV* CvSTASH(CV* cv)
838 get_cv Uses "strlen" to get the length of "name", then calls
840 "get_cvn_flags".
841 NOTE: the perl_ form of this function is deprecated.
843 CV* get_cv(const char* name, I32 flags)
845 get_cvn_flags
847 Returns the CV of the specified Perl subroutine. "flags" are
848 passed to "gv_fetchpvn_flags". If "GV_ADD" is set and the Perl
849 subroutine does not exist then it will be declared (which has
850 the same effect as saying "sub name;"). If "GV_ADD" is not set
851 and the subroutine does not exist then NULL is returned.
852 NOTE: the perl_ form of this function is deprecated.
854 CV* get_cvn_flags(const char* name, STRLEN len,
856 I32 flags)
857
859 cv_clone
860 Clone a CV, making a lexical closure. proto supplies the
861 prototype of the function: its code, pad structure, and other
862 attributes. The prototype is combined with a capture of outer
863 lexicals to which the code refers, which are taken from the
864 currently-executing instance of the immediately surrounding
865 code.
866 CV * cv_clone(CV *proto)
868 cv_undef
870 Clear out all the active components of a CV. This can happen
871 either by an explicit "undef &foo", or by the reference count
872 going to zero. In the former case, we keep the CvOUTSIDE
873 pointer, so that any anonymous children can still follow the
874 full lexical scope chain.
875 void cv_undef(CV* cv)
877 find_rundefsv
879 Find and return the variable that is named $_ in the lexical
880 scope of the currently-executing function. This may be a
881 lexical $_, or will otherwise be the global one.
882 SV * find_rundefsv()
884 find_rundefsvoffset
886 Find the position of the lexical $_ in the pad of the
887 currently-executing function. Returns the offset in the
888 current pad, or "NOT_IN_PAD" if there is no lexical $_ in scope
889 (in which case the global one should be used instead).
890 "find_rundefsv" is likely to be more convenient.
891 NOTE: the perl_ form of this function is deprecated.
893 PADOFFSET find_rundefsvoffset()
895 load_module
897 Loads the module whose name is pointed to by the string part of
898 name. Note that the actual module name, not its filename,
899 should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm".
900 flags can be any of PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT,
901 or PERL_LOADMOD_IMPORT_OPS (or 0 for no flags). ver, if
902 specified and not NULL, provides version semantics similar to
903 "use Foo::Bar VERSION". The optional trailing SV* arguments
904 can be used to specify arguments to the module's import()
905 method, similar to "use Foo::Bar VERSION LIST". They must be
906 terminated with a final NULL pointer. Note that this list can
907 only be omitted when the PERL_LOADMOD_NOIMPORT flag has been
908 used. Otherwise at least a single NULL pointer to designate
909 the default import list is required.
910 The reference count for each specified "SV*" parameter is
912 decremented.
913 void load_module(U32 flags, SV* name, SV* ver, ...)
915 nothreadhook
917 Stub that provides thread hook for perl_destruct when there are
918 no threads.
919 int nothreadhook()
921 pad_add_anon
923 Allocates a place in the currently-compiling pad (via
924 "pad_alloc") for an anonymous function that is lexically scoped
925 inside the currently-compiling function. The function func is
926 linked into the pad, and its "CvOUTSIDE" link to the outer
927 scope is weakened to avoid a reference loop.
928 optype should be an opcode indicating the type of operation
930 that the pad entry is to support. This doesn't affect
931 operational semantics, but is used for debugging.
932 PADOFFSET pad_add_anon(CV *func, I32 optype)
934 pad_add_name_pv
936 Exactly like "pad_add_name_pvn", but takes a nul-terminated
937 string instead of a string/length pair.
938 PADOFFSET pad_add_name_pv(const char *name, U32 flags,
940 HV *typestash, HV *ourstash)
941 pad_add_name_pvn
943 Allocates a place in the currently-compiling pad for a named
944 lexical variable. Stores the name and other metadata in the
945 name part of the pad, and makes preparations to manage the
946 variable's lexical scoping. Returns the offset of the
947 allocated pad slot.
948 namepv/namelen specify the variable's name, including leading
950 sigil. If typestash is non-null, the name is for a typed
951 lexical, and this identifies the type. If ourstash is non-
952 null, it's a lexical reference to a package variable, and this
953 identifies the package. The following flags can be OR'ed
954 together:
955 padadd_OUR redundantly specifies if it's a package var
957 padadd_STATE variable will retain value persistently
958 padadd_NO_DUP_CHECK skip check for lexical shadowing
959 PADOFFSET pad_add_name_pvn(const char *namepv,
961 STRLEN namelen, U32 flags,
962 HV *typestash, HV *ourstash)
963 pad_add_name_sv
965 Exactly like "pad_add_name_pvn", but takes the name string in
966 the form of an SV instead of a string/length pair.
967 PADOFFSET pad_add_name_sv(SV *name, U32 flags,
969 HV *typestash, HV *ourstash)
970 pad_alloc
972 Allocates a place in the currently-compiling pad, returning the
973 offset of the allocated pad slot. No name is initially
974 attached to the pad slot. tmptype is a set of flags indicating
975 the kind of pad entry required, which will be set in the value
976 SV for the allocated pad entry:
977 SVs_PADMY named lexical variable ("my", "our", "state")
979 SVs_PADTMP unnamed temporary store
980 optype should be an opcode indicating the type of operation
982 that the pad entry is to support. This doesn't affect
983 operational semantics, but is used for debugging.
984 NOTE: this function is experimental and may change or be
986 removed without notice.
987 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
989 pad_compname_type
991 Looks up the type of the lexical variable at position po in the
992 currently-compiling pad. If the variable is typed, the stash
993 of the class to which it is typed is returned. If not, "NULL"
994 is returned.
995 HV * pad_compname_type(PADOFFSET po)
997 pad_findmy_pv
999 Exactly like "pad_findmy_pvn", but takes a nul-terminated
1000 string instead of a string/length pair.
1001 PADOFFSET pad_findmy_pv(const char *name, U32 flags)
1003 pad_findmy_pvn
1005 Given the name of a lexical variable, find its position in the
1006 currently-compiling pad. namepv/namelen specify the variable's
1007 name, including leading sigil. flags is reserved and must be
1008 zero. If it is not in the current pad but appears in the pad
1009 of any lexically enclosing scope, then a pseudo-entry for it is
1010 added in the current pad. Returns the offset in the current
1011 pad, or "NOT_IN_PAD" if no such lexical is in scope.
1012 PADOFFSET pad_findmy_pvn(const char *namepv,
1014 STRLEN namelen, U32 flags)
1015 pad_findmy_sv
1017 Exactly like "pad_findmy_pvn", but takes the name string in the
1018 form of an SV instead of a string/length pair.
1019 PADOFFSET pad_findmy_sv(SV *name, U32 flags)
1021 pad_setsv
1023 Set the value at offset po in the current (compiling or
1024 executing) pad. Use the macro PAD_SETSV() rather than calling
1025 this function directly.
1026 void pad_setsv(PADOFFSET po, SV *sv)
1028 pad_sv Get the value at offset po in the current (compiling or
1030 executing) pad. Use macro PAD_SV instead of calling this
1031 function directly.
1032 SV * pad_sv(PADOFFSET po)
1034 pad_tidy
1036 Tidy up a pad at the end of compilation of the code to which it
1037 belongs. Jobs performed here are: remove most stuff from the
1038 pads of anonsub prototypes; give it a @_; mark temporaries as
1039 such. type indicates the kind of subroutine:
1040 padtidy_SUB ordinary subroutine
1042 padtidy_SUBCLONE prototype for lexical closure
1043 padtidy_FORMAT format
1044 NOTE: this function is experimental and may change or be
1046 removed without notice.
1047 void pad_tidy(padtidy_type type)
1049 perl_alloc
1051 Allocates a new Perl interpreter. See perlembed.
1052 PerlInterpreter* perl_alloc()
1054 perl_construct
1056 Initializes a new Perl interpreter. See perlembed.
1057 void perl_construct(PerlInterpreter *my_perl)
1059 perl_destruct
1061 Shuts down a Perl interpreter. See perlembed.
1062 int perl_destruct(PerlInterpreter *my_perl)
1064 perl_free
1066 Releases a Perl interpreter. See perlembed.
1067 void perl_free(PerlInterpreter *my_perl)
1069 perl_parse
1071 Tells a Perl interpreter to parse a Perl script. See
1072 perlembed.
1073 int perl_parse(PerlInterpreter *my_perl,
1075 XSINIT_t xsinit, int argc,
1076 char** argv, char** env)
1077 perl_run
1079 Tells a Perl interpreter to run. See perlembed.
1080 int perl_run(PerlInterpreter *my_perl)
1082 require_pv
1084 Tells Perl to "require" the file named by the string argument.
1085 It is analogous to the Perl code "eval "require '$file'"".
1086 It's even implemented that way; consider using load_module
1087 instead.
1088 NOTE: the perl_ form of this function is deprecated.
1090 void require_pv(const char* pv)
1092
1094 pv_display
1095 Similar to
1096 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
1098 except that an additional "\0" will be appended to the string
1100 when len > cur and pv[cur] is "\0".
1101 Note that the final string may be up to 7 chars longer than
1103 pvlim.
1104 char* pv_display(SV *dsv, const char *pv, STRLEN cur,
1106 STRLEN len, STRLEN pvlim)
1107 pv_escape
1109 Escapes at most the first "count" chars of pv and puts the
1110 results into dsv such that the size of the escaped string will
1111 not exceed "max" chars and will not contain any incomplete
1112 escape sequences.
1113 If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes
1115 in the string will also be escaped.
1116 Normally the SV will be cleared before the escaped string is
1118 prepared, but when PERL_PV_ESCAPE_NOCLEAR is set this will not
1119 occur.
1120 If PERL_PV_ESCAPE_UNI is set then the input string is treated
1122 as Unicode, if PERL_PV_ESCAPE_UNI_DETECT is set then the input
1123 string is scanned using "is_utf8_string()" to determine if it
1124 is Unicode.
1125 If PERL_PV_ESCAPE_ALL is set then all input chars will be
1127 output using "\x01F1" style escapes, otherwise if
1128 PERL_PV_ESCAPE_NONASCII is set, only chars above 127 will be
1129 escaped using this style; otherwise, only chars above 255 will
1130 be so escaped; other non printable chars will use octal or
1131 common escaped patterns like "\n". Otherwise, if
1132 PERL_PV_ESCAPE_NOBACKSLASH then all chars below 255 will be
1133 treated as printable and will be output as literals.
1134 If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of
1136 the string will be escaped, regardless of max. If the output is
1137 to be in hex, then it will be returned as a plain hex sequence.
1138 Thus the output will either be a single char, an octal escape
1139 sequence, a special escape like "\n" or a hex value.
1140 If PERL_PV_ESCAPE_RE is set then the escape char used will be a
1142 '%' and not a '\\'. This is because regexes very often contain
1143 backslashed sequences, whereas '%' is not a particularly common
1144 character in patterns.
1145 Returns a pointer to the escaped text as held by dsv.
1147 char* pv_escape(SV *dsv, char const * const str,
1149 const STRLEN count, const STRLEN max,
1150 STRLEN * const escaped,
1151 const U32 flags)
1152 pv_pretty
1154 Converts a string into something presentable, handling escaping
1155 via pv_escape() and supporting quoting and ellipses.
1156 If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
1158 double quoted with any double quotes in the string escaped.
1159 Otherwise if the PERL_PV_PRETTY_LTGT flag is set then the
1160 result be wrapped in angle brackets.
1161 If the PERL_PV_PRETTY_ELLIPSES flag is set and not all
1163 characters in string were output then an ellipsis "..." will be
1164 appended to the string. Note that this happens AFTER it has
1165 been quoted.
1166 If start_color is non-null then it will be inserted after the
1168 opening quote (if there is one) but before the escaped text. If
1169 end_color is non-null then it will be inserted after the
1170 escaped text but before any quotes or ellipses.
1171 Returns a pointer to the prettified text as held by dsv.
1173 char* pv_pretty(SV *dsv, char const * const str,
1175 const STRLEN count, const STRLEN max,
1176 char const * const start_color,
1177 char const * const end_color,
1178 const U32 flags)
1179
1181 custom_op_desc
1182 Return the description of a given custom op. This was once used
1183 by the OP_DESC macro, but is no longer: it has only been kept
1184 for compatibility, and should not be used.
1185 const char * custom_op_desc(const OP *o)
1187 custom_op_name
1189 Return the name for a given custom op. This was once used by
1190 the OP_NAME macro, but is no longer: it has only been kept for
1191 compatibility, and should not be used.
1192 const char * custom_op_name(const OP *o)
1194 gv_fetchmethod
1196 See "gv_fetchmethod_autoload".
1197 GV* gv_fetchmethod(HV* stash, const char* name)
1199 pack_cat
1201 The engine implementing pack() Perl function. Note: parameters
1202 next_in_list and flags are not used. This call should not be
1203 used; use packlist instead.
1204 void pack_cat(SV *cat, const char *pat,
1206 const char *patend, SV **beglist,
1207 SV **endlist, SV ***next_in_list,
1208 U32 flags)
1209 sv_2pvbyte_nolen
1211 Return a pointer to the byte-encoded representation of the SV.
1212 May cause the SV to be downgraded from UTF-8 as a side-effect.
1213 Usually accessed via the "SvPVbyte_nolen" macro.
1215 char* sv_2pvbyte_nolen(SV* sv)
1217 sv_2pvutf8_nolen
1219 Return a pointer to the UTF-8-encoded representation of the SV.
1220 May cause the SV to be upgraded to UTF-8 as a side-effect.
1221 Usually accessed via the "SvPVutf8_nolen" macro.
1223 char* sv_2pvutf8_nolen(SV* sv)
1225 sv_2pv_nolen
1227 Like "sv_2pv()", but doesn't return the length too. You should
1228 usually use the macro wrapper "SvPV_nolen(sv)" instead.
1229 char* sv_2pv_nolen(SV* sv)
1231 sv_catpvn_mg
1233 Like "sv_catpvn", but also handles 'set' magic.
1234 void sv_catpvn_mg(SV *sv, const char *ptr,
1236 STRLEN len)
1237 sv_catsv_mg
1239 Like "sv_catsv", but also handles 'set' magic.
1240 void sv_catsv_mg(SV *dsv, SV *ssv)
1242 sv_force_normal
1244 Undo various types of fakery on an SV: if the PV is a shared
1245 string, make a private copy; if we're a ref, stop refing; if
1246 we're a glob, downgrade to an xpvmg. See also
1247 "sv_force_normal_flags".
1248 void sv_force_normal(SV *sv)
1250 sv_iv A private implementation of the "SvIVx" macro for compilers
1252 which can't cope with complex macro expressions. Always use the
1253 macro instead.
1254 IV sv_iv(SV* sv)
1256 sv_nolocking
1258 Dummy routine which "locks" an SV when there is no locking
1259 module present. Exists to avoid test for a NULL function
1260 pointer and because it could potentially warn under some level
1261 of strict-ness.
1262 "Superseded" by sv_nosharing().
1264 void sv_nolocking(SV *sv)
1266 sv_nounlocking
1268 Dummy routine which "unlocks" an SV when there is no locking
1269 module present. Exists to avoid test for a NULL function
1270 pointer and because it could potentially warn under some level
1271 of strict-ness.
1272 "Superseded" by sv_nosharing().
1274 void sv_nounlocking(SV *sv)
1276 sv_nv A private implementation of the "SvNVx" macro for compilers
1278 which can't cope with complex macro expressions. Always use the
1279 macro instead.
1280 NV sv_nv(SV* sv)
1282 sv_pv Use the "SvPV_nolen" macro instead
1284 char* sv_pv(SV *sv)
1286 sv_pvbyte
1288 Use "SvPVbyte_nolen" instead.
1289 char* sv_pvbyte(SV *sv)
1291 sv_pvbyten
1293 A private implementation of the "SvPVbyte" macro for compilers
1294 which can't cope with complex macro expressions. Always use the
1295 macro instead.
1296 char* sv_pvbyten(SV *sv, STRLEN *lp)
1298 sv_pvn A private implementation of the "SvPV" macro for compilers
1300 which can't cope with complex macro expressions. Always use the
1301 macro instead.
1302 char* sv_pvn(SV *sv, STRLEN *lp)
1304 sv_pvutf8
1306 Use the "SvPVutf8_nolen" macro instead
1307 char* sv_pvutf8(SV *sv)
1309 sv_pvutf8n
1311 A private implementation of the "SvPVutf8" macro for compilers
1312 which can't cope with complex macro expressions. Always use the
1313 macro instead.
1314 char* sv_pvutf8n(SV *sv, STRLEN *lp)
1316 sv_taint
1318 Taint an SV. Use "SvTAINTED_on" instead.
1319 void sv_taint(SV* sv)
1321 sv_unref
1323 Unsets the RV status of the SV, and decrements the reference
1324 count of whatever was being referenced by the RV. This can
1325 almost be thought of as a reversal of "newSVrv". This is
1326 "sv_unref_flags" with the "flag" being zero. See "SvROK_off".
1327 void sv_unref(SV* sv)
1329 sv_usepvn
1331 Tells an SV to use "ptr" to find its string value. Implemented
1332 by calling "sv_usepvn_flags" with "flags" of 0, hence does not
1333 handle 'set' magic. See "sv_usepvn_flags".
1334 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
1336 sv_usepvn_mg
1338 Like "sv_usepvn", but also handles 'set' magic.
1339 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
1341 sv_uv A private implementation of the "SvUVx" macro for compilers
1343 which can't cope with complex macro expressions. Always use the
1344 macro instead.
1345 UV sv_uv(SV* sv)
1347 unpack_str
1349 The engine implementing unpack() Perl function. Note:
1350 parameters strbeg, new_s and ocnt are not used. This call
1351 should not be used, use unpackstring instead.
1352 I32 unpack_str(const char *pat, const char *patend,
1354 const char *s, const char *strbeg,
1355 const char *strend, char **new_s,
1356 I32 ocnt, U32 flags)
1357
1359 op_contextualize
1360 Applies a syntactic context to an op tree representing an
1361 expression. o is the op tree, and context must be "G_SCALAR",
1362 "G_ARRAY", or "G_VOID" to specify the context to apply. The
1363 modified op tree is returned.
1364 OP * op_contextualize(OP *o, I32 context)
1366
1368 PERL_SYS_INIT
1369 Provides system-specific tune up of the C runtime environment
1370 necessary to run Perl interpreters. This should be called only
1371 once, before creating any Perl interpreters.
1372 void PERL_SYS_INIT(int argc, char** argv)
1374 PERL_SYS_INIT3
1376 Provides system-specific tune up of the C runtime environment
1377 necessary to run Perl interpreters. This should be called only
1378 once, before creating any Perl interpreters.
1379 void PERL_SYS_INIT3(int argc, char** argv,
1381 char** env)
1382 PERL_SYS_TERM
1384 Provides system-specific clean up of the C runtime environment
1385 after running Perl interpreters. This should be called only
1386 once, after freeing any remaining Perl interpreters.
1387 void PERL_SYS_TERM()
1389
1391 caller_cx
1392 The XSUB-writer's equivalent of caller(). The returned
1393 "PERL_CONTEXT" structure can be interrogated to find all the
1394 information returned to Perl by "caller". Note that XSUBs don't
1395 get a stack frame, so "caller_cx(0, NULL)" will return
1396 information for the immediately-surrounding Perl code.
1397 This function skips over the automatic calls to &DB::sub made
1399 on the behalf of the debugger. If the stack frame requested was
1400 a sub called by "DB::sub", the return value will be the frame
1401 for the call to "DB::sub", since that has the correct line
1402 number/etc. for the call site. If dbcxp is non-"NULL", it will
1403 be set to a pointer to the frame for the sub call itself.
1404 const PERL_CONTEXT * caller_cx(
1406 I32 level,
1407 const PERL_CONTEXT **dbcxp
1408 )
1409 find_runcv
1411 Locate the CV corresponding to the currently executing sub or
1412 eval. If db_seqp is non_null, skip CVs that are in the DB
1413 package and populate *db_seqp with the cop sequence number at
1414 the point that the DB:: code was entered. (allows debuggers to
1415 eval in the scope of the breakpoint rather than in the scope of
1416 the debugger itself).
1417 CV* find_runcv(U32 *db_seqp)
1419
1421 packlist
1422 The engine implementing pack() Perl function.
1423 void packlist(SV *cat, const char *pat,
1425 const char *patend, SV **beglist,
1426 SV **endlist)
1427 unpackstring
1429 The engine implementing unpack() Perl function. "unpackstring"
1430 puts the extracted list items on the stack and returns the
1431 number of elements. Issue "PUTBACK" before and "SPAGAIN" after
1432 the call to this function.
1433 I32 unpackstring(const char *pat,
1435 const char *patend, const char *s,
1436 const char *strend, U32 flags)
1437
1439 setdefout
1440 Sets PL_defoutgv, the default file handle for output, to the
1441 passed in typeglob. As PL_defoutgv "owns" a reference on its
1442 typeglob, the reference count of the passed in typeglob is
1443 increased by one, and the reference count of the typeglob that
1444 PL_defoutgv points to is decreased by one.
1445 void setdefout(GV* gv)
1447
1449 ibcmp_utf8
1450 This is a synonym for (! foldEQ_utf8())
1451 I32 ibcmp_utf8(const char *s1, char **pe1, UV l1,
1453 bool u1, const char *s2, char **pe2,
1454 UV l2, bool u2)
1455
1457 ibcmp This is a synonym for (! foldEQ())
1458 I32 ibcmp(const char* a, const char* b, I32 len)
1460 ibcmp_locale
1462 This is a synonym for (! foldEQ_locale())
1463 I32 ibcmp_locale(const char* a, const char* b,
1465 I32 len)
1466
1468 PL_check
1469 Array, indexed by opcode, of functions that will be called for
1470 the "check" phase of optree building during compilation of Perl
1471 code. For most (but not all) types of op, once the op has been
1472 initially built and populated with child ops it will be
1473 filtered through the check function referenced by the
1474 appropriate element of this array. The new op is passed in as
1475 the sole argument to the check function, and the check function
1476 returns the completed op. The check function may (as the name
1477 suggests) check the op for validity and signal errors. It may
1478 also initialise or modify parts of the ops, or perform more
1479 radical surgery such as adding or removing child ops, or even
1480 throw the op away and return a different op in its place.
1481 This array of function pointers is a convenient place to hook
1483 into the compilation process. An XS module can put its own
1484 custom check function in place of any of the standard ones, to
1485 influence the compilation of a particular type of op. However,
1486 a custom check function must never fully replace a standard
1487 check function (or even a custom check function from another
1488 module). A module modifying checking must instead wrap the
1489 preexisting check function. A custom check function must be
1490 selective about when to apply its custom behaviour. In the
1491 usual case where it decides not to do anything special with an
1492 op, it must chain the preexisting op function. Check functions
1493 are thus linked in a chain, with the core's base checker at the
1494 end.
1495 For thread safety, modules should not write directly to this
1497 array. Instead, use the function "wrap_op_checker".
1498 PL_keyword_plugin
1500 Function pointer, pointing at a function used to handle
1501 extended keywords. The function should be declared as
1502 int keyword_plugin_function(pTHX_
1504 char *keyword_ptr, STRLEN keyword_len,
1505 OP **op_ptr)
1506 The function is called from the tokeniser, whenever a possible
1508 keyword is seen. "keyword_ptr" points at the word in the
1509 parser's input buffer, and "keyword_len" gives its length; it
1510 is not null-terminated. The function is expected to examine
1511 the word, and possibly other state such as %^H, to decide
1512 whether it wants to handle it as an extended keyword. If it
1513 does not, the function should return "KEYWORD_PLUGIN_DECLINE",
1514 and the normal parser process will continue.
1515 If the function wants to handle the keyword, it first must
1517 parse anything following the keyword that is part of the syntax
1518 introduced by the keyword. See "Lexer interface" for details.
1519 When a keyword is being handled, the plugin function must build
1521 a tree of "OP" structures, representing the code that was
1522 parsed. The root of the tree must be stored in *op_ptr. The
1523 function then returns a constant indicating the syntactic role
1524 of the construct that it has parsed: "KEYWORD_PLUGIN_STMT" if
1525 it is a complete statement, or "KEYWORD_PLUGIN_EXPR" if it is
1526 an expression. Note that a statement construct cannot be used
1527 inside an expression (except via "do BLOCK" and similar), and
1528 an expression is not a complete statement (it requires at least
1529 a terminating semicolon).
1530 When a keyword is handled, the plugin function may also have
1532 (compile-time) side effects. It may modify "%^H", define
1533 functions, and so on. Typically, if side effects are the main
1534 purpose of a handler, it does not wish to generate any ops to
1535 be included in the normal compilation. In this case it is
1536 still required to supply an op tree, but it suffices to
1537 generate a single null op.
1538 That's how the *PL_keyword_plugin function needs to behave
1540 overall. Conventionally, however, one does not completely
1541 replace the existing handler function. Instead, take a copy of
1542 "PL_keyword_plugin" before assigning your own function pointer
1543 to it. Your handler function should look for keywords that it
1544 is interested in and handle those. Where it is not interested,
1545 it should call the saved plugin function, passing on the
1546 arguments it received. Thus "PL_keyword_plugin" actually
1547 points at a chain of handler functions, all of which have an
1548 opportunity to handle keywords, and only the last function in
1549 the chain (built into the Perl core) will normally return
1550 "KEYWORD_PLUGIN_DECLINE".
1551 NOTE: this function is experimental and may change or be
1553 removed without notice.
1554
1556 GvSV Return the SV from the GV.
1557 SV* GvSV(GV* gv)
1559 gv_const_sv
1561 If "gv" is a typeglob whose subroutine entry is a constant sub
1562 eligible for inlining, or "gv" is a placeholder reference that
1563 would be promoted to such a typeglob, then returns the value
1564 returned by the sub. Otherwise, returns NULL.
1565 SV* gv_const_sv(GV* gv)
1567 gv_fetchmeth
1569 Like "gv_fetchmeth_pvn", but lacks a flags parameter.
1570 GV* gv_fetchmeth(HV* stash, const char* name,
1572 STRLEN len, I32 level)
1573 gv_fetchmethod_autoload
1575 Returns the glob which contains the subroutine to call to
1576 invoke the method on the "stash". In fact in the presence of
1577 autoloading this may be the glob for "AUTOLOAD". In this case
1578 the corresponding variable $AUTOLOAD is already setup.
1579 The third parameter of "gv_fetchmethod_autoload" determines
1581 whether AUTOLOAD lookup is performed if the given method is not
1582 present: non-zero means yes, look for AUTOLOAD; zero means no,
1583 don't look for AUTOLOAD. Calling "gv_fetchmethod" is
1584 equivalent to calling "gv_fetchmethod_autoload" with a non-zero
1585 "autoload" parameter.
1586 These functions grant "SUPER" token as a prefix of the method
1588 name. Note that if you want to keep the returned glob for a
1589 long time, you need to check for it being "AUTOLOAD", since at
1590 the later time the call may load a different subroutine due to
1591 $AUTOLOAD changing its value. Use the glob created via a side
1592 effect to do this.
1593 These functions have the same side-effects and as
1595 "gv_fetchmeth" with "level==0". "name" should be writable if
1596 contains ':' or ' ''. The warning against passing the GV
1597 returned by "gv_fetchmeth" to "call_sv" apply equally to these
1598 functions.
1599 GV* gv_fetchmethod_autoload(HV* stash,
1601 const char* name,
1602 I32 autoload)
1603 gv_fetchmeth_autoload
1605 This is the old form of "gv_fetchmeth_pvn_autoload", which has
1606 no flags parameter.
1607 GV* gv_fetchmeth_autoload(HV* stash,
1609 const char* name,
1610 STRLEN len, I32 level)
1611 gv_fetchmeth_pv
1613 Exactly like "gv_fetchmeth_pvn", but takes a nul-terminated
1614 string instead of a string/length pair.
1615 GV* gv_fetchmeth_pv(HV* stash, const char* name,
1617 I32 level, U32 flags)
1618 gv_fetchmeth_pvn
1620 Returns the glob with the given "name" and a defined subroutine
1621 or "NULL". The glob lives in the given "stash", or in the
1622 stashes accessible via @ISA and UNIVERSAL::.
1623 The argument "level" should be either 0 or -1. If "level==0",
1625 as a side-effect creates a glob with the given "name" in the
1626 given "stash" which in the case of success contains an alias
1627 for the subroutine, and sets up caching info for this glob.
1628 Currently, the only significant value for "flags" is SVf_UTF8.
1630 This function grants "SUPER" token as a postfix of the stash
1632 name. The GV returned from "gv_fetchmeth" may be a method cache
1633 entry, which is not visible to Perl code. So when calling
1634 "call_sv", you should not use the GV directly; instead, you
1635 should use the method's CV, which can be obtained from the GV
1636 with the "GvCV" macro.
1637 GV* gv_fetchmeth_pvn(HV* stash, const char* name,
1639 STRLEN len, I32 level,
1640 U32 flags)
1641 gv_fetchmeth_pvn_autoload
1643 Same as gv_fetchmeth_pvn(), but looks for autoloaded
1644 subroutines too. Returns a glob for the subroutine.
1645 For an autoloaded subroutine without a GV, will create a GV
1647 even if "level < 0". For an autoloaded subroutine without a
1648 stub, GvCV() of the result may be zero.
1649 Currently, the only significant value for "flags" is SVf_UTF8.
1651 GV* gv_fetchmeth_pvn_autoload(HV* stash,
1653 const char* name,
1654 STRLEN len, I32 level,
1655 U32 flags)
1656 gv_fetchmeth_pv_autoload
1658 Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-
1659 terminated string instead of a string/length pair.
1660 GV* gv_fetchmeth_pv_autoload(HV* stash,
1662 const char* name,
1663 I32 level, U32 flags)
1664 gv_fetchmeth_sv
1666 Exactly like "gv_fetchmeth_pvn", but takes the name string in
1667 the form of an SV instead of a string/length pair.
1668 GV* gv_fetchmeth_sv(HV* stash, SV* namesv,
1670 I32 level, U32 flags)
1671 gv_fetchmeth_sv_autoload
1673 Exactly like "gv_fetchmeth_pvn_autoload", but takes the name
1674 string in the form of an SV instead of a string/length pair.
1675 GV* gv_fetchmeth_sv_autoload(HV* stash, SV* namesv,
1677 I32 level, U32 flags)
1678 gv_init The old form of gv_init_pvn(). It does not work with UTF8
1680 strings, as it has no flags parameter. If the "multi"
1681 parameter is set, the GV_ADDMULTI flag will be passed to
1682 gv_init_pvn().
1683 void gv_init(GV* gv, HV* stash, const char* name,
1685 STRLEN len, int multi)
1686 gv_init_pv
1688 Same as gv_init_pvn(), but takes a nul-terminated string for
1689 the name instead of separate char * and length parameters.
1690 void gv_init_pv(GV* gv, HV* stash, const char* name,
1692 U32 flags)
1693 gv_init_pvn
1695 Converts a scalar into a typeglob. This is an incoercible
1696 typeglob; assigning a reference to it will assign to one of its
1697 slots, instead of overwriting it as happens with typeglobs
1698 created by SvSetSV. Converting any scalar that is SvOK() may
1699 produce unpredictable results and is reserved for perl's
1700 internal use.
1701 "gv" is the scalar to be converted.
1703 "stash" is the parent stash/package, if any.
1705 "name" and "len" give the name. The name must be unqualified;
1707 that is, it must not include the package name. If "gv" is a
1708 stash element, it is the caller's responsibility to ensure that
1709 the name passed to this function matches the name of the
1710 element. If it does not match, perl's internal bookkeeping
1711 will get out of sync.
1712 "flags" can be set to SVf_UTF8 if "name" is a UTF8 string, or
1714 the return value of SvUTF8(sv). It can also take the
1715 GV_ADDMULTI flag, which means to pretend that the GV has been
1716 seen before (i.e., suppress "Used once" warnings).
1717 void gv_init_pvn(GV* gv, HV* stash, const char* name,
1719 STRLEN len, U32 flags)
1720 gv_init_sv
1722 Same as gv_init_pvn(), but takes an SV * for the name instead
1723 of separate char * and length parameters. "flags" is currently
1724 unused.
1725 void gv_init_sv(GV* gv, HV* stash, SV* namesv,
1727 U32 flags)
1728 gv_stashpv
1730 Returns a pointer to the stash for a specified package. Uses
1731 "strlen" to determine the length of "name", then calls
1732 "gv_stashpvn()".
1733 HV* gv_stashpv(const char* name, I32 flags)
1735 gv_stashpvn
1737 Returns a pointer to the stash for a specified package. The
1738 "namelen" parameter indicates the length of the "name", in
1739 bytes. "flags" is passed to "gv_fetchpvn_flags()", so if set
1740 to "GV_ADD" then the package will be created if it does not
1741 already exist. If the package does not exist and "flags" is 0
1742 (or any other setting that does not create packages) then NULL
1743 is returned.
1744 HV* gv_stashpvn(const char* name, U32 namelen,
1746 I32 flags)
1747 gv_stashpvs
1749 Like "gv_stashpvn", but takes a literal string instead of a
1750 string/length pair.
1751 HV* gv_stashpvs(const char* name, I32 create)
1753 gv_stashsv
1755 Returns a pointer to the stash for a specified package. See
1756 "gv_stashpvn".
1757 HV* gv_stashsv(SV* sv, I32 flags)
1759
1761 Nullav Null AV pointer.
1762 (deprecated - use "(AV *)NULL" instead)
1764 Nullch Null character pointer. (No longer available when "PERL_CORE"
1766 is defined.)
1767 Nullcv Null CV pointer.
1769 (deprecated - use "(CV *)NULL" instead)
1771 Nullhv Null HV pointer.
1773 (deprecated - use "(HV *)NULL" instead)
1775 Nullsv Null SV pointer. (No longer available when "PERL_CORE" is
1777 defined.)
1778
1780 cop_fetch_label
1781 Returns the label attached to a cop. The flags pointer may be
1782 set to "SVf_UTF8" or 0.
1783 NOTE: this function is experimental and may change or be
1785 removed without notice.
1786 const char * cop_fetch_label(COP *const cop,
1788 STRLEN *len, U32 *flags)
1789 cop_store_label
1791 Save a label into a "cop_hints_hash". You need to set flags to
1792 "SVf_UTF8" for a utf-8 label.
1793 NOTE: this function is experimental and may change or be
1795 removed without notice.
1796 void cop_store_label(COP *const cop,
1798 const char *label, STRLEN len,
1799 U32 flags)
1800 get_hv Returns the HV of the specified Perl hash. "flags" are passed
1802 to "gv_fetchpv". If "GV_ADD" is set and the Perl variable does
1803 not exist then it will be created. If "flags" is zero and the
1804 variable does not exist then NULL is returned.
1805 NOTE: the perl_ form of this function is deprecated.
1807 HV* get_hv(const char *name, I32 flags)
1809 HEf_SVKEY
1811 This flag, used in the length slot of hash entries and magic
1812 structures, specifies the structure contains an "SV*" pointer
1813 where a "char*" pointer is to be expected. (For information
1814 only--not to be used).
1815 HeHASH Returns the computed hash stored in the hash entry.
1817 U32 HeHASH(HE* he)
1819 HeKEY Returns the actual pointer stored in the key slot of the hash
1821 entry. The pointer may be either "char*" or "SV*", depending on
1822 the value of "HeKLEN()". Can be assigned to. The "HePV()" or
1823 "HeSVKEY()" macros are usually preferable for finding the value
1824 of a key.
1825 void* HeKEY(HE* he)
1827 HeKLEN If this is negative, and amounts to "HEf_SVKEY", it indicates
1829 the entry holds an "SV*" key. Otherwise, holds the actual
1830 length of the key. Can be assigned to. The "HePV()" macro is
1831 usually preferable for finding key lengths.
1832 STRLEN HeKLEN(HE* he)
1834 HePV Returns the key slot of the hash entry as a "char*" value,
1836 doing any necessary dereferencing of possibly "SV*" keys. The
1837 length of the string is placed in "len" (this is a macro, so do
1838 not use &len). If you do not care about what the length of the
1839 key is, you may use the global variable "PL_na", though this is
1840 rather less efficient than using a local variable. Remember
1841 though, that hash keys in perl are free to contain embedded
1842 nulls, so using "strlen()" or similar is not a good way to find
1843 the length of hash keys. This is very similar to the "SvPV()"
1844 macro described elsewhere in this document. See also "HeUTF8".
1845 If you are using "HePV" to get values to pass to "newSVpvn()"
1847 to create a new SV, you should consider using
1848 "newSVhek(HeKEY_hek(he))" as it is more efficient.
1849 char* HePV(HE* he, STRLEN len)
1851 HeSVKEY Returns the key as an "SV*", or "NULL" if the hash entry does
1853 not contain an "SV*" key.
1854 SV* HeSVKEY(HE* he)
1856 HeSVKEY_force
1858 Returns the key as an "SV*". Will create and return a
1859 temporary mortal "SV*" if the hash entry contains only a
1860 "char*" key.
1861 SV* HeSVKEY_force(HE* he)
1863 HeSVKEY_set
1865 Sets the key to a given "SV*", taking care to set the
1866 appropriate flags to indicate the presence of an "SV*" key, and
1867 returns the same "SV*".
1868 SV* HeSVKEY_set(HE* he, SV* sv)
1870 HeUTF8 Returns whether the "char *" value returned by "HePV" is
1872 encoded in UTF-8, doing any necessary dereferencing of possibly
1873 "SV*" keys. The value returned will be 0 or non-0, not
1874 necessarily 1 (or even a value with any low bits set), so do
1875 not blindly assign this to a "bool" variable, as "bool" may be
1876 a typedef for "char".
1877 char* HeUTF8(HE* he)
1879 HeVAL Returns the value slot (type "SV*") stored in the hash entry.
1881 SV* HeVAL(HE* he)
1883 HvENAME Returns the effective name of a stash, or NULL if there is
1885 none. The effective name represents a location in the symbol
1886 table where this stash resides. It is updated automatically
1887 when packages are aliased or deleted. A stash that is no
1888 longer in the symbol table has no effective name. This name is
1889 preferable to "HvNAME" for use in MRO linearisations and isa
1890 caches.
1891 char* HvENAME(HV* stash)
1893 HvENAMELEN
1895 Returns the length of the stash's effective name.
1896 STRLEN HvENAMELEN(HV *stash)
1898 HvENAMEUTF8
1900 Returns true if the effective name is in UTF8 encoding.
1901 unsigned char HvENAMEUTF8(HV *stash)
1903 HvNAME Returns the package name of a stash, or NULL if "stash" isn't a
1905 stash. See "SvSTASH", "CvSTASH".
1906 char* HvNAME(HV* stash)
1908 HvNAMELEN
1910 Returns the length of the stash's name.
1911 STRLEN HvNAMELEN(HV *stash)
1913 HvNAMEUTF8
1915 Returns true if the name is in UTF8 encoding.
1916 unsigned char HvNAMEUTF8(HV *stash)
1918 hv_assert
1920 Check that a hash is in an internally consistent state.
1921 void hv_assert(HV *hv)
1923 hv_clear
1925 Frees the all the elements of a hash, leaving it empty. The XS
1926 equivalent of "%hash = ()". See also "hv_undef".
1927 If any destructors are triggered as a result, the hv itself may
1929 be freed.
1930 void hv_clear(HV *hv)
1932 hv_clear_placeholders
1934 Clears any placeholders from a hash. If a restricted hash has
1935 any of its keys marked as readonly and the key is subsequently
1936 deleted, the key is not actually deleted but is marked by
1937 assigning it a value of &PL_sv_placeholder. This tags it so it
1938 will be ignored by future operations such as iterating over the
1939 hash, but will still allow the hash to have a value reassigned
1940 to the key at some future point. This function clears any such
1941 placeholder keys from the hash. See Hash::Util::lock_keys()
1942 for an example of its use.
1943 void hv_clear_placeholders(HV *hv)
1945 hv_copy_hints_hv
1947 A specialised version of "newHVhv" for copying "%^H". ohv must
1948 be a pointer to a hash (which may have "%^H" magic, but should
1949 be generally non-magical), or "NULL" (interpreted as an empty
1950 hash). The content of ohv is copied to a new hash, which has
1951 the "%^H"-specific magic added to it. A pointer to the new
1952 hash is returned.
1953 HV * hv_copy_hints_hv(HV *ohv)
1955 hv_delete
1957 Deletes a key/value pair in the hash. The value's SV is
1958 removed from the hash, made mortal, and returned to the caller.
1959 The absolute value of "klen" is the length of the key. If
1960 "klen" is negative the key is assumed to be in UTF-8-encoded
1961 Unicode. The "flags" value will normally be zero; if set to
1962 G_DISCARD then NULL will be returned. NULL will also be
1963 returned if the key is not found.
1964 SV* hv_delete(HV *hv, const char *key, I32 klen,
1966 I32 flags)
1967 hv_delete_ent
1969 Deletes a key/value pair in the hash. The value SV is removed
1970 from the hash, made mortal, and returned to the caller. The
1971 "flags" value will normally be zero; if set to G_DISCARD then
1972 NULL will be returned. NULL will also be returned if the key
1973 is not found. "hash" can be a valid precomputed hash value, or
1974 0 to ask for it to be computed.
1975 SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags,
1977 U32 hash)
1978 hv_exists
1980 Returns a boolean indicating whether the specified hash key
1981 exists. The absolute value of "klen" is the length of the key.
1982 If "klen" is negative the key is assumed to be in UTF-8-encoded
1983 Unicode.
1984 bool hv_exists(HV *hv, const char *key, I32 klen)
1986 hv_exists_ent
1988 Returns a boolean indicating whether the specified hash key
1989 exists. "hash" can be a valid precomputed hash value, or 0 to
1990 ask for it to be computed.
1991 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
1993 hv_fetch
1995 Returns the SV which corresponds to the specified key in the
1996 hash. The absolute value of "klen" is the length of the key.
1997 If "klen" is negative the key is assumed to be in UTF-8-encoded
1998 Unicode. If "lval" is set then the fetch will be part of a
1999 store. Check that the return value is non-null before
2000 dereferencing it to an "SV*".
2001 See "Understanding the Magic of Tied Hashes and Arrays" in
2003 perlguts for more information on how to use this function on
2004 tied hashes.
2005 SV** hv_fetch(HV *hv, const char *key, I32 klen,
2007 I32 lval)
2008 hv_fetchs
2010 Like "hv_fetch", but takes a literal string instead of a
2011 string/length pair.
2012 SV** hv_fetchs(HV* tb, const char* key, I32 lval)
2014 hv_fetch_ent
2016 Returns the hash entry which corresponds to the specified key
2017 in the hash. "hash" must be a valid precomputed hash number
2018 for the given "key", or 0 if you want the function to compute
2019 it. IF "lval" is set then the fetch will be part of a store.
2020 Make sure the return value is non-null before accessing it.
2021 The return value when "hv" is a tied hash is a pointer to a
2022 static location, so be sure to make a copy of the structure if
2023 you need to store it somewhere.
2024 See "Understanding the Magic of Tied Hashes and Arrays" in
2026 perlguts for more information on how to use this function on
2027 tied hashes.
2028 HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval,
2030 U32 hash)
2031 hv_fill Returns the number of hash buckets that happen to be in use.
2033 This function is wrapped by the macro "HvFILL".
2034 Previously this value was stored in the HV structure, rather
2036 than being calculated on demand.
2037 STRLEN hv_fill(HV const *const hv)
2039 hv_iterinit
2041 Prepares a starting point to traverse a hash table. Returns
2042 the number of keys in the hash (i.e. the same as
2043 "HvUSEDKEYS(hv)"). The return value is currently only
2044 meaningful for hashes without tie magic.
2045 NOTE: Before version 5.004_65, "hv_iterinit" used to return the
2047 number of hash buckets that happen to be in use. If you still
2048 need that esoteric value, you can get it through the macro
2049 "HvFILL(hv)".
2050 I32 hv_iterinit(HV *hv)
2052 hv_iterkey
2054 Returns the key from the current position of the hash iterator.
2055 See "hv_iterinit".
2056 char* hv_iterkey(HE* entry, I32* retlen)
2058 hv_iterkeysv
2060 Returns the key as an "SV*" from the current position of the
2061 hash iterator. The return value will always be a mortal copy
2062 of the key. Also see "hv_iterinit".
2063 SV* hv_iterkeysv(HE* entry)
2065 hv_iternext
2067 Returns entries from a hash iterator. See "hv_iterinit".
2068 You may call "hv_delete" or "hv_delete_ent" on the hash entry
2070 that the iterator currently points to, without losing your
2071 place or invalidating your iterator. Note that in this case
2072 the current entry is deleted from the hash with your iterator
2073 holding the last reference to it. Your iterator is flagged to
2074 free the entry on the next call to "hv_iternext", so you must
2075 not discard your iterator immediately else the entry will leak
2076 - call "hv_iternext" to trigger the resource deallocation.
2077 HE* hv_iternext(HV *hv)
2079 hv_iternextsv
2081 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in
2082 one operation.
2083 SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
2085 hv_iternext_flags
2087 Returns entries from a hash iterator. See "hv_iterinit" and
2088 "hv_iternext". The "flags" value will normally be zero; if
2089 HV_ITERNEXT_WANTPLACEHOLDERS is set the placeholders keys (for
2090 restricted hashes) will be returned in addition to normal keys.
2091 By default placeholders are automatically skipped over.
2092 Currently a placeholder is implemented with a value that is
2093 &PL_sv_placeholder. Note that the implementation of
2094 placeholders and restricted hashes may change, and the
2095 implementation currently is insufficiently abstracted for any
2096 change to be tidy.
2097 NOTE: this function is experimental and may change or be
2099 removed without notice.
2100 HE* hv_iternext_flags(HV *hv, I32 flags)
2102 hv_iterval
2104 Returns the value from the current position of the hash
2105 iterator. See "hv_iterkey".
2106 SV* hv_iterval(HV *hv, HE *entry)
2108 hv_magic
2110 Adds magic to a hash. See "sv_magic".
2111 void hv_magic(HV *hv, GV *gv, int how)
2113 hv_scalar
2115 Evaluates the hash in scalar context and returns the result.
2116 Handles magic when the hash is tied.
2117 SV* hv_scalar(HV *hv)
2119 hv_store
2121 Stores an SV in a hash. The hash key is specified as "key" and
2122 the absolute value of "klen" is the length of the key. If
2123 "klen" is negative the key is assumed to be in UTF-8-encoded
2124 Unicode. The "hash" parameter is the precomputed hash value;
2125 if it is zero then Perl will compute it.
2126 The return value will be NULL if the operation failed or if the
2128 value did not need to be actually stored within the hash (as in
2129 the case of tied hashes). Otherwise it can be dereferenced to
2130 get the original "SV*". Note that the caller is responsible
2131 for suitably incrementing the reference count of "val" before
2132 the call, and decrementing it if the function returned NULL.
2133 Effectively a successful hv_store takes ownership of one
2134 reference to "val". This is usually what you want; a newly
2135 created SV has a reference count of one, so if all your code
2136 does is create SVs then store them in a hash, hv_store will own
2137 the only reference to the new SV, and your code doesn't need to
2138 do anything further to tidy up. hv_store is not implemented as
2139 a call to hv_store_ent, and does not create a temporary SV for
2140 the key, so if your key data is not already in SV form then use
2141 hv_store in preference to hv_store_ent.
2142 See "Understanding the Magic of Tied Hashes and Arrays" in
2144 perlguts for more information on how to use this function on
2145 tied hashes.
2146 SV** hv_store(HV *hv, const char *key, I32 klen,
2148 SV *val, U32 hash)
2149 hv_stores
2151 Like "hv_store", but takes a literal string instead of a
2152 string/length pair and omits the hash parameter.
2153 SV** hv_stores(HV* tb, const char* key,
2155 NULLOK SV* val)
2156 hv_store_ent
2158 Stores "val" in a hash. The hash key is specified as "key".
2159 The "hash" parameter is the precomputed hash value; if it is
2160 zero then Perl will compute it. The return value is the new
2161 hash entry so created. It will be NULL if the operation failed
2162 or if the value did not need to be actually stored within the
2163 hash (as in the case of tied hashes). Otherwise the contents
2164 of the return value can be accessed using the "He?" macros
2165 described here. Note that the caller is responsible for
2166 suitably incrementing the reference count of "val" before the
2167 call, and decrementing it if the function returned NULL.
2168 Effectively a successful hv_store_ent takes ownership of one
2169 reference to "val". This is usually what you want; a newly
2170 created SV has a reference count of one, so if all your code
2171 does is create SVs then store them in a hash, hv_store will own
2172 the only reference to the new SV, and your code doesn't need to
2173 do anything further to tidy up. Note that hv_store_ent only
2174 reads the "key"; unlike "val" it does not take ownership of it,
2175 so maintaining the correct reference count on "key" is entirely
2176 the caller's responsibility. hv_store is not implemented as a
2177 call to hv_store_ent, and does not create a temporary SV for
2178 the key, so if your key data is not already in SV form then use
2179 hv_store in preference to hv_store_ent.
2180 See "Understanding the Magic of Tied Hashes and Arrays" in
2182 perlguts for more information on how to use this function on
2183 tied hashes.
2184 HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
2186 hv_undef
2188 Undefines the hash. The XS equivalent of "undef(%hash)".
2189 As well as freeing all the elements of the hash (like
2191 hv_clear()), this also frees any auxiliary data and storage
2192 associated with the hash.
2193 If any destructors are triggered as a result, the hv itself may
2195 be freed.
2196 See also "hv_clear".
2198 void hv_undef(HV *hv)
2200 newHV Creates a new HV. The reference count is set to 1.
2202 HV* newHV()
2204
2206 wrap_op_checker
2207 Puts a C function into the chain of check functions for a
2208 specified op type. This is the preferred way to manipulate the
2209 "PL_check" array. opcode specifies which type of op is to be
2210 affected. new_checker is a pointer to the C function that is
2211 to be added to that opcode's check chain, and old_checker_p
2212 points to the storage location where a pointer to the next
2213 function in the chain will be stored. The value of new_pointer
2214 is written into the "PL_check" array, while the value
2215 previously stored there is written to *old_checker_p.
2216 "PL_check" is global to an entire process, and a module wishing
2218 to hook op checking may find itself invoked more than once per
2219 process, typically in different threads. To handle that
2220 situation, this function is idempotent. The location
2221 *old_checker_p must initially (once per process) contain a null
2222 pointer. A C variable of static duration (declared at file
2223 scope, typically also marked "static" to give it internal
2224 linkage) will be implicitly initialised appropriately, if it
2225 does not have an explicit initialiser. This function will only
2226 actually modify the check chain if it finds *old_checker_p to
2227 be null. This function is also thread safe on the small scale.
2228 It uses appropriate locking to avoid race conditions in
2229 accessing "PL_check".
2230 When this function is called, the function referenced by
2232 new_checker must be ready to be called, except for
2233 *old_checker_p being unfilled. In a threading situation,
2234 new_checker may be called immediately, even before this
2235 function has returned. *old_checker_p will always be
2236 appropriately set before new_checker is called. If new_checker
2237 decides not to do anything special with an op that it is given
2238 (which is the usual case for most uses of op check hooking), it
2239 must chain the check function referenced by *old_checker_p.
2240 If you want to influence compilation of calls to a specific
2242 subroutine, then use "cv_set_call_checker" rather than hooking
2243 checking of all "entersub" ops.
2244 void wrap_op_checker(Optype opcode,
2246 Perl_check_t new_checker,
2247 Perl_check_t *old_checker_p)
2248
2250 lex_bufutf8
2251 Indicates whether the octets in the lexer buffer
2252 ("PL_parser->linestr") should be interpreted as the UTF-8
2253 encoding of Unicode characters. If not, they should be
2254 interpreted as Latin-1 characters. This is analogous to the
2255 "SvUTF8" flag for scalars.
2256 In UTF-8 mode, it is not guaranteed that the lexer buffer
2258 actually contains valid UTF-8. Lexing code must be robust in
2259 the face of invalid encoding.
2260 The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
2262 significant, but not the whole story regarding the input
2263 character encoding. Normally, when a file is being read, the
2264 scalar contains octets and its "SvUTF8" flag is off, but the
2265 octets should be interpreted as UTF-8 if the "use utf8" pragma
2266 is in effect. During a string eval, however, the scalar may
2267 have the "SvUTF8" flag on, and in this case its octets should
2268 be interpreted as UTF-8 unless the "use bytes" pragma is in
2269 effect. This logic may change in the future; use this function
2270 instead of implementing the logic yourself.
2271 NOTE: this function is experimental and may change or be
2273 removed without notice.
2274 bool lex_bufutf8()
2276 lex_discard_to
2278 Discards the first part of the "PL_parser->linestr" buffer, up
2279 to ptr. The remaining content of the buffer will be moved, and
2280 all pointers into the buffer updated appropriately. ptr must
2281 not be later in the buffer than the position of
2282 "PL_parser->bufptr": it is not permitted to discard text that
2283 has yet to be lexed.
2284 Normally it is not necessarily to do this directly, because it
2286 suffices to use the implicit discarding behaviour of
2287 "lex_next_chunk" and things based on it. However, if a token
2288 stretches across multiple lines, and the lexing code has kept
2289 multiple lines of text in the buffer for that purpose, then
2290 after completion of the token it would be wise to explicitly
2291 discard the now-unneeded earlier lines, to avoid future multi-
2292 line tokens growing the buffer without bound.
2293 NOTE: this function is experimental and may change or be
2295 removed without notice.
2296 void lex_discard_to(char *ptr)
2298 lex_grow_linestr
2300 Reallocates the lexer buffer ("PL_parser->linestr") to
2301 accommodate at least len octets (including terminating NUL).
2302 Returns a pointer to the reallocated buffer. This is necessary
2303 before making any direct modification of the buffer that would
2304 increase its length. "lex_stuff_pvn" provides a more
2305 convenient way to insert text into the buffer.
2306 Do not use "SvGROW" or "sv_grow" directly on
2308 "PL_parser->linestr"; this function updates all of the lexer's
2309 variables that point directly into the buffer.
2310 NOTE: this function is experimental and may change or be
2312 removed without notice.
2313 char * lex_grow_linestr(STRLEN len)
2315 lex_next_chunk
2317 Reads in the next chunk of text to be lexed, appending it to
2318 "PL_parser->linestr". This should be called when lexing code
2319 has looked to the end of the current chunk and wants to know
2320 more. It is usual, but not necessary, for lexing to have
2321 consumed the entirety of the current chunk at this time.
2322 If "PL_parser->bufptr" is pointing to the very end of the
2324 current chunk (i.e., the current chunk has been entirely
2325 consumed), normally the current chunk will be discarded at the
2326 same time that the new chunk is read in. If flags includes
2327 "LEX_KEEP_PREVIOUS", the current chunk will not be discarded.
2328 If the current chunk has not been entirely consumed, then it
2329 will not be discarded regardless of the flag.
2330 Returns true if some new text was added to the buffer, or false
2332 if the buffer has reached the end of the input text.
2333 NOTE: this function is experimental and may change or be
2335 removed without notice.
2336 bool lex_next_chunk(U32 flags)
2338 lex_peek_unichar
2340 Looks ahead one (Unicode) character in the text currently being
2341 lexed. Returns the codepoint (unsigned integer value) of the
2342 next character, or -1 if lexing has reached the end of the
2343 input text. To consume the peeked character, use
2344 "lex_read_unichar".
2345 If the next character is in (or extends into) the next chunk of
2347 input text, the next chunk will be read in. Normally the
2348 current chunk will be discarded at the same time, but if flags
2349 includes "LEX_KEEP_PREVIOUS" then the current chunk will not be
2350 discarded.
2351 If the input is being interpreted as UTF-8 and a UTF-8 encoding
2353 error is encountered, an exception is generated.
2354 NOTE: this function is experimental and may change or be
2356 removed without notice.
2357 I32 lex_peek_unichar(U32 flags)
2359 lex_read_space
2361 Reads optional spaces, in Perl style, in the text currently
2362 being lexed. The spaces may include ordinary whitespace
2363 characters and Perl-style comments. "#line" directives are
2364 processed if encountered. "PL_parser->bufptr" is moved past
2365 the spaces, so that it points at a non-space character (or the
2366 end of the input text).
2367 If spaces extend into the next chunk of input text, the next
2369 chunk will be read in. Normally the current chunk will be
2370 discarded at the same time, but if flags includes
2371 "LEX_KEEP_PREVIOUS" then the current chunk will not be
2372 discarded.
2373 NOTE: this function is experimental and may change or be
2375 removed without notice.
2376 void lex_read_space(U32 flags)
2378 lex_read_to
2380 Consume text in the lexer buffer, from "PL_parser->bufptr" up
2381 to ptr. This advances "PL_parser->bufptr" to match ptr,
2382 performing the correct bookkeeping whenever a newline character
2383 is passed. This is the normal way to consume lexed text.
2384 Interpretation of the buffer's octets can be abstracted out by
2386 using the slightly higher-level functions "lex_peek_unichar"
2387 and "lex_read_unichar".
2388 NOTE: this function is experimental and may change or be
2390 removed without notice.
2391 void lex_read_to(char *ptr)
2393 lex_read_unichar
2395 Reads the next (Unicode) character in the text currently being
2396 lexed. Returns the codepoint (unsigned integer value) of the
2397 character read, and moves "PL_parser->bufptr" past the
2398 character, or returns -1 if lexing has reached the end of the
2399 input text. To non-destructively examine the next character,
2400 use "lex_peek_unichar" instead.
2401 If the next character is in (or extends into) the next chunk of
2403 input text, the next chunk will be read in. Normally the
2404 current chunk will be discarded at the same time, but if flags
2405 includes "LEX_KEEP_PREVIOUS" then the current chunk will not be
2406 discarded.
2407 If the input is being interpreted as UTF-8 and a UTF-8 encoding
2409 error is encountered, an exception is generated.
2410 NOTE: this function is experimental and may change or be
2412 removed without notice.
2413 I32 lex_read_unichar(U32 flags)
2415 lex_start
2417 Creates and initialises a new lexer/parser state object,
2418 supplying a context in which to lex and parse from a new source
2419 of Perl code. A pointer to the new state object is placed in
2420 "PL_parser". An entry is made on the save stack so that upon
2421 unwinding the new state object will be destroyed and the former
2422 value of "PL_parser" will be restored. Nothing else need be
2423 done to clean up the parsing context.
2424 The code to be parsed comes from line and rsfp. line, if non-
2426 null, provides a string (in SV form) containing code to be
2427 parsed. A copy of the string is made, so subsequent
2428 modification of line does not affect parsing. rsfp, if non-
2429 null, provides an input stream from which code will be read to
2430 be parsed. If both are non-null, the code in line comes first
2431 and must consist of complete lines of input, and rsfp supplies
2432 the remainder of the source.
2433 The flags parameter is reserved for future use. Currently it
2435 is only used by perl internally, so extensions should always
2436 pass zero.
2437 NOTE: this function is experimental and may change or be
2439 removed without notice.
2440 void lex_start(SV *line, PerlIO *rsfp, U32 flags)
2442 lex_stuff_pv
2444 Insert characters into the lexer buffer ("PL_parser->linestr"),
2445 immediately after the current lexing point
2446 ("PL_parser->bufptr"), reallocating the buffer if necessary.
2447 This means that lexing code that runs later will see the
2448 characters as if they had appeared in the input. It is not
2449 recommended to do this as part of normal parsing, and most uses
2450 of this facility run the risk of the inserted characters being
2451 interpreted in an unintended manner.
2452 The string to be inserted is represented by octets starting at
2454 pv and continuing to the first nul. These octets are
2455 interpreted as either UTF-8 or Latin-1, according to whether
2456 the "LEX_STUFF_UTF8" flag is set in flags. The characters are
2457 recoded for the lexer buffer, according to how the buffer is
2458 currently being interpreted ("lex_bufutf8"). If it is not
2459 convenient to nul-terminate a string to be inserted, the
2460 "lex_stuff_pvn" function is more appropriate.
2461 NOTE: this function is experimental and may change or be
2463 removed without notice.
2464 void lex_stuff_pv(const char *pv, U32 flags)
2466 lex_stuff_pvn
2468 Insert characters into the lexer buffer ("PL_parser->linestr"),
2469 immediately after the current lexing point
2470 ("PL_parser->bufptr"), reallocating the buffer if necessary.
2471 This means that lexing code that runs later will see the
2472 characters as if they had appeared in the input. It is not
2473 recommended to do this as part of normal parsing, and most uses
2474 of this facility run the risk of the inserted characters being
2475 interpreted in an unintended manner.
2476 The string to be inserted is represented by len octets starting
2478 at pv. These octets are interpreted as either UTF-8 or
2479 Latin-1, according to whether the "LEX_STUFF_UTF8" flag is set
2480 in flags. The characters are recoded for the lexer buffer,
2481 according to how the buffer is currently being interpreted
2482 ("lex_bufutf8"). If a string to be inserted is available as a
2483 Perl scalar, the "lex_stuff_sv" function is more convenient.
2484 NOTE: this function is experimental and may change or be
2486 removed without notice.
2487 void lex_stuff_pvn(const char *pv, STRLEN len,
2489 U32 flags)
2490 lex_stuff_pvs
2492 Like "lex_stuff_pvn", but takes a literal string instead of a
2493 string/length pair.
2494 NOTE: this function is experimental and may change or be
2496 removed without notice.
2497 void lex_stuff_pvs(const char *pv, U32 flags)
2499 lex_stuff_sv
2501 Insert characters into the lexer buffer ("PL_parser->linestr"),
2502 immediately after the current lexing point
2503 ("PL_parser->bufptr"), reallocating the buffer if necessary.
2504 This means that lexing code that runs later will see the
2505 characters as if they had appeared in the input. It is not
2506 recommended to do this as part of normal parsing, and most uses
2507 of this facility run the risk of the inserted characters being
2508 interpreted in an unintended manner.
2509 The string to be inserted is the string value of sv. The
2511 characters are recoded for the lexer buffer, according to how
2512 the buffer is currently being interpreted ("lex_bufutf8"). If
2513 a string to be inserted is not already a Perl scalar, the
2514 "lex_stuff_pvn" function avoids the need to construct a scalar.
2515 NOTE: this function is experimental and may change or be
2517 removed without notice.
2518 void lex_stuff_sv(SV *sv, U32 flags)
2520 lex_unstuff
2522 Discards text about to be lexed, from "PL_parser->bufptr" up to
2523 ptr. Text following ptr will be moved, and the buffer
2524 shortened. This hides the discarded text from any lexing code
2525 that runs later, as if the text had never appeared.
2526 This is not the normal way to consume lexed text. For that,
2528 use "lex_read_to".
2529 NOTE: this function is experimental and may change or be
2531 removed without notice.
2532 void lex_unstuff(char *ptr)
2534 parse_arithexpr
2536 Parse a Perl arithmetic expression. This may contain operators
2537 of precedence down to the bit shift operators. The expression
2538 must be followed (and thus terminated) either by a comparison
2539 or lower-precedence operator or by something that would
2540 normally terminate an expression such as semicolon. If flags
2541 includes "PARSE_OPTIONAL" then the expression is optional,
2542 otherwise it is mandatory. It is up to the caller to ensure
2543 that the dynamic parser state ("PL_parser" et al) is correctly
2544 set to reflect the source of the code to be parsed and the
2545 lexical context for the expression.
2546 The op tree representing the expression is returned. If an
2548 optional expression is absent, a null pointer is returned,
2549 otherwise the pointer will be non-null.
2550 If an error occurs in parsing or compilation, in most cases a
2552 valid op tree is returned anyway. The error is reflected in
2553 the parser state, normally resulting in a single exception at
2554 the top level of parsing which covers all the compilation
2555 errors that occurred. Some compilation errors, however, will
2556 throw an exception immediately.
2557 NOTE: this function is experimental and may change or be
2559 removed without notice.
2560 OP * parse_arithexpr(U32 flags)
2562 parse_barestmt
2564 Parse a single unadorned Perl statement. This may be a normal
2565 imperative statement or a declaration that has compile-time
2566 effect. It does not include any label or other affixture. It
2567 is up to the caller to ensure that the dynamic parser state
2568 ("PL_parser" et al) is correctly set to reflect the source of
2569 the code to be parsed and the lexical context for the
2570 statement.
2571 The op tree representing the statement is returned. This may
2573 be a null pointer if the statement is null, for example if it
2574 was actually a subroutine definition (which has compile-time
2575 side effects). If not null, it will be ops directly
2576 implementing the statement, suitable to pass to "newSTATEOP".
2577 It will not normally include a "nextstate" or equivalent op
2578 (except for those embedded in a scope contained entirely within
2579 the statement).
2580 If an error occurs in parsing or compilation, in most cases a
2582 valid op tree (most likely null) is returned anyway. The error
2583 is reflected in the parser state, normally resulting in a
2584 single exception at the top level of parsing which covers all
2585 the compilation errors that occurred. Some compilation errors,
2586 however, will throw an exception immediately.
2587 The flags parameter is reserved for future use, and must always
2589 be zero.
2590 NOTE: this function is experimental and may change or be
2592 removed without notice.
2593 OP * parse_barestmt(U32 flags)
2595 parse_block
2597 Parse a single complete Perl code block. This consists of an
2598 opening brace, a sequence of statements, and a closing brace.
2599 The block constitutes a lexical scope, so "my" variables and
2600 various compile-time effects can be contained within it. It is
2601 up to the caller to ensure that the dynamic parser state
2602 ("PL_parser" et al) is correctly set to reflect the source of
2603 the code to be parsed and the lexical context for the
2604 statement.
2605 The op tree representing the code block is returned. This is
2607 always a real op, never a null pointer. It will normally be a
2608 "lineseq" list, including "nextstate" or equivalent ops. No
2609 ops to construct any kind of runtime scope are included by
2610 virtue of it being a block.
2611 If an error occurs in parsing or compilation, in most cases a
2613 valid op tree (most likely null) is returned anyway. The error
2614 is reflected in the parser state, normally resulting in a
2615 single exception at the top level of parsing which covers all
2616 the compilation errors that occurred. Some compilation errors,
2617 however, will throw an exception immediately.
2618 The flags parameter is reserved for future use, and must always
2620 be zero.
2621 NOTE: this function is experimental and may change or be
2623 removed without notice.
2624 OP * parse_block(U32 flags)
2626 parse_fullexpr
2628 Parse a single complete Perl expression. This allows the full
2629 expression grammar, including the lowest-precedence operators
2630 such as "or". The expression must be followed (and thus
2631 terminated) by a token that an expression would normally be
2632 terminated by: end-of-file, closing bracketing punctuation,
2633 semicolon, or one of the keywords that signals a postfix
2634 expression-statement modifier. If flags includes
2635 "PARSE_OPTIONAL" then the expression is optional, otherwise it
2636 is mandatory. It is up to the caller to ensure that the
2637 dynamic parser state ("PL_parser" et al) is correctly set to
2638 reflect the source of the code to be parsed and the lexical
2639 context for the expression.
2640 The op tree representing the expression is returned. If an
2642 optional expression is absent, a null pointer is returned,
2643 otherwise the pointer will be non-null.
2644 If an error occurs in parsing or compilation, in most cases a
2646 valid op tree is returned anyway. The error is reflected in
2647 the parser state, normally resulting in a single exception at
2648 the top level of parsing which covers all the compilation
2649 errors that occurred. Some compilation errors, however, will
2650 throw an exception immediately.
2651 NOTE: this function is experimental and may change or be
2653 removed without notice.
2654 OP * parse_fullexpr(U32 flags)
2656 parse_fullstmt
2658 Parse a single complete Perl statement. This may be a normal
2659 imperative statement or a declaration that has compile-time
2660 effect, and may include optional labels. It is up to the
2661 caller to ensure that the dynamic parser state ("PL_parser" et
2662 al) is correctly set to reflect the source of the code to be
2663 parsed and the lexical context for the statement.
2664 The op tree representing the statement is returned. This may
2666 be a null pointer if the statement is null, for example if it
2667 was actually a subroutine definition (which has compile-time
2668 side effects). If not null, it will be the result of a
2669 "newSTATEOP" call, normally including a "nextstate" or
2670 equivalent op.
2671 If an error occurs in parsing or compilation, in most cases a
2673 valid op tree (most likely null) is returned anyway. The error
2674 is reflected in the parser state, normally resulting in a
2675 single exception at the top level of parsing which covers all
2676 the compilation errors that occurred. Some compilation errors,
2677 however, will throw an exception immediately.
2678 The flags parameter is reserved for future use, and must always
2680 be zero.
2681 NOTE: this function is experimental and may change or be
2683 removed without notice.
2684 OP * parse_fullstmt(U32 flags)
2686 parse_label
2688 Parse a single label, possibly optional, of the type that may
2689 prefix a Perl statement. It is up to the caller to ensure that
2690 the dynamic parser state ("PL_parser" et al) is correctly set
2691 to reflect the source of the code to be parsed. If flags
2692 includes "PARSE_OPTIONAL" then the label is optional, otherwise
2693 it is mandatory.
2694 The name of the label is returned in the form of a fresh
2696 scalar. If an optional label is absent, a null pointer is
2697 returned.
2698 If an error occurs in parsing, which can only occur if the
2700 label is mandatory, a valid label is returned anyway. The
2701 error is reflected in the parser state, normally resulting in a
2702 single exception at the top level of parsing which covers all
2703 the compilation errors that occurred.
2704 NOTE: this function is experimental and may change or be
2706 removed without notice.
2707 SV * parse_label(U32 flags)
2709 parse_listexpr
2711 Parse a Perl list expression. This may contain operators of
2712 precedence down to the comma operator. The expression must be
2713 followed (and thus terminated) either by a low-precedence logic
2714 operator such as "or" or by something that would normally
2715 terminate an expression such as semicolon. If flags includes
2716 "PARSE_OPTIONAL" then the expression is optional, otherwise it
2717 is mandatory. It is up to the caller to ensure that the
2718 dynamic parser state ("PL_parser" et al) is correctly set to
2719 reflect the source of the code to be parsed and the lexical
2720 context for the expression.
2721 The op tree representing the expression is returned. If an
2723 optional expression is absent, a null pointer is returned,
2724 otherwise the pointer will be non-null.
2725 If an error occurs in parsing or compilation, in most cases a
2727 valid op tree is returned anyway. The error is reflected in
2728 the parser state, normally resulting in a single exception at
2729 the top level of parsing which covers all the compilation
2730 errors that occurred. Some compilation errors, however, will
2731 throw an exception immediately.
2732 NOTE: this function is experimental and may change or be
2734 removed without notice.
2735 OP * parse_listexpr(U32 flags)
2737 parse_stmtseq
2739 Parse a sequence of zero or more Perl statements. These may be
2740 normal imperative statements, including optional labels, or
2741 declarations that have compile-time effect, or any mixture
2742 thereof. The statement sequence ends when a closing brace or
2743 end-of-file is encountered in a place where a new statement
2744 could have validly started. It is up to the caller to ensure
2745 that the dynamic parser state ("PL_parser" et al) is correctly
2746 set to reflect the source of the code to be parsed and the
2747 lexical context for the statements.
2748 The op tree representing the statement sequence is returned.
2750 This may be a null pointer if the statements were all null, for
2751 example if there were no statements or if there were only
2752 subroutine definitions (which have compile-time side effects).
2753 If not null, it will be a "lineseq" list, normally including
2754 "nextstate" or equivalent ops.
2755 If an error occurs in parsing or compilation, in most cases a
2757 valid op tree is returned anyway. The error is reflected in
2758 the parser state, normally resulting in a single exception at
2759 the top level of parsing which covers all the compilation
2760 errors that occurred. Some compilation errors, however, will
2761 throw an exception immediately.
2762 The flags parameter is reserved for future use, and must always
2764 be zero.
2765 NOTE: this function is experimental and may change or be
2767 removed without notice.
2768 OP * parse_stmtseq(U32 flags)
2770 parse_termexpr
2772 Parse a Perl term expression. This may contain operators of
2773 precedence down to the assignment operators. The expression
2774 must be followed (and thus terminated) either by a comma or
2775 lower-precedence operator or by something that would normally
2776 terminate an expression such as semicolon. If flags includes
2777 "PARSE_OPTIONAL" then the expression is optional, otherwise it
2778 is mandatory. It is up to the caller to ensure that the
2779 dynamic parser state ("PL_parser" et al) is correctly set to
2780 reflect the source of the code to be parsed and the lexical
2781 context for the expression.
2782 The op tree representing the expression is returned. If an
2784 optional expression is absent, a null pointer is returned,
2785 otherwise the pointer will be non-null.
2786 If an error occurs in parsing or compilation, in most cases a
2788 valid op tree is returned anyway. The error is reflected in
2789 the parser state, normally resulting in a single exception at
2790 the top level of parsing which covers all the compilation
2791 errors that occurred. Some compilation errors, however, will
2792 throw an exception immediately.
2793 NOTE: this function is experimental and may change or be
2795 removed without notice.
2796 OP * parse_termexpr(U32 flags)
2798 PL_parser
2800 Pointer to a structure encapsulating the state of the parsing
2801 operation currently in progress. The pointer can be locally
2802 changed to perform a nested parse without interfering with the
2803 state of an outer parse. Individual members of "PL_parser"
2804 have their own documentation.
2805 PL_parser->bufend
2807 Direct pointer to the end of the chunk of text currently being
2808 lexed, the end of the lexer buffer. This is equal to
2809 "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)". A NUL
2810 character (zero octet) is always located at the end of the
2811 buffer, and does not count as part of the buffer's contents.
2812 NOTE: this function is experimental and may change or be
2814 removed without notice.
2815 PL_parser->bufptr
2817 Points to the current position of lexing inside the lexer
2818 buffer. Characters around this point may be freely examined,
2819 within the range delimited by "SvPVX("PL_parser->linestr")" and
2820 "PL_parser->bufend". The octets of the buffer may be intended
2821 to be interpreted as either UTF-8 or Latin-1, as indicated by
2822 "lex_bufutf8".
2823 Lexing code (whether in the Perl core or not) moves this
2825 pointer past the characters that it consumes. It is also
2826 expected to perform some bookkeeping whenever a newline
2827 character is consumed. This movement can be more conveniently
2828 performed by the function "lex_read_to", which handles newlines
2829 appropriately.
2830 Interpretation of the buffer's octets can be abstracted out by
2832 using the slightly higher-level functions "lex_peek_unichar"
2833 and "lex_read_unichar".
2834 NOTE: this function is experimental and may change or be
2836 removed without notice.
2837 PL_parser->linestart
2839 Points to the start of the current line inside the lexer
2840 buffer. This is useful for indicating at which column an error
2841 occurred, and not much else. This must be updated by any
2842 lexing code that consumes a newline; the function "lex_read_to"
2843 handles this detail.
2844 NOTE: this function is experimental and may change or be
2846 removed without notice.
2847 PL_parser->linestr
2849 Buffer scalar containing the chunk currently under
2850 consideration of the text currently being lexed. This is
2851 always a plain string scalar (for which "SvPOK" is true). It
2852 is not intended to be used as a scalar by normal scalar means;
2853 instead refer to the buffer directly by the pointer variables
2854 described below.
2855 The lexer maintains various "char*" pointers to things in the
2857 "PL_parser->linestr" buffer. If "PL_parser->linestr" is ever
2858 reallocated, all of these pointers must be updated. Don't
2859 attempt to do this manually, but rather use "lex_grow_linestr"
2860 if you need to reallocate the buffer.
2861 The content of the text chunk in the buffer is commonly exactly
2863 one complete line of input, up to and including a newline
2864 terminator, but there are situations where it is otherwise.
2865 The octets of the buffer may be intended to be interpreted as
2866 either UTF-8 or Latin-1. The function "lex_bufutf8" tells you
2867 which. Do not use the "SvUTF8" flag on this scalar, which may
2868 disagree with it.
2869 For direct examination of the buffer, the variable
2871 "PL_parser->bufend" points to the end of the buffer. The
2872 current lexing position is pointed to by "PL_parser->bufptr".
2873 Direct use of these pointers is usually preferable to
2874 examination of the scalar through normal scalar means.
2875 NOTE: this function is experimental and may change or be
2877 removed without notice.
2878
2880 mg_clear
2881 Clear something magical that the SV represents. See
2882 "sv_magic".
2883 int mg_clear(SV* sv)
2885 mg_copy Copies the magic from one SV to another. See "sv_magic".
2887 int mg_copy(SV *sv, SV *nsv, const char *key,
2889 I32 klen)
2890 mg_find Finds the magic pointer for type matching the SV. See
2892 "sv_magic".
2893 MAGIC* mg_find(const SV* sv, int type)
2895 mg_findext
2897 Finds the magic pointer of "type" with the given "vtbl" for the
2898 "SV". See "sv_magicext".
2899 MAGIC* mg_findext(const SV* sv, int type,
2901 const MGVTBL *vtbl)
2902 mg_free Free any magic storage used by the SV. See "sv_magic".
2904 int mg_free(SV* sv)
2906 mg_free_type
2908 Remove any magic of type how from the SV sv. See "sv_magic".
2909 void mg_free_type(SV *sv, int how)
2911 mg_get Do magic before a value is retrieved from the SV. See
2913 "sv_magic".
2914 int mg_get(SV* sv)
2916 mg_length
2918 Report on the SV's length. See "sv_magic".
2919 U32 mg_length(SV* sv)
2921 mg_magical
2923 Turns on the magical status of an SV. See "sv_magic".
2924 void mg_magical(SV* sv)
2926 mg_set Do magic after a value is assigned to the SV. See "sv_magic".
2928 int mg_set(SV* sv)
2930 SvGETMAGIC
2932 Invokes "mg_get" on an SV if it has 'get' magic. This macro
2933 evaluates its argument more than once.
2934 void SvGETMAGIC(SV* sv)
2936 SvLOCK Arranges for a mutual exclusion lock to be obtained on sv if a
2938 suitable module has been loaded.
2939 void SvLOCK(SV* sv)
2941 SvSETMAGIC
2943 Invokes "mg_set" on an SV if it has 'set' magic. This macro
2944 evaluates its argument more than once.
2945 void SvSETMAGIC(SV* sv)
2947 SvSetMagicSV
2949 Like "SvSetSV", but does any set magic required afterwards.
2950 void SvSetMagicSV(SV* dsb, SV* ssv)
2952 SvSetMagicSV_nosteal
2954 Like "SvSetSV_nosteal", but does any set magic required
2955 afterwards.
2956 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
2958 SvSetSV Calls "sv_setsv" if dsv is not the same as ssv. May evaluate
2960 arguments more than once.
2961 void SvSetSV(SV* dsb, SV* ssv)
2963 SvSetSV_nosteal
2965 Calls a non-destructive version of "sv_setsv" if dsv is not the
2966 same as ssv. May evaluate arguments more than once.
2967 void SvSetSV_nosteal(SV* dsv, SV* ssv)
2969 SvSHARE Arranges for sv to be shared between threads if a suitable
2971 module has been loaded.
2972 void SvSHARE(SV* sv)
2974 SvUNLOCK
2976 Releases a mutual exclusion lock on sv if a suitable module has
2977 been loaded.
2978 void SvUNLOCK(SV* sv)
2980
2982 Copy The XSUB-writer's interface to the C "memcpy" function. The
2983 "src" is the source, "dest" is the destination, "nitems" is the
2984 number of items, and "type" is the type. May fail on
2985 overlapping copies. See also "Move".
2986 void Copy(void* src, void* dest, int nitems, type)
2988 CopyD Like "Copy" but returns dest. Useful for encouraging compilers
2990 to tail-call optimise.
2991 void * CopyD(void* src, void* dest, int nitems, type)
2993 Move The XSUB-writer's interface to the C "memmove" function. The
2995 "src" is the source, "dest" is the destination, "nitems" is the
2996 number of items, and "type" is the type. Can do overlapping
2997 moves. See also "Copy".
2998 void Move(void* src, void* dest, int nitems, type)
3000 MoveD Like "Move" but returns dest. Useful for encouraging compilers
3002 to tail-call optimise.
3003 void * MoveD(void* src, void* dest, int nitems, type)
3005 Newx The XSUB-writer's interface to the C "malloc" function.
3007 In 5.9.3, Newx() and friends replace the older New() API, and
3009 drops the first parameter, x, a debug aid which allowed callers
3010 to identify themselves. This aid has been superseded by a new
3011 build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in
3012 perlhacktips). The older API is still there for use in XS
3013 modules supporting older perls.
3014 void Newx(void* ptr, int nitems, type)
3016 Newxc The XSUB-writer's interface to the C "malloc" function, with
3018 cast. See also "Newx".
3019 void Newxc(void* ptr, int nitems, type, cast)
3021 Newxz The XSUB-writer's interface to the C "malloc" function. The
3023 allocated memory is zeroed with "memzero". See also "Newx".
3024 void Newxz(void* ptr, int nitems, type)
3026 Poison PoisonWith(0xEF) for catching access to freed memory.
3028 void Poison(void* dest, int nitems, type)
3030 PoisonFree
3032 PoisonWith(0xEF) for catching access to freed memory.
3033 void PoisonFree(void* dest, int nitems, type)
3035 PoisonNew
3037 PoisonWith(0xAB) for catching access to allocated but
3038 uninitialized memory.
3039 void PoisonNew(void* dest, int nitems, type)
3041 PoisonWith
3043 Fill up memory with a byte pattern (a byte repeated over and
3044 over again) that hopefully catches attempts to access
3045 uninitialized memory.
3046 void PoisonWith(void* dest, int nitems, type,
3048 U8 byte)
3049 Renew The XSUB-writer's interface to the C "realloc" function.
3051 void Renew(void* ptr, int nitems, type)
3053 Renewc The XSUB-writer's interface to the C "realloc" function, with
3055 cast.
3056 void Renewc(void* ptr, int nitems, type, cast)
3058 Safefree
3060 The XSUB-writer's interface to the C "free" function.
3061 void Safefree(void* ptr)
3063 savepv Perl's version of "strdup()". Returns a pointer to a newly
3065 allocated string which is a duplicate of "pv". The size of the
3066 string is determined by "strlen()". The memory allocated for
3067 the new string can be freed with the "Safefree()" function.
3068 char* savepv(const char* pv)
3070 savepvn Perl's version of what "strndup()" would be if it existed.
3072 Returns a pointer to a newly allocated string which is a
3073 duplicate of the first "len" bytes from "pv", plus a trailing
3074 NUL byte. The memory allocated for the new string can be freed
3075 with the "Safefree()" function.
3076 char* savepvn(const char* pv, I32 len)
3078 savepvs Like "savepvn", but takes a literal string instead of a
3080 string/length pair.
3081 char* savepvs(const char* s)
3083 savesharedpv
3085 A version of "savepv()" which allocates the duplicate string in
3086 memory which is shared between threads.
3087 char* savesharedpv(const char* pv)
3089 savesharedpvn
3091 A version of "savepvn()" which allocates the duplicate string
3092 in memory which is shared between threads. (With the specific
3093 difference that a NULL pointer is not acceptable)
3094 char* savesharedpvn(const char *const pv,
3096 const STRLEN len)
3097 savesharedpvs
3099 A version of "savepvs()" which allocates the duplicate string
3100 in memory which is shared between threads.
3101 char* savesharedpvs(const char* s)
3103 savesharedsvpv
3105 A version of "savesharedpv()" which allocates the duplicate
3106 string in memory which is shared between threads.
3107 char* savesharedsvpv(SV *sv)
3109 savesvpv
3111 A version of "savepv()"/"savepvn()" which gets the string to
3112 duplicate from the passed in SV using "SvPV()"
3113 char* savesvpv(SV* sv)
3115 StructCopy
3117 This is an architecture-independent macro to copy one structure
3118 to another.
3119 void StructCopy(type src, type dest, type)
3121 Zero The XSUB-writer's interface to the C "memzero" function. The
3123 "dest" is the destination, "nitems" is the number of items, and
3124 "type" is the type.
3125 void Zero(void* dest, int nitems, type)
3127 ZeroD Like "Zero" but returns dest. Useful for encouraging compilers
3129 to tail-call optimise.
3130 void * ZeroD(void* dest, int nitems, type)
3132
3134 fbm_compile
3135 Analyses the string in order to make fast searches on it using
3136 fbm_instr() -- the Boyer-Moore algorithm.
3137 void fbm_compile(SV* sv, U32 flags)
3139 fbm_instr
3141 Returns the location of the SV in the string delimited by "str"
3142 and "strend". It returns "NULL" if the string can't be found.
3143 The "sv" does not have to be fbm_compiled, but the search will
3144 not be as fast then.
3145 char* fbm_instr(unsigned char* big,
3147 unsigned char* bigend, SV* littlestr,
3148 U32 flags)
3149 foldEQ Returns true if the leading len bytes of the strings s1 and s2
3151 are the same case-insensitively; false otherwise. Uppercase
3152 and lowercase ASCII range bytes match themselves and their
3153 opposite case counterparts. Non-cased and non-ASCII range
3154 bytes match only themselves.
3155 I32 foldEQ(const char* a, const char* b, I32 len)
3157 foldEQ_locale
3159 Returns true if the leading len bytes of the strings s1 and s2
3160 are the same case-insensitively in the current locale; false
3161 otherwise.
3162 I32 foldEQ_locale(const char* a, const char* b,
3164 I32 len)
3165 form Takes a sprintf-style format pattern and conventional (non-SV)
3167 arguments and returns the formatted string.
3168 (char *) Perl_form(pTHX_ const char* pat, ...)
3170 can be used any place a string (char *) is required:
3172 char * s = Perl_form("%d.%d",major,minor);
3174 Uses a single private buffer so if you want to format several
3176 strings you must explicitly copy the earlier strings away (and
3177 free the copies when you are done).
3178 char* form(const char* pat, ...)
3180 getcwd_sv
3182 Fill the sv with current working directory
3183 int getcwd_sv(SV* sv)
3185 mess Take a sprintf-style format pattern and argument list. These
3187 are used to generate a string message. If the message does not
3188 end with a newline, then it will be extended with some
3189 indication of the current location in the code, as described
3190 for "mess_sv".
3191 Normally, the resulting message is returned in a new mortal SV.
3193 During global destruction a single SV may be shared between
3194 uses of this function.
3195 SV * mess(const char *pat, ...)
3197 mess_sv Expands a message, intended for the user, to include an
3199 indication of the current location in the code, if the message
3200 does not already appear to be complete.
3201 "basemsg" is the initial message or object. If it is a
3203 reference, it will be used as-is and will be the result of this
3204 function. Otherwise it is used as a string, and if it already
3205 ends with a newline, it is taken to be complete, and the result
3206 of this function will be the same string. If the message does
3207 not end with a newline, then a segment such as "at foo.pl line
3208 37" will be appended, and possibly other clauses indicating the
3209 current state of execution. The resulting message will end
3210 with a dot and a newline.
3211 Normally, the resulting message is returned in a new mortal SV.
3213 During global destruction a single SV may be shared between
3214 uses of this function. If "consume" is true, then the function
3215 is permitted (but not required) to modify and return "basemsg"
3216 instead of allocating a new SV.
3217 SV * mess_sv(SV *basemsg, bool consume)
3219 my_snprintf
3221 The C library "snprintf" functionality, if available and
3222 standards-compliant (uses "vsnprintf", actually). However, if
3223 the "vsnprintf" is not available, will unfortunately use the
3224 unsafe "vsprintf" which can overrun the buffer (there is an
3225 overrun check, but that may be too late). Consider using
3226 "sv_vcatpvf" instead, or getting "vsnprintf".
3227 int my_snprintf(char *buffer, const Size_t len,
3229 const char *format, ...)
3230 my_sprintf
3232 The C library "sprintf", wrapped if necessary, to ensure that
3233 it will return the length of the string written to the buffer.
3234 Only rare pre-ANSI systems need the wrapper function - usually
3235 this is a direct call to "sprintf".
3236 int my_sprintf(char *buffer, const char *pat, ...)
3238 my_vsnprintf
3240 The C library "vsnprintf" if available and standards-compliant.
3241 However, if if the "vsnprintf" is not available, will
3242 unfortunately use the unsafe "vsprintf" which can overrun the
3243 buffer (there is an overrun check, but that may be too late).
3244 Consider using "sv_vcatpvf" instead, or getting "vsnprintf".
3245 int my_vsnprintf(char *buffer, const Size_t len,
3247 const char *format, va_list ap)
3248 new_version
3250 Returns a new version object based on the passed in SV:
3251 SV *sv = new_version(SV *ver);
3253 Does not alter the passed in ver SV. See "upg_version" if you
3255 want to upgrade the SV.
3256 SV* new_version(SV *ver)
3258 prescan_version
3260 Validate that a given string can be parsed as a version object,
3261 but doesn't actually perform the parsing. Can use either
3262 strict or lax validation rules. Can optionally set a number of
3263 hint variables to save the parsing code some time when
3264 tokenizing.
3265 const char* prescan_version(const char *s, bool strict,
3267 const char** errstr,
3268 bool *sqv,
3269 int *ssaw_decimal,
3270 int *swidth, bool *salpha)
3271 scan_version
3273 Returns a pointer to the next character after the parsed
3274 version string, as well as upgrading the passed in SV to an RV.
3275 Function must be called with an already existing SV like
3277 sv = newSV(0);
3279 s = scan_version(s, SV *sv, bool qv);
3280 Performs some preprocessing to the string to ensure that it has
3282 the correct characteristics of a version. Flags the object if
3283 it contains an underscore (which denotes this is an alpha
3284 version). The boolean qv denotes that the version should be
3285 interpreted as if it had multiple decimals, even if it doesn't.
3286 const char* scan_version(const char *s, SV *rv, bool qv)
3288 strEQ Test two strings to see if they are equal. Returns true or
3290 false.
3291 bool strEQ(char* s1, char* s2)
3293 strGE Test two strings to see if the first, "s1", is greater than or
3295 equal to the second, "s2". Returns true or false.
3296 bool strGE(char* s1, char* s2)
3298 strGT Test two strings to see if the first, "s1", is greater than the
3300 second, "s2". Returns true or false.
3301 bool strGT(char* s1, char* s2)
3303 strLE Test two strings to see if the first, "s1", is less than or
3305 equal to the second, "s2". Returns true or false.
3306 bool strLE(char* s1, char* s2)
3308 strLT Test two strings to see if the first, "s1", is less than the
3310 second, "s2". Returns true or false.
3311 bool strLT(char* s1, char* s2)
3313 strNE Test two strings to see if they are different. Returns true or
3315 false.
3316 bool strNE(char* s1, char* s2)
3318 strnEQ Test two strings to see if they are equal. The "len" parameter
3320 indicates the number of bytes to compare. Returns true or
3321 false. (A wrapper for "strncmp").
3322 bool strnEQ(char* s1, char* s2, STRLEN len)
3324 strnNE Test two strings to see if they are different. The "len"
3326 parameter indicates the number of bytes to compare. Returns
3327 true or false. (A wrapper for "strncmp").
3328 bool strnNE(char* s1, char* s2, STRLEN len)
3330 sv_destroyable
3332 Dummy routine which reports that object can be destroyed when
3333 there is no sharing module present. It ignores its single SV
3334 argument, and returns 'true'. Exists to avoid test for a NULL
3335 function pointer and because it could potentially warn under
3336 some level of strict-ness.
3337 bool sv_destroyable(SV *sv)
3339 sv_nosharing
3341 Dummy routine which "shares" an SV when there is no sharing
3342 module present. Or "locks" it. Or "unlocks" it. In other
3343 words, ignores its single SV argument. Exists to avoid test
3344 for a NULL function pointer and because it could potentially
3345 warn under some level of strict-ness.
3346 void sv_nosharing(SV *sv)
3348 upg_version
3350 In-place upgrade of the supplied SV to a version object.
3351 SV *sv = upg_version(SV *sv, bool qv);
3353 Returns a pointer to the upgraded SV. Set the boolean qv if
3355 you want to force this SV to be interpreted as an "extended"
3356 version.
3357 SV* upg_version(SV *ver, bool qv)
3359 vcmp Version object aware cmp. Both operands must already have been
3361 converted into version objects.
3362 int vcmp(SV *lhv, SV *rhv)
3364 vmess "pat" and "args" are a sprintf-style format pattern and
3366 encapsulated argument list. These are used to generate a
3367 string message. If the message does not end with a newline,
3368 then it will be extended with some indication of the current
3369 location in the code, as described for "mess_sv".
3370 Normally, the resulting message is returned in a new mortal SV.
3372 During global destruction a single SV may be shared between
3373 uses of this function.
3374 SV * vmess(const char *pat, va_list *args)
3376 vnormal Accepts a version object and returns the normalized string
3378 representation. Call like:
3379 sv = vnormal(rv);
3381 NOTE: you can pass either the object directly or the SV
3383 contained within the RV.
3384 The SV returned has a refcount of 1.
3386 SV* vnormal(SV *vs)
3388 vnumify Accepts a version object and returns the normalized floating
3390 point representation. Call like:
3391 sv = vnumify(rv);
3393 NOTE: you can pass either the object directly or the SV
3395 contained within the RV.
3396 The SV returned has a refcount of 1.
3398 SV* vnumify(SV *vs)
3400 vstringify
3402 In order to maintain maximum compatibility with earlier
3403 versions of Perl, this function will return either the floating
3404 point notation or the multiple dotted notation, depending on
3405 whether the original version contained 1 or more dots,
3406 respectively.
3407 The SV returned has a refcount of 1.
3409 SV* vstringify(SV *vs)
3411 vverify Validates that the SV contains valid internal structure for a
3413 version object. It may be passed either the version object
3414 (RV) or the hash itself (HV). If the structure is valid, it
3415 returns the HV. If the structure is invalid, it returns NULL.
3416 SV *hv = vverify(sv);
3418 Note that it only confirms the bare minimum structure (so as
3420 not to get confused by derived classes which may contain
3421 additional hash entries):
3422 SV* vverify(SV *vs)
3424
3426 mro_get_linear_isa
3427 Returns the mro linearisation for the given stash. By default,
3428 this will be whatever "mro_get_linear_isa_dfs" returns unless
3429 some other MRO is in effect for the stash. The return value is
3430 a read-only AV*.
3431 You are responsible for "SvREFCNT_inc()" on the return value if
3433 you plan to store it anywhere semi-permanently (otherwise it
3434 might be deleted out from under you the next time the cache is
3435 invalidated).
3436 AV* mro_get_linear_isa(HV* stash)
3438 mro_method_changed_in
3440 Invalidates method caching on any child classes of the given
3441 stash, so that they might notice the changes in this one.
3442 Ideally, all instances of "PL_sub_generation++" in perl source
3444 outside of mro.c should be replaced by calls to this.
3445 Perl automatically handles most of the common ways a method
3447 might be redefined. However, there are a few ways you could
3448 change a method in a stash without the cache code noticing, in
3449 which case you need to call this method afterwards:
3450 1) Directly manipulating the stash HV entries from XS code.
3452 2) Assigning a reference to a readonly scalar constant into a
3454 stash entry in order to create a constant subroutine (like
3455 constant.pm does).
3456 This same method is available from pure perl via,
3458 "mro::method_changed_in(classname)".
3459 void mro_method_changed_in(HV* stash)
3461 mro_register
3463 Registers a custom mro plugin. See perlmroapi for details.
3464 void mro_register(const struct mro_alg *mro)
3466
3468 dMULTICALL
3469 Declare local variables for a multicall. See "LIGHTWEIGHT
3470 CALLBACKS" in perlcall.
3471 dMULTICALL;
3473 MULTICALL
3475 Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in
3476 perlcall.
3477 MULTICALL;
3479 POP_MULTICALL
3481 Closing bracket for a lightweight callback. See "LIGHTWEIGHT
3482 CALLBACKS" in perlcall.
3483 POP_MULTICALL;
3485 PUSH_MULTICALL
3487 Opening bracket for a lightweight callback. See "LIGHTWEIGHT
3488 CALLBACKS" in perlcall.
3489 PUSH_MULTICALL;
3491
3493 grok_bin
3494 converts a string representing a binary number to numeric form.
3495 On entry start and *len give the string to scan, *flags gives
3497 conversion flags, and result should be NULL or a pointer to an
3498 NV. The scan stops at the end of the string, or the first
3499 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
3500 in *flags, encountering an invalid character will also trigger
3501 a warning. On return *len is set to the length of the scanned
3502 string, and *flags gives output flags.
3503 If the value is <= "UV_MAX" it is returned as a UV, the output
3505 flags are clear, and nothing is written to *result. If the
3506 value is > UV_MAX "grok_bin" returns UV_MAX, sets
3507 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
3508 the value to *result (or the value is discarded if result is
3509 NULL).
3510 The binary number may optionally be prefixed with "0b" or "b"
3512 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
3513 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the
3514 binary number may use '_' characters to separate digits.
3515 UV grok_bin(const char* start, STRLEN* len_p,
3517 I32* flags, NV *result)
3518 grok_hex
3520 converts a string representing a hex number to numeric form.
3521 On entry start and *len give the string to scan, *flags gives
3523 conversion flags, and result should be NULL or a pointer to an
3524 NV. The scan stops at the end of the string, or the first
3525 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
3526 in *flags, encountering an invalid character will also trigger
3527 a warning. On return *len is set to the length of the scanned
3528 string, and *flags gives output flags.
3529 If the value is <= UV_MAX it is returned as a UV, the output
3531 flags are clear, and nothing is written to *result. If the
3532 value is > UV_MAX "grok_hex" returns UV_MAX, sets
3533 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
3534 the value to *result (or the value is discarded if result is
3535 NULL).
3536 The hex number may optionally be prefixed with "0x" or "x"
3538 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
3539 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the hex
3540 number may use '_' characters to separate digits.
3541 UV grok_hex(const char* start, STRLEN* len_p,
3543 I32* flags, NV *result)
3544 grok_number
3546 Recognise (or not) a number. The type of the number is
3547 returned (0 if unrecognised), otherwise it is a bit-ORed
3548 combination of IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX,
3549 IS_NUMBER_NOT_INT, IS_NUMBER_NEG, IS_NUMBER_INFINITY,
3550 IS_NUMBER_NAN (defined in perl.h).
3551 If the value of the number can fit an in UV, it is returned in
3553 the *valuep IS_NUMBER_IN_UV will be set to indicate that
3554 *valuep is valid, IS_NUMBER_IN_UV will never be set unless
3555 *valuep is valid, but *valuep may have been assigned to during
3556 processing even though IS_NUMBER_IN_UV is not set on return.
3557 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same
3558 cases as when valuep is non-NULL, but no actual assignment (or
3559 SEGV) will occur.
3560 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing
3562 decimals were seen (in which case *valuep gives the true value
3563 truncated to an integer), and IS_NUMBER_NEG if the number is
3564 negative (in which case *valuep holds the absolute value).
3565 IS_NUMBER_IN_UV is not set if e notation was used or the number
3566 is larger than a UV.
3567 int grok_number(const char *pv, STRLEN len,
3569 UV *valuep)
3570 grok_numeric_radix
3572 Scan and skip for a numeric decimal separator (radix).
3573 bool grok_numeric_radix(const char **sp,
3575 const char *send)
3576 grok_oct
3578 converts a string representing an octal number to numeric form.
3579 On entry start and *len give the string to scan, *flags gives
3581 conversion flags, and result should be NULL or a pointer to an
3582 NV. The scan stops at the end of the string, or the first
3583 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
3584 in *flags, encountering an 8 or 9 will also trigger a warning.
3585 On return *len is set to the length of the scanned string, and
3586 *flags gives output flags.
3587 If the value is <= UV_MAX it is returned as a UV, the output
3589 flags are clear, and nothing is written to *result. If the
3590 value is > UV_MAX "grok_oct" returns UV_MAX, sets
3591 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
3592 the value to *result (or the value is discarded if result is
3593 NULL).
3594 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the
3596 octal number may use '_' characters to separate digits.
3597 UV grok_oct(const char* start, STRLEN* len_p,
3599 I32* flags, NV *result)
3600 Perl_signbit
3602 Return a non-zero integer if the sign bit on an NV is set, and
3603 0 if it is not.
3604 If Configure detects this system has a signbit() that will work
3606 with our NVs, then we just use it via the #define in perl.h.
3607 Otherwise, fall back on this implementation. As a first pass,
3608 this gets everything right except -0.0. Alas, catching -0.0 is
3609 the main use for this function, so this is not too helpful yet.
3610 Still, at least we have the scaffolding in place to support
3611 other systems, should that prove useful.
3612 Configure notes: This function is called 'Perl_signbit'
3614 instead of a plain 'signbit' because it is easy to imagine a
3615 system having a signbit() function or macro that doesn't happen
3616 to work with our particular choice of NVs. We shouldn't just
3617 re-#define signbit as Perl_signbit and expect the standard
3618 system headers to be happy. Also, this is a no-context
3619 function (no pTHX_) because Perl_signbit() is usually
3620 re-#defined in perl.h as a simple macro call to the system's
3621 signbit(). Users should just always call Perl_signbit().
3622 NOTE: this function is experimental and may change or be
3624 removed without notice.
3625 int Perl_signbit(NV f)
3627 scan_bin
3629 For backwards compatibility. Use "grok_bin" instead.
3630 NV scan_bin(const char* start, STRLEN len,
3632 STRLEN* retlen)
3633 scan_hex
3635 For backwards compatibility. Use "grok_hex" instead.
3636 NV scan_hex(const char* start, STRLEN len,
3638 STRLEN* retlen)
3639 scan_oct
3641 For backwards compatibility. Use "grok_oct" instead.
3642 NV scan_oct(const char* start, STRLEN len,
3644 STRLEN* retlen)
3645
3647 newASSIGNOP
3648 Constructs, checks, and returns an assignment op. left and
3649 right supply the parameters of the assignment; they are
3650 consumed by this function and become part of the constructed op
3651 tree.
3652 If optype is "OP_ANDASSIGN", "OP_ORASSIGN", or "OP_DORASSIGN",
3654 then a suitable conditional optree is constructed. If optype
3655 is the opcode of a binary operator, such as "OP_BIT_OR", then
3656 an op is constructed that performs the binary operation and
3657 assigns the result to the left argument. Either way, if optype
3658 is non-zero then flags has no effect.
3659 If optype is zero, then a plain scalar or list assignment is
3661 constructed. Which type of assignment it is is automatically
3662 determined. flags gives the eight bits of "op_flags", except
3663 that "OPf_KIDS" will be set automatically, and, shifted up
3664 eight bits, the eight bits of "op_private", except that the bit
3665 with value 1 or 2 is automatically set as required.
3666 OP * newASSIGNOP(I32 flags, OP *left, I32 optype,
3668 OP *right)
3669 newBINOP
3671 Constructs, checks, and returns an op of any binary type. type
3672 is the opcode. flags gives the eight bits of "op_flags",
3673 except that "OPf_KIDS" will be set automatically, and, shifted
3674 up eight bits, the eight bits of "op_private", except that the
3675 bit with value 1 or 2 is automatically set as required. first
3676 and last supply up to two ops to be the direct children of the
3677 binary op; they are consumed by this function and become part
3678 of the constructed op tree.
3679 OP * newBINOP(I32 type, I32 flags, OP *first,
3681 OP *last)
3682 newCONDOP
3684 Constructs, checks, and returns a conditional-expression
3685 ("cond_expr") op. flags gives the eight bits of "op_flags",
3686 except that "OPf_KIDS" will be set automatically, and, shifted
3687 up eight bits, the eight bits of "op_private", except that the
3688 bit with value 1 is automatically set. first supplies the
3689 expression selecting between the two branches, and trueop and
3690 falseop supply the branches; they are consumed by this function
3691 and become part of the constructed op tree.
3692 OP * newCONDOP(I32 flags, OP *first, OP *trueop,
3694 OP *falseop)
3695 newFOROP
3697 Constructs, checks, and returns an op tree expressing a
3698 "foreach" loop (iteration through a list of values). This is a
3699 heavyweight loop, with structure that allows exiting the loop
3700 by "last" and suchlike.
3701 sv optionally supplies the variable that will be aliased to
3703 each item in turn; if null, it defaults to $_ (either lexical
3704 or global). expr supplies the list of values to iterate over.
3705 block supplies the main body of the loop, and cont optionally
3706 supplies a "continue" block that operates as a second half of
3707 the body. All of these optree inputs are consumed by this
3708 function and become part of the constructed op tree.
3709 flags gives the eight bits of "op_flags" for the "leaveloop" op
3711 and, shifted up eight bits, the eight bits of "op_private" for
3712 the "leaveloop" op, except that (in both cases) some bits will
3713 be set automatically.
3714 OP * newFOROP(I32 flags, OP *sv, OP *expr, OP *block,
3716 OP *cont)
3717 newGIVENOP
3719 Constructs, checks, and returns an op tree expressing a "given"
3720 block. cond supplies the expression that will be locally
3721 assigned to a lexical variable, and block supplies the body of
3722 the "given" construct; they are consumed by this function and
3723 become part of the constructed op tree. defsv_off is the pad
3724 offset of the scalar lexical variable that will be affected.
3725 OP * newGIVENOP(OP *cond, OP *block,
3727 PADOFFSET defsv_off)
3728 newGVOP Constructs, checks, and returns an op of any type that involves
3730 an embedded reference to a GV. type is the opcode. flags
3731 gives the eight bits of "op_flags". gv identifies the GV that
3732 the op should reference; calling this function does not
3733 transfer ownership of any reference to it.
3734 OP * newGVOP(I32 type, I32 flags, GV *gv)
3736 newLISTOP
3738 Constructs, checks, and returns an op of any list type. type
3739 is the opcode. flags gives the eight bits of "op_flags",
3740 except that "OPf_KIDS" will be set automatically if required.
3741 first and last supply up to two ops to be direct children of
3742 the list op; they are consumed by this function and become part
3743 of the constructed op tree.
3744 OP * newLISTOP(I32 type, I32 flags, OP *first,
3746 OP *last)
3747 newLOGOP
3749 Constructs, checks, and returns a logical (flow control) op.
3750 type is the opcode. flags gives the eight bits of "op_flags",
3751 except that "OPf_KIDS" will be set automatically, and, shifted
3752 up eight bits, the eight bits of "op_private", except that the
3753 bit with value 1 is automatically set. first supplies the
3754 expression controlling the flow, and other supplies the side
3755 (alternate) chain of ops; they are consumed by this function
3756 and become part of the constructed op tree.
3757 OP * newLOGOP(I32 type, I32 flags, OP *first,
3759 OP *other)
3760 newLOOPEX
3762 Constructs, checks, and returns a loop-exiting op (such as
3763 "goto" or "last"). type is the opcode. label supplies the
3764 parameter determining the target of the op; it is consumed by
3765 this function and become part of the constructed op tree.
3766 OP * newLOOPEX(I32 type, OP *label)
3768 newLOOPOP
3770 Constructs, checks, and returns an op tree expressing a loop.
3771 This is only a loop in the control flow through the op tree; it
3772 does not have the heavyweight loop structure that allows
3773 exiting the loop by "last" and suchlike. flags gives the eight
3774 bits of "op_flags" for the top-level op, except that some bits
3775 will be set automatically as required. expr supplies the
3776 expression controlling loop iteration, and block supplies the
3777 body of the loop; they are consumed by this function and become
3778 part of the constructed op tree. debuggable is currently
3779 unused and should always be 1.
3780 OP * newLOOPOP(I32 flags, I32 debuggable, OP *expr,
3782 OP *block)
3783 newNULLLIST
3785 Constructs, checks, and returns a new "stub" op, which
3786 represents an empty list expression.
3787 OP * newNULLLIST()
3789 newOP Constructs, checks, and returns an op of any base type (any
3791 type that has no extra fields). type is the opcode. flags
3792 gives the eight bits of "op_flags", and, shifted up eight bits,
3793 the eight bits of "op_private".
3794 OP * newOP(I32 type, I32 flags)
3796 newPADOP
3798 Constructs, checks, and returns an op of any type that involves
3799 a reference to a pad element. type is the opcode. flags gives
3800 the eight bits of "op_flags". A pad slot is automatically
3801 allocated, and is populated with sv; this function takes
3802 ownership of one reference to it.
3803 This function only exists if Perl has been compiled to use
3805 ithreads.
3806 OP * newPADOP(I32 type, I32 flags, SV *sv)
3808 newPMOP Constructs, checks, and returns an op of any pattern matching
3810 type. type is the opcode. flags gives the eight bits of
3811 "op_flags" and, shifted up eight bits, the eight bits of
3812 "op_private".
3813 OP * newPMOP(I32 type, I32 flags)
3815 newPVOP Constructs, checks, and returns an op of any type that involves
3817 an embedded C-level pointer (PV). type is the opcode. flags
3818 gives the eight bits of "op_flags". pv supplies the C-level
3819 pointer, which must have been allocated using
3820 "PerlMemShared_malloc"; the memory will be freed when the op is
3821 destroyed.
3822 OP * newPVOP(I32 type, I32 flags, char *pv)
3824 newRANGE
3826 Constructs and returns a "range" op, with subordinate "flip"
3827 and "flop" ops. flags gives the eight bits of "op_flags" for
3828 the "flip" op and, shifted up eight bits, the eight bits of
3829 "op_private" for both the "flip" and "range" ops, except that
3830 the bit with value 1 is automatically set. left and right
3831 supply the expressions controlling the endpoints of the range;
3832 they are consumed by this function and become part of the
3833 constructed op tree.
3834 OP * newRANGE(I32 flags, OP *left, OP *right)
3836 newSLICEOP
3838 Constructs, checks, and returns an "lslice" (list slice) op.
3839 flags gives the eight bits of "op_flags", except that
3840 "OPf_KIDS" will be set automatically, and, shifted up eight
3841 bits, the eight bits of "op_private", except that the bit with
3842 value 1 or 2 is automatically set as required. listval and
3843 subscript supply the parameters of the slice; they are consumed
3844 by this function and become part of the constructed op tree.
3845 OP * newSLICEOP(I32 flags, OP *subscript,
3847 OP *listval)
3848 newSTATEOP
3850 Constructs a state op (COP). The state op is normally a
3851 "nextstate" op, but will be a "dbstate" op if debugging is
3852 enabled for currently-compiled code. The state op is populated
3853 from "PL_curcop" (or "PL_compiling"). If label is non-null, it
3854 supplies the name of a label to attach to the state op; this
3855 function takes ownership of the memory pointed at by label, and
3856 will free it. flags gives the eight bits of "op_flags" for the
3857 state op.
3858 If o is null, the state op is returned. Otherwise the state op
3860 is combined with o into a "lineseq" list op, which is returned.
3861 o is consumed by this function and becomes part of the returned
3862 op tree.
3863 OP * newSTATEOP(I32 flags, char *label, OP *o)
3865 newSVOP Constructs, checks, and returns an op of any type that involves
3867 an embedded SV. type is the opcode. flags gives the eight
3868 bits of "op_flags". sv gives the SV to embed in the op; this
3869 function takes ownership of one reference to it.
3870 OP * newSVOP(I32 type, I32 flags, SV *sv)
3872 newUNOP Constructs, checks, and returns an op of any unary type. type
3874 is the opcode. flags gives the eight bits of "op_flags",
3875 except that "OPf_KIDS" will be set automatically if required,
3876 and, shifted up eight bits, the eight bits of "op_private",
3877 except that the bit with value 1 is automatically set. first
3878 supplies an optional op to be the direct child of the unary op;
3879 it is consumed by this function and become part of the
3880 constructed op tree.
3881 OP * newUNOP(I32 type, I32 flags, OP *first)
3883 newWHENOP
3885 Constructs, checks, and returns an op tree expressing a "when"
3886 block. cond supplies the test expression, and block supplies
3887 the block that will be executed if the test evaluates to true;
3888 they are consumed by this function and become part of the
3889 constructed op tree. cond will be interpreted DWIMically,
3890 often as a comparison against $_, and may be null to generate a
3891 "default" block.
3892 OP * newWHENOP(OP *cond, OP *block)
3894 newWHILEOP
3896 Constructs, checks, and returns an op tree expressing a "while"
3897 loop. This is a heavyweight loop, with structure that allows
3898 exiting the loop by "last" and suchlike.
3899 loop is an optional preconstructed "enterloop" op to use in the
3901 loop; if it is null then a suitable op will be constructed
3902 automatically. expr supplies the loop's controlling
3903 expression. block supplies the main body of the loop, and cont
3904 optionally supplies a "continue" block that operates as a
3905 second half of the body. All of these optree inputs are
3906 consumed by this function and become part of the constructed op
3907 tree.
3908 flags gives the eight bits of "op_flags" for the "leaveloop" op
3910 and, shifted up eight bits, the eight bits of "op_private" for
3911 the "leaveloop" op, except that (in both cases) some bits will
3912 be set automatically. debuggable is currently unused and
3913 should always be 1. has_my can be supplied as true to force
3914 the loop body to be enclosed in its own scope.
3915 OP * newWHILEOP(I32 flags, I32 debuggable,
3917 LOOP *loop, OP *expr, OP *block,
3918 OP *cont, I32 has_my)
3919
3921 ck_entersub_args_list
3922 Performs the default fixup of the arguments part of an
3923 "entersub" op tree. This consists of applying list context to
3924 each of the argument ops. This is the standard treatment used
3925 on a call marked with "&", or a method call, or a call through
3926 a subroutine reference, or any other call where the callee
3927 can't be identified at compile time, or a call where the callee
3928 has no prototype.
3929 OP * ck_entersub_args_list(OP *entersubop)
3931 ck_entersub_args_proto
3933 Performs the fixup of the arguments part of an "entersub" op
3934 tree based on a subroutine prototype. This makes various
3935 modifications to the argument ops, from applying context up to
3936 inserting "refgen" ops, and checking the number and syntactic
3937 types of arguments, as directed by the prototype. This is the
3938 standard treatment used on a subroutine call, not marked with
3939 "&", where the callee can be identified at compile time and has
3940 a prototype.
3941 protosv supplies the subroutine prototype to be applied to the
3943 call. It may be a normal defined scalar, of which the string
3944 value will be used. Alternatively, for convenience, it may be
3945 a subroutine object (a "CV*" that has been cast to "SV*") which
3946 has a prototype. The prototype supplied, in whichever form,
3947 does not need to match the actual callee referenced by the op
3948 tree.
3949 If the argument ops disagree with the prototype, for example by
3951 having an unacceptable number of arguments, a valid op tree is
3952 returned anyway. The error is reflected in the parser state,
3953 normally resulting in a single exception at the top level of
3954 parsing which covers all the compilation errors that occurred.
3955 In the error message, the callee is referred to by the name
3956 defined by the namegv parameter.
3957 OP * ck_entersub_args_proto(OP *entersubop,
3959 GV *namegv, SV *protosv)
3960 ck_entersub_args_proto_or_list
3962 Performs the fixup of the arguments part of an "entersub" op
3963 tree either based on a subroutine prototype or using default
3964 list-context processing. This is the standard treatment used
3965 on a subroutine call, not marked with "&", where the callee can
3966 be identified at compile time.
3967 protosv supplies the subroutine prototype to be applied to the
3969 call, or indicates that there is no prototype. It may be a
3970 normal scalar, in which case if it is defined then the string
3971 value will be used as a prototype, and if it is undefined then
3972 there is no prototype. Alternatively, for convenience, it may
3973 be a subroutine object (a "CV*" that has been cast to "SV*"),
3974 of which the prototype will be used if it has one. The
3975 prototype (or lack thereof) supplied, in whichever form, does
3976 not need to match the actual callee referenced by the op tree.
3977 If the argument ops disagree with the prototype, for example by
3979 having an unacceptable number of arguments, a valid op tree is
3980 returned anyway. The error is reflected in the parser state,
3981 normally resulting in a single exception at the top level of
3982 parsing which covers all the compilation errors that occurred.
3983 In the error message, the callee is referred to by the name
3984 defined by the namegv parameter.
3985 OP * ck_entersub_args_proto_or_list(OP *entersubop,
3987 GV *namegv,
3988 SV *protosv)
3989 cv_const_sv
3991 If "cv" is a constant sub eligible for inlining. returns the
3992 constant value returned by the sub. Otherwise, returns NULL.
3993 Constant subs can be created with "newCONSTSUB" or as described
3995 in "Constant Functions" in perlsub.
3996 SV* cv_const_sv(const CV *const cv)
3998 cv_get_call_checker
4000 Retrieves the function that will be used to fix up a call to
4001 cv. Specifically, the function is applied to an "entersub" op
4002 tree for a subroutine call, not marked with "&", where the
4003 callee can be identified at compile time as cv.
4004 The C-level function pointer is returned in *ckfun_p, and an SV
4006 argument for it is returned in *ckobj_p. The function is
4007 intended to be called in this manner:
4008 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
4010 In this call, entersubop is a pointer to the "entersub" op,
4012 which may be replaced by the check function, and namegv is a GV
4013 supplying the name that should be used by the check function to
4014 refer to the callee of the "entersub" op if it needs to emit
4015 any diagnostics. It is permitted to apply the check function
4016 in non-standard situations, such as to a call to a different
4017 subroutine or to a method call.
4018 By default, the function is
4020 Perl_ck_entersub_args_proto_or_list, and the SV parameter is cv
4021 itself. This implements standard prototype processing. It can
4022 be changed, for a particular subroutine, by
4023 "cv_set_call_checker".
4024 void cv_get_call_checker(CV *cv,
4026 Perl_call_checker *ckfun_p,
4027 SV **ckobj_p)
4028 cv_set_call_checker
4030 Sets the function that will be used to fix up a call to cv.
4031 Specifically, the function is applied to an "entersub" op tree
4032 for a subroutine call, not marked with "&", where the callee
4033 can be identified at compile time as cv.
4034 The C-level function pointer is supplied in ckfun, and an SV
4036 argument for it is supplied in ckobj. The function is intended
4037 to be called in this manner:
4038 entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
4040 In this call, entersubop is a pointer to the "entersub" op,
4042 which may be replaced by the check function, and namegv is a GV
4043 supplying the name that should be used by the check function to
4044 refer to the callee of the "entersub" op if it needs to emit
4045 any diagnostics. It is permitted to apply the check function
4046 in non-standard situations, such as to a call to a different
4047 subroutine or to a method call.
4048 The current setting for a particular CV can be retrieved by
4050 "cv_get_call_checker".
4051 void cv_set_call_checker(CV *cv,
4053 Perl_call_checker ckfun,
4054 SV *ckobj)
4055 LINKLIST
4057 Given the root of an optree, link the tree in execution order
4058 using the "op_next" pointers and return the first op executed.
4059 If this has already been done, it will not be redone, and
4060 "o->op_next" will be returned. If "o->op_next" is not already
4061 set, o should be at least an "UNOP".
4062 OP* LINKLIST(OP *o)
4064 newCONSTSUB
4066 See "newCONSTSUB_flags".
4067 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
4069 newCONSTSUB_flags
4071 Creates a constant sub equivalent to Perl "sub FOO () { 123 }"
4072 which is eligible for inlining at compile-time.
4073 Currently, the only useful value for "flags" is SVf_UTF8.
4075 Passing NULL for SV creates a constant sub equivalent to "sub
4077 BAR () {}", which won't be called if used as a destructor, but
4078 will suppress the overhead of a call to "AUTOLOAD". (This
4079 form, however, isn't eligible for inlining at compile time.)
4080 CV* newCONSTSUB_flags(HV* stash, const char* name,
4082 STRLEN len, U32 flags, SV* sv)
4083 newXS Used by "xsubpp" to hook up XSUBs as Perl subs. filename needs
4085 to be static storage, as it is used directly as CvFILE(),
4086 without a copy being made.
4087 op_append_elem
4089 Append an item to the list of ops contained directly within a
4090 list-type op, returning the lengthened list. first is the
4091 list-type op, and last is the op to append to the list. optype
4092 specifies the intended opcode for the list. If first is not
4093 already a list of the right type, it will be upgraded into one.
4094 If either first or last is null, the other is returned
4095 unchanged.
4096 OP * op_append_elem(I32 optype, OP *first, OP *last)
4098 op_append_list
4100 Concatenate the lists of ops contained directly within two
4101 list-type ops, returning the combined list. first and last are
4102 the list-type ops to concatenate. optype specifies the
4103 intended opcode for the list. If either first or last is not
4104 already a list of the right type, it will be upgraded into one.
4105 If either first or last is null, the other is returned
4106 unchanged.
4107 OP * op_append_list(I32 optype, OP *first, OP *last)
4109 OP_CLASS
4111 Return the class of the provided OP: that is, which of the *OP
4112 structures it uses. For core ops this currently gets the
4113 information out of PL_opargs, which does not always accurately
4114 reflect the type used. For custom ops the type is returned
4115 from the registration, and it is up to the registree to ensure
4116 it is accurate. The value returned will be one of the OA_*
4117 constants from op.h.
4118 U32 OP_CLASS(OP *o)
4120 OP_DESC Return a short description of the provided OP.
4122 const char * OP_DESC(OP *o)
4124 op_linklist
4126 This function is the implementation of the "LINKLIST" macro. It
4127 should not be called directly.
4128 OP* op_linklist(OP *o)
4130 op_lvalue
4132 Propagate lvalue ("modifiable") context to an op and its
4133 children. type represents the context type, roughly based on
4134 the type of op that would do the modifying, although "local()"
4135 is represented by OP_NULL, because it has no op type of its own
4136 (it is signalled by a flag on the lvalue op).
4137 This function detects things that can't be modified, such as
4139 "$x+1", and generates errors for them. For example, "$x+1 = 2"
4140 would cause it to be called with an op of type OP_ADD and a
4141 "type" argument of OP_SASSIGN.
4142 It also flags things that need to behave specially in an lvalue
4144 context, such as "$$x = 5" which might have to vivify a
4145 reference in $x.
4146 NOTE: this function is experimental and may change or be
4148 removed without notice.
4149 OP * op_lvalue(OP *o, I32 type)
4151 OP_NAME Return the name of the provided OP. For core ops this looks up
4153 the name from the op_type; for custom ops from the op_ppaddr.
4154 const char * OP_NAME(OP *o)
4156 op_prepend_elem
4158 Prepend an item to the list of ops contained directly within a
4159 list-type op, returning the lengthened list. first is the op
4160 to prepend to the list, and last is the list-type op. optype
4161 specifies the intended opcode for the list. If last is not
4162 already a list of the right type, it will be upgraded into one.
4163 If either first or last is null, the other is returned
4164 unchanged.
4165 OP * op_prepend_elem(I32 optype, OP *first, OP *last)
4167 op_scope
4169 Wraps up an op tree with some additional ops so that at runtime
4170 a dynamic scope will be created. The original ops run in the
4171 new dynamic scope, and then, provided that they exit normally,
4172 the scope will be unwound. The additional ops used to create
4173 and unwind the dynamic scope will normally be an
4174 "enter"/"leave" pair, but a "scope" op may be used instead if
4175 the ops are simple enough to not need the full dynamic scope
4176 structure.
4177 NOTE: this function is experimental and may change or be
4179 removed without notice.
4180 OP * op_scope(OP *o)
4182 rv2cv_op_cv
4184 Examines an op, which is expected to identify a subroutine at
4185 runtime, and attempts to determine at compile time which
4186 subroutine it identifies. This is normally used during Perl
4187 compilation to determine whether a prototype can be applied to
4188 a function call. cvop is the op being considered, normally an
4189 "rv2cv" op. A pointer to the identified subroutine is
4190 returned, if it could be determined statically, and a null
4191 pointer is returned if it was not possible to determine
4192 statically.
4193 Currently, the subroutine can be identified statically if the
4195 RV that the "rv2cv" is to operate on is provided by a suitable
4196 "gv" or "const" op. A "gv" op is suitable if the GV's CV slot
4197 is populated. A "const" op is suitable if the constant value
4198 must be an RV pointing to a CV. Details of this process may
4199 change in future versions of Perl. If the "rv2cv" op has the
4200 "OPpENTERSUB_AMPER" flag set then no attempt is made to
4201 identify the subroutine statically: this flag is used to
4202 suppress compile-time magic on a subroutine call, forcing it to
4203 use default runtime behaviour.
4204 If flags has the bit "RV2CVOPCV_MARK_EARLY" set, then the
4206 handling of a GV reference is modified. If a GV was examined
4207 and its CV slot was found to be empty, then the "gv" op has the
4208 "OPpEARLY_CV" flag set. If the op is not optimised away, and
4209 the CV slot is later populated with a subroutine having a
4210 prototype, that flag eventually triggers the warning "called
4211 too early to check prototype".
4212 If flags has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then
4214 instead of returning a pointer to the subroutine it returns a
4215 pointer to the GV giving the most appropriate name for the
4216 subroutine in this context. Normally this is just the "CvGV"
4217 of the subroutine, but for an anonymous ("CvANON") subroutine
4218 that is referenced through a GV it will be the referencing GV.
4219 The resulting "GV*" is cast to "CV*" to be returned. A null
4220 pointer is returned as usual if there is no statically-
4221 determinable subroutine.
4222 CV * rv2cv_op_cv(OP *cvop, U32 flags)
4224
4226 CvPADLIST
4227 CV's can have CvPADLIST(cv) set to point to an AV. This is the
4228 CV's scratchpad, which stores lexical variables and opcode
4229 temporary and per-thread values.
4230 For these purposes "forms" are a kind-of CV, eval""s are too
4232 (except they're not callable at will and are always thrown away
4233 after the eval"" is done executing). Require'd files are simply
4234 evals without any outer lexical scope.
4235 XSUBs don't have CvPADLIST set - dXSTARG fetches values from
4237 PL_curpad, but that is really the callers pad (a slot of which
4238 is allocated by every entersub).
4239 The CvPADLIST AV has the REFCNT of its component items managed
4241 "manually" (mostly in pad.c) rather than by normal av.c rules.
4242 So we turn off AvREAL just before freeing it, to let av.c know
4243 not to touch the entries. The items in the AV are not SVs as
4244 for a normal AV, but other AVs:
4245 0'th Entry of the CvPADLIST is an AV which represents the
4247 "names" or rather the "static type information" for lexicals.
4248 The CvDEPTH'th entry of CvPADLIST AV is an AV which is the
4250 stack frame at that depth of recursion into the CV. The 0'th
4251 slot of a frame AV is an AV which is @_. other entries are
4252 storage for variables and op targets.
4253 Iterating over the names AV iterates over all possible pad
4255 items. Pad slots that are SVs_PADTMP (targets/GVs/constants)
4256 end up having &PL_sv_undef "names" (see pad_alloc()).
4257 Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid
4259 names. The rest are op targets/GVs/constants which are
4260 statically allocated or resolved at compile time. These don't
4261 have names by which they can be looked up from Perl code at run
4262 time through eval"" like my/our variables can be. Since they
4263 can't be looked up by "name" but only by their index allocated
4264 at compile time (which is usually in PL_op->op_targ), wasting a
4265 name SV for them doesn't make sense.
4266 The SVs in the names AV have their PV being the name of the
4268 variable. xlow+1..xhigh inclusive in the NV union is a range
4269 of cop_seq numbers for which the name is valid (accessed
4270 through the macros COP_SEQ_RANGE_LOW and _HIGH). During
4271 compilation, these fields may hold the special value
4272 PERL_PADSEQ_INTRO to indicate various stages:
4273 COP_SEQ_RANGE_LOW _HIGH
4275 ----------------- -----
4276 PERL_PADSEQ_INTRO 0 variable not yet introduced: { my ($x
4277 valid-seq# PERL_PADSEQ_INTRO variable in scope: { my ($x)
4278 valid-seq# valid-seq# compilation of scope complete: { my ($x) }
4279 For typed lexicals name SV is SVt_PVMG and SvSTASH points at
4281 the type. For "our" lexicals, the type is also SVt_PVMG, with
4282 the SvOURSTASH slot pointing at the stash of the associated
4283 global (so that duplicate "our" declarations in the same
4284 package can be detected). SvUVX is sometimes hijacked to store
4285 the generation number during compilation.
4286 If SvFAKE is set on the name SV, then that slot in the frame AV
4288 is a REFCNT'ed reference to a lexical from "outside". In this
4289 case, the name SV does not use xlow and xhigh to store a
4290 cop_seq range, since it is in scope throughout. Instead xhigh
4291 stores some flags containing info about the real lexical (is it
4292 declared in an anon, and is it capable of being instantiated
4293 multiple times?), and for fake ANONs, xlow contains the index
4294 within the parent's pad where the lexical's value is stored, to
4295 make cloning quicker.
4296 If the 'name' is '&' the corresponding entry in frame AV is a
4298 CV representing a possible closure. (SvFAKE and name of '&' is
4299 not a meaningful combination currently but could become so if
4300 "my sub foo {}" is implemented.)
4301 Note that formats are treated as anon subs, and are cloned each
4303 time write is called (if necessary).
4304 The flag SVs_PADSTALE is cleared on lexicals each time the my()
4306 is executed, and set on scope exit. This allows the 'Variable
4307 $x is not available' warning to be generated in evals, such as
4308 { my $x = 1; sub f { eval '$x'} } f();
4310 For state vars, SVs_PADSTALE is overloaded to mean 'not yet
4312 initialised'
4313 NOTE: this function is experimental and may change or be
4315 removed without notice.
4316 PADLIST * CvPADLIST(CV *cv)
4318 pad_add_name_pvs
4320 Exactly like "pad_add_name_pvn", but takes a literal string
4321 instead of a string/length pair.
4322 PADOFFSET pad_add_name_pvs(const char *name, U32 flags,
4324 HV *typestash, HV *ourstash)
4325 pad_findmy_pvs
4327 Exactly like "pad_findmy_pvn", but takes a literal string
4328 instead of a string/length pair.
4329 PADOFFSET pad_findmy_pvs(const char *name, U32 flags)
4331 pad_new Create a new padlist, updating the global variables for the
4333 currently-compiling padlist to point to the new padlist. The
4334 following flags can be OR'ed together:
4335 padnew_CLONE this pad is for a cloned CV
4337 padnew_SAVE save old globals on the save stack
4338 padnew_SAVESUB also save extra stuff for start of sub
4339 PADLIST * pad_new(int flags)
4341 PL_comppad
4343 During compilation, this points to the array containing the
4344 values part of the pad for the currently-compiling code. (At
4345 runtime a CV may have many such value arrays; at compile time
4346 just one is constructed.) At runtime, this points to the array
4347 containing the currently-relevant values for the pad for the
4348 currently-executing code.
4349 NOTE: this function is experimental and may change or be
4351 removed without notice.
4352 PL_comppad_name
4354 During compilation, this points to the array containing the
4355 names part of the pad for the currently-compiling code.
4356 NOTE: this function is experimental and may change or be
4358 removed without notice.
4359 PL_curpad
4361 Points directly to the body of the "PL_comppad" array. (I.e.,
4362 this is "AvARRAY(PL_comppad)".)
4363 NOTE: this function is experimental and may change or be
4365 removed without notice.
4366
4368 PL_modglobal
4369 "PL_modglobal" is a general purpose, interpreter global HV for
4370 use by extensions that need to keep information on a per-
4371 interpreter basis. In a pinch, it can also be used as a symbol
4372 table for extensions to share data among each other. It is a
4373 good idea to use keys prefixed by the package name of the
4374 extension that owns the data.
4375 HV* PL_modglobal
4377 PL_na A convenience variable which is typically used with "SvPV" when
4379 one doesn't care about the length of the string. It is usually
4380 more efficient to either declare a local variable and use that
4381 instead or to use the "SvPV_nolen" macro.
4382 STRLEN PL_na
4384 PL_opfreehook
4386 When non-"NULL", the function pointed by this variable will be
4387 called each time an OP is freed with the corresponding OP as
4388 the argument. This allows extensions to free any extra
4389 attribute they have locally attached to an OP. It is also
4390 assured to first fire for the parent OP and then for its kids.
4391 When you replace this variable, it is considered a good
4393 practice to store the possibly previously installed hook and
4394 that you recall it inside your own.
4395 Perl_ophook_t PL_opfreehook
4397 PL_peepp
4399 Pointer to the per-subroutine peephole optimiser. This is a
4400 function that gets called at the end of compilation of a Perl
4401 subroutine (or equivalently independent piece of Perl code) to
4402 perform fixups of some ops and to perform small-scale
4403 optimisations. The function is called once for each subroutine
4404 that is compiled, and is passed, as sole parameter, a pointer
4405 to the op that is the entry point to the subroutine. It
4406 modifies the op tree in place.
4407 The peephole optimiser should never be completely replaced.
4409 Rather, add code to it by wrapping the existing optimiser. The
4410 basic way to do this can be seen in "Compile pass 3: peephole
4411 optimization" in perlguts. If the new code wishes to operate
4412 on ops throughout the subroutine's structure, rather than just
4413 at the top level, it is likely to be more convenient to wrap
4414 the "PL_rpeepp" hook.
4415 peep_t PL_peepp
4417 PL_rpeepp
4419 Pointer to the recursive peephole optimiser. This is a
4420 function that gets called at the end of compilation of a Perl
4421 subroutine (or equivalently independent piece of Perl code) to
4422 perform fixups of some ops and to perform small-scale
4423 optimisations. The function is called once for each chain of
4424 ops linked through their "op_next" fields; it is recursively
4425 called to handle each side chain. It is passed, as sole
4426 parameter, a pointer to the op that is at the head of the
4427 chain. It modifies the op tree in place.
4428 The peephole optimiser should never be completely replaced.
4430 Rather, add code to it by wrapping the existing optimiser. The
4431 basic way to do this can be seen in "Compile pass 3: peephole
4432 optimization" in perlguts. If the new code wishes to operate
4433 only on ops at a subroutine's top level, rather than throughout
4434 the structure, it is likely to be more convenient to wrap the
4435 "PL_peepp" hook.
4436 peep_t PL_rpeepp
4438 PL_sv_no
4440 This is the "false" SV. See "PL_sv_yes". Always refer to this
4441 as &PL_sv_no.
4442 SV PL_sv_no
4444 PL_sv_undef
4446 This is the "undef" SV. Always refer to this as &PL_sv_undef.
4447 SV PL_sv_undef
4449 PL_sv_yes
4451 This is the "true" SV. See "PL_sv_no". Always refer to this
4452 as &PL_sv_yes.
4453 SV PL_sv_yes
4455
4457 SvRX Convenience macro to get the REGEXP from a SV. This is
4458 approximately equivalent to the following snippet:
4459 if (SvMAGICAL(sv))
4461 mg_get(sv);
4462 if (SvROK(sv))
4463 sv = MUTABLE_SV(SvRV(sv));
4464 if (SvTYPE(sv) == SVt_REGEXP)
4465 return (REGEXP*) sv;
4466 NULL will be returned if a REGEXP* is not found.
4468 REGEXP * SvRX(SV *sv)
4470 SvRXOK Returns a boolean indicating whether the SV (or the one it
4472 references) is a REGEXP.
4473 If you want to do something with the REGEXP* later use SvRX
4475 instead and check for NULL.
4476 bool SvRXOK(SV* sv)
4478
4480 dXCPT Set up necessary local variables for exception handling. See
4481 "Exception Handling" in perlguts.
4482 dXCPT;
4484 XCPT_CATCH
4486 Introduces a catch block. See "Exception Handling" in
4487 perlguts.
4488 XCPT_RETHROW
4490 Rethrows a previously caught exception. See "Exception
4491 Handling" in perlguts.
4492 XCPT_RETHROW;
4494 XCPT_TRY_END
4496 Ends a try block. See "Exception Handling" in perlguts.
4497 XCPT_TRY_START
4499 Starts a try block. See "Exception Handling" in perlguts.
4500
4502 dMARK Declare a stack marker variable, "mark", for the XSUB. See
4503 "MARK" and "dORIGMARK".
4504 dMARK;
4506 dORIGMARK
4508 Saves the original stack mark for the XSUB. See "ORIGMARK".
4509 dORIGMARK;
4511 dSP Declares a local copy of perl's stack pointer for the XSUB,
4513 available via the "SP" macro. See "SP".
4514 dSP;
4516 EXTEND Used to extend the argument stack for an XSUB's return values.
4518 Once used, guarantees that there is room for at least "nitems"
4519 to be pushed onto the stack.
4520 void EXTEND(SP, int nitems)
4522 MARK Stack marker variable for the XSUB. See "dMARK".
4524 mPUSHi Push an integer onto the stack. The stack must have room for
4526 this element. Does not use "TARG". See also "PUSHi",
4527 "mXPUSHi" and "XPUSHi".
4528 void mPUSHi(IV iv)
4530 mPUSHn Push a double onto the stack. The stack must have room for
4532 this element. Does not use "TARG". See also "PUSHn",
4533 "mXPUSHn" and "XPUSHn".
4534 void mPUSHn(NV nv)
4536 mPUSHp Push a string onto the stack. The stack must have room for
4538 this element. The "len" indicates the length of the string.
4539 Does not use "TARG". See also "PUSHp", "mXPUSHp" and "XPUSHp".
4540 void mPUSHp(char* str, STRLEN len)
4542 mPUSHs Push an SV onto the stack and mortalizes the SV. The stack
4544 must have room for this element. Does not use "TARG". See
4545 also "PUSHs" and "mXPUSHs".
4546 void mPUSHs(SV* sv)
4548 mPUSHu Push an unsigned integer onto the stack. The stack must have
4550 room for this element. Does not use "TARG". See also "PUSHu",
4551 "mXPUSHu" and "XPUSHu".
4552 void mPUSHu(UV uv)
4554 mXPUSHi Push an integer onto the stack, extending the stack if
4556 necessary. Does not use "TARG". See also "XPUSHi", "mPUSHi"
4557 and "PUSHi".
4558 void mXPUSHi(IV iv)
4560 mXPUSHn Push a double onto the stack, extending the stack if necessary.
4562 Does not use "TARG". See also "XPUSHn", "mPUSHn" and "PUSHn".
4563 void mXPUSHn(NV nv)
4565 mXPUSHp Push a string onto the stack, extending the stack if necessary.
4567 The "len" indicates the length of the string. Does not use
4568 "TARG". See also "XPUSHp", "mPUSHp" and "PUSHp".
4569 void mXPUSHp(char* str, STRLEN len)
4571 mXPUSHs Push an SV onto the stack, extending the stack if necessary and
4573 mortalizes the SV. Does not use "TARG". See also "XPUSHs" and
4574 "mPUSHs".
4575 void mXPUSHs(SV* sv)
4577 mXPUSHu Push an unsigned integer onto the stack, extending the stack if
4579 necessary. Does not use "TARG". See also "XPUSHu", "mPUSHu"
4580 and "PUSHu".
4581 void mXPUSHu(UV uv)
4583 ORIGMARK
4585 The original stack mark for the XSUB. See "dORIGMARK".
4586 POPi Pops an integer off the stack.
4588 IV POPi
4590 POPl Pops a long off the stack.
4592 long POPl
4594 POPn Pops a double off the stack.
4596 NV POPn
4598 POPp Pops a string off the stack. Deprecated. New code should use
4600 POPpx.
4601 char* POPp
4603 POPpbytex
4605 Pops a string off the stack which must consist of bytes i.e.
4606 characters < 256.
4607 char* POPpbytex
4609 POPpx Pops a string off the stack.
4611 char* POPpx
4613 POPs Pops an SV off the stack.
4615 SV* POPs
4617 PUSHi Push an integer onto the stack. The stack must have room for
4619 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
4620 or "dXSTARG" should be called to declare it. Do not call
4621 multiple "TARG"-oriented macros to return lists from XSUB's -
4622 see "mPUSHi" instead. See also "XPUSHi" and "mXPUSHi".
4623 void PUSHi(IV iv)
4625 PUSHMARK
4627 Opening bracket for arguments on a callback. See "PUTBACK" and
4628 perlcall.
4629 void PUSHMARK(SP)
4631 PUSHmortal
4633 Push a new mortal SV onto the stack. The stack must have room
4634 for this element. Does not use "TARG". See also "PUSHs",
4635 "XPUSHmortal" and "XPUSHs".
4636 void PUSHmortal()
4638 PUSHn Push a double onto the stack. The stack must have room for
4640 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
4641 or "dXSTARG" should be called to declare it. Do not call
4642 multiple "TARG"-oriented macros to return lists from XSUB's -
4643 see "mPUSHn" instead. See also "XPUSHn" and "mXPUSHn".
4644 void PUSHn(NV nv)
4646 PUSHp Push a string onto the stack. The stack must have room for
4648 this element. The "len" indicates the length of the string.
4649 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
4650 should be called to declare it. Do not call multiple
4651 "TARG"-oriented macros to return lists from XSUB's - see
4652 "mPUSHp" instead. See also "XPUSHp" and "mXPUSHp".
4653 void PUSHp(char* str, STRLEN len)
4655 PUSHs Push an SV onto the stack. The stack must have room for this
4657 element. Does not handle 'set' magic. Does not use "TARG".
4658 See also "PUSHmortal", "XPUSHs" and "XPUSHmortal".
4659 void PUSHs(SV* sv)
4661 PUSHu Push an unsigned integer onto the stack. The stack must have
4663 room for this element. Handles 'set' magic. Uses "TARG", so
4664 "dTARGET" or "dXSTARG" should be called to declare it. Do not
4665 call multiple "TARG"-oriented macros to return lists from
4666 XSUB's - see "mPUSHu" instead. See also "XPUSHu" and
4667 "mXPUSHu".
4668 void PUSHu(UV uv)
4670 PUTBACK Closing bracket for XSUB arguments. This is usually handled by
4672 "xsubpp". See "PUSHMARK" and perlcall for other uses.
4673 PUTBACK;
4675 SP Stack pointer. This is usually handled by "xsubpp". See "dSP"
4677 and "SPAGAIN".
4678 SPAGAIN Refetch the stack pointer. Used after a callback. See
4680 perlcall.
4681 SPAGAIN;
4683 XPUSHi Push an integer onto the stack, extending the stack if
4685 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
4686 "dXSTARG" should be called to declare it. Do not call multiple
4687 "TARG"-oriented macros to return lists from XSUB's - see
4688 "mXPUSHi" instead. See also "PUSHi" and "mPUSHi".
4689 void XPUSHi(IV iv)
4691 XPUSHmortal
4693 Push a new mortal SV onto the stack, extending the stack if
4694 necessary. Does not use "TARG". See also "XPUSHs",
4695 "PUSHmortal" and "PUSHs".
4696 void XPUSHmortal()
4698 XPUSHn Push a double onto the stack, extending the stack if necessary.
4700 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
4701 should be called to declare it. Do not call multiple
4702 "TARG"-oriented macros to return lists from XSUB's - see
4703 "mXPUSHn" instead. See also "PUSHn" and "mPUSHn".
4704 void XPUSHn(NV nv)
4706 XPUSHp Push a string onto the stack, extending the stack if necessary.
4708 The "len" indicates the length of the string. Handles 'set'
4709 magic. Uses "TARG", so "dTARGET" or "dXSTARG" should be called
4710 to declare it. Do not call multiple "TARG"-oriented macros to
4711 return lists from XSUB's - see "mXPUSHp" instead. See also
4712 "PUSHp" and "mPUSHp".
4713 void XPUSHp(char* str, STRLEN len)
4715 XPUSHs Push an SV onto the stack, extending the stack if necessary.
4717 Does not handle 'set' magic. Does not use "TARG". See also
4718 "XPUSHmortal", "PUSHs" and "PUSHmortal".
4719 void XPUSHs(SV* sv)
4721 XPUSHu Push an unsigned integer onto the stack, extending the stack if
4723 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
4724 "dXSTARG" should be called to declare it. Do not call multiple
4725 "TARG"-oriented macros to return lists from XSUB's - see
4726 "mXPUSHu" instead. See also "PUSHu" and "mPUSHu".
4727 void XPUSHu(UV uv)
4729 XSRETURN
4731 Return from XSUB, indicating number of items on the stack.
4732 This is usually handled by "xsubpp".
4733 void XSRETURN(int nitems)
4735 XSRETURN_EMPTY
4737 Return an empty list from an XSUB immediately.
4738 XSRETURN_EMPTY;
4740 XSRETURN_IV
4742 Return an integer from an XSUB immediately. Uses "XST_mIV".
4743 void XSRETURN_IV(IV iv)
4745 XSRETURN_NO
4747 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
4748 XSRETURN_NO;
4750 XSRETURN_NV
4752 Return a double from an XSUB immediately. Uses "XST_mNV".
4753 void XSRETURN_NV(NV nv)
4755 XSRETURN_PV
4757 Return a copy of a string from an XSUB immediately. Uses
4758 "XST_mPV".
4759 void XSRETURN_PV(char* str)
4761 XSRETURN_UNDEF
4763 Return &PL_sv_undef from an XSUB immediately. Uses
4764 "XST_mUNDEF".
4765 XSRETURN_UNDEF;
4767 XSRETURN_UV
4769 Return an integer from an XSUB immediately. Uses "XST_mUV".
4770 void XSRETURN_UV(IV uv)
4772 XSRETURN_YES
4774 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
4775 XSRETURN_YES;
4777 XST_mIV Place an integer into the specified position "pos" on the
4779 stack. The value is stored in a new mortal SV.
4780 void XST_mIV(int pos, IV iv)
4782 XST_mNO Place &PL_sv_no into the specified position "pos" on the stack.
4784 void XST_mNO(int pos)
4786 XST_mNV Place a double into the specified position "pos" on the stack.
4788 The value is stored in a new mortal SV.
4789 void XST_mNV(int pos, NV nv)
4791 XST_mPV Place a copy of a string into the specified position "pos" on
4793 the stack. The value is stored in a new mortal SV.
4794 void XST_mPV(int pos, char* str)
4796 XST_mUNDEF
4798 Place &PL_sv_undef into the specified position "pos" on the
4799 stack.
4800 void XST_mUNDEF(int pos)
4802 XST_mYES
4804 Place &PL_sv_yes into the specified position "pos" on the
4805 stack.
4806 void XST_mYES(int pos)
4808
4810 svtype An enum of flags for Perl types. These are found in the file
4811 sv.h in the "svtype" enum. Test these flags with the "SvTYPE"
4812 macro.
4813 SVt_IV Integer type flag for scalars. See "svtype".
4815 SVt_NV Double type flag for scalars. See "svtype".
4817 SVt_PV Pointer type flag for scalars. See "svtype".
4819 SVt_PVAV
4821 Type flag for arrays. See "svtype".
4822 SVt_PVCV
4824 Type flag for code refs. See "svtype".
4825 SVt_PVHV
4827 Type flag for hashes. See "svtype".
4828 SVt_PVMG
4830 Type flag for blessed scalars. See "svtype".
4831
4833 boolSV Returns a true SV if "b" is a true value, or a false SV if "b"
4834 is 0.
4835 See also "PL_sv_yes" and "PL_sv_no".
4837 SV * boolSV(bool b)
4839 croak_xs_usage
4841 A specialised variant of "croak()" for emitting the usage
4842 message for xsubs
4843 croak_xs_usage(cv, "eee_yow");
4845 works out the package name and subroutine name from "cv", and
4847 then calls "croak()". Hence if "cv" is &ouch::awk, it would
4848 call "croak" as:
4849 Perl_croak(aTHX_ "Usage: %"SVf"::%"SVf"(%s)", "ouch" "awk", "eee_yow");
4851 void croak_xs_usage(const CV *const cv,
4853 const char *const params)
4854 get_sv Returns the SV of the specified Perl scalar. "flags" are
4856 passed to "gv_fetchpv". If "GV_ADD" is set and the Perl
4857 variable does not exist then it will be created. If "flags" is
4858 zero and the variable does not exist then NULL is returned.
4859 NOTE: the perl_ form of this function is deprecated.
4861 SV* get_sv(const char *name, I32 flags)
4863 newRV_inc
4865 Creates an RV wrapper for an SV. The reference count for the
4866 original SV is incremented.
4867 SV* newRV_inc(SV* sv)
4869 newSVpvn_utf8
4871 Creates a new SV and copies a string into it. If utf8 is true,
4872 calls "SvUTF8_on" on the new SV. Implemented as a wrapper
4873 around "newSVpvn_flags".
4874 SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len,
4876 U32 utf8)
4877 SvCUR Returns the length of the string which is in the SV. See
4879 "SvLEN".
4880 STRLEN SvCUR(SV* sv)
4882 SvCUR_set
4884 Set the current length of the string which is in the SV. See
4885 "SvCUR" and "SvIV_set".
4886 void SvCUR_set(SV* sv, STRLEN len)
4888 SvEND Returns a pointer to the spot just after the last character in
4890 the string which is in the SV, where there is usually a
4891 trailing null (even though Perl scalars do not strictly require
4892 it). See "SvCUR". Access the character as *(SvEND(sv)).
4893 Warning: If "SvCUR" is equal to "SvLEN", then "SvEND" points to
4895 unallocated memory.
4896 char* SvEND(SV* sv)
4898 SvGAMAGIC
4900 Returns true if the SV has get magic or overloading. If either
4901 is true then the scalar is active data, and has the potential
4902 to return a new value every time it is accessed. Hence you
4903 must be careful to only read it once per user logical operation
4904 and work with that returned value. If neither is true then the
4905 scalar's value cannot change unless written to.
4906 U32 SvGAMAGIC(SV* sv)
4908 SvGROW Expands the character buffer in the SV so that it has room for
4910 the indicated number of bytes (remember to reserve space for an
4911 extra trailing NUL character). Calls "sv_grow" to perform the
4912 expansion if necessary. Returns a pointer to the character
4913 buffer.
4914 char * SvGROW(SV* sv, STRLEN len)
4916 SvIOK Returns a U32 value indicating whether the SV contains an
4918 integer.
4919 U32 SvIOK(SV* sv)
4921 SvIOKp Returns a U32 value indicating whether the SV contains an
4923 integer. Checks the private setting. Use "SvIOK" instead.
4924 U32 SvIOKp(SV* sv)
4926 SvIOK_notUV
4928 Returns a boolean indicating whether the SV contains a signed
4929 integer.
4930 bool SvIOK_notUV(SV* sv)
4932 SvIOK_off
4934 Unsets the IV status of an SV.
4935 void SvIOK_off(SV* sv)
4937 SvIOK_on
4939 Tells an SV that it is an integer.
4940 void SvIOK_on(SV* sv)
4942 SvIOK_only
4944 Tells an SV that it is an integer and disables all other OK
4945 bits.
4946 void SvIOK_only(SV* sv)
4948 SvIOK_only_UV
4950 Tells and SV that it is an unsigned integer and disables all
4951 other OK bits.
4952 void SvIOK_only_UV(SV* sv)
4954 SvIOK_UV
4956 Returns a boolean indicating whether the SV contains an
4957 unsigned integer.
4958 bool SvIOK_UV(SV* sv)
4960 SvIsCOW Returns a boolean indicating whether the SV is Copy-On-Write
4962 (either shared hash key scalars, or full Copy On Write scalars
4963 if 5.9.0 is configured for COW).
4964 bool SvIsCOW(SV* sv)
4966 SvIsCOW_shared_hash
4968 Returns a boolean indicating whether the SV is Copy-On-Write
4969 shared hash key scalar.
4970 bool SvIsCOW_shared_hash(SV* sv)
4972 SvIV Coerces the given SV to an integer and returns it. See "SvIVx"
4974 for a version which guarantees to evaluate sv only once.
4975 IV SvIV(SV* sv)
4977 SvIVX Returns the raw value in the SV's IV slot, without checks or
4979 conversions. Only use when you are sure SvIOK is true. See
4980 also "SvIV()".
4981 IV SvIVX(SV* sv)
4983 SvIVx Coerces the given SV to an integer and returns it. Guarantees
4985 to evaluate "sv" only once. Only use this if "sv" is an
4986 expression with side effects, otherwise use the more efficient
4987 "SvIV".
4988 IV SvIVx(SV* sv)
4990 SvIV_nomg
4992 Like "SvIV" but doesn't process magic.
4993 IV SvIV_nomg(SV* sv)
4995 SvIV_set
4997 Set the value of the IV pointer in sv to val. It is possible
4998 to perform the same function of this macro with an lvalue
4999 assignment to "SvIVX". With future Perls, however, it will be
5000 more efficient to use "SvIV_set" instead of the lvalue
5001 assignment to "SvIVX".
5002 void SvIV_set(SV* sv, IV val)
5004 SvLEN Returns the size of the string buffer in the SV, not including
5006 any part attributable to "SvOOK". See "SvCUR".
5007 STRLEN SvLEN(SV* sv)
5009 SvLEN_set
5011 Set the actual length of the string which is in the SV. See
5012 "SvIV_set".
5013 void SvLEN_set(SV* sv, STRLEN len)
5015 SvMAGIC_set
5017 Set the value of the MAGIC pointer in sv to val. See
5018 "SvIV_set".
5019 void SvMAGIC_set(SV* sv, MAGIC* val)
5021 SvNIOK Returns a U32 value indicating whether the SV contains a
5023 number, integer or double.
5024 U32 SvNIOK(SV* sv)
5026 SvNIOKp Returns a U32 value indicating whether the SV contains a
5028 number, integer or double. Checks the private setting. Use
5029 "SvNIOK" instead.
5030 U32 SvNIOKp(SV* sv)
5032 SvNIOK_off
5034 Unsets the NV/IV status of an SV.
5035 void SvNIOK_off(SV* sv)
5037 SvNOK Returns a U32 value indicating whether the SV contains a
5039 double.
5040 U32 SvNOK(SV* sv)
5042 SvNOKp Returns a U32 value indicating whether the SV contains a
5044 double. Checks the private setting. Use "SvNOK" instead.
5045 U32 SvNOKp(SV* sv)
5047 SvNOK_off
5049 Unsets the NV status of an SV.
5050 void SvNOK_off(SV* sv)
5052 SvNOK_on
5054 Tells an SV that it is a double.
5055 void SvNOK_on(SV* sv)
5057 SvNOK_only
5059 Tells an SV that it is a double and disables all other OK bits.
5060 void SvNOK_only(SV* sv)
5062 SvNV Coerce the given SV to a double and return it. See "SvNVx" for
5064 a version which guarantees to evaluate sv only once.
5065 NV SvNV(SV* sv)
5067 SvNVX Returns the raw value in the SV's NV slot, without checks or
5069 conversions. Only use when you are sure SvNOK is true. See
5070 also "SvNV()".
5071 NV SvNVX(SV* sv)
5073 SvNVx Coerces the given SV to a double and returns it. Guarantees to
5075 evaluate "sv" only once. Only use this if "sv" is an
5076 expression with side effects, otherwise use the more efficient
5077 "SvNV".
5078 NV SvNVx(SV* sv)
5080 SvNV_nomg
5082 Like "SvNV" but doesn't process magic.
5083 NV SvNV_nomg(SV* sv)
5085 SvNV_set
5087 Set the value of the NV pointer in sv to val. See "SvIV_set".
5088 void SvNV_set(SV* sv, NV val)
5090 SvOK Returns a U32 value indicating whether the value is defined.
5092 This is only meaningful for scalars.
5093 U32 SvOK(SV* sv)
5095 SvOOK Returns a U32 indicating whether the pointer to the string
5097 buffer is offset. This hack is used internally to speed up
5098 removal of characters from the beginning of a SvPV. When SvOOK
5099 is true, then the start of the allocated string buffer is
5100 actually "SvOOK_offset()" bytes before SvPVX. This offset used
5101 to be stored in SvIVX, but is now stored within the spare part
5102 of the buffer.
5103 U32 SvOOK(SV* sv)
5105 SvOOK_offset
5107 Reads into len the offset from SvPVX back to the true start of
5108 the allocated buffer, which will be non-zero if "sv_chop" has
5109 been used to efficiently remove characters from start of the
5110 buffer. Implemented as a macro, which takes the address of
5111 len, which must be of type "STRLEN". Evaluates sv more than
5112 once. Sets len to 0 if "SvOOK(sv)" is false.
5113 void SvOOK_offset(NN SV*sv, STRLEN len)
5115 SvPOK Returns a U32 value indicating whether the SV contains a
5117 character string.
5118 U32 SvPOK(SV* sv)
5120 SvPOKp Returns a U32 value indicating whether the SV contains a
5122 character string. Checks the private setting. Use "SvPOK"
5123 instead.
5124 U32 SvPOKp(SV* sv)
5126 SvPOK_off
5128 Unsets the PV status of an SV.
5129 void SvPOK_off(SV* sv)
5131 SvPOK_on
5133 Tells an SV that it is a string.
5134 void SvPOK_on(SV* sv)
5136 SvPOK_only
5138 Tells an SV that it is a string and disables all other OK bits.
5139 Will also turn off the UTF-8 status.
5140 void SvPOK_only(SV* sv)
5142 SvPOK_only_UTF8
5144 Tells an SV that it is a string and disables all other OK bits,
5145 and leaves the UTF-8 status as it was.
5146 void SvPOK_only_UTF8(SV* sv)
5148 SvPV Returns a pointer to the string in the SV, or a stringified
5150 form of the SV if the SV does not contain a string. The SV may
5151 cache the stringified version becoming "SvPOK". Handles 'get'
5152 magic. See also "SvPVx" for a version which guarantees to
5153 evaluate sv only once.
5154 char* SvPV(SV* sv, STRLEN len)
5156 SvPVbyte
5158 Like "SvPV", but converts sv to byte representation first if
5159 necessary.
5160 char* SvPVbyte(SV* sv, STRLEN len)
5162 SvPVbytex
5164 Like "SvPV", but converts sv to byte representation first if
5165 necessary. Guarantees to evaluate sv only once; use the more
5166 efficient "SvPVbyte" otherwise.
5167 char* SvPVbytex(SV* sv, STRLEN len)
5169 SvPVbytex_force
5171 Like "SvPV_force", but converts sv to byte representation first
5172 if necessary. Guarantees to evaluate sv only once; use the
5173 more efficient "SvPVbyte_force" otherwise.
5174 char* SvPVbytex_force(SV* sv, STRLEN len)
5176 SvPVbyte_force
5178 Like "SvPV_force", but converts sv to byte representation first
5179 if necessary.
5180 char* SvPVbyte_force(SV* sv, STRLEN len)
5182 SvPVbyte_nolen
5184 Like "SvPV_nolen", but converts sv to byte representation first
5185 if necessary.
5186 char* SvPVbyte_nolen(SV* sv)
5188 SvPVutf8
5190 Like "SvPV", but converts sv to utf8 first if necessary.
5191 char* SvPVutf8(SV* sv, STRLEN len)
5193 SvPVutf8x
5195 Like "SvPV", but converts sv to utf8 first if necessary.
5196 Guarantees to evaluate sv only once; use the more efficient
5197 "SvPVutf8" otherwise.
5198 char* SvPVutf8x(SV* sv, STRLEN len)
5200 SvPVutf8x_force
5202 Like "SvPV_force", but converts sv to utf8 first if necessary.
5203 Guarantees to evaluate sv only once; use the more efficient
5204 "SvPVutf8_force" otherwise.
5205 char* SvPVutf8x_force(SV* sv, STRLEN len)
5207 SvPVutf8_force
5209 Like "SvPV_force", but converts sv to utf8 first if necessary.
5210 char* SvPVutf8_force(SV* sv, STRLEN len)
5212 SvPVutf8_nolen
5214 Like "SvPV_nolen", but converts sv to utf8 first if necessary.
5215 char* SvPVutf8_nolen(SV* sv)
5217 SvPVX Returns a pointer to the physical string in the SV. The SV
5219 must contain a string.
5220 This is also used to store the name of an autoloaded subroutine
5222 in an XS AUTOLOAD routine. See "Autoloading with XSUBs" in
5223 perlguts.
5224 char* SvPVX(SV* sv)
5226 SvPVx A version of "SvPV" which guarantees to evaluate "sv" only
5228 once. Only use this if "sv" is an expression with side
5229 effects, otherwise use the more efficient "SvPV".
5230 char* SvPVx(SV* sv, STRLEN len)
5232 SvPV_force
5234 Like "SvPV" but will force the SV into containing just a string
5235 ("SvPOK_only"). You want force if you are going to update the
5236 "SvPVX" directly.
5237 char* SvPV_force(SV* sv, STRLEN len)
5239 SvPV_force_nomg
5241 Like "SvPV" but will force the SV into containing just a string
5242 ("SvPOK_only"). You want force if you are going to update the
5243 "SvPVX" directly. Doesn't process magic.
5244 char* SvPV_force_nomg(SV* sv, STRLEN len)
5246 SvPV_nolen
5248 Returns a pointer to the string in the SV, or a stringified
5249 form of the SV if the SV does not contain a string. The SV may
5250 cache the stringified form becoming "SvPOK". Handles 'get'
5251 magic.
5252 char* SvPV_nolen(SV* sv)
5254 SvPV_nomg
5256 Like "SvPV" but doesn't process magic.
5257 char* SvPV_nomg(SV* sv, STRLEN len)
5259 SvPV_nomg_nolen
5261 Like "SvPV_nolen" but doesn't process magic.
5262 char* SvPV_nomg_nolen(SV* sv)
5264 SvPV_set
5266 Set the value of the PV pointer in sv to val. See "SvIV_set".
5267 void SvPV_set(SV* sv, char* val)
5269 SvREFCNT
5271 Returns the value of the object's reference count.
5272 U32 SvREFCNT(SV* sv)
5274 SvREFCNT_dec
5276 Decrements the reference count of the given SV.
5277 void SvREFCNT_dec(SV* sv)
5279 SvREFCNT_inc
5281 Increments the reference count of the given SV.
5282 All of the following SvREFCNT_inc* macros are optimized
5284 versions of SvREFCNT_inc, and can be replaced with
5285 SvREFCNT_inc.
5286 SV* SvREFCNT_inc(SV* sv)
5288 SvREFCNT_inc_NN
5290 Same as SvREFCNT_inc, but can only be used if you know sv is
5291 not NULL. Since we don't have to check the NULLness, it's
5292 faster and smaller.
5293 SV* SvREFCNT_inc_NN(SV* sv)
5295 SvREFCNT_inc_simple
5297 Same as SvREFCNT_inc, but can only be used with expressions
5298 without side effects. Since we don't have to store a temporary
5299 value, it's faster.
5300 SV* SvREFCNT_inc_simple(SV* sv)
5302 SvREFCNT_inc_simple_NN
5304 Same as SvREFCNT_inc_simple, but can only be used if you know
5305 sv is not NULL. Since we don't have to check the NULLness,
5306 it's faster and smaller.
5307 SV* SvREFCNT_inc_simple_NN(SV* sv)
5309 SvREFCNT_inc_simple_void
5311 Same as SvREFCNT_inc_simple, but can only be used if you don't
5312 need the return value. The macro doesn't need to return a
5313 meaningful value.
5314 void SvREFCNT_inc_simple_void(SV* sv)
5316 SvREFCNT_inc_simple_void_NN
5318 Same as SvREFCNT_inc, but can only be used if you don't need
5319 the return value, and you know that sv is not NULL. The macro
5320 doesn't need to return a meaningful value, or check for
5321 NULLness, so it's smaller and faster.
5322 void SvREFCNT_inc_simple_void_NN(SV* sv)
5324 SvREFCNT_inc_void
5326 Same as SvREFCNT_inc, but can only be used if you don't need
5327 the return value. The macro doesn't need to return a
5328 meaningful value.
5329 void SvREFCNT_inc_void(SV* sv)
5331 SvREFCNT_inc_void_NN
5333 Same as SvREFCNT_inc, but can only be used if you don't need
5334 the return value, and you know that sv is not NULL. The macro
5335 doesn't need to return a meaningful value, or check for
5336 NULLness, so it's smaller and faster.
5337 void SvREFCNT_inc_void_NN(SV* sv)
5339 SvROK Tests if the SV is an RV.
5341 U32 SvROK(SV* sv)
5343 SvROK_off
5345 Unsets the RV status of an SV.
5346 void SvROK_off(SV* sv)
5348 SvROK_on
5350 Tells an SV that it is an RV.
5351 void SvROK_on(SV* sv)
5353 SvRV Dereferences an RV to return the SV.
5355 SV* SvRV(SV* sv)
5357 SvRV_set
5359 Set the value of the RV pointer in sv to val. See "SvIV_set".
5360 void SvRV_set(SV* sv, SV* val)
5362 SvSTASH Returns the stash of the SV.
5364 HV* SvSTASH(SV* sv)
5366 SvSTASH_set
5368 Set the value of the STASH pointer in sv to val. See
5369 "SvIV_set".
5370 void SvSTASH_set(SV* sv, HV* val)
5372 SvTAINT Taints an SV if tainting is enabled, and if some input to the
5374 current expression is tainted--usually a variable, but possibly
5375 also implicit inputs such as locale settings. "SvTAINT"
5376 propagates that taintedness to the outputs of an expression in
5377 a pessimistic fashion; i.e., without paying attention to
5378 precisely which outputs are influenced by which inputs.
5379 void SvTAINT(SV* sv)
5381 SvTAINTED
5383 Checks to see if an SV is tainted. Returns TRUE if it is,
5384 FALSE if not.
5385 bool SvTAINTED(SV* sv)
5387 SvTAINTED_off
5389 Untaints an SV. Be very careful with this routine, as it
5390 short-circuits some of Perl's fundamental security features.
5391 XS module authors should not use this function unless they
5392 fully understand all the implications of unconditionally
5393 untainting the value. Untainting should be done in the standard
5394 perl fashion, via a carefully crafted regexp, rather than
5395 directly untainting variables.
5396 void SvTAINTED_off(SV* sv)
5398 SvTAINTED_on
5400 Marks an SV as tainted if tainting is enabled.
5401 void SvTAINTED_on(SV* sv)
5403 SvTRUE Returns a boolean indicating whether Perl would evaluate the SV
5405 as true or false. See SvOK() for a defined/undefined test.
5406 Handles 'get' magic unless the scalar is already SvPOK, SvIOK
5407 or SvNOK (the public, not the private flags).
5408 bool SvTRUE(SV* sv)
5410 SvTRUE_nomg
5412 Returns a boolean indicating whether Perl would evaluate the SV
5413 as true or false. See SvOK() for a defined/undefined test.
5414 Does not handle 'get' magic.
5415 bool SvTRUE_nomg(SV* sv)
5417 SvTYPE Returns the type of the SV. See "svtype".
5419 svtype SvTYPE(SV* sv)
5421 SvUOK Returns a boolean indicating whether the SV contains an
5423 unsigned integer.
5424 bool SvUOK(SV* sv)
5426 SvUPGRADE
5428 Used to upgrade an SV to a more complex form. Uses
5429 "sv_upgrade" to perform the upgrade if necessary. See
5430 "svtype".
5431 void SvUPGRADE(SV* sv, svtype type)
5433 SvUTF8 Returns a U32 value indicating the UTF-8 status of an SV. If
5435 things are set-up properly, this indicates whether or not the
5436 SV contains UTF-8 encoded data. Call this after SvPV() in case
5437 any call to string overloading updates the internal flag.
5438 U32 SvUTF8(SV* sv)
5440 SvUTF8_off
5442 Unsets the UTF-8 status of an SV (the data is not changed, just
5443 the flag). Do not use frivolously.
5444 void SvUTF8_off(SV *sv)
5446 SvUTF8_on
5448 Turn on the UTF-8 status of an SV (the data is not changed,
5449 just the flag). Do not use frivolously.
5450 void SvUTF8_on(SV *sv)
5452 SvUV Coerces the given SV to an unsigned integer and returns it.
5454 See "SvUVx" for a version which guarantees to evaluate sv only
5455 once.
5456 UV SvUV(SV* sv)
5458 SvUVX Returns the raw value in the SV's UV slot, without checks or
5460 conversions. Only use when you are sure SvIOK is true. See
5461 also "SvUV()".
5462 UV SvUVX(SV* sv)
5464 SvUVx Coerces the given SV to an unsigned integer and returns it.
5466 Guarantees to "sv" only once. Only use this if "sv" is an
5467 expression with side effects, otherwise use the more efficient
5468 "SvUV".
5469 UV SvUVx(SV* sv)
5471 SvUV_nomg
5473 Like "SvUV" but doesn't process magic.
5474 UV SvUV_nomg(SV* sv)
5476 SvUV_set
5478 Set the value of the UV pointer in sv to val. See "SvIV_set".
5479 void SvUV_set(SV* sv, UV val)
5481 SvVOK Returns a boolean indicating whether the SV contains a
5483 v-string.
5484 bool SvVOK(SV* sv)
5486 sv_catpvn_nomg
5488 Like "sv_catpvn" but doesn't process magic.
5489 void sv_catpvn_nomg(SV* sv, const char* ptr,
5491 STRLEN len)
5492 sv_catpv_nomg
5494 Like "sv_catpv" but doesn't process magic.
5495 void sv_catpv_nomg(SV* sv, const char* ptr)
5497 sv_catsv_nomg
5499 Like "sv_catsv" but doesn't process magic.
5500 void sv_catsv_nomg(SV* dsv, SV* ssv)
5502 sv_derived_from
5504 Exactly like "sv_derived_from_pv", but doesn't take a "flags"
5505 parameter.
5506 bool sv_derived_from(SV* sv, const char *const name)
5508 sv_derived_from_pv
5510 Exactly like "sv_derived_from_pvn", but takes a nul-terminated
5511 string instead of a string/length pair.
5512 bool sv_derived_from_pv(SV* sv,
5514 const char *const name,
5515 U32 flags)
5516 sv_derived_from_pvn
5518 Returns a boolean indicating whether the SV is derived from the
5519 specified class at the C level. To check derivation at the
5520 Perl level, call "isa()" as a normal Perl method.
5521 Currently, the only significant value for "flags" is SVf_UTF8.
5523 bool sv_derived_from_pvn(SV* sv,
5525 const char *const name,
5526 const STRLEN len, U32 flags)
5527 sv_derived_from_sv
5529 Exactly like "sv_derived_from_pvn", but takes the name string
5530 in the form of an SV instead of a string/length pair.
5531 bool sv_derived_from_sv(SV* sv, SV *namesv,
5533 U32 flags)
5534 sv_does Like "sv_does_pv", but doesn't take a "flags" parameter.
5536 bool sv_does(SV* sv, const char *const name)
5538 sv_does_pv
5540 Like "sv_does_sv", but takes a nul-terminated string instead of
5541 an SV.
5542 bool sv_does_pv(SV* sv, const char *const name,
5544 U32 flags)
5545 sv_does_pvn
5547 Like "sv_does_sv", but takes a string/length pair instead of an
5548 SV.
5549 bool sv_does_pvn(SV* sv, const char *const name,
5551 const STRLEN len, U32 flags)
5552 sv_does_sv
5554 Returns a boolean indicating whether the SV performs a
5555 specific, named role. The SV can be a Perl object or the name
5556 of a Perl class.
5557 bool sv_does_sv(SV* sv, SV* namesv, U32 flags)
5559 sv_report_used
5561 Dump the contents of all SVs not yet freed (debugging aid).
5562 void sv_report_used()
5564 sv_setsv_nomg
5566 Like "sv_setsv" but doesn't process magic.
5567 void sv_setsv_nomg(SV* dsv, SV* ssv)
5569 sv_utf8_upgrade_nomg
5571 Like sv_utf8_upgrade, but doesn't do magic on "sv".
5572 STRLEN sv_utf8_upgrade_nomg(NN SV *sv)
5574
5576 looks_like_number
5577 Test if the content of an SV looks like a number (or is a
5578 number). "Inf" and "Infinity" are treated as numbers (so will
5579 not issue a non-numeric warning), even if your atof() doesn't
5580 grok them. Get-magic is ignored.
5581 I32 looks_like_number(SV *const sv)
5583 newRV_noinc
5585 Creates an RV wrapper for an SV. The reference count for the
5586 original SV is not incremented.
5587 SV* newRV_noinc(SV *const sv)
5589 newSV Creates a new SV. A non-zero "len" parameter indicates the
5591 number of bytes of preallocated string space the SV should
5592 have. An extra byte for a trailing NUL is also reserved.
5593 (SvPOK is not set for the SV even if string space is
5594 allocated.) The reference count for the new SV is set to 1.
5595 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the
5597 first parameter, x, a debug aid which allowed callers to
5598 identify themselves. This aid has been superseded by a new
5599 build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in
5600 perlhacktips). The older API is still there for use in XS
5601 modules supporting older perls.
5602 SV* newSV(const STRLEN len)
5604 newSVhek
5606 Creates a new SV from the hash key structure. It will generate
5607 scalars that point to the shared string table where possible.
5608 Returns a new (undefined) SV if the hek is NULL.
5609 SV* newSVhek(const HEK *const hek)
5611 newSViv Creates a new SV and copies an integer into it. The reference
5613 count for the SV is set to 1.
5614 SV* newSViv(const IV i)
5616 newSVnv Creates a new SV and copies a floating point value into it.
5618 The reference count for the SV is set to 1.
5619 SV* newSVnv(const NV n)
5621 newSVpv Creates a new SV and copies a string into it. The reference
5623 count for the SV is set to 1. If "len" is zero, Perl will
5624 compute the length using strlen(). For efficiency, consider
5625 using "newSVpvn" instead.
5626 SV* newSVpv(const char *const s, const STRLEN len)
5628 newSVpvf
5630 Creates a new SV and initializes it with the string formatted
5631 like "sprintf".
5632 SV* newSVpvf(const char *const pat, ...)
5634 newSVpvn
5636 Creates a new SV and copies a buffer into it, which may contain
5637 NUL characters ("\0") and other binary data. The reference
5638 count for the SV is set to 1. Note that if "len" is zero, Perl
5639 will create a zero length (Perl) string. You are responsible
5640 for ensuring that the source buffer is at least "len" bytes
5641 long. If the "buffer" argument is NULL the new SV will be
5642 undefined.
5643 SV* newSVpvn(const char *const s, const STRLEN len)
5645 newSVpvn_flags
5647 Creates a new SV and copies a string into it. The reference
5648 count for the SV is set to 1. Note that if "len" is zero, Perl
5649 will create a zero length string. You are responsible for
5650 ensuring that the source string is at least "len" bytes long.
5651 If the "s" argument is NULL the new SV will be undefined.
5652 Currently the only flag bits accepted are "SVf_UTF8" and
5653 "SVs_TEMP". If "SVs_TEMP" is set, then "sv_2mortal()" is
5654 called on the result before returning. If "SVf_UTF8" is set,
5655 "s" is considered to be in UTF-8 and the "SVf_UTF8" flag will
5656 be set on the new SV. "newSVpvn_utf8()" is a convenience
5657 wrapper for this function, defined as
5658 #define newSVpvn_utf8(s, len, u) \
5660 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
5661 SV* newSVpvn_flags(const char *const s,
5663 const STRLEN len,
5664 const U32 flags)
5665 newSVpvn_share
5667 Creates a new SV with its SvPVX_const pointing to a shared
5668 string in the string table. If the string does not already
5669 exist in the table, it is created first. Turns on READONLY and
5670 FAKE. If the "hash" parameter is non-zero, that value is used;
5671 otherwise the hash is computed. The string's hash can later be
5672 retrieved from the SV with the "SvSHARED_HASH()" macro. The
5673 idea here is that as the string table is used for shared hash
5674 keys these strings will have SvPVX_const == HeKEY and hash
5675 lookup will avoid string compare.
5676 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
5678 newSVpvs
5680 Like "newSVpvn", but takes a literal string instead of a
5681 string/length pair.
5682 SV* newSVpvs(const char* s)
5684 newSVpvs_flags
5686 Like "newSVpvn_flags", but takes a literal string instead of a
5687 string/length pair.
5688 SV* newSVpvs_flags(const char* s, U32 flags)
5690 newSVpvs_share
5692 Like "newSVpvn_share", but takes a literal string instead of a
5693 string/length pair and omits the hash parameter.
5694 SV* newSVpvs_share(const char* s)
5696 newSVpv_share
5698 Like "newSVpvn_share", but takes a nul-terminated string
5699 instead of a string/length pair.
5700 SV* newSVpv_share(const char* s, U32 hash)
5702 newSVrv Creates a new SV for the RV, "rv", to point to. If "rv" is not
5704 an RV then it will be upgraded to one. If "classname" is non-
5705 null then the new SV will be blessed in the specified package.
5706 The new SV is returned and its reference count is 1.
5707 SV* newSVrv(SV *const rv,
5709 const char *const classname)
5710 newSVsv Creates a new SV which is an exact duplicate of the original
5712 SV. (Uses "sv_setsv".)
5713 SV* newSVsv(SV *const old)
5715 newSVuv Creates a new SV and copies an unsigned integer into it. The
5717 reference count for the SV is set to 1.
5718 SV* newSVuv(const UV u)
5720 newSV_type
5722 Creates a new SV, of the type specified. The reference count
5723 for the new SV is set to 1.
5724 SV* newSV_type(const svtype type)
5726 sv_2bool
5728 This macro is only used by sv_true() or its macro equivalent,
5729 and only if the latter's argument is neither SvPOK, SvIOK nor
5730 SvNOK. It calls sv_2bool_flags with the SV_GMAGIC flag.
5731 bool sv_2bool(SV *const sv)
5733 sv_2bool_flags
5735 This function is only used by sv_true() and friends, and only
5736 if the latter's argument is neither SvPOK, SvIOK nor SvNOK. If
5737 the flags contain SV_GMAGIC, then it does an mg_get() first.
5738 bool sv_2bool_flags(SV *const sv, const I32 flags)
5740 sv_2cv Using various gambits, try to get a CV from an SV; in addition,
5742 try if possible to set *st and *gvp to the stash and GV
5743 associated with it. The flags in "lref" are passed to
5744 gv_fetchsv.
5745 CV* sv_2cv(SV* sv, HV **const st, GV **const gvp,
5747 const I32 lref)
5748 sv_2io Using various gambits, try to get an IO from an SV: the IO slot
5750 if its a GV; or the recursive result if we're an RV; or the IO
5751 slot of the symbol named after the PV if we're a string.
5752 'Get' magic is ignored on the sv passed in, but will be called
5754 on "SvRV(sv)" if sv is an RV.
5755 IO* sv_2io(SV *const sv)
5757 sv_2iv_flags
5759 Return the integer value of an SV, doing any necessary string
5760 conversion. If flags includes SV_GMAGIC, does an mg_get()
5761 first. Normally used via the "SvIV(sv)" and "SvIVx(sv)"
5762 macros.
5763 IV sv_2iv_flags(SV *const sv, const I32 flags)
5765 sv_2mortal
5767 Marks an existing SV as mortal. The SV will be destroyed
5768 "soon", either by an explicit call to FREETMPS, or by an
5769 implicit call at places such as statement boundaries. SvTEMP()
5770 is turned on which means that the SV's string buffer can be
5771 "stolen" if this SV is copied. See also "sv_newmortal" and
5772 "sv_mortalcopy".
5773 SV* sv_2mortal(SV *const sv)
5775 sv_2nv_flags
5777 Return the num value of an SV, doing any necessary string or
5778 integer conversion. If flags includes SV_GMAGIC, does an
5779 mg_get() first. Normally used via the "SvNV(sv)" and
5780 "SvNVx(sv)" macros.
5781 NV sv_2nv_flags(SV *const sv, const I32 flags)
5783 sv_2pvbyte
5785 Return a pointer to the byte-encoded representation of the SV,
5786 and set *lp to its length. May cause the SV to be downgraded
5787 from UTF-8 as a side-effect.
5788 Usually accessed via the "SvPVbyte" macro.
5790 char* sv_2pvbyte(SV *sv, STRLEN *const lp)
5792 sv_2pvutf8
5794 Return a pointer to the UTF-8-encoded representation of the SV,
5795 and set *lp to its length. May cause the SV to be upgraded to
5796 UTF-8 as a side-effect.
5797 Usually accessed via the "SvPVutf8" macro.
5799 char* sv_2pvutf8(SV *sv, STRLEN *const lp)
5801 sv_2pv_flags
5803 Returns a pointer to the string value of an SV, and sets *lp to
5804 its length. If flags includes SV_GMAGIC, does an mg_get()
5805 first. Coerces sv to a string if necessary. Normally invoked
5806 via the "SvPV_flags" macro. "sv_2pv()" and "sv_2pv_nomg"
5807 usually end up here too.
5808 char* sv_2pv_flags(SV *const sv, STRLEN *const lp,
5810 const I32 flags)
5811 sv_2uv_flags
5813 Return the unsigned integer value of an SV, doing any necessary
5814 string conversion. If flags includes SV_GMAGIC, does an
5815 mg_get() first. Normally used via the "SvUV(sv)" and
5816 "SvUVx(sv)" macros.
5817 UV sv_2uv_flags(SV *const sv, const I32 flags)
5819 sv_backoff
5821 Remove any string offset. You should normally use the
5822 "SvOOK_off" macro wrapper instead.
5823 int sv_backoff(SV *const sv)
5825 sv_bless
5827 Blesses an SV into a specified package. The SV must be an RV.
5828 The package must be designated by its stash (see
5829 "gv_stashpv()"). The reference count of the SV is unaffected.
5830 SV* sv_bless(SV *const sv, HV *const stash)
5832 sv_catpv
5834 Concatenates the string onto the end of the string which is in
5835 the SV. If the SV has the UTF-8 status set, then the bytes
5836 appended should be valid UTF-8. Handles 'get' magic, but not
5837 'set' magic. See "sv_catpv_mg".
5838 void sv_catpv(SV *const sv, const char* ptr)
5840 sv_catpvf
5842 Processes its arguments like "sprintf" and appends the
5843 formatted output to an SV. If the appended data contains
5844 "wide" characters (including, but not limited to, SVs with a
5845 UTF-8 PV formatted with %s, and characters >255 formatted with
5846 %c), the original SV might get upgraded to UTF-8. Handles
5847 'get' magic, but not 'set' magic. See "sv_catpvf_mg". If the
5848 original SV was UTF-8, the pattern should be valid UTF-8; if
5849 the original SV was bytes, the pattern should be too.
5850 void sv_catpvf(SV *const sv, const char *const pat,
5852 ...)
5853 sv_catpvf_mg
5855 Like "sv_catpvf", but also handles 'set' magic.
5856 void sv_catpvf_mg(SV *const sv,
5858 const char *const pat, ...)
5859 sv_catpvn
5861 Concatenates the string onto the end of the string which is in
5862 the SV. The "len" indicates number of bytes to copy. If the
5863 SV has the UTF-8 status set, then the bytes appended should be
5864 valid UTF-8. Handles 'get' magic, but not 'set' magic. See
5865 "sv_catpvn_mg".
5866 void sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
5868 sv_catpvn_flags
5870 Concatenates the string onto the end of the string which is in
5871 the SV. The "len" indicates number of bytes to copy. If the
5872 SV has the UTF-8 status set, then the bytes appended should be
5873 valid UTF-8. If "flags" has the "SV_SMAGIC" bit set, will
5874 "mg_set" on "dsv" afterwards if appropriate. "sv_catpvn" and
5875 "sv_catpvn_nomg" are implemented in terms of this function.
5876 void sv_catpvn_flags(SV *const dstr,
5878 const char *sstr,
5879 const STRLEN len,
5880 const I32 flags)
5881 sv_catpvs
5883 Like "sv_catpvn", but takes a literal string instead of a
5884 string/length pair.
5885 void sv_catpvs(SV* sv, const char* s)
5887 sv_catpvs_flags
5889 Like "sv_catpvn_flags", but takes a literal string instead of a
5890 string/length pair.
5891 void sv_catpvs_flags(SV* sv, const char* s,
5893 I32 flags)
5894 sv_catpvs_mg
5896 Like "sv_catpvn_mg", but takes a literal string instead of a
5897 string/length pair.
5898 void sv_catpvs_mg(SV* sv, const char* s)
5900 sv_catpvs_nomg
5902 Like "sv_catpvn_nomg", but takes a literal string instead of a
5903 string/length pair.
5904 void sv_catpvs_nomg(SV* sv, const char* s)
5906 sv_catpv_flags
5908 Concatenates the string onto the end of the string which is in
5909 the SV. If the SV has the UTF-8 status set, then the bytes
5910 appended should be valid UTF-8. If "flags" has the "SV_SMAGIC"
5911 bit set, will "mg_set" on the modified SV if appropriate.
5912 void sv_catpv_flags(SV *dstr, const char *sstr,
5914 const I32 flags)
5915 sv_catpv_mg
5917 Like "sv_catpv", but also handles 'set' magic.
5918 void sv_catpv_mg(SV *const sv, const char *const ptr)
5920 sv_catsv
5922 Concatenates the string from SV "ssv" onto the end of the
5923 string in SV "dsv". Modifies "dsv" but not "ssv". Handles
5924 'get' magic, but not 'set' magic. See "sv_catsv_mg".
5925 void sv_catsv(SV *dstr, SV *sstr)
5927 sv_catsv_flags
5929 Concatenates the string from SV "ssv" onto the end of the
5930 string in SV "dsv". Modifies "dsv" but not "ssv". If "flags"
5931 has "SV_GMAGIC" bit set, will "mg_get" on the "ssv", if
5932 appropriate, before reading it. If the "flags" contain
5933 "SV_SMAGIC", "mg_set" will be called on the modified SV
5934 afterward, if appropriate. "sv_catsv" and "sv_catsv_nomg" are
5935 implemented in terms of this function.
5936 void sv_catsv_flags(SV *const dsv, SV *const ssv,
5938 const I32 flags)
5939 sv_chop Efficient removal of characters from the beginning of the
5941 string buffer. SvPOK(sv) must be true and the "ptr" must be a
5942 pointer to somewhere inside the string buffer. The "ptr"
5943 becomes the first character of the adjusted string. Uses the
5944 "OOK hack".
5945 Beware: after this function returns, "ptr" and SvPVX_const(sv)
5947 may no longer refer to the same chunk of data.
5948 The unfortunate similarity of this function's name to that of
5950 Perl's "chop" operator is strictly coincidental. This function
5951 works from the left; "chop" works from the right.
5952 void sv_chop(SV *const sv, const char *const ptr)
5954 sv_clear
5956 Clear an SV: call any destructors, free up any memory used by
5957 the body, and free the body itself. The SV's head is not
5958 freed, although its type is set to all 1's so that it won't
5959 inadvertently be assumed to be live during global destruction
5960 etc. This function should only be called when REFCNT is zero.
5961 Most of the time you'll want to call "sv_free()" (or its macro
5962 wrapper "SvREFCNT_dec") instead.
5963 void sv_clear(SV *const orig_sv)
5965 sv_cmp Compares the strings in two SVs. Returns -1, 0, or 1
5967 indicating whether the string in "sv1" is less than, equal to,
5968 or greater than the string in "sv2". Is UTF-8 and 'use bytes'
5969 aware, handles get magic, and will coerce its args to strings
5970 if necessary. See also "sv_cmp_locale".
5971 I32 sv_cmp(SV *const sv1, SV *const sv2)
5973 sv_cmp_flags
5975 Compares the strings in two SVs. Returns -1, 0, or 1
5976 indicating whether the string in "sv1" is less than, equal to,
5977 or greater than the string in "sv2". Is UTF-8 and 'use bytes'
5978 aware and will coerce its args to strings if necessary. If the
5979 flags include SV_GMAGIC, it handles get magic. See also
5980 "sv_cmp_locale_flags".
5981 I32 sv_cmp_flags(SV *const sv1, SV *const sv2,
5983 const U32 flags)
5984 sv_cmp_locale
5986 Compares the strings in two SVs in a locale-aware manner. Is
5987 UTF-8 and 'use bytes' aware, handles get magic, and will coerce
5988 its args to strings if necessary. See also "sv_cmp".
5989 I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
5991 sv_cmp_locale_flags
5993 Compares the strings in two SVs in a locale-aware manner. Is
5994 UTF-8 and 'use bytes' aware and will coerce its args to strings
5995 if necessary. If the flags contain SV_GMAGIC, it handles get
5996 magic. See also "sv_cmp_flags".
5997 I32 sv_cmp_locale_flags(SV *const sv1,
5999 SV *const sv2,
6000 const U32 flags)
6001 sv_collxfrm
6003 This calls "sv_collxfrm_flags" with the SV_GMAGIC flag. See
6004 "sv_collxfrm_flags".
6005 char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
6007 sv_collxfrm_flags
6009 Add Collate Transform magic to an SV if it doesn't already have
6010 it. If the flags contain SV_GMAGIC, it handles get-magic.
6011 Any scalar variable may carry PERL_MAGIC_collxfrm magic that
6013 contains the scalar data of the variable, but transformed to
6014 such a format that a normal memory comparison can be used to
6015 compare the data according to the locale settings.
6016 char* sv_collxfrm_flags(SV *const sv,
6018 STRLEN *const nxp,
6019 I32 const flags)
6020 sv_copypv
6022 Copies a stringified representation of the source SV into the
6023 destination SV. Automatically performs any necessary mg_get
6024 and coercion of numeric values into strings. Guaranteed to
6025 preserve UTF8 flag even from overloaded objects. Similar in
6026 nature to sv_2pv[_flags] but operates directly on an SV instead
6027 of just the string. Mostly uses sv_2pv_flags to do its work,
6028 except when that would lose the UTF-8'ness of the PV.
6029 void sv_copypv(SV *const dsv, SV *const ssv)
6031 sv_dec Auto-decrement of the value in the SV, doing string to numeric
6033 conversion if necessary. Handles 'get' magic and operator
6034 overloading.
6035 void sv_dec(SV *const sv)
6037 sv_dec_nomg
6039 Auto-decrement of the value in the SV, doing string to numeric
6040 conversion if necessary. Handles operator overloading. Skips
6041 handling 'get' magic.
6042 void sv_dec_nomg(SV *const sv)
6044 sv_eq Returns a boolean indicating whether the strings in the two SVs
6046 are identical. Is UTF-8 and 'use bytes' aware, handles get
6047 magic, and will coerce its args to strings if necessary.
6048 I32 sv_eq(SV* sv1, SV* sv2)
6050 sv_eq_flags
6052 Returns a boolean indicating whether the strings in the two SVs
6053 are identical. Is UTF-8 and 'use bytes' aware and coerces its
6054 args to strings if necessary. If the flags include SV_GMAGIC,
6055 it handles get-magic, too.
6056 I32 sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)
6058 sv_force_normal_flags
6060 Undo various types of fakery on an SV: if the PV is a shared
6061 string, make a private copy; if we're a ref, stop refing; if
6062 we're a glob, downgrade to an xpvmg; if we're a copy-on-write
6063 scalar, this is the on-write time when we do the copy, and is
6064 also used locally. If "SV_COW_DROP_PV" is set then a copy-on-
6065 write scalar drops its PV buffer (if any) and becomes SvPOK_off
6066 rather than making a copy. (Used where this scalar is about to
6067 be set to some other value.) In addition, the "flags"
6068 parameter gets passed to "sv_unref_flags()" when unreffing.
6069 "sv_force_normal" calls this function with flags set to 0.
6070 void sv_force_normal_flags(SV *const sv,
6072 const U32 flags)
6073 sv_free Decrement an SV's reference count, and if it drops to zero,
6075 call "sv_clear" to invoke destructors and free up any memory
6076 used by the body; finally, deallocate the SV's head itself.
6077 Normally called via a wrapper macro "SvREFCNT_dec".
6078 void sv_free(SV *const sv)
6080 sv_gets Get a line from the filehandle and store it into the SV,
6082 optionally appending to the currently-stored string.
6083 char* sv_gets(SV *const sv, PerlIO *const fp,
6085 I32 append)
6086 sv_grow Expands the character buffer in the SV. If necessary, uses
6088 "sv_unref" and upgrades the SV to "SVt_PV". Returns a pointer
6089 to the character buffer. Use the "SvGROW" wrapper instead.
6090 char* sv_grow(SV *const sv, STRLEN newlen)
6092 sv_inc Auto-increment of the value in the SV, doing string to numeric
6094 conversion if necessary. Handles 'get' magic and operator
6095 overloading.
6096 void sv_inc(SV *const sv)
6098 sv_inc_nomg
6100 Auto-increment of the value in the SV, doing string to numeric
6101 conversion if necessary. Handles operator overloading. Skips
6102 handling 'get' magic.
6103 void sv_inc_nomg(SV *const sv)
6105 sv_insert
6107 Inserts a string at the specified offset/length within the SV.
6108 Similar to the Perl substr() function. Handles get magic.
6109 void sv_insert(SV *const bigstr, const STRLEN offset,
6111 const STRLEN len,
6112 const char *const little,
6113 const STRLEN littlelen)
6114 sv_insert_flags
6116 Same as "sv_insert", but the extra "flags" are passed to the
6117 "SvPV_force_flags" that applies to "bigstr".
6118 void sv_insert_flags(SV *const bigstr,
6120 const STRLEN offset,
6121 const STRLEN len,
6122 const char *const little,
6123 const STRLEN littlelen,
6124 const U32 flags)
6125 sv_isa Returns a boolean indicating whether the SV is blessed into the
6127 specified class. This does not check for subtypes; use
6128 "sv_derived_from" to verify an inheritance relationship.
6129 int sv_isa(SV* sv, const char *const name)
6131 sv_isobject
6133 Returns a boolean indicating whether the SV is an RV pointing
6134 to a blessed object. If the SV is not an RV, or if the object
6135 is not blessed, then this will return false.
6136 int sv_isobject(SV* sv)
6138 sv_len Returns the length of the string in the SV. Handles magic and
6140 type coercion. See also "SvCUR", which gives raw access to the
6141 xpv_cur slot.
6142 STRLEN sv_len(SV *const sv)
6144 sv_len_utf8
6146 Returns the number of characters in the string in an SV,
6147 counting wide UTF-8 bytes as a single character. Handles magic
6148 and type coercion.
6149 STRLEN sv_len_utf8(SV *const sv)
6151 sv_magic
6153 Adds magic to an SV. First upgrades "sv" to type "SVt_PVMG" if
6154 necessary, then adds a new magic item of type "how" to the head
6155 of the magic list.
6156 See "sv_magicext" (which "sv_magic" now calls) for a
6158 description of the handling of the "name" and "namlen"
6159 arguments.
6160 You need to use "sv_magicext" to add magic to SvREADONLY SVs
6162 and also to add more than one instance of the same 'how'.
6163 void sv_magic(SV *const sv, SV *const obj,
6165 const int how, const char *const name,
6166 const I32 namlen)
6167 sv_magicext
6169 Adds magic to an SV, upgrading it if necessary. Applies the
6170 supplied vtable and returns a pointer to the magic added.
6171 Note that "sv_magicext" will allow things that "sv_magic" will
6173 not. In particular, you can add magic to SvREADONLY SVs, and
6174 add more than one instance of the same 'how'.
6175 If "namlen" is greater than zero then a "savepvn" copy of
6177 "name" is stored, if "namlen" is zero then "name" is stored as-
6178 is and - as another special case - if "(name && namlen ==
6179 HEf_SVKEY)" then "name" is assumed to contain an "SV*" and is
6180 stored as-is with its REFCNT incremented.
6181 (This is now used as a subroutine by "sv_magic".)
6183 MAGIC * sv_magicext(SV *const sv, SV *const obj,
6185 const int how,
6186 const MGVTBL *const vtbl,
6187 const char *const name,
6188 const I32 namlen)
6189 sv_mortalcopy
6191 Creates a new SV which is a copy of the original SV (using
6192 "sv_setsv"). The new SV is marked as mortal. It will be
6193 destroyed "soon", either by an explicit call to FREETMPS, or by
6194 an implicit call at places such as statement boundaries. See
6195 also "sv_newmortal" and "sv_2mortal".
6196 SV* sv_mortalcopy(SV *const oldsv)
6198 sv_newmortal
6200 Creates a new null SV which is mortal. The reference count of
6201 the SV is set to 1. It will be destroyed "soon", either by an
6202 explicit call to FREETMPS, or by an implicit call at places
6203 such as statement boundaries. See also "sv_mortalcopy" and
6204 "sv_2mortal".
6205 SV* sv_newmortal()
6207 sv_newref
6209 Increment an SV's reference count. Use the "SvREFCNT_inc()"
6210 wrapper instead.
6211 SV* sv_newref(SV *const sv)
6213 sv_pos_b2u
6215 Converts the value pointed to by offsetp from a count of bytes
6216 from the start of the string, to a count of the equivalent
6217 number of UTF-8 chars. Handles magic and type coercion.
6218 void sv_pos_b2u(SV *const sv, I32 *const offsetp)
6220 sv_pos_u2b
6222 Converts the value pointed to by offsetp from a count of UTF-8
6223 chars from the start of the string, to a count of the
6224 equivalent number of bytes; if lenp is non-zero, it does the
6225 same to lenp, but this time starting from the offset, rather
6226 than from the start of the string. Handles magic and type
6227 coercion.
6228 Use "sv_pos_u2b_flags" in preference, which correctly handles
6230 strings longer than 2Gb.
6231 void sv_pos_u2b(SV *const sv, I32 *const offsetp,
6233 I32 *const lenp)
6234 sv_pos_u2b_flags
6236 Converts the value pointed to by offsetp from a count of UTF-8
6237 chars from the start of the string, to a count of the
6238 equivalent number of bytes; if lenp is non-zero, it does the
6239 same to lenp, but this time starting from the offset, rather
6240 than from the start of the string. Handles type coercion.
6241 flags is passed to "SvPV_flags", and usually should be
6242 "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
6243 STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
6245 STRLEN *const lenp, U32 flags)
6246 sv_pvbyten_force
6248 The backend for the "SvPVbytex_force" macro. Always use the
6249 macro instead.
6250 char* sv_pvbyten_force(SV *const sv, STRLEN *const lp)
6252 sv_pvn_force
6254 Get a sensible string out of the SV somehow. A private
6255 implementation of the "SvPV_force" macro for compilers which
6256 can't cope with complex macro expressions. Always use the
6257 macro instead.
6258 char* sv_pvn_force(SV* sv, STRLEN* lp)
6260 sv_pvn_force_flags
6262 Get a sensible string out of the SV somehow. If "flags" has
6263 "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate, else
6264 not. "sv_pvn_force" and "sv_pvn_force_nomg" are implemented in
6265 terms of this function. You normally want to use the various
6266 wrapper macros instead: see "SvPV_force" and "SvPV_force_nomg"
6267 char* sv_pvn_force_flags(SV *const sv,
6269 STRLEN *const lp,
6270 const I32 flags)
6271 sv_pvutf8n_force
6273 The backend for the "SvPVutf8x_force" macro. Always use the
6274 macro instead.
6275 char* sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
6277 sv_reftype
6279 Returns a string describing what the SV is a reference to.
6280 const char* sv_reftype(const SV *const sv, const int ob)
6282 sv_replace
6284 Make the first argument a copy of the second, then delete the
6285 original. The target SV physically takes over ownership of the
6286 body of the source SV and inherits its flags; however, the
6287 target keeps any magic it owns, and any magic in the source is
6288 discarded. Note that this is a rather specialist SV copying
6289 operation; most of the time you'll want to use "sv_setsv" or
6290 one of its many macro front-ends.
6291 void sv_replace(SV *const sv, SV *const nsv)
6293 sv_reset
6295 Underlying implementation for the "reset" Perl function. Note
6296 that the perl-level function is vaguely deprecated.
6297 void sv_reset(const char* s, HV *const stash)
6299 sv_rvweaken
6301 Weaken a reference: set the "SvWEAKREF" flag on this RV; give
6302 the referred-to SV "PERL_MAGIC_backref" magic if it hasn't
6303 already; and push a back-reference to this RV onto the array of
6304 backreferences associated with that magic. If the RV is
6305 magical, set magic will be called after the RV is cleared.
6306 SV* sv_rvweaken(SV *const sv)
6308 sv_setiv
6310 Copies an integer into the given SV, upgrading first if
6311 necessary. Does not handle 'set' magic. See also
6312 "sv_setiv_mg".
6313 void sv_setiv(SV *const sv, const IV num)
6315 sv_setiv_mg
6317 Like "sv_setiv", but also handles 'set' magic.
6318 void sv_setiv_mg(SV *const sv, const IV i)
6320 sv_setnv
6322 Copies a double into the given SV, upgrading first if
6323 necessary. Does not handle 'set' magic. See also
6324 "sv_setnv_mg".
6325 void sv_setnv(SV *const sv, const NV num)
6327 sv_setnv_mg
6329 Like "sv_setnv", but also handles 'set' magic.
6330 void sv_setnv_mg(SV *const sv, const NV num)
6332 sv_setpv
6334 Copies a string into an SV. The string must be null-
6335 terminated. Does not handle 'set' magic. See "sv_setpv_mg".
6336 void sv_setpv(SV *const sv, const char *const ptr)
6338 sv_setpvf
6340 Works like "sv_catpvf" but copies the text into the SV instead
6341 of appending it. Does not handle 'set' magic. See
6342 "sv_setpvf_mg".
6343 void sv_setpvf(SV *const sv, const char *const pat,
6345 ...)
6346 sv_setpvf_mg
6348 Like "sv_setpvf", but also handles 'set' magic.
6349 void sv_setpvf_mg(SV *const sv,
6351 const char *const pat, ...)
6352 sv_setpviv
6354 Copies an integer into the given SV, also updating its string
6355 value. Does not handle 'set' magic. See "sv_setpviv_mg".
6356 void sv_setpviv(SV *const sv, const IV num)
6358 sv_setpviv_mg
6360 Like "sv_setpviv", but also handles 'set' magic.
6361 void sv_setpviv_mg(SV *const sv, const IV iv)
6363 sv_setpvn
6365 Copies a string into an SV. The "len" parameter indicates the
6366 number of bytes to be copied. If the "ptr" argument is NULL
6367 the SV will become undefined. Does not handle 'set' magic.
6368 See "sv_setpvn_mg".
6369 void sv_setpvn(SV *const sv, const char *const ptr,
6371 const STRLEN len)
6372 sv_setpvn_mg
6374 Like "sv_setpvn", but also handles 'set' magic.
6375 void sv_setpvn_mg(SV *const sv,
6377 const char *const ptr,
6378 const STRLEN len)
6379 sv_setpvs
6381 Like "sv_setpvn", but takes a literal string instead of a
6382 string/length pair.
6383 void sv_setpvs(SV* sv, const char* s)
6385 sv_setpvs_mg
6387 Like "sv_setpvn_mg", but takes a literal string instead of a
6388 string/length pair.
6389 void sv_setpvs_mg(SV* sv, const char* s)
6391 sv_setpv_mg
6393 Like "sv_setpv", but also handles 'set' magic.
6394 void sv_setpv_mg(SV *const sv, const char *const ptr)
6396 sv_setref_iv
6398 Copies an integer into a new SV, optionally blessing the SV.
6399 The "rv" argument will be upgraded to an RV. That RV will be
6400 modified to point to the new SV. The "classname" argument
6401 indicates the package for the blessing. Set "classname" to
6402 "NULL" to avoid the blessing. The new SV will have a reference
6403 count of 1, and the RV will be returned.
6404 SV* sv_setref_iv(SV *const rv,
6406 const char *const classname,
6407 const IV iv)
6408 sv_setref_nv
6410 Copies a double into a new SV, optionally blessing the SV. The
6411 "rv" argument will be upgraded to an RV. That RV will be
6412 modified to point to the new SV. The "classname" argument
6413 indicates the package for the blessing. Set "classname" to
6414 "NULL" to avoid the blessing. The new SV will have a reference
6415 count of 1, and the RV will be returned.
6416 SV* sv_setref_nv(SV *const rv,
6418 const char *const classname,
6419 const NV nv)
6420 sv_setref_pv
6422 Copies a pointer into a new SV, optionally blessing the SV.
6423 The "rv" argument will be upgraded to an RV. That RV will be
6424 modified to point to the new SV. If the "pv" argument is NULL
6425 then "PL_sv_undef" will be placed into the SV. The "classname"
6426 argument indicates the package for the blessing. Set
6427 "classname" to "NULL" to avoid the blessing. The new SV will
6428 have a reference count of 1, and the RV will be returned.
6429 Do not use with other Perl types such as HV, AV, SV, CV,
6431 because those objects will become corrupted by the pointer copy
6432 process.
6433 Note that "sv_setref_pvn" copies the string while this copies
6435 the pointer.
6436 SV* sv_setref_pv(SV *const rv,
6438 const char *const classname,
6439 void *const pv)
6440 sv_setref_pvn
6442 Copies a string into a new SV, optionally blessing the SV. The
6443 length of the string must be specified with "n". The "rv"
6444 argument will be upgraded to an RV. That RV will be modified
6445 to point to the new SV. The "classname" argument indicates the
6446 package for the blessing. Set "classname" to "NULL" to avoid
6447 the blessing. The new SV will have a reference count of 1, and
6448 the RV will be returned.
6449 Note that "sv_setref_pv" copies the pointer while this copies
6451 the string.
6452 SV* sv_setref_pvn(SV *const rv,
6454 const char *const classname,
6455 const char *const pv,
6456 const STRLEN n)
6457 sv_setref_pvs
6459 Like "sv_setref_pvn", but takes a literal string instead of a
6460 string/length pair.
6461 SV * sv_setref_pvs(const char* s)
6463 sv_setref_uv
6465 Copies an unsigned integer into a new SV, optionally blessing
6466 the SV. The "rv" argument will be upgraded to an RV. That RV
6467 will be modified to point to the new SV. The "classname"
6468 argument indicates the package for the blessing. Set
6469 "classname" to "NULL" to avoid the blessing. The new SV will
6470 have a reference count of 1, and the RV will be returned.
6471 SV* sv_setref_uv(SV *const rv,
6473 const char *const classname,
6474 const UV uv)
6475 sv_setsv
6477 Copies the contents of the source SV "ssv" into the destination
6478 SV "dsv". The source SV may be destroyed if it is mortal, so
6479 don't use this function if the source SV needs to be reused.
6480 Does not handle 'set' magic. Loosely speaking, it performs a
6481 copy-by-value, obliterating any previous content of the
6482 destination.
6483 You probably want to use one of the assortment of wrappers,
6485 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
6486 "SvSetMagicSV_nosteal".
6487 void sv_setsv(SV *dstr, SV *sstr)
6489 sv_setsv_flags
6491 Copies the contents of the source SV "ssv" into the destination
6492 SV "dsv". The source SV may be destroyed if it is mortal, so
6493 don't use this function if the source SV needs to be reused.
6494 Does not handle 'set' magic. Loosely speaking, it performs a
6495 copy-by-value, obliterating any previous content of the
6496 destination. If the "flags" parameter has the "SV_GMAGIC" bit
6497 set, will "mg_get" on "ssv" if appropriate, else not. If the
6498 "flags" parameter has the "NOSTEAL" bit set then the buffers of
6499 temps will not be stolen. <sv_setsv> and "sv_setsv_nomg" are
6500 implemented in terms of this function.
6501 You probably want to use one of the assortment of wrappers,
6503 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
6504 "SvSetMagicSV_nosteal".
6505 This is the primary function for copying scalars, and most
6507 other copy-ish functions and macros use this underneath.
6508 void sv_setsv_flags(SV *dstr, SV *sstr,
6510 const I32 flags)
6511 sv_setsv_mg
6513 Like "sv_setsv", but also handles 'set' magic.
6514 void sv_setsv_mg(SV *const dstr, SV *const sstr)
6516 sv_setuv
6518 Copies an unsigned integer into the given SV, upgrading first
6519 if necessary. Does not handle 'set' magic. See also
6520 "sv_setuv_mg".
6521 void sv_setuv(SV *const sv, const UV num)
6523 sv_setuv_mg
6525 Like "sv_setuv", but also handles 'set' magic.
6526 void sv_setuv_mg(SV *const sv, const UV u)
6528 sv_tainted
6530 Test an SV for taintedness. Use "SvTAINTED" instead.
6531 bool sv_tainted(SV *const sv)
6533 sv_true Returns true if the SV has a true value by Perl's rules. Use
6535 the "SvTRUE" macro instead, which may call "sv_true()" or may
6536 instead use an in-line version.
6537 I32 sv_true(SV *const sv)
6539 sv_unmagic
6541 Removes all magic of type "type" from an SV.
6542 int sv_unmagic(SV *const sv, const int type)
6544 sv_unmagicext
6546 Removes all magic of type "type" with the specified "vtbl" from
6547 an SV.
6548 int sv_unmagicext(SV *const sv, const int type,
6550 MGVTBL *vtbl)
6551 sv_unref_flags
6553 Unsets the RV status of the SV, and decrements the reference
6554 count of whatever was being referenced by the RV. This can
6555 almost be thought of as a reversal of "newSVrv". The "cflags"
6556 argument can contain "SV_IMMEDIATE_UNREF" to force the
6557 reference count to be decremented (otherwise the decrementing
6558 is conditional on the reference count being different from one
6559 or the reference being a readonly SV). See "SvROK_off".
6560 void sv_unref_flags(SV *const ref, const U32 flags)
6562 sv_untaint
6564 Untaint an SV. Use "SvTAINTED_off" instead.
6565 void sv_untaint(SV *const sv)
6567 sv_upgrade
6569 Upgrade an SV to a more complex form. Generally adds a new
6570 body type to the SV, then copies across as much information as
6571 possible from the old body. It croaks if the SV is already in
6572 a more complex form than requested. You generally want to use
6573 the "SvUPGRADE" macro wrapper, which checks the type before
6574 calling "sv_upgrade", and hence does not croak. See also
6575 "svtype".
6576 void sv_upgrade(SV *const sv, svtype new_type)
6578 sv_usepvn_flags
6580 Tells an SV to use "ptr" to find its string value. Normally
6581 the string is stored inside the SV but sv_usepvn allows the SV
6582 to use an outside string. The "ptr" should point to memory
6583 that was allocated by "malloc". It must be the start of a
6584 mallocked block of memory, and not a pointer to the middle of
6585 it. The string length, "len", must be supplied. By default
6586 this function will realloc (i.e. move) the memory pointed to by
6587 "ptr", so that pointer should not be freed or used by the
6588 programmer after giving it to sv_usepvn, and neither should any
6589 pointers from "behind" that pointer (e.g. ptr + 1) be used.
6590 If "flags" & SV_SMAGIC is true, will call SvSETMAGIC. If
6592 "flags" & SV_HAS_TRAILING_NUL is true, then "ptr[len]" must be
6593 NUL, and the realloc will be skipped (i.e. the buffer is
6594 actually at least 1 byte longer than "len", and already meets
6595 the requirements for storing in "SvPVX").
6596 void sv_usepvn_flags(SV *const sv, char* ptr,
6598 const STRLEN len,
6599 const U32 flags)
6600 sv_utf8_decode
6602 If the PV of the SV is an octet sequence in UTF-8 and contains
6603 a multiple-byte character, the "SvUTF8" flag is turned on so
6604 that it looks like a character. If the PV contains only
6605 single-byte characters, the "SvUTF8" flag stays off. Scans PV
6606 for validity and returns false if the PV is invalid UTF-8.
6607 NOTE: this function is experimental and may change or be
6609 removed without notice.
6610 bool sv_utf8_decode(SV *const sv)
6612 sv_utf8_downgrade
6614 Attempts to convert the PV of an SV from characters to bytes.
6615 If the PV contains a character that cannot fit in a byte, this
6616 conversion will fail; in this case, either returns false or, if
6617 "fail_ok" is not true, croaks.
6618 This is not as a general purpose Unicode to byte encoding
6620 interface: use the Encode extension for that.
6621 NOTE: this function is experimental and may change or be
6623 removed without notice.
6624 bool sv_utf8_downgrade(SV *const sv,
6626 const bool fail_ok)
6627 sv_utf8_encode
6629 Converts the PV of an SV to UTF-8, but then turns the "SvUTF8"
6630 flag off so that it looks like octets again.
6631 void sv_utf8_encode(SV *const sv)
6633 sv_utf8_upgrade
6635 Converts the PV of an SV to its UTF-8-encoded form. Forces the
6636 SV to string form if it is not already. Will "mg_get" on "sv"
6637 if appropriate. Always sets the SvUTF8 flag to avoid future
6638 validity checks even if the whole string is the same in UTF-8
6639 as not. Returns the number of bytes in the converted string
6640 This is not as a general purpose byte encoding to Unicode
6642 interface: use the Encode extension for that.
6643 STRLEN sv_utf8_upgrade(SV *sv)
6645 sv_utf8_upgrade_flags
6647 Converts the PV of an SV to its UTF-8-encoded form. Forces the
6648 SV to string form if it is not already. Always sets the SvUTF8
6649 flag to avoid future validity checks even if all the bytes are
6650 invariant in UTF-8. If "flags" has "SV_GMAGIC" bit set, will
6651 "mg_get" on "sv" if appropriate, else not. Returns the number
6652 of bytes in the converted string "sv_utf8_upgrade" and
6653 "sv_utf8_upgrade_nomg" are implemented in terms of this
6654 function.
6655 This is not as a general purpose byte encoding to Unicode
6657 interface: use the Encode extension for that.
6658 STRLEN sv_utf8_upgrade_flags(SV *const sv,
6660 const I32 flags)
6661 sv_utf8_upgrade_nomg
6663 Like sv_utf8_upgrade, but doesn't do magic on "sv".
6664 STRLEN sv_utf8_upgrade_nomg(SV *sv)
6666 sv_vcatpvf
6668 Processes its arguments like "vsprintf" and appends the
6669 formatted output to an SV. Does not handle 'set' magic. See
6670 "sv_vcatpvf_mg".
6671 Usually used via its frontend "sv_catpvf".
6673 void sv_vcatpvf(SV *const sv, const char *const pat,
6675 va_list *const args)
6676 sv_vcatpvfn
6678 Processes its arguments like "vsprintf" and appends the
6679 formatted output to an SV. Uses an array of SVs if the C style
6680 variable argument list is missing (NULL). When running with
6681 taint checks enabled, indicates via "maybe_tainted" if results
6682 are untrustworthy (often due to the use of locales).
6683 Usually used via one of its frontends "sv_vcatpvf" and
6685 "sv_vcatpvf_mg".
6686 void sv_vcatpvfn(SV *const sv, const char *const pat,
6688 const STRLEN patlen,
6689 va_list *const args,
6690 SV **const svargs, const I32 svmax,
6691 bool *const maybe_tainted)
6692 sv_vcatpvf_mg
6694 Like "sv_vcatpvf", but also handles 'set' magic.
6695 Usually used via its frontend "sv_catpvf_mg".
6697 void sv_vcatpvf_mg(SV *const sv,
6699 const char *const pat,
6700 va_list *const args)
6701 sv_vsetpvf
6703 Works like "sv_vcatpvf" but copies the text into the SV instead
6704 of appending it. Does not handle 'set' magic. See
6705 "sv_vsetpvf_mg".
6706 Usually used via its frontend "sv_setpvf".
6708 void sv_vsetpvf(SV *const sv, const char *const pat,
6710 va_list *const args)
6711 sv_vsetpvfn
6713 Works like "sv_vcatpvfn" but copies the text into the SV
6714 instead of appending it.
6715 Usually used via one of its frontends "sv_vsetpvf" and
6717 "sv_vsetpvf_mg".
6718 void sv_vsetpvfn(SV *const sv, const char *const pat,
6720 const STRLEN patlen,
6721 va_list *const args,
6722 SV **const svargs, const I32 svmax,
6723 bool *const maybe_tainted)
6724 sv_vsetpvf_mg
6726 Like "sv_vsetpvf", but also handles 'set' magic.
6727 Usually used via its frontend "sv_setpvf_mg".
6729 void sv_vsetpvf_mg(SV *const sv,
6731 const char *const pat,
6732 va_list *const args)
6733
6735 bytes_cmp_utf8
6736 Compares the sequence of characters (stored as octets) in "b",
6737 "blen" with the sequence of characters (stored as UTF-8) in
6738 "u", "ulen". Returns 0 if they are equal, -1 or -2 if the first
6739 string is less than the second string, +1 or +2 if the first
6740 string is greater than the second string.
6741 -1 or +1 is returned if the shorter string was identical to the
6743 start of the longer string. -2 or +2 is returned if the was a
6744 difference between characters within the strings.
6745 int bytes_cmp_utf8(const U8 *b, STRLEN blen,
6747 const U8 *u, STRLEN ulen)
6748 bytes_from_utf8
6750 Converts a string "s" of length "len" from UTF-8 into native
6751 byte encoding. Unlike "utf8_to_bytes" but like
6752 "bytes_to_utf8", returns a pointer to the newly-created string,
6753 and updates "len" to contain the new length. Returns the
6754 original string if no conversion occurs, "len" is unchanged. Do
6755 nothing if "is_utf8" points to 0. Sets "is_utf8" to 0 if "s" is
6756 converted or consisted entirely of characters that are
6757 invariant in utf8 (i.e., US-ASCII on non-EBCDIC machines).
6758 NOTE: this function is experimental and may change or be
6760 removed without notice.
6761 U8* bytes_from_utf8(const U8 *s, STRLEN *len,
6763 bool *is_utf8)
6764 bytes_to_utf8
6766 Converts a string "s" of length "len" bytes from the native
6767 encoding into UTF-8. Returns a pointer to the newly-created
6768 string, and sets "len" to reflect the new length in bytes.
6769 A NUL character will be written after the end of the string.
6771 If you want to convert to UTF-8 from encodings other than the
6773 native (Latin1 or EBCDIC), see "sv_recode_to_utf8"().
6774 NOTE: this function is experimental and may change or be
6776 removed without notice.
6777 U8* bytes_to_utf8(const U8 *s, STRLEN *len)
6779 foldEQ_utf8
6781 Returns true if the leading portions of the strings "s1" and
6782 "s2" (either or both of which may be in UTF-8) are the same
6783 case-insensitively; false otherwise. How far into the strings
6784 to compare is determined by other input parameters.
6785 If "u1" is true, the string "s1" is assumed to be in
6787 UTF-8-encoded Unicode; otherwise it is assumed to be in native
6788 8-bit encoding. Correspondingly for "u2" with respect to "s2".
6789 If the byte length "l1" is non-zero, it says how far into "s1"
6791 to check for fold equality. In other words, "s1"+"l1" will be
6792 used as a goal to reach. The scan will not be considered to be
6793 a match unless the goal is reached, and scanning won't continue
6794 past that goal. Correspondingly for "l2" with respect to "s2".
6795 If "pe1" is non-NULL and the pointer it points to is not NULL,
6797 that pointer is considered an end pointer beyond which scanning
6798 of "s1" will not continue under any circumstances. This means
6799 that if both "l1" and "pe1" are specified, and "pe1" is less
6800 than "s1"+"l1", the match will never be successful because it
6801 can never get as far as its goal (and in fact is asserted
6802 against). Correspondingly for "pe2" with respect to "s2".
6803 At least one of "s1" and "s2" must have a goal (at least one of
6805 "l1" and "l2" must be non-zero), and if both do, both have to
6806 be reached for a successful match. Also, if the fold of a
6807 character is multiple characters, all of them must be matched
6808 (see tr21 reference below for 'folding').
6809 Upon a successful match, if "pe1" is non-NULL, it will be set
6811 to point to the beginning of the next character of "s1" beyond
6812 what was matched. Correspondingly for "pe2" and "s2".
6813 For case-insensitiveness, the "casefolding" of Unicode is used
6815 instead of upper/lowercasing both the characters, see
6816 <http://www.unicode.org/unicode/reports/tr21/> (Case Mappings).
6817 I32 foldEQ_utf8(const char *s1, char **pe1, UV l1,
6819 bool u1, const char *s2, char **pe2,
6820 UV l2, bool u2)
6821 is_ascii_string
6823 Returns true if the first "len" bytes of the string "s" are the
6824 same whether or not the string is encoded in UTF-8 (or UTF-
6825 EBCDIC on EBCDIC machines). That is, if they are invariant.
6826 On ASCII-ish machines, only ASCII characters fit this
6827 definition, hence the function's name.
6828 If "len" is 0, it will be calculated using strlen(s).
6830 See also "is_utf8_string"(), "is_utf8_string_loclen"(), and
6832 "is_utf8_string_loc"().
6833 bool is_ascii_string(const U8 *s, STRLEN len)
6835 is_utf8_char
6837 DEPRECATED!
6838 Tests if some arbitrary number of bytes begins in a valid UTF-8
6840 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC
6841 machines) character is a valid UTF-8 character. The actual
6842 number of bytes in the UTF-8 character will be returned if it
6843 is valid, otherwise 0.
6844 This function is deprecated due to the possibility that
6846 malformed input could cause reading beyond the end of the input
6847 buffer. Use "is_utf8_char_buf" instead.
6848 STRLEN is_utf8_char(const U8 *s)
6850 is_utf8_char_buf
6852 Returns the number of bytes that comprise the first UTF-8
6853 encoded character in buffer "buf". "buf_end" should point to
6854 one position beyond the end of the buffer. 0 is returned if
6855 "buf" does not point to a complete, valid UTF-8 encoded
6856 character.
6857 Note that an INVARIANT character (i.e. ASCII on non-EBCDIC
6859 machines) is a valid UTF-8 character.
6860 STRLEN is_utf8_char_buf(const U8 *buf,
6862 const U8 *buf_end)
6863 is_utf8_string
6865 Returns true if the first "len" bytes of string "s" form a
6866 valid UTF-8 string, false otherwise. If "len" is 0, it will be
6867 calculated using strlen(s) (which means if you use this option,
6868 that "s" has to have a terminating NUL byte). Note that all
6869 characters being ASCII constitute 'a valid UTF-8 string'.
6870 See also "is_ascii_string"(), "is_utf8_string_loclen"(), and
6872 "is_utf8_string_loc"().
6873 bool is_utf8_string(const U8 *s, STRLEN len)
6875 is_utf8_string_loc
6877 Like "is_utf8_string" but stores the location of the failure
6878 (in the case of "utf8ness failure") or the location "s"+"len"
6879 (in the case of "utf8ness success") in the "ep".
6880 See also "is_utf8_string_loclen"() and "is_utf8_string"().
6882 bool is_utf8_string_loc(const U8 *s, STRLEN len,
6884 const U8 **p)
6885 is_utf8_string_loclen
6887 Like "is_utf8_string"() but stores the location of the failure
6888 (in the case of "utf8ness failure") or the location "s"+"len"
6889 (in the case of "utf8ness success") in the "ep", and the number
6890 of UTF-8 encoded characters in the "el".
6891 See also "is_utf8_string_loc"() and "is_utf8_string"().
6893 bool is_utf8_string_loclen(const U8 *s, STRLEN len,
6895 const U8 **ep, STRLEN *el)
6896 pv_uni_display
6898 Build to the scalar "dsv" a displayable version of the string
6899 "spv", length "len", the displayable version being at most
6900 "pvlim" bytes long (if longer, the rest is truncated and "..."
6901 will be appended).
6902 The "flags" argument can have UNI_DISPLAY_ISPRINT set to
6904 display isPRINT()able characters as themselves,
6905 UNI_DISPLAY_BACKSLASH to display the \\[nrfta\\] as the
6906 backslashed versions (like '\n') (UNI_DISPLAY_BACKSLASH is
6907 preferred over UNI_DISPLAY_ISPRINT for \\). UNI_DISPLAY_QQ
6908 (and its alias UNI_DISPLAY_REGEX) have both
6909 UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
6910 The pointer to the PV of the "dsv" is returned.
6912 char* pv_uni_display(SV *dsv, const U8 *spv,
6914 STRLEN len, STRLEN pvlim,
6915 UV flags)
6916 sv_cat_decode
6918 The encoding is assumed to be an Encode object, the PV of the
6919 ssv is assumed to be octets in that encoding and decoding the
6920 input starts from the position which (PV + *offset) pointed to.
6921 The dsv will be concatenated the decoded UTF-8 string from ssv.
6922 Decoding will terminate when the string tstr appears in
6923 decoding output or the input ends on the PV of the ssv. The
6924 value which the offset points will be modified to the last
6925 input position on the ssv.
6926 Returns TRUE if the terminator was found, else returns FALSE.
6928 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv,
6930 int *offset, char* tstr, int tlen)
6931 sv_recode_to_utf8
6933 The encoding is assumed to be an Encode object, on entry the PV
6934 of the sv is assumed to be octets in that encoding, and the sv
6935 will be converted into Unicode (and UTF-8).
6936 If the sv already is UTF-8 (or if it is not POK), or if the
6938 encoding is not a reference, nothing is done to the sv. If the
6939 encoding is not an "Encode::XS" Encoding object, bad things
6940 will happen. (See lib/encoding.pm and Encode.)
6941 The PV of the sv is returned.
6943 char* sv_recode_to_utf8(SV* sv, SV *encoding)
6945 sv_uni_display
6947 Build to the scalar "dsv" a displayable version of the scalar
6948 "sv", the displayable version being at most "pvlim" bytes long
6949 (if longer, the rest is truncated and "..." will be appended).
6950 The "flags" argument is as in "pv_uni_display"().
6952 The pointer to the PV of the "dsv" is returned.
6954 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim,
6956 UV flags)
6957 to_utf8_case
6959 The "p" contains the pointer to the UTF-8 string encoding the
6960 character that is being converted. This routine assumes that
6961 the character at "p" is well-formed.
6962 The "ustrp" is a pointer to the character buffer to put the
6964 conversion result to. The "lenp" is a pointer to the length of
6965 the result.
6966 The "swashp" is a pointer to the swash to use.
6968 Both the special and normal mappings are stored in
6970 lib/unicore/To/Foo.pl, and loaded by SWASHNEW, using
6971 lib/utf8_heavy.pl. The "special" (usually, but not always, a
6972 multicharacter mapping), is tried first.
6973 The "special" is a string like "utf8::ToSpecLower", which means
6975 the hash %utf8::ToSpecLower. The access to the hash is through
6976 Perl_to_utf8_case().
6977 The "normal" is a string like "ToLower" which means the swash
6979 %utf8::ToLower.
6980 UV to_utf8_case(const U8 *p, U8* ustrp,
6982 STRLEN *lenp, SV **swashp,
6983 const char *normal,
6984 const char *special)
6985 to_utf8_fold
6987 Convert the UTF-8 encoded character at "p" to its foldcase
6988 version and store that in UTF-8 in "ustrp" and its length in
6989 bytes in "lenp". Note that the "ustrp" needs to be at least
6990 UTF8_MAXBYTES_CASE+1 bytes since the foldcase version may be
6991 longer than the original character (up to three characters).
6992 The first character of the foldcased version is returned (but
6994 note, as explained above, that there may be more.)
6995 The character at "p" is assumed by this routine to be well-
6997 formed.
6998 UV to_utf8_fold(const U8 *p, U8* ustrp,
7000 STRLEN *lenp)
7001 to_utf8_lower
7003 Convert the UTF-8 encoded character at "p" to its lowercase
7004 version and store that in UTF-8 in ustrp and its length in
7005 bytes in "lenp". Note that the "ustrp" needs to be at least
7006 UTF8_MAXBYTES_CASE+1 bytes since the lowercase version may be
7007 longer than the original character.
7008 The first character of the lowercased version is returned (but
7010 note, as explained above, that there may be more.)
7011 The character at "p" is assumed by this routine to be well-
7013 formed.
7014 UV to_utf8_lower(const U8 *p, U8* ustrp,
7016 STRLEN *lenp)
7017 to_utf8_title
7019 Convert the UTF-8 encoded character at "p" to its titlecase
7020 version and store that in UTF-8 in "ustrp" and its length in
7021 bytes in "lenp". Note that the "ustrp" needs to be at least
7022 UTF8_MAXBYTES_CASE+1 bytes since the titlecase version may be
7023 longer than the original character.
7024 The first character of the titlecased version is returned (but
7026 note, as explained above, that there may be more.)
7027 The character at "p" is assumed by this routine to be well-
7029 formed.
7030 UV to_utf8_title(const U8 *p, U8* ustrp,
7032 STRLEN *lenp)
7033 to_utf8_upper
7035 Convert the UTF-8 encoded character at "p" to its uppercase
7036 version and store that in UTF-8 in "ustrp" and its length in
7037 bytes in "lenp". Note that the ustrp needs to be at least
7038 UTF8_MAXBYTES_CASE+1 bytes since the uppercase version may be
7039 longer than the original character.
7040 The first character of the uppercased version is returned (but
7042 note, as explained above, that there may be more.)
7043 The character at "p" is assumed by this routine to be well-
7045 formed.
7046 UV to_utf8_upper(const U8 *p, U8* ustrp,
7048 STRLEN *lenp)
7049 utf8n_to_uvchr
7051 Returns the native character value of the first character in
7052 the string "s" which is assumed to be in UTF-8 encoding;
7053 "retlen" will be set to the length, in bytes, of that
7054 character.
7055 "length" and "flags" are the same as "utf8n_to_uvuni"().
7057 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen,
7059 STRLEN *retlen, U32 flags)
7060 utf8n_to_uvuni
7062 Bottom level UTF-8 decode routine. Returns the code point
7063 value of the first character in the string "s", which is
7064 assumed to be in UTF-8 (or UTF-EBCDIC) encoding, and no longer
7065 than "curlen" bytes; *retlen (if "retlen" isn't NULL) will be
7066 set to the length, in bytes, of that character.
7067 The value of "flags" determines the behavior when "s" does not
7069 point to a well-formed UTF-8 character. If "flags" is 0, when
7070 a malformation is found, zero is returned and *retlen is set so
7071 that ("s" + *retlen) is the next possible position in "s" that
7072 could begin a non-malformed character. Also, if UTF-8 warnings
7073 haven't been lexically disabled, a warning is raised.
7074 Various ALLOW flags can be set in "flags" to allow (and not
7076 warn on) individual types of malformations, such as the
7077 sequence being overlong (that is, when there is a shorter
7078 sequence that can express the same code point; overlong
7079 sequences are expressly forbidden in the UTF-8 standard due to
7080 potential security issues). Another malformation example is
7081 the first byte of a character not being a legal first byte.
7082 See utf8.h for the list of such flags. For allowed 0 length
7083 strings, this function returns 0; for allowed overlong
7084 sequences, the computed code point is returned; for all other
7085 allowed malformations, the Unicode REPLACEMENT CHARACTER is
7086 returned, as these have no determinable reasonable value.
7087 The UTF8_CHECK_ONLY flag overrides the behavior when a non-
7089 allowed (by other flags) malformation is found. If this flag
7090 is set, the routine assumes that the caller will raise a
7091 warning, and this function will silently just set "retlen" to
7092 "-1" and return zero.
7093 Certain code points are considered problematic. These are
7095 Unicode surrogates, Unicode non-characters, and code points
7096 above the Unicode maximum of 0x10FFFF. By default these are
7097 considered regular code points, but certain situations warrant
7098 special handling for them. If "flags" contains
7099 UTF8_DISALLOW_ILLEGAL_INTERCHANGE, all three classes are
7100 treated as malformations and handled as such. The flags
7101 UTF8_DISALLOW_SURROGATE, UTF8_DISALLOW_NONCHAR, and
7102 UTF8_DISALLOW_SUPER (meaning above the legal Unicode maximum)
7103 can be set to disallow these categories individually.
7104 The flags UTF8_WARN_ILLEGAL_INTERCHANGE, UTF8_WARN_SURROGATE,
7106 UTF8_WARN_NONCHAR, and UTF8_WARN_SUPER will cause warning
7107 messages to be raised for their respective categories, but
7108 otherwise the code points are considered valid (not
7109 malformations). To get a category to both be treated as a
7110 malformation and raise a warning, specify both the WARN and
7111 DISALLOW flags. (But note that warnings are not raised if
7112 lexically disabled nor if UTF8_CHECK_ONLY is also specified.)
7113 Very large code points (above 0x7FFF_FFFF) are considered more
7115 problematic than the others that are above the Unicode legal
7116 maximum. There are several reasons: they requre at least 32
7117 bits to represent them on ASCII platforms, are not
7118 representable at all on EBCDIC platforms, and the original
7119 UTF-8 specification never went above this number (the current
7120 0x10FFFF limit was imposed later). (The smaller ones, those
7121 that fit into 32 bits, are representable by a UV on ASCII
7122 platforms, but not by an IV, which means that the number of
7123 operations that can be performed on them is quite restricted.)
7124 The UTF-8 encoding on ASCII platforms for these large code
7125 points begins with a byte containing 0xFE or 0xFF. The
7126 UTF8_DISALLOW_FE_FF flag will cause them to be treated as
7127 malformations, while allowing smaller above-Unicode code
7128 points. (Of course UTF8_DISALLOW_SUPER will treat all above-
7129 Unicode code points, including these, as malformations.)
7130 Similarly, UTF8_WARN_FE_FF acts just like the other WARN flags,
7131 but applies just to these code points.
7132 All other code points corresponding to Unicode characters,
7134 including private use and those yet to be assigned, are never
7135 considered malformed and never warn.
7136 Most code should use "utf8_to_uvchr_buf"() rather than call
7138 this directly.
7139 UV utf8n_to_uvuni(const U8 *s, STRLEN curlen,
7141 STRLEN *retlen, U32 flags)
7142 utf8_distance
7144 Returns the number of UTF-8 characters between the UTF-8
7145 pointers "a" and "b".
7146 WARNING: use only if you *know* that the pointers point inside
7148 the same UTF-8 buffer.
7149 IV utf8_distance(const U8 *a, const U8 *b)
7151 utf8_hop
7153 Return the UTF-8 pointer "s" displaced by "off" characters,
7154 either forward or backward.
7155 WARNING: do not use the following unless you *know* "off" is
7157 within the UTF-8 data pointed to by "s" *and* that on entry "s"
7158 is aligned on the first byte of character or just after the
7159 last byte of a character.
7160 U8* utf8_hop(const U8 *s, I32 off)
7162 utf8_length
7164 Return the length of the UTF-8 char encoded string "s" in
7165 characters. Stops at "e" (inclusive). If "e < s" or if the
7166 scan would end up past "e", croaks.
7167 STRLEN utf8_length(const U8* s, const U8 *e)
7169 utf8_to_bytes
7171 Converts a string "s" of length "len" from UTF-8 into native
7172 byte encoding. Unlike "bytes_to_utf8", this over-writes the
7173 original string, and updates "len" to contain the new length.
7174 Returns zero on failure, setting "len" to -1.
7175 If you need a copy of the string, see "bytes_from_utf8".
7177 NOTE: this function is experimental and may change or be
7179 removed without notice.
7180 U8* utf8_to_bytes(U8 *s, STRLEN *len)
7182 utf8_to_uvchr
7184 DEPRECATED!
7185 Returns the native code point of the first character in the
7187 string "s" which is assumed to be in UTF-8 encoding; "retlen"
7188 will be set to the length, in bytes, of that character.
7189 Some, but not all, UTF-8 malformations are detected, and in
7191 fact, some malformed input could cause reading beyond the end
7192 of the input buffer, which is why this function is deprecated.
7193 Use "utf8_to_uvchr_buf" instead.
7194 If "s" points to one of the detected malformations, and UTF8
7196 warnings are enabled, zero is returned and *retlen is set (if
7197 "retlen" isn't NULL) to -1. If those warnings are off, the
7198 computed value if well-defined (or the Unicode REPLACEMENT
7199 CHARACTER, if not) is silently returned, and *retlen is set (if
7200 "retlen" isn't NULL) so that ("s" + *retlen) is the next
7201 possible position in "s" that could begin a non-malformed
7202 character. See "utf8n_to_uvuni" for details on when the
7203 REPLACEMENT CHARACTER is returned.
7204 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
7206 utf8_to_uvchr_buf
7208 Returns the native code point of the first character in the
7209 string "s" which is assumed to be in UTF-8 encoding; "send"
7210 points to 1 beyond the end of "s". *retlen will be set to the
7211 length, in bytes, of that character.
7212 If "s" does not point to a well-formed UTF-8 character and UTF8
7214 warnings are enabled, zero is returned and *retlen is set (if
7215 "retlen" isn't NULL) to -1. If those warnings are off, the
7216 computed value if well-defined (or the Unicode REPLACEMENT
7217 CHARACTER, if not) is silently returned, and *retlen is set (if
7218 "retlen" isn't NULL) so that ("s" + *retlen) is the next
7219 possible position in "s" that could begin a non-malformed
7220 character. See "utf8n_to_uvuni" for details on when the
7221 REPLACEMENT CHARACTER is returned.
7222 UV utf8_to_uvchr_buf(const U8 *s, const U8 *send,
7224 STRLEN *retlen)
7225 utf8_to_uvuni
7227 DEPRECATED!
7228 Returns the Unicode code point of the first character in the
7230 string "s" which is assumed to be in UTF-8 encoding; "retlen"
7231 will be set to the length, in bytes, of that character.
7232 This function should only be used when the returned UV is
7234 considered an index into the Unicode semantic tables (e.g.
7235 swashes).
7236 Some, but not all, UTF-8 malformations are detected, and in
7238 fact, some malformed input could cause reading beyond the end
7239 of the input buffer, which is why this function is deprecated.
7240 Use "utf8_to_uvuni_buf" instead.
7241 If "s" points to one of the detected malformations, and UTF8
7243 warnings are enabled, zero is returned and *retlen is set (if
7244 "retlen" doesn't point to NULL) to -1. If those warnings are
7245 off, the computed value if well-defined (or the Unicode
7246 REPLACEMENT CHARACTER, if not) is silently returned, and
7247 *retlen is set (if "retlen" isn't NULL) so that ("s" + *retlen)
7248 is the next possible position in "s" that could begin a non-
7249 malformed character. See "utf8n_to_uvuni" for details on when
7250 the REPLACEMENT CHARACTER is returned.
7251 UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
7253 utf8_to_uvuni_buf
7255 Returns the Unicode code point of the first character in the
7256 string "s" which is assumed to be in UTF-8 encoding; "send"
7257 points to 1 beyond the end of "s". "retlen" will be set to the
7258 length, in bytes, of that character.
7259 This function should only be used when the returned UV is
7261 considered an index into the Unicode semantic tables (e.g.
7262 swashes).
7263 If "s" does not point to a well-formed UTF-8 character and UTF8
7265 warnings are enabled, zero is returned and *retlen is set (if
7266 "retlen" isn't NULL) to -1. If those warnings are off, the
7267 computed value if well-defined (or the Unicode REPLACEMENT
7268 CHARACTER, if not) is silently returned, and *retlen is set (if
7269 "retlen" isn't NULL) so that ("s" + *retlen) is the next
7270 possible position in "s" that could begin a non-malformed
7271 character. See "utf8n_to_uvuni" for details on when the
7272 REPLACEMENT CHARACTER is returned.
7273 UV utf8_to_uvuni_buf(const U8 *s, const U8 *send,
7275 STRLEN *retlen)
7276 uvchr_to_utf8
7278 Adds the UTF-8 representation of the Native code point "uv" to
7279 the end of the string "d"; "d" should have at least
7280 "UTF8_MAXBYTES+1" free bytes available. The return value is the
7281 pointer to the byte after the end of the new character. In
7282 other words,
7283 d = uvchr_to_utf8(d, uv);
7285 is the recommended wide native character-aware way of saying
7287 *(d++) = uv;
7289 U8* uvchr_to_utf8(U8 *d, UV uv)
7291 uvuni_to_utf8_flags
7293 Adds the UTF-8 representation of the code point "uv" to the end
7294 of the string "d"; "d" should have at least "UTF8_MAXBYTES+1"
7295 free bytes available. The return value is the pointer to the
7296 byte after the end of the new character. In other words,
7297 d = uvuni_to_utf8_flags(d, uv, flags);
7299 or, in most cases,
7301 d = uvuni_to_utf8(d, uv);
7303 (which is equivalent to)
7305 d = uvuni_to_utf8_flags(d, uv, 0);
7307 This is the recommended Unicode-aware way of saying
7309 *(d++) = uv;
7311 This function will convert to UTF-8 (and not warn) even code
7313 points that aren't legal Unicode or are problematic, unless
7314 "flags" contains one or more of the following flags:
7315 If "uv" is a Unicode surrogate code point and
7317 UNICODE_WARN_SURROGATE is set, the function will raise a
7318 warning, provided UTF8 warnings are enabled. If instead
7319 UNICODE_DISALLOW_SURROGATE is set, the function will fail and
7320 return NULL. If both flags are set, the function will both
7321 warn and return NULL.
7322 The UNICODE_WARN_NONCHAR and UNICODE_DISALLOW_NONCHAR flags
7324 correspondingly affect how the function handles a Unicode non-
7325 character. And, likewise for the UNICODE_WARN_SUPER and
7326 UNICODE_DISALLOW_SUPER flags, and code points that are above
7327 the Unicode maximum of 0x10FFFF. Code points above 0x7FFF_FFFF
7328 (which are even less portable) can be warned and/or disallowed
7329 even if other above-Unicode code points are accepted by the
7330 UNICODE_WARN_FE_FF and UNICODE_DISALLOW_FE_FF flags.
7331 And finally, the flag UNICODE_WARN_ILLEGAL_INTERCHANGE selects
7333 all four of the above WARN flags; and
7334 UNICODE_DISALLOW_ILLEGAL_INTERCHANGE selects all four DISALLOW
7335 flags.
7336 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
7338
7340 ax Variable which is setup by "xsubpp" to indicate the stack base
7341 offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros.
7342 The "dMARK" macro must be called prior to setup the "MARK"
7343 variable.
7344 I32 ax
7346 CLASS Variable which is setup by "xsubpp" to indicate the class name
7348 for a C++ XS constructor. This is always a "char*". See
7349 "THIS".
7350 char* CLASS
7352 dAX Sets up the "ax" variable. This is usually handled
7354 automatically by "xsubpp" by calling "dXSARGS".
7355 dAX;
7357 dAXMARK Sets up the "ax" variable and stack marker variable "mark".
7359 This is usually handled automatically by "xsubpp" by calling
7360 "dXSARGS".
7361 dAXMARK;
7363 dITEMS Sets up the "items" variable. This is usually handled
7365 automatically by "xsubpp" by calling "dXSARGS".
7366 dITEMS;
7368 dUNDERBAR
7370 Sets up any variable needed by the "UNDERBAR" macro. It used to
7371 define "padoff_du", but it is currently a noop. However, it is
7372 strongly advised to still use it for ensuring past and future
7373 compatibility.
7374 dUNDERBAR;
7376 dXSARGS Sets up stack and mark pointers for an XSUB, calling dSP and
7378 dMARK. Sets up the "ax" and "items" variables by calling "dAX"
7379 and "dITEMS". This is usually handled automatically by
7380 "xsubpp".
7381 dXSARGS;
7383 dXSI32 Sets up the "ix" variable for an XSUB which has aliases. This
7385 is usually handled automatically by "xsubpp".
7386 dXSI32;
7388 items Variable which is setup by "xsubpp" to indicate the number of
7390 items on the stack. See "Variable-length Parameter Lists" in
7391 perlxs.
7392 I32 items
7394 ix Variable which is setup by "xsubpp" to indicate which of an
7396 XSUB's aliases was used to invoke it. See "The ALIAS: Keyword"
7397 in perlxs.
7398 I32 ix
7400 newXSproto
7402 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl
7403 prototypes to the subs.
7404 RETVAL Variable which is setup by "xsubpp" to hold the return value
7406 for an XSUB. This is always the proper type for the XSUB. See
7407 "The RETVAL Variable" in perlxs.
7408 (whatever) RETVAL
7410 ST Used to access elements on the XSUB's stack.
7412 SV* ST(int ix)
7414 THIS Variable which is setup by "xsubpp" to designate the object in
7416 a C++ XSUB. This is always the proper type for the C++ object.
7417 See "CLASS" and "Using XS With C++" in perlxs.
7418 (whatever) THIS
7420 UNDERBAR
7422 The SV* corresponding to the $_ variable. Works even if there
7423 is a lexical $_ in scope.
7424 XS Macro to declare an XSUB and its C parameter list. This is
7426 handled by "xsubpp". It is the same as using the more explicit
7427 XS_EXTERNAL macro.
7428 XS_APIVERSION_BOOTCHECK
7430 Macro to verify that the perl api version an XS module has been
7431 compiled against matches the api version of the perl
7432 interpreter it's being loaded into.
7433 XS_APIVERSION_BOOTCHECK;
7435 XS_EXTERNAL
7437 Macro to declare an XSUB and its C parameter list explicitly
7438 exporting the symbols.
7439 XS_INTERNAL
7441 Macro to declare an XSUB and its C parameter list without
7442 exporting the symbols. This is handled by "xsubpp" and
7443 generally preferable over exporting the XSUB symbols
7444 unnecessarily.
7445 XS_VERSION
7447 The version identifier for an XS module. This is usually
7448 handled automatically by "ExtUtils::MakeMaker". See
7449 "XS_VERSION_BOOTCHECK".
7450 XS_VERSION_BOOTCHECK
7452 Macro to verify that a PM module's $VERSION variable matches
7453 the XS module's "XS_VERSION" variable. This is usually handled
7454 automatically by "xsubpp". See "The VERSIONCHECK: Keyword" in
7455 perlxs.
7456 XS_VERSION_BOOTCHECK;
7458
7460 croak This is an XS interface to Perl's "die" function.
7461 Take a sprintf-style format pattern and argument list. These
7463 are used to generate a string message. If the message does not
7464 end with a newline, then it will be extended with some
7465 indication of the current location in the code, as described
7466 for "mess_sv".
7467 The error message will be used as an exception, by default
7469 returning control to the nearest enclosing "eval", but subject
7470 to modification by a $SIG{__DIE__} handler. In any case, the
7471 "croak" function never returns normally.
7472 For historical reasons, if "pat" is null then the contents of
7474 "ERRSV" ($@) will be used as an error message or object instead
7475 of building an error message from arguments. If you want to
7476 throw a non-string object, or build an error message in an SV
7477 yourself, it is preferable to use the "croak_sv" function,
7478 which does not involve clobbering "ERRSV".
7479 void croak(const char *pat, ...)
7481 croak_no_modify
7483 Exactly equivalent to "Perl_croak(aTHX_ "%s", PL_no_modify)",
7484 but generates terser object code than using "Perl_croak". Less
7485 code used on exception code paths reduces CPU cache pressure.
7486 void croak_no_modify()
7488 croak_sv
7490 This is an XS interface to Perl's "die" function.
7491 "baseex" is the error message or object. If it is a reference,
7493 it will be used as-is. Otherwise it is used as a string, and
7494 if it does not end with a newline then it will be extended with
7495 some indication of the current location in the code, as
7496 described for "mess_sv".
7497 The error message or object will be used as an exception, by
7499 default returning control to the nearest enclosing "eval", but
7500 subject to modification by a $SIG{__DIE__} handler. In any
7501 case, the "croak_sv" function never returns normally.
7502 To die with a simple string message, the "croak" function may
7504 be more convenient.
7505 void croak_sv(SV *baseex)
7507 die Behaves the same as "croak", except for the return type. It
7509 should be used only where the "OP *" return type is required.
7510 The function never actually returns.
7511 OP * die(const char *pat, ...)
7513 die_sv Behaves the same as "croak_sv", except for the return type. It
7515 should be used only where the "OP *" return type is required.
7516 The function never actually returns.
7517 OP * die_sv(SV *baseex)
7519 vcroak This is an XS interface to Perl's "die" function.
7521 "pat" and "args" are a sprintf-style format pattern and
7523 encapsulated argument list. These are used to generate a
7524 string message. If the message does not end with a newline,
7525 then it will be extended with some indication of the current
7526 location in the code, as described for "mess_sv".
7527 The error message will be used as an exception, by default
7529 returning control to the nearest enclosing "eval", but subject
7530 to modification by a $SIG{__DIE__} handler. In any case, the
7531 "croak" function never returns normally.
7532 For historical reasons, if "pat" is null then the contents of
7534 "ERRSV" ($@) will be used as an error message or object instead
7535 of building an error message from arguments. If you want to
7536 throw a non-string object, or build an error message in an SV
7537 yourself, it is preferable to use the "croak_sv" function,
7538 which does not involve clobbering "ERRSV".
7539 void vcroak(const char *pat, va_list *args)
7541 vwarn This is an XS interface to Perl's "warn" function.
7543 "pat" and "args" are a sprintf-style format pattern and
7545 encapsulated argument list. These are used to generate a
7546 string message. If the message does not end with a newline,
7547 then it will be extended with some indication of the current
7548 location in the code, as described for "mess_sv".
7549 The error message or object will by default be written to
7551 standard error, but this is subject to modification by a
7552 $SIG{__WARN__} handler.
7553 Unlike with "vcroak", "pat" is not permitted to be null.
7555 void vwarn(const char *pat, va_list *args)
7557 warn This is an XS interface to Perl's "warn" function.
7559 Take a sprintf-style format pattern and argument list. These
7561 are used to generate a string message. If the message does not
7562 end with a newline, then it will be extended with some
7563 indication of the current location in the code, as described
7564 for "mess_sv".
7565 The error message or object will by default be written to
7567 standard error, but this is subject to modification by a
7568 $SIG{__WARN__} handler.
7569 Unlike with "croak", "pat" is not permitted to be null.
7571 void warn(const char *pat, ...)
7573 warn_sv This is an XS interface to Perl's "warn" function.
7575 "baseex" is the error message or object. If it is a reference,
7577 it will be used as-is. Otherwise it is used as a string, and
7578 if it does not end with a newline then it will be extended with
7579 some indication of the current location in the code, as
7580 described for "mess_sv".
7581 The error message or object will by default be written to
7583 standard error, but this is subject to modification by a
7584 $SIG{__WARN__} handler.
7585 To warn with a simple string message, the "warn" function may
7587 be more convenient.
7588 void warn_sv(SV *baseex)
7590
7592 The following functions have been flagged as part of the public API,
7593 but are currently undocumented. Use them at your own risk, as the
7594 interfaces are subject to change.
7595 If you use one of them, you may wish to consider creating and
7597 submitting documentation for it. If your patch is accepted, this will
7598 indicate that the interface is stable (unless it is explicitly marked
7599 otherwise).
7600 GetVars
7602 Gv_AMupdate
7603 PerlIO_clearerr
7604 PerlIO_close
7605 PerlIO_context_layers
7606 PerlIO_eof
7607 PerlIO_error
7608 PerlIO_fileno
7609 PerlIO_fill
7610 PerlIO_flush
7611 PerlIO_get_base
7612 PerlIO_get_bufsiz
7613 PerlIO_get_cnt
7614 PerlIO_get_ptr
7615 PerlIO_read
7616 PerlIO_seek
7617 PerlIO_set_cnt
7618 PerlIO_set_ptrcnt
7619 PerlIO_setlinebuf
7620 PerlIO_stderr
7621 PerlIO_stdin
7622 PerlIO_stdout
7623 PerlIO_tell
7624 PerlIO_unread
7625 PerlIO_write
7626 Slab_Alloc
7627 Slab_Free
7628 _is_utf8_quotemeta
7629 amagic_call
7630 amagic_deref_call
7631 any_dup
7632 atfork_lock
7633 atfork_unlock
7634 av_arylen_p
7635 av_iter_p
7636 block_gimme
7637 call_atexit
7638 call_list
7639 calloc
7640 cast_i32
7641 cast_iv
7642 cast_ulong
7643 cast_uv
7644 ck_warner
7645 ck_warner_d
7646 ckwarn
7647 ckwarn_d
7648 clone_params_del
7649 clone_params_new
7650 croak_nocontext
7651 csighandler
7652 cx_dump
7653 cx_dup
7654 cxinc
7655 deb
7656 deb_nocontext
7657 debop
7658 debprofdump
7659 debstack
7660 debstackptrs
7661 delimcpy
7662 despatch_signals
7663 die_nocontext
7664 dirp_dup
7665 do_aspawn
7666 do_binmode
7667 do_close
7668 do_gv_dump
7669 do_gvgv_dump
7670 do_hv_dump
7671 do_join
7672 do_magic_dump
7673 do_op_dump
7674 do_open
7675 do_open9
7676 do_openn
7677 do_pmop_dump
7678 do_spawn
7679 do_spawn_nowait
7680 do_sprintf
7681 do_sv_dump
7682 doing_taint
7683 doref
7684 dounwind
7685 dowantarray
7686 dump_all
7687 dump_eval
7688 dump_fds
7689 dump_form
7690 dump_indent
7691 dump_mstats
7692 dump_packsubs
7693 dump_sub
7694 dump_vindent
7695 filter_add
7696 filter_del
7697 filter_read
7698 foldEQ_latin1
7699 form_nocontext
7700 fp_dup
7701 fprintf_nocontext
7702 free_global_struct
7703 free_tmps
7704 get_context
7705 get_mstats
7706 get_op_descs
7707 get_op_names
7708 get_ppaddr
7709 get_vtbl
7710 gp_dup
7711 gp_free
7712 gp_ref
7713 gv_AVadd
7714 gv_HVadd
7715 gv_IOadd
7716 gv_SVadd
7717 gv_add_by_type
7718 gv_autoload4
7719 gv_autoload_pv
7720 gv_autoload_pvn
7721 gv_autoload_sv
7722 gv_check
7723 gv_dump
7724 gv_efullname
7725 gv_efullname3
7726 gv_efullname4
7727 gv_fetchfile
7728 gv_fetchfile_flags
7729 gv_fetchpv
7730 gv_fetchpvn_flags
7731 gv_fetchsv
7732 gv_fullname
7733 gv_fullname3
7734 gv_fullname4
7735 gv_handler
7736 gv_name_set
7737 he_dup
7738 hek_dup
7739 hv_common
7740 hv_common_key_len
7741 hv_delayfree_ent
7742 hv_eiter_p
7743 hv_eiter_set
7744 hv_free_ent
7745 hv_ksplit
7746 hv_name_set
7747 hv_placeholders_get
7748 hv_placeholders_p
7749 hv_placeholders_set
7750 hv_riter_p
7751 hv_riter_set
7752 init_global_struct
7753 init_i18nl10n
7754 init_i18nl14n
7755 init_stacks
7756 init_tm
7757 instr
7758 is_lvalue_sub
7759 is_uni_alnum
7760 is_uni_alnum_lc
7761 is_uni_alpha
7762 is_uni_alpha_lc
7763 is_uni_ascii
7764 is_uni_ascii_lc
7765 is_uni_cntrl
7766 is_uni_cntrl_lc
7767 is_uni_digit
7768 is_uni_digit_lc
7769 is_uni_graph
7770 is_uni_graph_lc
7771 is_uni_idfirst
7772 is_uni_idfirst_lc
7773 is_uni_lower
7774 is_uni_lower_lc
7775 is_uni_print
7776 is_uni_print_lc
7777 is_uni_punct
7778 is_uni_punct_lc
7779 is_uni_space
7780 is_uni_space_lc
7781 is_uni_upper
7782 is_uni_upper_lc
7783 is_uni_xdigit
7784 is_uni_xdigit_lc
7785 is_utf8_alnum
7786 is_utf8_alpha
7787 is_utf8_ascii
7788 is_utf8_cntrl
7789 is_utf8_digit
7790 is_utf8_graph
7791 is_utf8_idcont
7792 is_utf8_idfirst
7793 is_utf8_lower
7794 is_utf8_mark
7795 is_utf8_perl_space
7796 is_utf8_perl_word
7797 is_utf8_posix_digit
7798 is_utf8_print
7799 is_utf8_punct
7800 is_utf8_space
7801 is_utf8_upper
7802 is_utf8_xdigit
7803 is_utf8_xidcont
7804 is_utf8_xidfirst
7805 leave_scope
7806 load_module_nocontext
7807 magic_dump
7808 malloc
7809 markstack_grow
7810 mess_nocontext
7811 mfree
7812 mg_dup
7813 mg_size
7814 mini_mktime
7815 moreswitches
7816 mro_get_from_name
7817 mro_get_private_data
7818 mro_set_mro
7819 mro_set_private_data
7820 my_atof
7821 my_atof2
7822 my_bcopy
7823 my_bzero
7824 my_chsize
7825 my_cxt_index
7826 my_cxt_init
7827 my_dirfd
7828 my_exit
7829 my_failure_exit
7830 my_fflush_all
7831 my_fork
7832 my_htonl
7833 my_lstat
7834 my_memcmp
7835 my_memset
7836 my_ntohl
7837 my_pclose
7838 my_popen
7839 my_popen_list
7840 my_setenv
7841 my_socketpair
7842 my_stat
7843 my_strftime
7844 my_strlcat
7845 my_strlcpy
7846 my_swap
7847 newANONATTRSUB
7848 newANONHASH
7849 newANONLIST
7850 newANONSUB
7851 newATTRSUB
7852 newAVREF
7853 newCVREF
7854 newFORM
7855 newGVREF
7856 newGVgen
7857 newGVgen_flags
7858 newHVREF
7859 newHVhv
7860 newIO
7861 newMYSUB
7862 newPROG
7863 newRV
7864 newSUB
7865 newSVREF
7866 newSVpvf_nocontext
7867 new_collate
7868 new_ctype
7869 new_numeric
7870 new_stackinfo
7871 ninstr
7872 op_dump
7873 op_free
7874 op_null
7875 op_refcnt_lock
7876 op_refcnt_unlock
7877 parser_dup
7878 perl_alloc_using
7879 perl_clone_using
7880 pmop_dump
7881 pop_scope
7882 pregcomp
7883 pregexec
7884 pregfree
7885 pregfree2
7886 printf_nocontext
7887 ptr_table_clear
7888 ptr_table_fetch
7889 ptr_table_free
7890 ptr_table_new
7891 ptr_table_split
7892 ptr_table_store
7893 push_scope
7894 re_compile
7895 re_dup_guts
7896 re_intuit_start
7897 re_intuit_string
7898 realloc
7899 reentrant_free
7900 reentrant_init
7901 reentrant_retry
7902 reentrant_size
7903 ref
7904 reg_named_buff_all
7905 reg_named_buff_exists
7906 reg_named_buff_fetch
7907 reg_named_buff_firstkey
7908 reg_named_buff_nextkey
7909 reg_named_buff_scalar
7910 regclass_swash
7911 regdump
7912 regdupe_internal
7913 regexec_flags
7914 regfree_internal
7915 reginitcolors
7916 regnext
7917 repeatcpy
7918 rninstr
7919 rsignal
7920 rsignal_state
7921 runops_debug
7922 runops_standard
7923 rvpv_dup
7924 safesyscalloc
7925 safesysfree
7926 safesysmalloc
7927 safesysrealloc
7928 save_I16
7929 save_I32
7930 save_I8
7931 save_adelete
7932 save_aelem
7933 save_aelem_flags
7934 save_alloc
7935 save_aptr
7936 save_ary
7937 save_bool
7938 save_clearsv
7939 save_delete
7940 save_destructor
7941 save_destructor_x
7942 save_freeop
7943 save_freepv
7944 save_freesv
7945 save_generic_pvref
7946 save_generic_svref
7947 save_gp
7948 save_hash
7949 save_hdelete
7950 save_helem
7951 save_helem_flags
7952 save_hints
7953 save_hptr
7954 save_int
7955 save_item
7956 save_iv
7957 save_list
7958 save_long
7959 save_mortalizesv
7960 save_nogv
7961 save_op
7962 save_padsv_and_mortalize
7963 save_pptr
7964 save_pushi32ptr
7965 save_pushptr
7966 save_pushptrptr
7967 save_re_context
7968 save_scalar
7969 save_set_svflags
7970 save_shared_pvref
7971 save_sptr
7972 save_svref
7973 save_vptr
7974 savestack_grow
7975 savestack_grow_cnt
7976 scan_num
7977 scan_vstring
7978 screaminstr
7979 seed
7980 set_context
7981 set_numeric_local
7982 set_numeric_radix
7983 set_numeric_standard
7984 share_hek
7985 si_dup
7986 ss_dup
7987 stack_grow
7988 start_subparse
7989 stashpv_hvname_match
7990 str_to_version
7991 sv_2iv
7992 sv_2pv
7993 sv_2uv
7994 sv_catpvf_mg_nocontext
7995 sv_catpvf_nocontext
7996 sv_compile_2op
7997 sv_dump
7998 sv_dup
7999 sv_dup_inc
8000 sv_peek
8001 sv_pvn_nomg
8002 sv_setpvf_mg_nocontext
8003 sv_setpvf_nocontext
8004 sv_utf8_upgrade_flags_grow
8005 swash_fetch
8006 swash_init
8007 sys_init
8008 sys_init3
8009 sys_intern_clear
8010 sys_intern_dup
8011 sys_intern_init
8012 sys_term
8013 taint_env
8014 taint_proper
8015 tmps_grow
8016 to_uni_fold
8017 to_uni_lower
8018 to_uni_lower_lc
8019 to_uni_title
8020 to_uni_title_lc
8021 to_uni_upper
8022 to_uni_upper_lc
8023 unlnk
8024 unsharepvn
8025 utf16_to_utf8
8026 utf16_to_utf8_reversed
8027 uvchr_to_utf8_flags
8028 uvuni_to_utf8
8029 vdeb
8030 vform
8031 vload_module
8032 vnewSVpvf
8033 vwarner
8034 warn_nocontext
8035 warner
8036 warner_nocontext
8037 whichsig
8038 whichsig_pv
8039 whichsig_pvn
8040 whichsig_sv
8041
8043 Until May 1997, this document was maintained by Jeff Okamoto
8044 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
8045 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
8047 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
8048 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
8049 Stephen McCamant, and Gurusamy Sarathy.
8050 API Listing originally by Dean Roehrich <roehrich@cray.com>.
8052 Updated to be autogenerated from comments in the source by Benjamin
8054 Stuhl.
8055
8057 perlguts, perlxs, perlxstut, perlintern
8058perl v5.16.3 2019-01-21 PERLAPI(1)