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. The interfaces of any
12 functions that are not listed here are subject to change without
13 notice. For this reason, blindly using functions listed in proto.h is
14 to be avoided when writing extensions.
15 Note that all Perl API global variables must be referenced with the
17 "PL_" prefix. Some macros are provided for compatibility with the
18 older, unadorned names, but this support may be disabled in a future
19 release.
20 Perl was originally written to handle US-ASCII only (that is characters
22 whose ordinal numbers are in the range 0 - 127). And documentation and
23 comments may still use the term ASCII, when sometimes in fact the
24 entire range from 0 - 255 is meant.
25 Note that Perl can be compiled and run under EBCDIC (See perlebcdic) or
27 ASCII. Most of the documentation (and even comments in the code)
28 ignore the EBCDIC possibility. For almost all purposes the differences
29 are transparent. As an example, under EBCDIC, instead of UTF-8, UTF-
30 EBCDIC is used to encode Unicode strings, and so whenever this
31 documentation refers to "utf8" (and variants of that name, including in
32 function names), it also (essentially transparently) means
33 "UTF-EBCDIC". But the ordinals of characters differ between ASCII,
34 EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may
35 occupy more bytes than in UTF-8.
36 Also, on some EBCDIC machines, functions that are documented as
38 operating on US-ASCII (or Basic Latin in Unicode terminology) may in
39 fact operate on all 256 characters in the EBCDIC range, not just the
40 subset corresponding to US-ASCII.
41 The listing below is alphabetical, case insensitive.
43
45 GIMME A backward-compatible version of "GIMME_V" which can only
46 return "G_SCALAR" or "G_ARRAY"; in a void context, it returns
47 "G_SCALAR". Deprecated. Use "GIMME_V" instead.
48 U32 GIMME
50 GIMME_V The XSUB-writer's equivalent to Perl's "wantarray". Returns
52 "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list
53 context, respectively.
54 U32 GIMME_V
56 G_ARRAY Used to indicate list context. See "GIMME_V", "GIMME" and
58 perlcall.
59 G_DISCARD
61 Indicates that arguments returned from a callback should be
62 discarded. See perlcall.
63 G_EVAL Used to force a Perl "eval" wrapper around a callback. See
65 perlcall.
66 G_NOARGS
68 Indicates that no arguments are being sent to a callback. See
69 perlcall.
70 G_SCALAR
72 Used to indicate scalar context. See "GIMME_V", "GIMME", and
73 perlcall.
74 G_VOID Used to indicate void context. See "GIMME_V" and perlcall.
76
78 AvFILL Same as "av_len()". Deprecated, use "av_len()" instead.
79 int AvFILL(AV* av)
81 av_clear
83 Clears an array, making it empty. Does not free the memory
84 used by the array itself.
85 void av_clear(AV *av)
87 av_create_and_push
89 Push an SV onto the end of the array, creating the array if
90 necessary. A small internal helper function to remove a
91 commonly duplicated idiom.
92 NOTE: this function is experimental and may change or be
94 removed without notice.
95 void av_create_and_push(AV **const avp, SV *const val)
97 av_create_and_unshift_one
99 Unshifts an SV onto the beginning of the array, creating the
100 array if necessary. A small internal helper function to remove
101 a commonly duplicated idiom.
102 NOTE: this function is experimental and may change or be
104 removed without notice.
105 SV** av_create_and_unshift_one(AV **const avp, SV *const val)
107 av_delete
109 Deletes the element indexed by "key" from the array. Returns
110 the deleted element. If "flags" equals "G_DISCARD", the element
111 is freed and null is returned.
112 SV* av_delete(AV *av, I32 key, I32 flags)
114 av_exists
116 Returns true if the element indexed by "key" has been
117 initialized.
118 This relies on the fact that uninitialized array elements are
120 set to &PL_sv_undef.
121 bool av_exists(AV *av, I32 key)
123 av_extend
125 Pre-extend an array. The "key" is the index to which the array
126 should be extended.
127 void av_extend(AV *av, I32 key)
129 av_fetch
131 Returns the SV at the specified index in the array. The "key"
132 is the index. If "lval" is set then the fetch will be part of
133 a store. Check that the return value is non-null before
134 dereferencing it to a "SV*".
135 See "Understanding the Magic of Tied Hashes and Arrays" in
137 perlguts for more information on how to use this function on
138 tied arrays.
139 SV** av_fetch(AV *av, I32 key, I32 lval)
141 av_fill Set the highest index in the array to the given number,
143 equivalent to Perl's "$#array = $fill;".
144 The number of elements in the an array will be "fill + 1" after
146 av_fill() returns. If the array was previously shorter then
147 the additional elements appended are set to "PL_sv_undef". If
148 the array was longer, then the excess elements are freed.
149 "av_fill(av, -1)" is the same as "av_clear(av)".
150 void av_fill(AV *av, I32 fill)
152 av_len Returns the highest index in the array. The number of elements
154 in the array is "av_len(av) + 1". Returns -1 if the array is
155 empty.
156 I32 av_len(AV *av)
158 av_make Creates a new AV and populates it with a list of SVs. The SVs
160 are copied into the array, so they may be freed after the call
161 to av_make. The new AV will have a reference count of 1.
162 AV* av_make(I32 size, SV **strp)
164 av_pop Pops an SV off the end of the array. Returns &PL_sv_undef if
166 the array is empty.
167 SV* av_pop(AV *av)
169 av_push Pushes an SV onto the end of the array. The array will grow
171 automatically to accommodate the addition. Like "av_store",
172 this takes ownership of one reference count.
173 void av_push(AV *av, SV *val)
175 av_shift
177 Shifts an SV off the beginning of the array. Returns
178 &PL_sv_undef if the array is empty.
179 SV* av_shift(AV *av)
181 av_store
183 Stores an SV in an array. The array index is specified as
184 "key". The return value will be NULL if the operation failed
185 or if the value did not need to be actually stored within the
186 array (as in the case of tied arrays). Otherwise it can be
187 dereferenced to get the original "SV*". Note that the caller
188 is responsible for suitably incrementing the reference count of
189 "val" before the call, and decrementing it if the function
190 returned NULL.
191 See "Understanding the Magic of Tied Hashes and Arrays" in
193 perlguts for more information on how to use this function on
194 tied arrays.
195 SV** av_store(AV *av, I32 key, SV *val)
197 av_undef
199 Undefines the array. Frees the memory used by the array
200 itself.
201 void av_undef(AV *av)
203 av_unshift
205 Unshift the given number of "undef" values onto the beginning
206 of the array. The array will grow automatically to accommodate
207 the addition. You must then use "av_store" to assign values to
208 these new elements.
209 void av_unshift(AV *av, I32 num)
211 get_av Returns the AV of the specified Perl array. "flags" are passed
213 to "gv_fetchpv". If "GV_ADD" is set and the Perl variable does
214 not exist then it will be created. If "flags" is zero and the
215 variable does not exist then NULL is returned.
216 NOTE: the perl_ form of this function is deprecated.
218 AV* get_av(const char *name, I32 flags)
220 newAV Creates a new AV. The reference count is set to 1.
222 AV* newAV()
224 sortsv Sort an array. Here is an example:
226 sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
228 Currently this always uses mergesort. See sortsv_flags for a
230 more flexible routine.
231 void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
233 sortsv_flags
235 Sort an array, with various options.
236 void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags)
238
240 call_argv
241 Performs a callback to the specified Perl sub. See perlcall.
242 NOTE: the perl_ form of this function is deprecated.
244 I32 call_argv(const char* sub_name, I32 flags, char** argv)
246 call_method
248 Performs a callback to the specified Perl method. The blessed
249 object must be on the stack. See perlcall.
250 NOTE: the perl_ form of this function is deprecated.
252 I32 call_method(const char* methname, I32 flags)
254 call_pv Performs a callback to the specified Perl sub. See perlcall.
256 NOTE: the perl_ form of this function is deprecated.
258 I32 call_pv(const char* sub_name, I32 flags)
260 call_sv Performs a callback to the Perl sub whose name is in the SV.
262 See perlcall.
263 NOTE: the perl_ form of this function is deprecated.
265 I32 call_sv(SV* sv, VOL I32 flags)
267 ENTER Opening bracket on a callback. See "LEAVE" and perlcall.
269 ENTER;
271 eval_pv Tells Perl to "eval" the given string and return an SV* result.
273 NOTE: the perl_ form of this function is deprecated.
275 SV* eval_pv(const char* p, I32 croak_on_error)
277 eval_sv Tells Perl to "eval" the string in the SV.
279 NOTE: the perl_ form of this function is deprecated.
281 I32 eval_sv(SV* sv, I32 flags)
283 FREETMPS
285 Closing bracket for temporaries on a callback. See "SAVETMPS"
286 and perlcall.
287 FREETMPS;
289 LEAVE Closing bracket on a callback. See "ENTER" and perlcall.
291 LEAVE;
293 SAVETMPS
295 Opening bracket for temporaries on a callback. See "FREETMPS"
296 and perlcall.
297 SAVETMPS;
299
301 isALNUM Returns a boolean indicating whether the C "char" is a US-ASCII
302 (Basic Latin) alphanumeric character (including underscore) or
303 digit.
304 bool isALNUM(char ch)
306 isALPHA Returns a boolean indicating whether the C "char" is a US-ASCII
308 (Basic Latin) alphabetic character.
309 bool isALPHA(char ch)
311 isDIGIT Returns a boolean indicating whether the C "char" is a US-ASCII
313 (Basic Latin) digit.
314 bool isDIGIT(char ch)
316 isLOWER Returns a boolean indicating whether the C "char" is a US-ASCII
318 (Basic Latin) lowercase character.
319 bool isLOWER(char ch)
321 isSPACE Returns a boolean indicating whether the C "char" is a US-ASCII
323 (Basic Latin) whitespace.
324 bool isSPACE(char ch)
326 isUPPER Returns a boolean indicating whether the C "char" is a US-ASCII
328 (Basic Latin) uppercase character.
329 bool isUPPER(char ch)
331 toLOWER Converts the specified character to lowercase. Characters
333 outside the US-ASCII (Basic Latin) range are viewed as not
334 having any case.
335 char toLOWER(char ch)
337 toUPPER Converts the specified character to uppercase. Characters
339 outside the US-ASCII (Basic Latin) range are viewed as not
340 having any case.
341 char toUPPER(char ch)
343
345 perl_clone
346 Create and return a new interpreter by cloning the current one.
347 perl_clone takes these flags as parameters:
349 CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
351 without it we only clone the data and zero the stacks, with it
352 we copy the stacks and the new perl interpreter is ready to run
353 at the exact same point as the previous one. The pseudo-fork
354 code uses COPY_STACKS while the threads->create doesn't.
355 CLONEf_KEEP_PTR_TABLE perl_clone keeps a ptr_table with the
357 pointer of the old variable as a key and the new variable as a
358 value, this allows it to check if something has been cloned and
359 not clone it again but rather just use the value and increase
360 the refcount. If KEEP_PTR_TABLE is not set then perl_clone will
361 kill the ptr_table using the function
362 "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;", reason to
363 keep it around is if you want to dup some of your own variable
364 who are outside the graph perl scans, example of this code is
365 in threads.xs create
366 CLONEf_CLONE_HOST This is a win32 thing, it is ignored on unix,
368 it tells perls win32host code (which is c++) to clone itself,
369 this is needed on win32 if you want to run two threads at the
370 same time, if you just want to do some stuff in a separate perl
371 interpreter and then throw it away and return to the original
372 one, you don't need to do anything.
373 PerlInterpreter* perl_clone(PerlInterpreter *proto_perl, UV flags)
375
377 CvSTASH Returns the stash of the CV.
378 HV* CvSTASH(CV* cv)
380 get_cv Uses "strlen" to get the length of "name", then calls
382 "get_cvn_flags".
383 NOTE: the perl_ form of this function is deprecated.
385 CV* get_cv(const char* name, I32 flags)
387 get_cvn_flags
389 Returns the CV of the specified Perl subroutine. "flags" are
390 passed to "gv_fetchpvn_flags". If "GV_ADD" is set and the Perl
391 subroutine does not exist then it will be declared (which has
392 the same effect as saying "sub name;"). If "GV_ADD" is not set
393 and the subroutine does not exist then NULL is returned.
394 NOTE: the perl_ form of this function is deprecated.
396 CV* get_cvn_flags(const char* name, STRLEN len, I32 flags)
398
400 cv_undef
401 Clear out all the active components of a CV. This can happen
402 either by an explicit "undef &foo", or by the reference count
403 going to zero. In the former case, we keep the CvOUTSIDE
404 pointer, so that any anonymous children can still follow the
405 full lexical scope chain.
406 void cv_undef(CV* cv)
408 load_module
410 Loads the module whose name is pointed to by the string part of
411 name. Note that the actual module name, not its filename,
412 should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm".
413 flags can be any of PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT,
414 or PERL_LOADMOD_IMPORT_OPS (or 0 for no flags). ver, if
415 specified, provides version semantics similar to "use Foo::Bar
416 VERSION". The optional trailing SV* arguments can be used to
417 specify arguments to the module's import() method, similar to
418 "use Foo::Bar VERSION LIST". They must be terminated with a
419 final NULL pointer. Note that this list can only be omitted
420 when the PERL_LOADMOD_NOIMPORT flag has been used. Otherwise
421 at least a single NULL pointer to designate the default import
422 list is required.
423 void load_module(U32 flags, SV* name, SV* ver, ...)
425 nothreadhook
427 Stub that provides thread hook for perl_destruct when there are
428 no threads.
429 int nothreadhook()
431 perl_alloc
433 Allocates a new Perl interpreter. See perlembed.
434 PerlInterpreter* perl_alloc()
436 perl_construct
438 Initializes a new Perl interpreter. See perlembed.
439 void perl_construct(PerlInterpreter *my_perl)
441 perl_destruct
443 Shuts down a Perl interpreter. See perlembed.
444 int perl_destruct(PerlInterpreter *my_perl)
446 perl_free
448 Releases a Perl interpreter. See perlembed.
449 void perl_free(PerlInterpreter *my_perl)
451 perl_parse
453 Tells a Perl interpreter to parse a Perl script. See
454 perlembed.
455 int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit, int argc, char** argv, char** env)
457 perl_run
459 Tells a Perl interpreter to run. See perlembed.
460 int perl_run(PerlInterpreter *my_perl)
462 require_pv
464 Tells Perl to "require" the file named by the string argument.
465 It is analogous to the Perl code "eval "require '$file'"".
466 It's even implemented that way; consider using load_module
467 instead.
468 NOTE: the perl_ form of this function is deprecated.
470 void require_pv(const char* pv)
472
474 pv_display
475 Similar to
476 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
478 except that an additional "\0" will be appended to the string
480 when len > cur and pv[cur] is "\0".
481 Note that the final string may be up to 7 chars longer than
483 pvlim.
484 char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
486 pv_escape
488 Escapes at most the first "count" chars of pv and puts the
489 results into dsv such that the size of the escaped string will
490 not exceed "max" chars and will not contain any incomplete
491 escape sequences.
492 If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes
494 in the string will also be escaped.
495 Normally the SV will be cleared before the escaped string is
497 prepared, but when PERL_PV_ESCAPE_NOCLEAR is set this will not
498 occur.
499 If PERL_PV_ESCAPE_UNI is set then the input string is treated
501 as Unicode, if PERL_PV_ESCAPE_UNI_DETECT is set then the input
502 string is scanned using "is_utf8_string()" to determine if it
503 is Unicode.
504 If PERL_PV_ESCAPE_ALL is set then all input chars will be
506 output using "\x01F1" style escapes, otherwise only chars above
507 255 will be escaped using this style, other non printable chars
508 will use octal or common escaped patterns like "\n". If
509 PERL_PV_ESCAPE_NOBACKSLASH then all chars below 255 will be
510 treated as printable and will be output as literals.
511 If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of
513 the string will be escaped, regardles of max. If the string is
514 utf8 and the chars value is >255 then it will be returned as a
515 plain hex sequence. Thus the output will either be a single
516 char, an octal escape sequence, a special escape like "\n" or a
517 3 or more digit hex value.
518 If PERL_PV_ESCAPE_RE is set then the escape char used will be a
520 '%' and not a '\\'. This is because regexes very often contain
521 backslashed sequences, whereas '%' is not a particularly common
522 character in patterns.
523 Returns a pointer to the escaped text as held by dsv.
525 char* pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
527 pv_pretty
529 Converts a string into something presentable, handling escaping
530 via pv_escape() and supporting quoting and ellipses.
531 If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
533 double quoted with any double quotes in the string escaped.
534 Otherwise if the PERL_PV_PRETTY_LTGT flag is set then the
535 result be wrapped in angle brackets.
536 If the PERL_PV_PRETTY_ELLIPSES flag is set and not all
538 characters in string were output then an ellipsis "..." will be
539 appended to the string. Note that this happens AFTER it has
540 been quoted.
541 If start_color is non-null then it will be inserted after the
543 opening quote (if there is one) but before the escaped text. If
544 end_color is non-null then it will be inserted after the
545 escaped text but before any quotes or ellipses.
546 Returns a pointer to the prettified text as held by dsv.
548 char* pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)
550
552 gv_fetchmethod
553 See gv_fetchmethod_autoload.
554 GV* gv_fetchmethod(HV* stash, const char* name)
556 pack_cat
558 The engine implementing pack() Perl function. Note: parameters
559 next_in_list and flags are not used. This call should not be
560 used; use packlist instead.
561 void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
563 sv_2pvbyte_nolen
565 Return a pointer to the byte-encoded representation of the SV.
566 May cause the SV to be downgraded from UTF-8 as a side-effect.
567 Usually accessed via the "SvPVbyte_nolen" macro.
569 char* sv_2pvbyte_nolen(SV* sv)
571 sv_2pvutf8_nolen
573 Return a pointer to the UTF-8-encoded representation of the SV.
574 May cause the SV to be upgraded to UTF-8 as a side-effect.
575 Usually accessed via the "SvPVutf8_nolen" macro.
577 char* sv_2pvutf8_nolen(SV* sv)
579 sv_2pv_nolen
581 Like "sv_2pv()", but doesn't return the length too. You should
582 usually use the macro wrapper "SvPV_nolen(sv)" instead.
583 char* sv_2pv_nolen(SV* sv)
584 sv_catpvn_mg
586 Like "sv_catpvn", but also handles 'set' magic.
587 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
589 sv_catsv_mg
591 Like "sv_catsv", but also handles 'set' magic.
592 void sv_catsv_mg(SV *dsv, SV *ssv)
594 sv_force_normal
596 Undo various types of fakery on an SV: if the PV is a shared
597 string, make a private copy; if we're a ref, stop refing; if
598 we're a glob, downgrade to an xpvmg. See also
599 "sv_force_normal_flags".
600 void sv_force_normal(SV *sv)
602 sv_iv A private implementation of the "SvIVx" macro for compilers
604 which can't cope with complex macro expressions. Always use the
605 macro instead.
606 IV sv_iv(SV* sv)
608 sv_nolocking
610 Dummy routine which "locks" an SV when there is no locking
611 module present. Exists to avoid test for a NULL function
612 pointer and because it could potentially warn under some level
613 of strict-ness.
614 "Superseded" by sv_nosharing().
616 void sv_nolocking(SV *sv)
618 sv_nounlocking
620 Dummy routine which "unlocks" an SV when there is no locking
621 module present. Exists to avoid test for a NULL function
622 pointer and because it could potentially warn under some level
623 of strict-ness.
624 "Superseded" by sv_nosharing().
626 void sv_nounlocking(SV *sv)
628 sv_nv A private implementation of the "SvNVx" macro for compilers
630 which can't cope with complex macro expressions. Always use the
631 macro instead.
632 NV sv_nv(SV* sv)
634 sv_pv Use the "SvPV_nolen" macro instead
636 char* sv_pv(SV *sv)
638 sv_pvbyte
640 Use "SvPVbyte_nolen" instead.
641 char* sv_pvbyte(SV *sv)
643 sv_pvbyten
645 A private implementation of the "SvPVbyte" macro for compilers
646 which can't cope with complex macro expressions. Always use the
647 macro instead.
648 char* sv_pvbyten(SV *sv, STRLEN *lp)
650 sv_pvn A private implementation of the "SvPV" macro for compilers
652 which can't cope with complex macro expressions. Always use the
653 macro instead.
654 char* sv_pvn(SV *sv, STRLEN *lp)
656 sv_pvutf8
658 Use the "SvPVutf8_nolen" macro instead
659 char* sv_pvutf8(SV *sv)
661 sv_pvutf8n
663 A private implementation of the "SvPVutf8" macro for compilers
664 which can't cope with complex macro expressions. Always use the
665 macro instead.
666 char* sv_pvutf8n(SV *sv, STRLEN *lp)
668 sv_taint
670 Taint an SV. Use "SvTAINTED_on" instead.
671 void sv_taint(SV* sv)
672 sv_unref
674 Unsets the RV status of the SV, and decrements the reference
675 count of whatever was being referenced by the RV. This can
676 almost be thought of as a reversal of "newSVrv". This is
677 "sv_unref_flags" with the "flag" being zero. See "SvROK_off".
678 void sv_unref(SV* sv)
680 sv_usepvn
682 Tells an SV to use "ptr" to find its string value. Implemented
683 by calling "sv_usepvn_flags" with "flags" of 0, hence does not
684 handle 'set' magic. See "sv_usepvn_flags".
685 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
687 sv_usepvn_mg
689 Like "sv_usepvn", but also handles 'set' magic.
690 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
692 sv_uv A private implementation of the "SvUVx" macro for compilers
694 which can't cope with complex macro expressions. Always use the
695 macro instead.
696 UV sv_uv(SV* sv)
698 unpack_str
700 The engine implementing unpack() Perl function. Note:
701 parameters strbeg, new_s and ocnt are not used. This call
702 should not be used, use unpackstring instead.
703 I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
705
707 PERL_SYS_INIT
708 Provides system-specific tune up of the C runtime environment
709 necessary to run Perl interpreters. This should be called only
710 once, before creating any Perl interpreters.
711 void PERL_SYS_INIT(int argc, char** argv)
713 PERL_SYS_INIT3
715 Provides system-specific tune up of the C runtime environment
716 necessary to run Perl interpreters. This should be called only
717 once, before creating any Perl interpreters.
718 void PERL_SYS_INIT3(int argc, char** argv, char** env)
720 PERL_SYS_TERM
722 Provides system-specific clean up of the C runtime environment
723 after running Perl interpreters. This should be called only
724 once, after freeing any remaining Perl interpreters.
725 void PERL_SYS_TERM()
727
729 find_runcv
730 Locate the CV corresponding to the currently executing sub or
731 eval. If db_seqp is non_null, skip CVs that are in the DB
732 package and populate *db_seqp with the cop sequence number at
733 the point that the DB:: code was entered. (allows debuggers to
734 eval in the scope of the breakpoint rather than in the scope of
735 the debugger itself).
736 CV* find_runcv(U32 *db_seqp)
738
740 packlist
741 The engine implementing pack() Perl function.
742 void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
744 unpackstring
746 The engine implementing unpack() Perl function. "unpackstring"
747 puts the extracted list items on the stack and returns the
748 number of elements. Issue "PUTBACK" before and "SPAGAIN" after
749 the call to this function.
750 I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
752
754 setdefout
755 Sets PL_defoutgv, the default file handle for output, to the
756 passed in typeglob. As PL_defoutgv "owns" a reference on its
757 typeglob, the reference count of the passed in typeglob is
758 increased by one, and the reference count of the typeglob that
759 PL_defoutgv points to is decreased by one.
760 void setdefout(GV* gv)
762
764 PL_keyword_plugin
765 Function pointer, pointing at a function used to handle
766 extended keywords. The function should be declared as
767 int keyword_plugin_function(pTHX_
769 char *keyword_ptr, STRLEN keyword_len,
770 OP **op_ptr)
771 The function is called from the tokeniser, whenever a possible
773 keyword is seen. "keyword_ptr" points at the word in the
774 parser's input buffer, and "keyword_len" gives its length; it
775 is not null-terminated. The function is expected to examine
776 the word, and possibly other state such as %^H, to decide
777 whether it wants to handle it as an extended keyword. If it
778 does not, the function should return "KEYWORD_PLUGIN_DECLINE",
779 and the normal parser process will continue.
780 If the function wants to handle the keyword, it first must
782 parse anything following the keyword that is part of the syntax
783 introduced by the keyword. See "Lexer interface" for details.
784 When a keyword is being handled, the plugin function must build
786 a tree of "OP" structures, representing the code that was
787 parsed. The root of the tree must be stored in *op_ptr. The
788 function then returns a contant indicating the syntactic role
789 of the construct that it has parsed: "KEYWORD_PLUGIN_STMT" if
790 it is a complete statement, or "KEYWORD_PLUGIN_EXPR" if it is
791 an expression. Note that a statement construct cannot be used
792 inside an expression (except via "do BLOCK" and similar), and
793 an expression is not a complete statement (it requires at least
794 a terminating semicolon).
795 When a keyword is handled, the plugin function may also have
797 (compile-time) side effects. It may modify "%^H", define
798 functions, and so on. Typically, if side effects are the main
799 purpose of a handler, it does not wish to generate any ops to
800 be included in the normal compilation. In this case it is
801 still required to supply an op tree, but it suffices to
802 generate a single null op.
803 That's how the *PL_keyword_plugin function needs to behave
805 overall. Conventionally, however, one does not completely
806 replace the existing handler function. Instead, take a copy of
807 "PL_keyword_plugin" before assigning your own function pointer
808 to it. Your handler function should look for keywords that it
809 is interested in and handle those. Where it is not interested,
810 it should call the saved plugin function, passing on the
811 arguments it received. Thus "PL_keyword_plugin" actually
812 points at a chain of handler functions, all of which have an
813 opportunity to handle keywords, and only the last function in
814 the chain (built into the Perl core) will normally return
815 "KEYWORD_PLUGIN_DECLINE".
816 NOTE: this function is experimental and may change or be
818 removed without notice.
819
821 GvSV Return the SV from the GV.
822 SV* GvSV(GV* gv)
824 gv_const_sv
826 If "gv" is a typeglob whose subroutine entry is a constant sub
827 eligible for inlining, or "gv" is a placeholder reference that
828 would be promoted to such a typeglob, then returns the value
829 returned by the sub. Otherwise, returns NULL.
830 SV* gv_const_sv(GV* gv)
832 gv_fetchmeth
834 Returns the glob with the given "name" and a defined subroutine
835 or "NULL". The glob lives in the given "stash", or in the
836 stashes accessible via @ISA and UNIVERSAL::.
837 The argument "level" should be either 0 or -1. If "level==0",
839 as a side-effect creates a glob with the given "name" in the
840 given "stash" which in the case of success contains an alias
841 for the subroutine, and sets up caching info for this glob.
842 This function grants "SUPER" token as a postfix of the stash
844 name. The GV returned from "gv_fetchmeth" may be a method cache
845 entry, which is not visible to Perl code. So when calling
846 "call_sv", you should not use the GV directly; instead, you
847 should use the method's CV, which can be obtained from the GV
848 with the "GvCV" macro.
849 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
851 gv_fetchmethod_autoload
853 Returns the glob which contains the subroutine to call to
854 invoke the method on the "stash". In fact in the presence of
855 autoloading this may be the glob for "AUTOLOAD". In this case
856 the corresponding variable $AUTOLOAD is already setup.
857 The third parameter of "gv_fetchmethod_autoload" determines
859 whether AUTOLOAD lookup is performed if the given method is not
860 present: non-zero means yes, look for AUTOLOAD; zero means no,
861 don't look for AUTOLOAD. Calling "gv_fetchmethod" is
862 equivalent to calling "gv_fetchmethod_autoload" with a non-zero
863 "autoload" parameter.
864 These functions grant "SUPER" token as a prefix of the method
866 name. Note that if you want to keep the returned glob for a
867 long time, you need to check for it being "AUTOLOAD", since at
868 the later time the call may load a different subroutine due to
869 $AUTOLOAD changing its value. Use the glob created via a side
870 effect to do this.
871 These functions have the same side-effects and as
873 "gv_fetchmeth" with "level==0". "name" should be writable if
874 contains ':' or ' ''. The warning against passing the GV
875 returned by "gv_fetchmeth" to "call_sv" apply equally to these
876 functions.
877 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
879 gv_fetchmeth_autoload
881 Same as gv_fetchmeth(), but looks for autoloaded subroutines
882 too. Returns a glob for the subroutine.
883 For an autoloaded subroutine without a GV, will create a GV
885 even if "level < 0". For an autoloaded subroutine without a
886 stub, GvCV() of the result may be zero.
887 GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
889 gv_stashpv
891 Returns a pointer to the stash for a specified package. Uses
892 "strlen" to determine the length of "name", then calls
893 "gv_stashpvn()".
894 HV* gv_stashpv(const char* name, I32 flags)
896 gv_stashpvn
898 Returns a pointer to the stash for a specified package. The
899 "namelen" parameter indicates the length of the "name", in
900 bytes. "flags" is passed to "gv_fetchpvn_flags()", so if set
901 to "GV_ADD" then the package will be created if it does not
902 already exist. If the package does not exist and "flags" is 0
903 (or any other setting that does not create packages) then NULL
904 is returned.
905 HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
907 gv_stashpvs
909 Like "gv_stashpvn", but takes a literal string instead of a
910 string/length pair.
911 HV* gv_stashpvs(const char* name, I32 create)
913 gv_stashsv
915 Returns a pointer to the stash for a specified package. See
916 "gv_stashpvn".
917 HV* gv_stashsv(SV* sv, I32 flags)
919
921 Nullav Null AV pointer.
922 (deprecated - use "(AV *)NULL" instead)
924 Nullch Null character pointer. (No longer available when "PERL_CORE"
926 is defined.)
927 Nullcv Null CV pointer.
929 (deprecated - use "(CV *)NULL" instead)
931 Nullhv Null HV pointer.
933 (deprecated - use "(HV *)NULL" instead)
935 Nullsv Null SV pointer. (No longer available when "PERL_CORE" is
937 defined.)
938
940 get_hv Returns the HV of the specified Perl hash. "flags" are passed
941 to "gv_fetchpv". If "GV_ADD" is set and the Perl variable does
942 not exist then it will be created. If "flags" is zero and the
943 variable does not exist then NULL is returned.
944 NOTE: the perl_ form of this function is deprecated.
946 HV* get_hv(const char *name, I32 flags)
948 HEf_SVKEY
950 This flag, used in the length slot of hash entries and magic
951 structures, specifies the structure contains an "SV*" pointer
952 where a "char*" pointer is to be expected. (For information
953 only--not to be used).
954 HeHASH Returns the computed hash stored in the hash entry.
956 U32 HeHASH(HE* he)
958 HeKEY Returns the actual pointer stored in the key slot of the hash
960 entry. The pointer may be either "char*" or "SV*", depending on
961 the value of "HeKLEN()". Can be assigned to. The "HePV()" or
962 "HeSVKEY()" macros are usually preferable for finding the value
963 of a key.
964 void* HeKEY(HE* he)
966 HeKLEN If this is negative, and amounts to "HEf_SVKEY", it indicates
968 the entry holds an "SV*" key. Otherwise, holds the actual
969 length of the key. Can be assigned to. The "HePV()" macro is
970 usually preferable for finding key lengths.
971 STRLEN HeKLEN(HE* he)
973 HePV Returns the key slot of the hash entry as a "char*" value,
975 doing any necessary dereferencing of possibly "SV*" keys. The
976 length of the string is placed in "len" (this is a macro, so do
977 not use &len). If you do not care about what the length of the
978 key is, you may use the global variable "PL_na", though this is
979 rather less efficient than using a local variable. Remember
980 though, that hash keys in perl are free to contain embedded
981 nulls, so using "strlen()" or similar is not a good way to find
982 the length of hash keys. This is very similar to the "SvPV()"
983 macro described elsewhere in this document. See also "HeUTF8".
984 If you are using "HePV" to get values to pass to "newSVpvn()"
986 to create a new SV, you should consider using
987 "newSVhek(HeKEY_hek(he))" as it is more efficient.
988 char* HePV(HE* he, STRLEN len)
990 HeSVKEY Returns the key as an "SV*", or "NULL" if the hash entry does
992 not contain an "SV*" key.
993 SV* HeSVKEY(HE* he)
995 HeSVKEY_force
997 Returns the key as an "SV*". Will create and return a
998 temporary mortal "SV*" if the hash entry contains only a
999 "char*" key.
1000 SV* HeSVKEY_force(HE* he)
1002 HeSVKEY_set
1004 Sets the key to a given "SV*", taking care to set the
1005 appropriate flags to indicate the presence of an "SV*" key, and
1006 returns the same "SV*".
1007 SV* HeSVKEY_set(HE* he, SV* sv)
1009 HeUTF8 Returns whether the "char *" value returned by "HePV" is
1011 encoded in UTF-8, doing any necessary dereferencing of possibly
1012 "SV*" keys. The value returned will be 0 or non-0, not
1013 necessarily 1 (or even a value with any low bits set), so do
1014 not blindly assign this to a "bool" variable, as "bool" may be
1015 a typedef for "char".
1016 char* HeUTF8(HE* he)
1018 HeVAL Returns the value slot (type "SV*") stored in the hash entry.
1020 SV* HeVAL(HE* he)
1022 HvNAME Returns the package name of a stash, or NULL if "stash" isn't a
1024 stash. See "SvSTASH", "CvSTASH".
1025 char* HvNAME(HV* stash)
1027 hv_assert
1029 Check that a hash is in an internally consistent state.
1030 void hv_assert(HV *hv)
1032 hv_clear
1034 Clears a hash, making it empty.
1035 void hv_clear(HV *hv)
1037 hv_clear_placeholders
1039 Clears any placeholders from a hash. If a restricted hash has
1040 any of its keys marked as readonly and the key is subsequently
1041 deleted, the key is not actually deleted but is marked by
1042 assigning it a value of &PL_sv_placeholder. This tags it so it
1043 will be ignored by future operations such as iterating over the
1044 hash, but will still allow the hash to have a value reassigned
1045 to the key at some future point. This function clears any such
1046 placeholder keys from the hash. See Hash::Util::lock_keys()
1047 for an example of its use.
1048 void hv_clear_placeholders(HV *hv)
1050 hv_delete
1052 Deletes a key/value pair in the hash. The value SV is removed
1053 from the hash and returned to the caller. The "klen" is the
1054 length of the key. The "flags" value will normally be zero; if
1055 set to G_DISCARD then NULL will be returned.
1056 SV* hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
1058 hv_delete_ent
1060 Deletes a key/value pair in the hash. The value SV is removed
1061 from the hash and returned to the caller. The "flags" value
1062 will normally be zero; if set to G_DISCARD then NULL will be
1063 returned. "hash" can be a valid precomputed hash value, or 0
1064 to ask for it to be computed.
1065 SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
1067 hv_exists
1069 Returns a boolean indicating whether the specified hash key
1070 exists. The "klen" is the length of the key.
1071 bool hv_exists(HV *hv, const char *key, I32 klen)
1073 hv_exists_ent
1075 Returns a boolean indicating whether the specified hash key
1076 exists. "hash" can be a valid precomputed hash value, or 0 to
1077 ask for it to be computed.
1078 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
1080 hv_fetch
1082 Returns the SV which corresponds to the specified key in the
1083 hash. The "klen" is the length of the key. If "lval" is set
1084 then the fetch will be part of a store. Check that the return
1085 value is non-null before dereferencing it to an "SV*".
1086 See "Understanding the Magic of Tied Hashes and Arrays" in
1088 perlguts for more information on how to use this function on
1089 tied hashes.
1090 SV** hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
1092 hv_fetchs
1094 Like "hv_fetch", but takes a literal string instead of a
1095 string/length pair.
1096 SV** hv_fetchs(HV* tb, const char* key, I32 lval)
1098 hv_fetch_ent
1100 Returns the hash entry which corresponds to the specified key
1101 in the hash. "hash" must be a valid precomputed hash number
1102 for the given "key", or 0 if you want the function to compute
1103 it. IF "lval" is set then the fetch will be part of a store.
1104 Make sure the return value is non-null before accessing it.
1105 The return value when "tb" is a tied hash is a pointer to a
1106 static location, so be sure to make a copy of the structure if
1107 you need to store it somewhere.
1108 See "Understanding the Magic of Tied Hashes and Arrays" in
1110 perlguts for more information on how to use this function on
1111 tied hashes.
1112 HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
1114 hv_iterinit
1116 Prepares a starting point to traverse a hash table. Returns
1117 the number of keys in the hash (i.e. the same as "HvKEYS(tb)").
1118 The return value is currently only meaningful for hashes
1119 without tie magic.
1120 NOTE: Before version 5.004_65, "hv_iterinit" used to return the
1122 number of hash buckets that happen to be in use. If you still
1123 need that esoteric value, you can get it through the macro
1124 "HvFILL(tb)".
1125 I32 hv_iterinit(HV *hv)
1127 hv_iterkey
1129 Returns the key from the current position of the hash iterator.
1130 See "hv_iterinit".
1131 char* hv_iterkey(HE* entry, I32* retlen)
1133 hv_iterkeysv
1135 Returns the key as an "SV*" from the current position of the
1136 hash iterator. The return value will always be a mortal copy
1137 of the key. Also see "hv_iterinit".
1138 SV* hv_iterkeysv(HE* entry)
1140 hv_iternext
1142 Returns entries from a hash iterator. See "hv_iterinit".
1143 You may call "hv_delete" or "hv_delete_ent" on the hash entry
1145 that the iterator currently points to, without losing your
1146 place or invalidating your iterator. Note that in this case
1147 the current entry is deleted from the hash with your iterator
1148 holding the last reference to it. Your iterator is flagged to
1149 free the entry on the next call to "hv_iternext", so you must
1150 not discard your iterator immediately else the entry will leak
1151 - call "hv_iternext" to trigger the resource deallocation.
1152 HE* hv_iternext(HV *hv)
1154 hv_iternextsv
1156 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in
1157 one operation.
1158 SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
1160 hv_iternext_flags
1162 Returns entries from a hash iterator. See "hv_iterinit" and
1163 "hv_iternext". The "flags" value will normally be zero; if
1164 HV_ITERNEXT_WANTPLACEHOLDERS is set the placeholders keys (for
1165 restricted hashes) will be returned in addition to normal keys.
1166 By default placeholders are automatically skipped over.
1167 Currently a placeholder is implemented with a value that is
1168 &Perl_sv_placeholder. Note that the implementation of
1169 placeholders and restricted hashes may change, and the
1170 implementation currently is insufficiently abstracted for any
1171 change to be tidy.
1172 NOTE: this function is experimental and may change or be
1174 removed without notice.
1175 HE* hv_iternext_flags(HV *hv, I32 flags)
1177 hv_iterval
1179 Returns the value from the current position of the hash
1180 iterator. See "hv_iterkey".
1181 SV* hv_iterval(HV *hv, HE *entry)
1183 hv_magic
1185 Adds magic to a hash. See "sv_magic".
1186 void hv_magic(HV *hv, GV *gv, int how)
1188 hv_scalar
1190 Evaluates the hash in scalar context and returns the result.
1191 Handles magic when the hash is tied.
1192 SV* hv_scalar(HV *hv)
1194 hv_store
1196 Stores an SV in a hash. The hash key is specified as "key" and
1197 "klen" is the length of the key. The "hash" parameter is the
1198 precomputed hash value; if it is zero then Perl will compute
1199 it. The return value will be NULL if the operation failed or
1200 if the value did not need to be actually stored within the hash
1201 (as in the case of tied hashes). Otherwise it can be
1202 dereferenced to get the original "SV*". Note that the caller
1203 is responsible for suitably incrementing the reference count of
1204 "val" before the call, and decrementing it if the function
1205 returned NULL. Effectively a successful hv_store takes
1206 ownership of one reference to "val". This is usually what you
1207 want; a newly created SV has a reference count of one, so if
1208 all your code does is create SVs then store them in a hash,
1209 hv_store will own the only reference to the new SV, and your
1210 code doesn't need to do anything further to tidy up. hv_store
1211 is not implemented as a call to hv_store_ent, and does not
1212 create a temporary SV for the key, so if your key data is not
1213 already in SV form then use hv_store in preference to
1214 hv_store_ent.
1215 See "Understanding the Magic of Tied Hashes and Arrays" in
1217 perlguts for more information on how to use this function on
1218 tied hashes.
1219 SV** hv_store(HV *hv, const char *key, I32 klen, SV *val, U32 hash)
1221 hv_stores
1223 Like "hv_store", but takes a literal string instead of a
1224 string/length pair and omits the hash parameter.
1225 SV** hv_stores(HV* tb, const char* key, NULLOK SV* val)
1227 hv_store_ent
1229 Stores "val" in a hash. The hash key is specified as "key".
1230 The "hash" parameter is the precomputed hash value; if it is
1231 zero then Perl will compute it. The return value is the new
1232 hash entry so created. It will be NULL if the operation failed
1233 or if the value did not need to be actually stored within the
1234 hash (as in the case of tied hashes). Otherwise the contents
1235 of the return value can be accessed using the "He?" macros
1236 described here. Note that the caller is responsible for
1237 suitably incrementing the reference count of "val" before the
1238 call, and decrementing it if the function returned NULL.
1239 Effectively a successful hv_store_ent takes ownership of one
1240 reference to "val". This is usually what you want; a newly
1241 created SV has a reference count of one, so if all your code
1242 does is create SVs then store them in a hash, hv_store will own
1243 the only reference to the new SV, and your code doesn't need to
1244 do anything further to tidy up. Note that hv_store_ent only
1245 reads the "key"; unlike "val" it does not take ownership of it,
1246 so maintaining the correct reference count on "key" is entirely
1247 the caller's responsibility. hv_store is not implemented as a
1248 call to hv_store_ent, and does not create a temporary SV for
1249 the key, so if your key data is not already in SV form then use
1250 hv_store in preference to hv_store_ent.
1251 See "Understanding the Magic of Tied Hashes and Arrays" in
1253 perlguts for more information on how to use this function on
1254 tied hashes.
1255 HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
1257 hv_undef
1259 Undefines the hash.
1260 void hv_undef(HV *hv)
1262 newHV Creates a new HV. The reference count is set to 1.
1264 HV* newHV()
1266
1268 lex_bufutf8
1269 Indicates whether the octets in the lexer buffer
1270 ("PL_parser->linestr") should be interpreted as the UTF-8
1271 encoding of Unicode characters. If not, they should be
1272 interpreted as Latin-1 characters. This is analogous to the
1273 "SvUTF8" flag for scalars.
1274 In UTF-8 mode, it is not guaranteed that the lexer buffer
1276 actually contains valid UTF-8. Lexing code must be robust in
1277 the face of invalid encoding.
1278 The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
1280 significant, but not the whole story regarding the input
1281 character encoding. Normally, when a file is being read, the
1282 scalar contains octets and its "SvUTF8" flag is off, but the
1283 octets should be interpreted as UTF-8 if the "use utf8" pragma
1284 is in effect. During a string eval, however, the scalar may
1285 have the "SvUTF8" flag on, and in this case its octets should
1286 be interpreted as UTF-8 unless the "use bytes" pragma is in
1287 effect. This logic may change in the future; use this function
1288 instead of implementing the logic yourself.
1289 NOTE: this function is experimental and may change or be
1291 removed without notice.
1292 bool lex_bufutf8()
1294 lex_discard_to
1296 Discards the first part of the "PL_parser->linestr" buffer, up
1297 to ptr. The remaining content of the buffer will be moved, and
1298 all pointers into the buffer updated appropriately. ptr must
1299 not be later in the buffer than the position of
1300 "PL_parser->bufptr": it is not permitted to discard text that
1301 has yet to be lexed.
1302 Normally it is not necessarily to do this directly, because it
1304 suffices to use the implicit discarding behaviour of
1305 "lex_next_chunk" and things based on it. However, if a token
1306 stretches across multiple lines, and the lexing code has kept
1307 multiple lines of text in the buffer fof that purpose, then
1308 after completion of the token it would be wise to explicitly
1309 discard the now-unneeded earlier lines, to avoid future multi-
1310 line tokens growing the buffer without bound.
1311 NOTE: this function is experimental and may change or be
1313 removed without notice.
1314 void lex_discard_to(char *ptr)
1316 lex_grow_linestr
1318 Reallocates the lexer buffer ("PL_parser->linestr") to
1319 accommodate at least len octets (including terminating NUL).
1320 Returns a pointer to the reallocated buffer. This is necessary
1321 before making any direct modification of the buffer that would
1322 increase its length. "lex_stuff_pvn" provides a more
1323 convenient way to insert text into the buffer.
1324 Do not use "SvGROW" or "sv_grow" directly on
1326 "PL_parser->linestr"; this function updates all of the lexer's
1327 variables that point directly into the buffer.
1328 NOTE: this function is experimental and may change or be
1330 removed without notice.
1331 char * lex_grow_linestr(STRLEN len)
1333 lex_next_chunk
1335 Reads in the next chunk of text to be lexed, appending it to
1336 "PL_parser->linestr". This should be called when lexing code
1337 has looked to the end of the current chunk and wants to know
1338 more. It is usual, but not necessary, for lexing to have
1339 consumed the entirety of the current chunk at this time.
1340 If "PL_parser->bufptr" is pointing to the very end of the
1342 current chunk (i.e., the current chunk has been entirely
1343 consumed), normally the current chunk will be discarded at the
1344 same time that the new chunk is read in. If flags includes
1345 "LEX_KEEP_PREVIOUS", the current chunk will not be discarded.
1346 If the current chunk has not been entirely consumed, then it
1347 will not be discarded regardless of the flag.
1348 Returns true if some new text was added to the buffer, or false
1350 if the buffer has reached the end of the input text.
1351 NOTE: this function is experimental and may change or be
1353 removed without notice.
1354 bool lex_next_chunk(U32 flags)
1356 lex_peek_unichar
1358 Looks ahead one (Unicode) character in the text currently being
1359 lexed. Returns the codepoint (unsigned integer value) of the
1360 next character, or -1 if lexing has reached the end of the
1361 input text. To consume the peeked character, use
1362 "lex_read_unichar".
1363 If the next character is in (or extends into) the next chunk of
1365 input text, the next chunk will be read in. Normally the
1366 current chunk will be discarded at the same time, but if flags
1367 includes "LEX_KEEP_PREVIOUS" then the current chunk will not be
1368 discarded.
1369 If the input is being interpreted as UTF-8 and a UTF-8 encoding
1371 error is encountered, an exception is generated.
1372 NOTE: this function is experimental and may change or be
1374 removed without notice.
1375 I32 lex_peek_unichar(U32 flags)
1377 lex_read_space
1379 Reads optional spaces, in Perl style, in the text currently
1380 being lexed. The spaces may include ordinary whitespace
1381 characters and Perl-style comments. "#line" directives are
1382 processed if encountered. "PL_parser->bufptr" is moved past
1383 the spaces, so that it points at a non-space character (or the
1384 end of the input text).
1385 If spaces extend into the next chunk of input text, the next
1387 chunk will be read in. Normally the current chunk will be
1388 discarded at the same time, but if flags includes
1389 "LEX_KEEP_PREVIOUS" then the current chunk will not be
1390 discarded.
1391 NOTE: this function is experimental and may change or be
1393 removed without notice.
1394 void lex_read_space(U32 flags)
1396 lex_read_to
1398 Consume text in the lexer buffer, from "PL_parser->bufptr" up
1399 to ptr. This advances "PL_parser->bufptr" to match ptr,
1400 performing the correct bookkeeping whenever a newline character
1401 is passed. This is the normal way to consume lexed text.
1402 Interpretation of the buffer's octets can be abstracted out by
1404 using the slightly higher-level functions "lex_peek_unichar"
1405 and "lex_read_unichar".
1406 NOTE: this function is experimental and may change or be
1408 removed without notice.
1409 void lex_read_to(char *ptr)
1411 lex_read_unichar
1413 Reads the next (Unicode) character in the text currently being
1414 lexed. Returns the codepoint (unsigned integer value) of the
1415 character read, and moves "PL_parser->bufptr" past the
1416 character, or returns -1 if lexing has reached the end of the
1417 input text. To non-destructively examine the next character,
1418 use "lex_peek_unichar" instead.
1419 If the next character is in (or extends into) the next chunk of
1421 input text, the next chunk will be read in. Normally the
1422 current chunk will be discarded at the same time, but if flags
1423 includes "LEX_KEEP_PREVIOUS" then the current chunk will not be
1424 discarded.
1425 If the input is being interpreted as UTF-8 and a UTF-8 encoding
1427 error is encountered, an exception is generated.
1428 NOTE: this function is experimental and may change or be
1430 removed without notice.
1431 I32 lex_read_unichar(U32 flags)
1433 lex_stuff_pvn
1435 Insert characters into the lexer buffer ("PL_parser->linestr"),
1436 immediately after the current lexing point
1437 ("PL_parser->bufptr"), reallocating the buffer if necessary.
1438 This means that lexing code that runs later will see the
1439 characters as if they had appeared in the input. It is not
1440 recommended to do this as part of normal parsing, and most uses
1441 of this facility run the risk of the inserted characters being
1442 interpreted in an unintended manner.
1443 The string to be inserted is represented by len octets starting
1445 at pv. These octets are interpreted as either UTF-8 or
1446 Latin-1, according to whether the "LEX_STUFF_UTF8" flag is set
1447 in flags. The characters are recoded for the lexer buffer,
1448 according to how the buffer is currently being interpreted
1449 ("lex_bufutf8"). If a string to be interpreted is available as
1450 a Perl scalar, the "lex_stuff_sv" function is more convenient.
1451 NOTE: this function is experimental and may change or be
1453 removed without notice.
1454 void lex_stuff_pvn(char *pv, STRLEN len, U32 flags)
1456 lex_stuff_sv
1458 Insert characters into the lexer buffer ("PL_parser->linestr"),
1459 immediately after the current lexing point
1460 ("PL_parser->bufptr"), reallocating the buffer if necessary.
1461 This means that lexing code that runs later will see the
1462 characters as if they had appeared in the input. It is not
1463 recommended to do this as part of normal parsing, and most uses
1464 of this facility run the risk of the inserted characters being
1465 interpreted in an unintended manner.
1466 The string to be inserted is the string value of sv. The
1468 characters are recoded for the lexer buffer, according to how
1469 the buffer is currently being interpreted ("lex_bufutf8"). If
1470 a string to be interpreted is not already a Perl scalar, the
1471 "lex_stuff_pvn" function avoids the need to construct a scalar.
1472 NOTE: this function is experimental and may change or be
1474 removed without notice.
1475 void lex_stuff_sv(SV *sv, U32 flags)
1477 lex_unstuff
1479 Discards text about to be lexed, from "PL_parser->bufptr" up to
1480 ptr. Text following ptr will be moved, and the buffer
1481 shortened. This hides the discarded text from any lexing code
1482 that runs later, as if the text had never appeared.
1483 This is not the normal way to consume lexed text. For that,
1485 use "lex_read_to".
1486 NOTE: this function is experimental and may change or be
1488 removed without notice.
1489 void lex_unstuff(char *ptr)
1491 PL_parser
1493 Pointer to a structure encapsulating the state of the parsing
1494 operation currently in progress. The pointer can be locally
1495 changed to perform a nested parse without interfering with the
1496 state of an outer parse. Individual members of "PL_parser"
1497 have their own documentation.
1498 PL_parser->bufend
1500 Direct pointer to the end of the chunk of text currently being
1501 lexed, the end of the lexer buffer. This is equal to
1502 "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)". A NUL
1503 character (zero octet) is always located at the end of the
1504 buffer, and does not count as part of the buffer's contents.
1505 NOTE: this function is experimental and may change or be
1507 removed without notice.
1508 PL_parser->bufptr
1510 Points to the current position of lexing inside the lexer
1511 buffer. Characters around this point may be freely examined,
1512 within the range delimited by "SvPVX("PL_parser->linestr")" and
1513 "PL_parser->bufend". The octets of the buffer may be intended
1514 to be interpreted as either UTF-8 or Latin-1, as indicated by
1515 "lex_bufutf8".
1516 Lexing code (whether in the Perl core or not) moves this
1518 pointer past the characters that it consumes. It is also
1519 expected to perform some bookkeeping whenever a newline
1520 character is consumed. This movement can be more conveniently
1521 performed by the function "lex_read_to", which handles newlines
1522 appropriately.
1523 Interpretation of the buffer's octets can be abstracted out by
1525 using the slightly higher-level functions "lex_peek_unichar"
1526 and "lex_read_unichar".
1527 NOTE: this function is experimental and may change or be
1529 removed without notice.
1530 PL_parser->linestart
1532 Points to the start of the current line inside the lexer
1533 buffer. This is useful for indicating at which column an error
1534 occurred, and not much else. This must be updated by any
1535 lexing code that consumes a newline; the function "lex_read_to"
1536 handles this detail.
1537 NOTE: this function is experimental and may change or be
1539 removed without notice.
1540 PL_parser->linestr
1542 Buffer scalar containing the chunk currently under
1543 consideration of the text currently being lexed. This is
1544 always a plain string scalar (for which "SvPOK" is true). It
1545 is not intended to be used as a scalar by normal scalar means;
1546 instead refer to the buffer directly by the pointer variables
1547 described below.
1548 The lexer maintains various "char*" pointers to things in the
1550 "PL_parser->linestr" buffer. If "PL_parser->linestr" is ever
1551 reallocated, all of these pointers must be updated. Don't
1552 attempt to do this manually, but rather use "lex_grow_linestr"
1553 if you need to reallocate the buffer.
1554 The content of the text chunk in the buffer is commonly exactly
1556 one complete line of input, up to and including a newline
1557 terminator, but there are situations where it is otherwise.
1558 The octets of the buffer may be intended to be interpreted as
1559 either UTF-8 or Latin-1. The function "lex_bufutf8" tells you
1560 which. Do not use the "SvUTF8" flag on this scalar, which may
1561 disagree with it.
1562 For direct examination of the buffer, the variable
1564 "PL_parser->bufend" points to the end of the buffer. The
1565 current lexing position is pointed to by "PL_parser->bufptr".
1566 Direct use of these pointers is usually preferable to
1567 examination of the scalar through normal scalar means.
1568 NOTE: this function is experimental and may change or be
1570 removed without notice.
1571
1573 mg_clear
1574 Clear something magical that the SV represents. See
1575 "sv_magic".
1576 int mg_clear(SV* sv)
1578 mg_copy Copies the magic from one SV to another. See "sv_magic".
1580 int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
1582 mg_find Finds the magic pointer for type matching the SV. See
1584 "sv_magic".
1585 MAGIC* mg_find(const SV* sv, int type)
1587 mg_free Free any magic storage used by the SV. See "sv_magic".
1589 int mg_free(SV* sv)
1591 mg_get Do magic after a value is retrieved from the SV. See
1593 "sv_magic".
1594 int mg_get(SV* sv)
1596 mg_length
1598 Report on the SV's length. See "sv_magic".
1599 U32 mg_length(SV* sv)
1601 mg_magical
1603 Turns on the magical status of an SV. See "sv_magic".
1604 void mg_magical(SV* sv)
1606 mg_set Do magic after a value is assigned to the SV. See "sv_magic".
1608 int mg_set(SV* sv)
1610 SvGETMAGIC
1612 Invokes "mg_get" on an SV if it has 'get' magic. This macro
1613 evaluates its argument more than once.
1614 void SvGETMAGIC(SV* sv)
1616 SvLOCK Arranges for a mutual exclusion lock to be obtained on sv if a
1618 suitable module has been loaded.
1619 void SvLOCK(SV* sv)
1621 SvSETMAGIC
1623 Invokes "mg_set" on an SV if it has 'set' magic. This macro
1624 evaluates its argument more than once.
1625 void SvSETMAGIC(SV* sv)
1627 SvSetMagicSV
1629 Like "SvSetSV", but does any set magic required afterwards.
1630 void SvSetMagicSV(SV* dsb, SV* ssv)
1632 SvSetMagicSV_nosteal
1634 Like "SvSetSV_nosteal", but does any set magic required
1635 afterwards.
1636 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
1638 SvSetSV Calls "sv_setsv" if dsv is not the same as ssv. May evaluate
1640 arguments more than once.
1641 void SvSetSV(SV* dsb, SV* ssv)
1643 SvSetSV_nosteal
1645 Calls a non-destructive version of "sv_setsv" if dsv is not the
1646 same as ssv. May evaluate arguments more than once.
1647 void SvSetSV_nosteal(SV* dsv, SV* ssv)
1649 SvSHARE Arranges for sv to be shared between threads if a suitable
1651 module has been loaded.
1652 void SvSHARE(SV* sv)
1654 SvUNLOCK
1656 Releases a mutual exclusion lock on sv if a suitable module has
1657 been loaded.
1658 void SvUNLOCK(SV* sv)
1660
1662 Copy The XSUB-writer's interface to the C "memcpy" function. The
1663 "src" is the source, "dest" is the destination, "nitems" is the
1664 number of items, and "type" is the type. May fail on
1665 overlapping copies. See also "Move".
1666 void Copy(void* src, void* dest, int nitems, type)
1668 CopyD Like "Copy" but returns dest. Useful for encouraging compilers
1670 to tail-call optimise.
1671 void * CopyD(void* src, void* dest, int nitems, type)
1673 Move The XSUB-writer's interface to the C "memmove" function. The
1675 "src" is the source, "dest" is the destination, "nitems" is the
1676 number of items, and "type" is the type. Can do overlapping
1677 moves. See also "Copy".
1678 void Move(void* src, void* dest, int nitems, type)
1680 MoveD Like "Move" but returns dest. Useful for encouraging compilers
1682 to tail-call optimise.
1683 void * MoveD(void* src, void* dest, int nitems, type)
1685 Newx The XSUB-writer's interface to the C "malloc" function.
1687 In 5.9.3, Newx() and friends replace the older New() API, and
1689 drops the first parameter, x, a debug aid which allowed callers
1690 to identify themselves. This aid has been superseded by a new
1691 build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhack).
1692 The older API is still there for use in XS modules supporting
1693 older perls.
1694 void Newx(void* ptr, int nitems, type)
1696 Newxc The XSUB-writer's interface to the C "malloc" function, with
1698 cast. See also "Newx".
1699 void Newxc(void* ptr, int nitems, type, cast)
1701 Newxz The XSUB-writer's interface to the C "malloc" function. The
1703 allocated memory is zeroed with "memzero". See also "Newx".
1704 void Newxz(void* ptr, int nitems, type)
1706 Poison PoisonWith(0xEF) for catching access to freed memory.
1708 void Poison(void* dest, int nitems, type)
1710 PoisonFree
1712 PoisonWith(0xEF) for catching access to freed memory.
1713 void PoisonFree(void* dest, int nitems, type)
1715 PoisonNew
1717 PoisonWith(0xAB) for catching access to allocated but
1718 uninitialized memory.
1719 void PoisonNew(void* dest, int nitems, type)
1721 PoisonWith
1723 Fill up memory with a byte pattern (a byte repeated over and
1724 over again) that hopefully catches attempts to access
1725 uninitialized memory.
1726 void PoisonWith(void* dest, int nitems, type, U8 byte)
1728 Renew The XSUB-writer's interface to the C "realloc" function.
1730 void Renew(void* ptr, int nitems, type)
1732 Renewc The XSUB-writer's interface to the C "realloc" function, with
1734 cast.
1735 void Renewc(void* ptr, int nitems, type, cast)
1737 Safefree
1739 The XSUB-writer's interface to the C "free" function.
1740 void Safefree(void* ptr)
1742 savepv Perl's version of "strdup()". Returns a pointer to a newly
1744 allocated string which is a duplicate of "pv". The size of the
1745 string is determined by "strlen()". The memory allocated for
1746 the new string can be freed with the "Safefree()" function.
1747 char* savepv(const char* pv)
1749 savepvn Perl's version of what "strndup()" would be if it existed.
1751 Returns a pointer to a newly allocated string which is a
1752 duplicate of the first "len" bytes from "pv", plus a trailing
1753 NUL byte. The memory allocated for the new string can be freed
1754 with the "Safefree()" function.
1755 char* savepvn(const char* pv, I32 len)
1757 savepvs Like "savepvn", but takes a literal string instead of a
1759 string/length pair.
1760 char* savepvs(const char* s)
1762 savesharedpv
1764 A version of "savepv()" which allocates the duplicate string in
1765 memory which is shared between threads.
1766 char* savesharedpv(const char* pv)
1768 savesharedpvn
1770 A version of "savepvn()" which allocates the duplicate string
1771 in memory which is shared between threads. (With the specific
1772 difference that a NULL pointer is not acceptable)
1773 char* savesharedpvn(const char *const pv, const STRLEN len)
1775 savesvpv
1777 A version of "savepv()"/"savepvn()" which gets the string to
1778 duplicate from the passed in SV using "SvPV()"
1779 char* savesvpv(SV* sv)
1781 StructCopy
1783 This is an architecture-independent macro to copy one structure
1784 to another.
1785 void StructCopy(type src, type dest, type)
1787 Zero The XSUB-writer's interface to the C "memzero" function. The
1789 "dest" is the destination, "nitems" is the number of items, and
1790 "type" is the type.
1791 void Zero(void* dest, int nitems, type)
1793 ZeroD Like "Zero" but returns dest. Useful for encouraging compilers
1795 to tail-call optimise.
1796 void * ZeroD(void* dest, int nitems, type)
1798
1800 fbm_compile
1801 Analyses the string in order to make fast searches on it using
1802 fbm_instr() -- the Boyer-Moore algorithm.
1803 void fbm_compile(SV* sv, U32 flags)
1805 fbm_instr
1807 Returns the location of the SV in the string delimited by "str"
1808 and "strend". It returns "NULL" if the string can't be found.
1809 The "sv" does not have to be fbm_compiled, but the search will
1810 not be as fast then.
1811 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlestr, U32 flags)
1813 form Takes a sprintf-style format pattern and conventional (non-SV)
1815 arguments and returns the formatted string.
1816 (char *) Perl_form(pTHX_ const char* pat, ...)
1818 can be used any place a string (char *) is required:
1820 char * s = Perl_form("%d.%d",major,minor);
1822 Uses a single private buffer so if you want to format several
1824 strings you must explicitly copy the earlier strings away (and
1825 free the copies when you are done).
1826 char* form(const char* pat, ...)
1828 getcwd_sv
1830 Fill the sv with current working directory
1831 int getcwd_sv(SV* sv)
1833 my_snprintf
1835 The C library "snprintf" functionality, if available and
1836 standards-compliant (uses "vsnprintf", actually). However, if
1837 the "vsnprintf" is not available, will unfortunately use the
1838 unsafe "vsprintf" which can overrun the buffer (there is an
1839 overrun check, but that may be too late). Consider using
1840 "sv_vcatpvf" instead, or getting "vsnprintf".
1841 int my_snprintf(char *buffer, const Size_t len, const char *format, ...)
1843 my_sprintf
1845 The C library "sprintf", wrapped if necessary, to ensure that
1846 it will return the length of the string written to the buffer.
1847 Only rare pre-ANSI systems need the wrapper function - usually
1848 this is a direct call to "sprintf".
1849 int my_sprintf(char *buffer, const char *pat, ...)
1851 my_vsnprintf
1853 The C library "vsnprintf" if available and standards-compliant.
1854 However, if if the "vsnprintf" is not available, will
1855 unfortunately use the unsafe "vsprintf" which can overrun the
1856 buffer (there is an overrun check, but that may be too late).
1857 Consider using "sv_vcatpvf" instead, or getting "vsnprintf".
1858 int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
1860 new_version
1862 Returns a new version object based on the passed in SV:
1863 SV *sv = new_version(SV *ver);
1865 Does not alter the passed in ver SV. See "upg_version" if you
1867 want to upgrade the SV.
1868 SV* new_version(SV *ver)
1870 prescan_version
1872 const char* prescan_version(const char *s, bool strict, const char** errstr, bool *sqv, int *ssaw_decimal, int *swidth, bool *salpha)
1873 scan_version
1875 Returns a pointer to the next character after the parsed
1876 version string, as well as upgrading the passed in SV to an RV.
1877 Function must be called with an already existing SV like
1879 sv = newSV(0);
1881 s = scan_version(s, SV *sv, bool qv);
1882 Performs some preprocessing to the string to ensure that it has
1884 the correct characteristics of a version. Flags the object if
1885 it contains an underscore (which denotes this is an alpha
1886 version). The boolean qv denotes that the version should be
1887 interpreted as if it had multiple decimals, even if it doesn't.
1888 const char* scan_version(const char *s, SV *rv, bool qv)
1890 strEQ Test two strings to see if they are equal. Returns true or
1892 false.
1893 bool strEQ(char* s1, char* s2)
1895 strGE Test two strings to see if the first, "s1", is greater than or
1897 equal to the second, "s2". Returns true or false.
1898 bool strGE(char* s1, char* s2)
1900 strGT Test two strings to see if the first, "s1", is greater than the
1902 second, "s2". Returns true or false.
1903 bool strGT(char* s1, char* s2)
1905 strLE Test two strings to see if the first, "s1", is less than or
1907 equal to the second, "s2". Returns true or false.
1908 bool strLE(char* s1, char* s2)
1910 strLT Test two strings to see if the first, "s1", is less than the
1912 second, "s2". Returns true or false.
1913 bool strLT(char* s1, char* s2)
1915 strNE Test two strings to see if they are different. Returns true or
1917 false.
1918 bool strNE(char* s1, char* s2)
1920 strnEQ Test two strings to see if they are equal. The "len" parameter
1922 indicates the number of bytes to compare. Returns true or
1923 false. (A wrapper for "strncmp").
1924 bool strnEQ(char* s1, char* s2, STRLEN len)
1926 strnNE Test two strings to see if they are different. The "len"
1928 parameter indicates the number of bytes to compare. Returns
1929 true or false. (A wrapper for "strncmp").
1930 bool strnNE(char* s1, char* s2, STRLEN len)
1932 sv_destroyable
1934 Dummy routine which reports that object can be destroyed when
1935 there is no sharing module present. It ignores its single SV
1936 argument, and returns 'true'. Exists to avoid test for a NULL
1937 function pointer and because it could potentially warn under
1938 some level of strict-ness.
1939 bool sv_destroyable(SV *sv)
1941 sv_nosharing
1943 Dummy routine which "shares" an SV when there is no sharing
1944 module present. Or "locks" it. Or "unlocks" it. In other
1945 words, ignores its single SV argument. Exists to avoid test
1946 for a NULL function pointer and because it could potentially
1947 warn under some level of strict-ness.
1948 void sv_nosharing(SV *sv)
1950 upg_version
1952 In-place upgrade of the supplied SV to a version object.
1953 SV *sv = upg_version(SV *sv, bool qv);
1955 Returns a pointer to the upgraded SV. Set the boolean qv if
1957 you want to force this SV to be interpreted as an "extended"
1958 version.
1959 SV* upg_version(SV *ver, bool qv)
1961 vcmp Version object aware cmp. Both operands must already have been
1963 converted into version objects.
1964 int vcmp(SV *lhv, SV *rhv)
1966 vnormal Accepts a version object and returns the normalized string
1968 representation. Call like:
1969 sv = vnormal(rv);
1971 NOTE: you can pass either the object directly or the SV
1973 contained within the RV.
1974 SV* vnormal(SV *vs)
1976 vnumify Accepts a version object and returns the normalized floating
1978 point representation. Call like:
1979 sv = vnumify(rv);
1981 NOTE: you can pass either the object directly or the SV
1983 contained within the RV.
1984 SV* vnumify(SV *vs)
1986 vstringify
1988 In order to maintain maximum compatibility with earlier
1989 versions of Perl, this function will return either the floating
1990 point notation or the multiple dotted notation, depending on
1991 whether the original version contained 1 or more dots,
1992 respectively
1993 SV* vstringify(SV *vs)
1995 vverify Validates that the SV contains a valid version object.
1997 bool vverify(SV *vobj);
1999 Note that it only confirms the bare minimum structure (so as
2001 not to get confused by derived classes which may contain
2002 additional hash entries):
2003 bool vverify(SV *vs)
2005
2007 mro_get_linear_isa
2008 Returns either "mro_get_linear_isa_c3" or
2009 "mro_get_linear_isa_dfs" for the given stash, dependant upon
2010 which MRO is in effect for that stash. The return value is a
2011 read-only AV*.
2012 You are responsible for "SvREFCNT_inc()" on the return value if
2014 you plan to store it anywhere semi-permanently (otherwise it
2015 might be deleted out from under you the next time the cache is
2016 invalidated).
2017 AV* mro_get_linear_isa(HV* stash)
2019 mro_method_changed_in
2021 Invalidates method caching on any child classes of the given
2022 stash, so that they might notice the changes in this one.
2023 Ideally, all instances of "PL_sub_generation++" in perl source
2025 outside of "mro.c" should be replaced by calls to this.
2026 Perl automatically handles most of the common ways a method
2028 might be redefined. However, there are a few ways you could
2029 change a method in a stash without the cache code noticing, in
2030 which case you need to call this method afterwards:
2031 1) Directly manipulating the stash HV entries from XS code.
2033 2) Assigning a reference to a readonly scalar constant into a
2035 stash entry in order to create a constant subroutine (like
2036 constant.pm does).
2037 This same method is available from pure perl via,
2039 "mro::method_changed_in(classname)".
2040 void mro_method_changed_in(HV* stash)
2042
2044 dMULTICALL
2045 Declare local variables for a multicall. See "Lightweight
2046 Callbacks" in perlcall.
2047 dMULTICALL;
2049 MULTICALL
2051 Make a lightweight callback. See "Lightweight Callbacks" in
2052 perlcall.
2053 MULTICALL;
2055 POP_MULTICALL
2057 Closing bracket for a lightweight callback. See "Lightweight
2058 Callbacks" in perlcall.
2059 POP_MULTICALL;
2061 PUSH_MULTICALL
2063 Opening bracket for a lightweight callback. See "Lightweight
2064 Callbacks" in perlcall.
2065 PUSH_MULTICALL;
2067
2069 grok_bin
2070 converts a string representing a binary number to numeric form.
2071 On entry start and *len give the string to scan, *flags gives
2073 conversion flags, and result should be NULL or a pointer to an
2074 NV. The scan stops at the end of the string, or the first
2075 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
2076 in *flags, encountering an invalid character will also trigger
2077 a warning. On return *len is set to the length of the scanned
2078 string, and *flags gives output flags.
2079 If the value is <= "UV_MAX" it is returned as a UV, the output
2081 flags are clear, and nothing is written to *result. If the
2082 value is > UV_MAX "grok_bin" returns UV_MAX, sets
2083 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
2084 the value to *result (or the value is discarded if result is
2085 NULL).
2086 The binary number may optionally be prefixed with "0b" or "b"
2088 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
2089 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the
2090 binary number may use '_' characters to separate digits.
2091 UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
2093 grok_hex
2095 converts a string representing a hex number to numeric form.
2096 On entry start and *len give the string to scan, *flags gives
2098 conversion flags, and result should be NULL or a pointer to an
2099 NV. The scan stops at the end of the string, or the first
2100 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
2101 in *flags, encountering an invalid character will also trigger
2102 a warning. On return *len is set to the length of the scanned
2103 string, and *flags gives output flags.
2104 If the value is <= UV_MAX it is returned as a UV, the output
2106 flags are clear, and nothing is written to *result. If the
2107 value is > UV_MAX "grok_hex" returns UV_MAX, sets
2108 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
2109 the value to *result (or the value is discarded if result is
2110 NULL).
2111 The hex number may optionally be prefixed with "0x" or "x"
2113 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
2114 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the hex
2115 number may use '_' characters to separate digits.
2116 UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
2118 grok_number
2120 Recognise (or not) a number. The type of the number is
2121 returned (0 if unrecognised), otherwise it is a bit-ORed
2122 combination of IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX,
2123 IS_NUMBER_NOT_INT, IS_NUMBER_NEG, IS_NUMBER_INFINITY,
2124 IS_NUMBER_NAN (defined in perl.h).
2125 If the value of the number can fit an in UV, it is returned in
2127 the *valuep IS_NUMBER_IN_UV will be set to indicate that
2128 *valuep is valid, IS_NUMBER_IN_UV will never be set unless
2129 *valuep is valid, but *valuep may have been assigned to during
2130 processing even though IS_NUMBER_IN_UV is not set on return.
2131 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same
2132 cases as when valuep is non-NULL, but no actual assignment (or
2133 SEGV) will occur.
2134 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing
2136 decimals were seen (in which case *valuep gives the true value
2137 truncated to an integer), and IS_NUMBER_NEG if the number is
2138 negative (in which case *valuep holds the absolute value).
2139 IS_NUMBER_IN_UV is not set if e notation was used or the number
2140 is larger than a UV.
2141 int grok_number(const char *pv, STRLEN len, UV *valuep)
2143 grok_numeric_radix
2145 Scan and skip for a numeric decimal separator (radix).
2146 bool grok_numeric_radix(const char **sp, const char *send)
2148 grok_oct
2150 converts a string representing an octal number to numeric form.
2151 On entry start and *len give the string to scan, *flags gives
2153 conversion flags, and result should be NULL or a pointer to an
2154 NV. The scan stops at the end of the string, or the first
2155 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
2156 in *flags, encountering an invalid character will also trigger
2157 a warning. On return *len is set to the length of the scanned
2158 string, and *flags gives output flags.
2159 If the value is <= UV_MAX it is returned as a UV, the output
2161 flags are clear, and nothing is written to *result. If the
2162 value is > UV_MAX "grok_oct" returns UV_MAX, sets
2163 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
2164 the value to *result (or the value is discarded if result is
2165 NULL).
2166 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the
2168 octal number may use '_' characters to separate digits.
2169 UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
2171 Perl_signbit
2173 Return a non-zero integer if the sign bit on an NV is set, and
2174 0 if it is not.
2175 If Configure detects this system has a signbit() that will work
2177 with our NVs, then we just use it via the #define in perl.h.
2178 Otherwise, fall back on this implementation. As a first pass,
2179 this gets everything right except -0.0. Alas, catching -0.0 is
2180 the main use for this function, so this is not too helpful yet.
2181 Still, at least we have the scaffolding in place to support
2182 other systems, should that prove useful.
2183 Configure notes: This function is called 'Perl_signbit'
2185 instead of a plain 'signbit' because it is easy to imagine a
2186 system having a signbit() function or macro that doesn't happen
2187 to work with our particular choice of NVs. We shouldn't just
2188 re-#define signbit as Perl_signbit and expect the standard
2189 system headers to be happy. Also, this is a no-context
2190 function (no pTHX_) because Perl_signbit() is usually
2191 re-#defined in perl.h as a simple macro call to the system's
2192 signbit(). Users should just always call Perl_signbit().
2193 NOTE: this function is experimental and may change or be
2195 removed without notice.
2196 int Perl_signbit(NV f)
2198 scan_bin
2200 For backwards compatibility. Use "grok_bin" instead.
2201 NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
2203 scan_hex
2205 For backwards compatibility. Use "grok_hex" instead.
2206 NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
2208 scan_oct
2210 For backwards compatibility. Use "grok_oct" instead.
2211 NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
2213
2215 cv_const_sv
2216 If "cv" is a constant sub eligible for inlining. returns the
2217 constant value returned by the sub. Otherwise, returns NULL.
2218 Constant subs can be created with "newCONSTSUB" or as described
2220 in "Constant Functions" in perlsub.
2221 SV* cv_const_sv(const CV *const cv)
2223 newCONSTSUB
2225 Creates a constant sub equivalent to Perl "sub FOO () { 123 }"
2226 which is eligible for inlining at compile-time.
2227 Passing NULL for SV creates a constant sub equivalent to "sub
2229 BAR () {}", which won't be called if used as a destructor, but
2230 will suppress the overhead of a call to "AUTOLOAD". (This
2231 form, however, isn't eligible for inlining at compile time.)
2232 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
2234 newXS Used by "xsubpp" to hook up XSUBs as Perl subs. filename needs
2236 to be static storage, as it is used directly as CvFILE(),
2237 without a copy being made.
2238
2240 pad_findmy
2241 Given a lexical name, try to find its offset, first in the
2242 current pad, or failing that, in the pads of any lexically
2243 enclosing subs (including the complications introduced by
2244 eval). If the name is found in an outer pad, then a fake entry
2245 is added to the current pad. Returns the offset in the current
2246 pad, or NOT_IN_PAD on failure.
2247 NOTE: this function is experimental and may change or be
2249 removed without notice.
2250 PADOFFSET pad_findmy(const char* name, STRLEN len, U32 flags)
2252 pad_sv Get the value at offset po in the current pad. Use macro
2254 PAD_SV instead of calling this function directly.
2255 SV* pad_sv(PADOFFSET po)
2257
2259 PL_modglobal
2260 "PL_modglobal" is a general purpose, interpreter global HV for
2261 use by extensions that need to keep information on a per-
2262 interpreter basis. In a pinch, it can also be used as a symbol
2263 table for extensions to share data among each other. It is a
2264 good idea to use keys prefixed by the package name of the
2265 extension that owns the data.
2266 HV* PL_modglobal
2268 PL_na A convenience variable which is typically used with "SvPV" when
2270 one doesn't care about the length of the string. It is usually
2271 more efficient to either declare a local variable and use that
2272 instead or to use the "SvPV_nolen" macro.
2273 STRLEN PL_na
2275 PL_opfreehook
2277 When non-"NULL", the function pointed by this variable will be
2278 called each time an OP is freed with the corresponding OP as
2279 the argument. This allows extensions to free any extra
2280 attribute they have locally attached to an OP. It is also
2281 assured to first fire for the parent OP and then for its kids.
2282 When you replace this variable, it is considered a good
2284 practice to store the possibly previously installed hook and
2285 that you recall it inside your own.
2286 Perl_ophook_t PL_opfreehook
2288 PL_sv_no
2290 This is the "false" SV. See "PL_sv_yes". Always refer to this
2291 as &PL_sv_no.
2292 SV PL_sv_no
2294 PL_sv_undef
2296 This is the "undef" SV. Always refer to this as &PL_sv_undef.
2297 SV PL_sv_undef
2299 PL_sv_yes
2301 This is the "true" SV. See "PL_sv_no". Always refer to this
2302 as &PL_sv_yes.
2303 SV PL_sv_yes
2305
2307 SvRX Convenience macro to get the REGEXP from a SV. This is
2308 approximately equivalent to the following snippet:
2309 if (SvMAGICAL(sv))
2311 mg_get(sv);
2312 if (SvROK(sv) &&
2313 (tmpsv = (SV*)SvRV(sv)) &&
2314 SvTYPE(tmpsv) == SVt_PVMG &&
2315 (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
2316 {
2317 return (REGEXP *)tmpmg->mg_obj;
2318 }
2319 NULL will be returned if a REGEXP* is not found.
2321 REGEXP * SvRX(SV *sv)
2323 SvRXOK Returns a boolean indicating whether the SV contains qr magic
2325 (PERL_MAGIC_qr).
2326 If you want to do something with the REGEXP* later use SvRX
2328 instead and check for NULL.
2329 bool SvRXOK(SV* sv)
2331
2333 dXCPT Set up necessary local variables for exception handling. See
2334 "Exception Handling" in perlguts.
2335 dXCPT;
2337 XCPT_CATCH
2339 Introduces a catch block. See "Exception Handling" in
2340 perlguts.
2341 XCPT_RETHROW
2343 Rethrows a previously caught exception. See "Exception
2344 Handling" in perlguts.
2345 XCPT_RETHROW;
2347 XCPT_TRY_END
2349 Ends a try block. See "Exception Handling" in perlguts.
2350 XCPT_TRY_START
2352 Starts a try block. See "Exception Handling" in perlguts.
2353
2355 dMARK Declare a stack marker variable, "mark", for the XSUB. See
2356 "MARK" and "dORIGMARK".
2357 dMARK;
2359 dORIGMARK
2361 Saves the original stack mark for the XSUB. See "ORIGMARK".
2362 dORIGMARK;
2364 dSP Declares a local copy of perl's stack pointer for the XSUB,
2366 available via the "SP" macro. See "SP".
2367 dSP;
2369 EXTEND Used to extend the argument stack for an XSUB's return values.
2371 Once used, guarantees that there is room for at least "nitems"
2372 to be pushed onto the stack.
2373 void EXTEND(SP, int nitems)
2375 MARK Stack marker variable for the XSUB. See "dMARK".
2377 mPUSHi Push an integer onto the stack. The stack must have room for
2379 this element. Does not use "TARG". See also "PUSHi",
2380 "mXPUSHi" and "XPUSHi".
2381 void mPUSHi(IV iv)
2383 mPUSHn Push a double onto the stack. The stack must have room for
2385 this element. Does not use "TARG". See also "PUSHn",
2386 "mXPUSHn" and "XPUSHn".
2387 void mPUSHn(NV nv)
2389 mPUSHp Push a string onto the stack. The stack must have room for
2391 this element. The "len" indicates the length of the string.
2392 Does not use "TARG". See also "PUSHp", "mXPUSHp" and "XPUSHp".
2393 void mPUSHp(char* str, STRLEN len)
2395 mPUSHs Push an SV onto the stack and mortalizes the SV. The stack
2397 must have room for this element. Does not use "TARG". See
2398 also "PUSHs" and "mXPUSHs".
2399 void mPUSHs(SV* sv)
2401 mPUSHu Push an unsigned integer onto the stack. The stack must have
2403 room for this element. Does not use "TARG". See also "PUSHu",
2404 "mXPUSHu" and "XPUSHu".
2405 void mPUSHu(UV uv)
2407 mXPUSHi Push an integer onto the stack, extending the stack if
2409 necessary. Does not use "TARG". See also "XPUSHi", "mPUSHi"
2410 and "PUSHi".
2411 void mXPUSHi(IV iv)
2413 mXPUSHn Push a double onto the stack, extending the stack if necessary.
2415 Does not use "TARG". See also "XPUSHn", "mPUSHn" and "PUSHn".
2416 void mXPUSHn(NV nv)
2418 mXPUSHp Push a string onto the stack, extending the stack if necessary.
2420 The "len" indicates the length of the string. Does not use
2421 "TARG". See also "XPUSHp", "mPUSHp" and "PUSHp".
2422 void mXPUSHp(char* str, STRLEN len)
2424 mXPUSHs Push an SV onto the stack, extending the stack if necessary and
2426 mortalizes the SV. Does not use "TARG". See also "XPUSHs" and
2427 "mPUSHs".
2428 void mXPUSHs(SV* sv)
2430 mXPUSHu Push an unsigned integer onto the stack, extending the stack if
2432 necessary. Does not use "TARG". See also "XPUSHu", "mPUSHu"
2433 and "PUSHu".
2434 void mXPUSHu(UV uv)
2436 ORIGMARK
2438 The original stack mark for the XSUB. See "dORIGMARK".
2439 POPi Pops an integer off the stack.
2441 IV POPi
2443 POPl Pops a long off the stack.
2445 long POPl
2447 POPn Pops a double off the stack.
2449 NV POPn
2451 POPp Pops a string off the stack. Deprecated. New code should use
2453 POPpx.
2454 char* POPp
2456 POPpbytex
2458 Pops a string off the stack which must consist of bytes i.e.
2459 characters < 256.
2460 char* POPpbytex
2462 POPpx Pops a string off the stack.
2464 char* POPpx
2466 POPs Pops an SV off the stack.
2468 SV* POPs
2470 PUSHi Push an integer onto the stack. The stack must have room for
2472 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
2473 or "dXSTARG" should be called to declare it. Do not call
2474 multiple "TARG"-oriented macros to return lists from XSUB's -
2475 see "mPUSHi" instead. See also "XPUSHi" and "mXPUSHi".
2476 void PUSHi(IV iv)
2478 PUSHMARK
2480 Opening bracket for arguments on a callback. See "PUTBACK" and
2481 perlcall.
2482 void PUSHMARK(SP)
2484 PUSHmortal
2486 Push a new mortal SV onto the stack. The stack must have room
2487 for this element. Does not use "TARG". See also "PUSHs",
2488 "XPUSHmortal" and "XPUSHs".
2489 void PUSHmortal()
2491 PUSHn Push a double onto the stack. The stack must have room for
2493 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
2494 or "dXSTARG" should be called to declare it. Do not call
2495 multiple "TARG"-oriented macros to return lists from XSUB's -
2496 see "mPUSHn" instead. See also "XPUSHn" and "mXPUSHn".
2497 void PUSHn(NV nv)
2499 PUSHp Push a string onto the stack. The stack must have room for
2501 this element. The "len" indicates the length of the string.
2502 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
2503 should be called to declare it. Do not call multiple
2504 "TARG"-oriented macros to return lists from XSUB's - see
2505 "mPUSHp" instead. See also "XPUSHp" and "mXPUSHp".
2506 void PUSHp(char* str, STRLEN len)
2508 PUSHs Push an SV onto the stack. The stack must have room for this
2510 element. Does not handle 'set' magic. Does not use "TARG".
2511 See also "PUSHmortal", "XPUSHs" and "XPUSHmortal".
2512 void PUSHs(SV* sv)
2514 PUSHu Push an unsigned integer onto the stack. The stack must have
2516 room for this element. Handles 'set' magic. Uses "TARG", so
2517 "dTARGET" or "dXSTARG" should be called to declare it. Do not
2518 call multiple "TARG"-oriented macros to return lists from
2519 XSUB's - see "mPUSHu" instead. See also "XPUSHu" and
2520 "mXPUSHu".
2521 void PUSHu(UV uv)
2523 PUTBACK Closing bracket for XSUB arguments. This is usually handled by
2525 "xsubpp". See "PUSHMARK" and perlcall for other uses.
2526 PUTBACK;
2528 SP Stack pointer. This is usually handled by "xsubpp". See "dSP"
2530 and "SPAGAIN".
2531 SPAGAIN Refetch the stack pointer. Used after a callback. See
2533 perlcall.
2534 SPAGAIN;
2536 XPUSHi Push an integer onto the stack, extending the stack if
2538 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
2539 "dXSTARG" should be called to declare it. Do not call multiple
2540 "TARG"-oriented macros to return lists from XSUB's - see
2541 "mXPUSHi" instead. See also "PUSHi" and "mPUSHi".
2542 void XPUSHi(IV iv)
2544 XPUSHmortal
2546 Push a new mortal SV onto the stack, extending the stack if
2547 necessary. Does not use "TARG". See also "XPUSHs",
2548 "PUSHmortal" and "PUSHs".
2549 void XPUSHmortal()
2551 XPUSHn Push a double onto the stack, extending the stack if necessary.
2553 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
2554 should be called to declare it. Do not call multiple
2555 "TARG"-oriented macros to return lists from XSUB's - see
2556 "mXPUSHn" instead. See also "PUSHn" and "mPUSHn".
2557 void XPUSHn(NV nv)
2559 XPUSHp Push a string onto the stack, extending the stack if necessary.
2561 The "len" indicates the length of the string. Handles 'set'
2562 magic. Uses "TARG", so "dTARGET" or "dXSTARG" should be called
2563 to declare it. Do not call multiple "TARG"-oriented macros to
2564 return lists from XSUB's - see "mXPUSHp" instead. See also
2565 "PUSHp" and "mPUSHp".
2566 void XPUSHp(char* str, STRLEN len)
2568 XPUSHs Push an SV onto the stack, extending the stack if necessary.
2570 Does not handle 'set' magic. Does not use "TARG". See also
2571 "XPUSHmortal", "PUSHs" and "PUSHmortal".
2572 void XPUSHs(SV* sv)
2574 XPUSHu Push an unsigned integer onto the stack, extending the stack if
2576 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
2577 "dXSTARG" should be called to declare it. Do not call multiple
2578 "TARG"-oriented macros to return lists from XSUB's - see
2579 "mXPUSHu" instead. See also "PUSHu" and "mPUSHu".
2580 void XPUSHu(UV uv)
2582 XSRETURN
2584 Return from XSUB, indicating number of items on the stack.
2585 This is usually handled by "xsubpp".
2586 void XSRETURN(int nitems)
2588 XSRETURN_EMPTY
2590 Return an empty list from an XSUB immediately.
2591 XSRETURN_EMPTY;
2593 XSRETURN_IV
2595 Return an integer from an XSUB immediately. Uses "XST_mIV".
2596 void XSRETURN_IV(IV iv)
2598 XSRETURN_NO
2600 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
2601 XSRETURN_NO;
2603 XSRETURN_NV
2605 Return a double from an XSUB immediately. Uses "XST_mNV".
2606 void XSRETURN_NV(NV nv)
2608 XSRETURN_PV
2610 Return a copy of a string from an XSUB immediately. Uses
2611 "XST_mPV".
2612 void XSRETURN_PV(char* str)
2614 XSRETURN_UNDEF
2616 Return &PL_sv_undef from an XSUB immediately. Uses
2617 "XST_mUNDEF".
2618 XSRETURN_UNDEF;
2620 XSRETURN_UV
2622 Return an integer from an XSUB immediately. Uses "XST_mUV".
2623 void XSRETURN_UV(IV uv)
2625 XSRETURN_YES
2627 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
2628 XSRETURN_YES;
2630 XST_mIV Place an integer into the specified position "pos" on the
2632 stack. The value is stored in a new mortal SV.
2633 void XST_mIV(int pos, IV iv)
2635 XST_mNO Place &PL_sv_no into the specified position "pos" on the stack.
2637 void XST_mNO(int pos)
2639 XST_mNV Place a double into the specified position "pos" on the stack.
2641 The value is stored in a new mortal SV.
2642 void XST_mNV(int pos, NV nv)
2644 XST_mPV Place a copy of a string into the specified position "pos" on
2646 the stack. The value is stored in a new mortal SV.
2647 void XST_mPV(int pos, char* str)
2649 XST_mUNDEF
2651 Place &PL_sv_undef into the specified position "pos" on the
2652 stack.
2653 void XST_mUNDEF(int pos)
2655 XST_mYES
2657 Place &PL_sv_yes into the specified position "pos" on the
2658 stack.
2659 void XST_mYES(int pos)
2661
2663 svtype An enum of flags for Perl types. These are found in the file
2664 sv.h in the "svtype" enum. Test these flags with the "SvTYPE"
2665 macro.
2666 SVt_IV Integer type flag for scalars. See "svtype".
2668 SVt_NV Double type flag for scalars. See "svtype".
2670 SVt_PV Pointer type flag for scalars. See "svtype".
2672 SVt_PVAV
2674 Type flag for arrays. See "svtype".
2675 SVt_PVCV
2677 Type flag for code refs. See "svtype".
2678 SVt_PVHV
2680 Type flag for hashes. See "svtype".
2681 SVt_PVMG
2683 Type flag for blessed scalars. See "svtype".
2684
2686 croak_xs_usage
2687 A specialised variant of "croak()" for emitting the usage
2688 message for xsubs
2689 croak_xs_usage(cv, "eee_yow");
2691 works out the package name and subroutine name from "cv", and
2693 then calls "croak()". Hence if "cv" is &ouch::awk, it would
2694 call "croak" as:
2695 Perl_croak(aTHX_ "Usage %s::%s(%s)", "ouch" "awk", "eee_yow");
2697 void croak_xs_usage(const CV *const cv, const char *const params)
2699 get_sv Returns the SV of the specified Perl scalar. "flags" are
2701 passed to "gv_fetchpv". If "GV_ADD" is set and the Perl
2702 variable does not exist then it will be created. If "flags" is
2703 zero and the variable does not exist then NULL is returned.
2704 NOTE: the perl_ form of this function is deprecated.
2706 SV* get_sv(const char *name, I32 flags)
2708 newRV_inc
2710 Creates an RV wrapper for an SV. The reference count for the
2711 original SV is incremented.
2712 SV* newRV_inc(SV* sv)
2714 newSVpvn_utf8
2716 Creates a new SV and copies a string into it. If utf8 is true,
2717 calls "SvUTF8_on" on the new SV. Implemented as a wrapper
2718 around "newSVpvn_flags".
2719 SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len, U32 utf8)
2721 SvCUR Returns the length of the string which is in the SV. See
2723 "SvLEN".
2724 STRLEN SvCUR(SV* sv)
2726 SvCUR_set
2728 Set the current length of the string which is in the SV. See
2729 "SvCUR" and "SvIV_set".
2730 void SvCUR_set(SV* sv, STRLEN len)
2732 SvEND Returns a pointer to the last character in the string which is
2734 in the SV. See "SvCUR". Access the character as *(SvEND(sv)).
2735 char* SvEND(SV* sv)
2737 SvGAMAGIC
2739 Returns true if the SV has get magic or overloading. If either
2740 is true then the scalar is active data, and has the potential
2741 to return a new value every time it is accessed. Hence you must
2742 be careful to only read it once per user logical operation and
2743 work with that returned value. If neither is true then the
2744 scalar's value cannot change unless written to.
2745 U32 SvGAMAGIC(SV* sv)
2747 SvGROW Expands the character buffer in the SV so that it has room for
2749 the indicated number of bytes (remember to reserve space for an
2750 extra trailing NUL character). Calls "sv_grow" to perform the
2751 expansion if necessary. Returns a pointer to the character
2752 buffer.
2753 char * SvGROW(SV* sv, STRLEN len)
2755 SvIOK Returns a U32 value indicating whether the SV contains an
2757 integer.
2758 U32 SvIOK(SV* sv)
2760 SvIOKp Returns a U32 value indicating whether the SV contains an
2762 integer. Checks the private setting. Use "SvIOK" instead.
2763 U32 SvIOKp(SV* sv)
2765 SvIOK_notUV
2767 Returns a boolean indicating whether the SV contains a signed
2768 integer.
2769 bool SvIOK_notUV(SV* sv)
2771 SvIOK_off
2773 Unsets the IV status of an SV.
2774 void SvIOK_off(SV* sv)
2776 SvIOK_on
2778 Tells an SV that it is an integer.
2779 void SvIOK_on(SV* sv)
2781 SvIOK_only
2783 Tells an SV that it is an integer and disables all other OK
2784 bits.
2785 void SvIOK_only(SV* sv)
2787 SvIOK_only_UV
2789 Tells and SV that it is an unsigned integer and disables all
2790 other OK bits.
2791 void SvIOK_only_UV(SV* sv)
2793 SvIOK_UV
2795 Returns a boolean indicating whether the SV contains an
2796 unsigned integer.
2797 bool SvIOK_UV(SV* sv)
2799 SvIsCOW Returns a boolean indicating whether the SV is Copy-On-Write.
2801 (either shared hash key scalars, or full Copy On Write scalars
2802 if 5.9.0 is configured for COW)
2803 bool SvIsCOW(SV* sv)
2805 SvIsCOW_shared_hash
2807 Returns a boolean indicating whether the SV is Copy-On-Write
2808 shared hash key scalar.
2809 bool SvIsCOW_shared_hash(SV* sv)
2811 SvIV Coerces the given SV to an integer and returns it. See "SvIVx"
2813 for a version which guarantees to evaluate sv only once.
2814 IV SvIV(SV* sv)
2816 SvIVX Returns the raw value in the SV's IV slot, without checks or
2818 conversions. Only use when you are sure SvIOK is true. See
2819 also "SvIV()".
2820 IV SvIVX(SV* sv)
2822 SvIVx Coerces the given SV to an integer and returns it. Guarantees
2824 to evaluate "sv" only once. Only use this if "sv" is an
2825 expression with side effects, otherwise use the more efficient
2826 "SvIV".
2827 IV SvIVx(SV* sv)
2829 SvIV_nomg
2831 Like "SvIV" but doesn't process magic.
2832 IV SvIV_nomg(SV* sv)
2834 SvIV_set
2836 Set the value of the IV pointer in sv to val. It is possible
2837 to perform the same function of this macro with an lvalue
2838 assignment to "SvIVX". With future Perls, however, it will be
2839 more efficient to use "SvIV_set" instead of the lvalue
2840 assignment to "SvIVX".
2841 void SvIV_set(SV* sv, IV val)
2843 SvLEN Returns the size of the string buffer in the SV, not including
2845 any part attributable to "SvOOK". See "SvCUR".
2846 STRLEN SvLEN(SV* sv)
2848 SvLEN_set
2850 Set the actual length of the string which is in the SV. See
2851 "SvIV_set".
2852 void SvLEN_set(SV* sv, STRLEN len)
2854 SvMAGIC_set
2856 Set the value of the MAGIC pointer in sv to val. See
2857 "SvIV_set".
2858 void SvMAGIC_set(SV* sv, MAGIC* val)
2860 SvNIOK Returns a U32 value indicating whether the SV contains a
2862 number, integer or double.
2863 U32 SvNIOK(SV* sv)
2865 SvNIOKp Returns a U32 value indicating whether the SV contains a
2867 number, integer or double. Checks the private setting. Use
2868 "SvNIOK" instead.
2869 U32 SvNIOKp(SV* sv)
2871 SvNIOK_off
2873 Unsets the NV/IV status of an SV.
2874 void SvNIOK_off(SV* sv)
2876 SvNOK Returns a U32 value indicating whether the SV contains a
2878 double.
2879 U32 SvNOK(SV* sv)
2881 SvNOKp Returns a U32 value indicating whether the SV contains a
2883 double. Checks the private setting. Use "SvNOK" instead.
2884 U32 SvNOKp(SV* sv)
2886 SvNOK_off
2888 Unsets the NV status of an SV.
2889 void SvNOK_off(SV* sv)
2891 SvNOK_on
2893 Tells an SV that it is a double.
2894 void SvNOK_on(SV* sv)
2896 SvNOK_only
2898 Tells an SV that it is a double and disables all other OK bits.
2899 void SvNOK_only(SV* sv)
2901 SvNV Coerce the given SV to a double and return it. See "SvNVx" for
2903 a version which guarantees to evaluate sv only once.
2904 NV SvNV(SV* sv)
2906 SvNVX Returns the raw value in the SV's NV slot, without checks or
2908 conversions. Only use when you are sure SvNOK is true. See
2909 also "SvNV()".
2910 NV SvNVX(SV* sv)
2912 SvNVx Coerces the given SV to a double and returns it. Guarantees to
2914 evaluate "sv" only once. Only use this if "sv" is an expression
2915 with side effects, otherwise use the more efficient "SvNV".
2916 NV SvNVx(SV* sv)
2918 SvNV_set
2920 Set the value of the NV pointer in sv to val. See "SvIV_set".
2921 void SvNV_set(SV* sv, NV val)
2923 SvOK Returns a U32 value indicating whether the value is defined.
2925 This is only meaningful for scalars.
2926 U32 SvOK(SV* sv)
2928 SvOOK Returns a U32 indicating whether the pointer to the string
2930 buffer is offset. This hack is used internally to speed up
2931 removal of characters from the beginning of a SvPV. When SvOOK
2932 is true, then the start of the allocated string buffer is
2933 actually "SvOOK_offset()" bytes before SvPVX. This offset used
2934 to be stored in SvIVX, but is now stored within the spare part
2935 of the buffer.
2936 U32 SvOOK(SV* sv)
2938 SvOOK_offset
2940 Reads into len the offset from SvPVX back to the true start of
2941 the allocated buffer, which will be non-zero if "sv_chop" has
2942 been used to efficiently remove characters from start of the
2943 buffer. Implemented as a macro, which takes the address of len,
2944 which must be of type "STRLEN". Evaluates sv more than once.
2945 Sets len to 0 if "SvOOK(sv)" is false.
2946 void SvOOK_offset(NN SV*sv, STRLEN len)
2948 SvPOK Returns a U32 value indicating whether the SV contains a
2950 character string.
2951 U32 SvPOK(SV* sv)
2953 SvPOKp Returns a U32 value indicating whether the SV contains a
2955 character string. Checks the private setting. Use "SvPOK"
2956 instead.
2957 U32 SvPOKp(SV* sv)
2959 SvPOK_off
2961 Unsets the PV status of an SV.
2962 void SvPOK_off(SV* sv)
2964 SvPOK_on
2966 Tells an SV that it is a string.
2967 void SvPOK_on(SV* sv)
2969 SvPOK_only
2971 Tells an SV that it is a string and disables all other OK bits.
2972 Will also turn off the UTF-8 status.
2973 void SvPOK_only(SV* sv)
2975 SvPOK_only_UTF8
2977 Tells an SV that it is a string and disables all other OK bits,
2978 and leaves the UTF-8 status as it was.
2979 void SvPOK_only_UTF8(SV* sv)
2981 SvPV Returns a pointer to the string in the SV, or a stringified
2983 form of the SV if the SV does not contain a string. The SV may
2984 cache the stringified version becoming "SvPOK". Handles 'get'
2985 magic. See also "SvPVx" for a version which guarantees to
2986 evaluate sv only once.
2987 char* SvPV(SV* sv, STRLEN len)
2989 SvPVbyte
2991 Like "SvPV", but converts sv to byte representation first if
2992 necessary.
2993 char* SvPVbyte(SV* sv, STRLEN len)
2995 SvPVbytex
2997 Like "SvPV", but converts sv to byte representation first if
2998 necessary. Guarantees to evaluate sv only once; use the more
2999 efficient "SvPVbyte" otherwise.
3000 char* SvPVbytex(SV* sv, STRLEN len)
3002 SvPVbytex_force
3004 Like "SvPV_force", but converts sv to byte representation first
3005 if necessary. Guarantees to evaluate sv only once; use the
3006 more efficient "SvPVbyte_force" otherwise.
3007 char* SvPVbytex_force(SV* sv, STRLEN len)
3009 SvPVbyte_force
3011 Like "SvPV_force", but converts sv to byte representation first
3012 if necessary.
3013 char* SvPVbyte_force(SV* sv, STRLEN len)
3015 SvPVbyte_nolen
3017 Like "SvPV_nolen", but converts sv to byte representation first
3018 if necessary.
3019 char* SvPVbyte_nolen(SV* sv)
3021 SvPVutf8
3023 Like "SvPV", but converts sv to utf8 first if necessary.
3024 char* SvPVutf8(SV* sv, STRLEN len)
3026 SvPVutf8x
3028 Like "SvPV", but converts sv to utf8 first if necessary.
3029 Guarantees to evaluate sv only once; use the more efficient
3030 "SvPVutf8" otherwise.
3031 char* SvPVutf8x(SV* sv, STRLEN len)
3033 SvPVutf8x_force
3035 Like "SvPV_force", but converts sv to utf8 first if necessary.
3036 Guarantees to evaluate sv only once; use the more efficient
3037 "SvPVutf8_force" otherwise.
3038 char* SvPVutf8x_force(SV* sv, STRLEN len)
3040 SvPVutf8_force
3042 Like "SvPV_force", but converts sv to utf8 first if necessary.
3043 char* SvPVutf8_force(SV* sv, STRLEN len)
3045 SvPVutf8_nolen
3047 Like "SvPV_nolen", but converts sv to utf8 first if necessary.
3048 char* SvPVutf8_nolen(SV* sv)
3050 SvPVX Returns a pointer to the physical string in the SV. The SV
3052 must contain a string.
3053 char* SvPVX(SV* sv)
3055 SvPVx A version of "SvPV" which guarantees to evaluate "sv" only
3057 once. Only use this if "sv" is an expression with side
3058 effects, otherwise use the more efficient "SvPVX".
3059 char* SvPVx(SV* sv, STRLEN len)
3061 SvPV_force
3063 Like "SvPV" but will force the SV into containing just a string
3064 ("SvPOK_only"). You want force if you are going to update the
3065 "SvPVX" directly.
3066 char* SvPV_force(SV* sv, STRLEN len)
3068 SvPV_force_nomg
3070 Like "SvPV" but will force the SV into containing just a string
3071 ("SvPOK_only"). You want force if you are going to update the
3072 "SvPVX" directly. Doesn't process magic.
3073 char* SvPV_force_nomg(SV* sv, STRLEN len)
3075 SvPV_nolen
3077 Returns a pointer to the string in the SV, or a stringified
3078 form of the SV if the SV does not contain a string. The SV may
3079 cache the stringified form becoming "SvPOK". Handles 'get'
3080 magic.
3081 char* SvPV_nolen(SV* sv)
3083 SvPV_nomg
3085 Like "SvPV" but doesn't process magic.
3086 char* SvPV_nomg(SV* sv, STRLEN len)
3088 SvPV_set
3090 Set the value of the PV pointer in sv to val. See "SvIV_set".
3091 void SvPV_set(SV* sv, char* val)
3093 SvREFCNT
3095 Returns the value of the object's reference count.
3096 U32 SvREFCNT(SV* sv)
3098 SvREFCNT_dec
3100 Decrements the reference count of the given SV.
3101 void SvREFCNT_dec(SV* sv)
3103 SvREFCNT_inc
3105 Increments the reference count of the given SV.
3106 All of the following SvREFCNT_inc* macros are optimized
3108 versions of SvREFCNT_inc, and can be replaced with
3109 SvREFCNT_inc.
3110 SV* SvREFCNT_inc(SV* sv)
3112 SvREFCNT_inc_NN
3114 Same as SvREFCNT_inc, but can only be used if you know sv is
3115 not NULL. Since we don't have to check the NULLness, it's
3116 faster and smaller.
3117 SV* SvREFCNT_inc_NN(SV* sv)
3119 SvREFCNT_inc_simple
3121 Same as SvREFCNT_inc, but can only be used with expressions
3122 without side effects. Since we don't have to store a temporary
3123 value, it's faster.
3124 SV* SvREFCNT_inc_simple(SV* sv)
3126 SvREFCNT_inc_simple_NN
3128 Same as SvREFCNT_inc_simple, but can only be used if you know
3129 sv is not NULL. Since we don't have to check the NULLness,
3130 it's faster and smaller.
3131 SV* SvREFCNT_inc_simple_NN(SV* sv)
3133 SvREFCNT_inc_simple_void
3135 Same as SvREFCNT_inc_simple, but can only be used if you don't
3136 need the return value. The macro doesn't need to return a
3137 meaningful value.
3138 void SvREFCNT_inc_simple_void(SV* sv)
3140 SvREFCNT_inc_simple_void_NN
3142 Same as SvREFCNT_inc, but can only be used if you don't need
3143 the return value, and you know that sv is not NULL. The macro
3144 doesn't need to return a meaningful value, or check for
3145 NULLness, so it's smaller and faster.
3146 void SvREFCNT_inc_simple_void_NN(SV* sv)
3148 SvREFCNT_inc_void
3150 Same as SvREFCNT_inc, but can only be used if you don't need
3151 the return value. The macro doesn't need to return a
3152 meaningful value.
3153 void SvREFCNT_inc_void(SV* sv)
3155 SvREFCNT_inc_void_NN
3157 Same as SvREFCNT_inc, but can only be used if you don't need
3158 the return value, and you know that sv is not NULL. The macro
3159 doesn't need to return a meaningful value, or check for
3160 NULLness, so it's smaller and faster.
3161 void SvREFCNT_inc_void_NN(SV* sv)
3163 SvROK Tests if the SV is an RV.
3165 U32 SvROK(SV* sv)
3167 SvROK_off
3169 Unsets the RV status of an SV.
3170 void SvROK_off(SV* sv)
3172 SvROK_on
3174 Tells an SV that it is an RV.
3175 void SvROK_on(SV* sv)
3177 SvRV Dereferences an RV to return the SV.
3179 SV* SvRV(SV* sv)
3181 SvRV_set
3183 Set the value of the RV pointer in sv to val. See "SvIV_set".
3184 void SvRV_set(SV* sv, SV* val)
3186 SvSTASH Returns the stash of the SV.
3188 HV* SvSTASH(SV* sv)
3190 SvSTASH_set
3192 Set the value of the STASH pointer in sv to val. See
3193 "SvIV_set".
3194 void SvSTASH_set(SV* sv, HV* val)
3196 SvTAINT Taints an SV if tainting is enabled.
3198 void SvTAINT(SV* sv)
3200 SvTAINTED
3202 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE
3203 if not.
3204 bool SvTAINTED(SV* sv)
3206 SvTAINTED_off
3208 Untaints an SV. Be very careful with this routine, as it short-
3209 circuits some of Perl's fundamental security features. XS
3210 module authors should not use this function unless they fully
3211 understand all the implications of unconditionally untainting
3212 the value. Untainting should be done in the standard perl
3213 fashion, via a carefully crafted regexp, rather than directly
3214 untainting variables.
3215 void SvTAINTED_off(SV* sv)
3217 SvTAINTED_on
3219 Marks an SV as tainted if tainting is enabled.
3220 void SvTAINTED_on(SV* sv)
3222 SvTRUE Returns a boolean indicating whether Perl would evaluate the SV
3224 as true or false. See SvOK() for a defined/undefined test.
3225 Does not handle 'get' magic.
3226 bool SvTRUE(SV* sv)
3228 SvTYPE Returns the type of the SV. See "svtype".
3230 svtype SvTYPE(SV* sv)
3232 SvUOK Returns a boolean indicating whether the SV contains an
3234 unsigned integer.
3235 bool SvUOK(SV* sv)
3237 SvUPGRADE
3239 Used to upgrade an SV to a more complex form. Uses
3240 "sv_upgrade" to perform the upgrade if necessary. See
3241 "svtype".
3242 void SvUPGRADE(SV* sv, svtype type)
3244 SvUTF8 Returns a U32 value indicating whether the SV contains UTF-8
3246 encoded data. Call this after SvPV() in case any call to
3247 string overloading updates the internal flag.
3248 U32 SvUTF8(SV* sv)
3250 SvUTF8_off
3252 Unsets the UTF-8 status of an SV.
3253 void SvUTF8_off(SV *sv)
3255 SvUTF8_on
3257 Turn on the UTF-8 status of an SV (the data is not changed,
3258 just the flag). Do not use frivolously.
3259 void SvUTF8_on(SV *sv)
3261 SvUV Coerces the given SV to an unsigned integer and returns it.
3263 See "SvUVx" for a version which guarantees to evaluate sv only
3264 once.
3265 UV SvUV(SV* sv)
3267 SvUVX Returns the raw value in the SV's UV slot, without checks or
3269 conversions. Only use when you are sure SvIOK is true. See
3270 also "SvUV()".
3271 UV SvUVX(SV* sv)
3273 SvUVx Coerces the given SV to an unsigned integer and returns it.
3275 Guarantees to "sv" only once. Only use this if "sv" is an
3276 expression with side effects, otherwise use the more efficient
3277 "SvUV".
3278 UV SvUVx(SV* sv)
3280 SvUV_nomg
3282 Like "SvUV" but doesn't process magic.
3283 UV SvUV_nomg(SV* sv)
3285 SvUV_set
3287 Set the value of the UV pointer in sv to val. See "SvIV_set".
3288 void SvUV_set(SV* sv, UV val)
3290 SvVOK Returns a boolean indicating whether the SV contains a
3292 v-string.
3293 bool SvVOK(SV* sv)
3295 sv_catpvn_nomg
3297 Like "sv_catpvn" but doesn't process magic.
3298 void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
3300 sv_catsv_nomg
3302 Like "sv_catsv" but doesn't process magic.
3303 void sv_catsv_nomg(SV* dsv, SV* ssv)
3305 sv_derived_from
3307 Returns a boolean indicating whether the SV is derived from the
3308 specified class at the C level. To check derivation at the
3309 Perl level, call "isa()" as a normal Perl method.
3310 bool sv_derived_from(SV* sv, const char *const name)
3312 sv_does Returns a boolean indicating whether the SV performs a
3314 specific, named role. The SV can be a Perl object or the name
3315 of a Perl class.
3316 bool sv_does(SV* sv, const char *const name)
3318 sv_report_used
3320 Dump the contents of all SVs not yet freed. (Debugging aid).
3321 void sv_report_used()
3323 sv_setsv_nomg
3325 Like "sv_setsv" but doesn't process magic.
3326 void sv_setsv_nomg(SV* dsv, SV* ssv)
3328 sv_utf8_upgrade_nomg
3330 Like sv_utf8_upgrade, but doesn't do magic on "sv"
3331 STRLEN sv_utf8_upgrade_nomg(NN SV *sv)
3333
3335 looks_like_number
3336 Test if the content of an SV looks like a number (or is a
3337 number). "Inf" and "Infinity" are treated as numbers (so will
3338 not issue a non-numeric warning), even if your atof() doesn't
3339 grok them.
3340 I32 looks_like_number(SV *const sv)
3342 newRV_noinc
3344 Creates an RV wrapper for an SV. The reference count for the
3345 original SV is not incremented.
3346 SV* newRV_noinc(SV *const sv)
3348 newSV Creates a new SV. A non-zero "len" parameter indicates the
3350 number of bytes of preallocated string space the SV should
3351 have. An extra byte for a trailing NUL is also reserved.
3352 (SvPOK is not set for the SV even if string space is
3353 allocated.) The reference count for the new SV is set to 1.
3354 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the
3356 first parameter, x, a debug aid which allowed callers to
3357 identify themselves. This aid has been superseded by a new
3358 build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhack).
3359 The older API is still there for use in XS modules supporting
3360 older perls.
3361 SV* newSV(const STRLEN len)
3363 newSVhek
3365 Creates a new SV from the hash key structure. It will generate
3366 scalars that point to the shared string table where possible.
3367 Returns a new (undefined) SV if the hek is NULL.
3368 SV* newSVhek(const HEK *const hek)
3370 newSViv Creates a new SV and copies an integer into it. The reference
3372 count for the SV is set to 1.
3373 SV* newSViv(const IV i)
3375 newSVnv Creates a new SV and copies a floating point value into it.
3377 The reference count for the SV is set to 1.
3378 SV* newSVnv(const NV n)
3380 newSVpv Creates a new SV and copies a string into it. The reference
3382 count for the SV is set to 1. If "len" is zero, Perl will
3383 compute the length using strlen(). For efficiency, consider
3384 using "newSVpvn" instead.
3385 SV* newSVpv(const char *const s, const STRLEN len)
3387 newSVpvf
3389 Creates a new SV and initializes it with the string formatted
3390 like "sprintf".
3391 SV* newSVpvf(const char *const pat, ...)
3393 newSVpvn
3395 Creates a new SV and copies a string into it. The reference
3396 count for the SV is set to 1. Note that if "len" is zero, Perl
3397 will create a zero length string. You are responsible for
3398 ensuring that the source string is at least "len" bytes long.
3399 If the "s" argument is NULL the new SV will be undefined.
3400 SV* newSVpvn(const char *const s, const STRLEN len)
3402 newSVpvn_flags
3404 Creates a new SV and copies a string into it. The reference
3405 count for the SV is set to 1. Note that if "len" is zero, Perl
3406 will create a zero length string. You are responsible for
3407 ensuring that the source string is at least "len" bytes long.
3408 If the "s" argument is NULL the new SV will be undefined.
3409 Currently the only flag bits accepted are "SVf_UTF8" and
3410 "SVs_TEMP". If "SVs_TEMP" is set, then "sv2mortal()" is called
3411 on the result before returning. If "SVf_UTF8" is set, "s" is
3412 considered to be in UTF-8 and the "SVf_UTF8" flag will be set
3413 on the new SV. "newSVpvn_utf8()" is a convenience wrapper for
3414 this function, defined as
3415 #define newSVpvn_utf8(s, len, u) \
3417 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
3418 SV* newSVpvn_flags(const char *const s, const STRLEN len, const U32 flags)
3420 newSVpvn_share
3422 Creates a new SV with its SvPVX_const pointing to a shared
3423 string in the string table. If the string does not already
3424 exist in the table, it is created first. Turns on READONLY and
3425 FAKE. If the "hash" parameter is non-zero, that value is used;
3426 otherwise the hash is computed. The string's hash can be later
3427 be retrieved from the SV with the "SvSHARED_HASH()" macro. The
3428 idea here is that as the string table is used for shared hash
3429 keys these strings will have SvPVX_const == HeKEY and hash
3430 lookup will avoid string compare.
3431 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
3433 newSVpvs
3435 Like "newSVpvn", but takes a literal string instead of a
3436 string/length pair.
3437 SV* newSVpvs(const char* s)
3439 newSVpvs_flags
3441 Like "newSVpvn_flags", but takes a literal string instead of a
3442 string/length pair.
3443 SV* newSVpvs_flags(const char* s, U32 flags)
3445 newSVpvs_share
3447 Like "newSVpvn_share", but takes a literal string instead of a
3448 string/length pair and omits the hash parameter.
3449 SV* newSVpvs_share(const char* s)
3451 newSVrv Creates a new SV for the RV, "rv", to point to. If "rv" is not
3453 an RV then it will be upgraded to one. If "classname" is non-
3454 null then the new SV will be blessed in the specified package.
3455 The new SV is returned and its reference count is 1.
3456 SV* newSVrv(SV *const rv, const char *const classname)
3458 newSVsv Creates a new SV which is an exact duplicate of the original
3460 SV. (Uses "sv_setsv").
3461 SV* newSVsv(SV *const old)
3463 newSVuv Creates a new SV and copies an unsigned integer into it. The
3465 reference count for the SV is set to 1.
3466 SV* newSVuv(const UV u)
3468 newSV_type
3470 Creates a new SV, of the type specified. The reference count
3471 for the new SV is set to 1.
3472 SV* newSV_type(const svtype type)
3474 sv_2bool
3476 This function is only called on magical items, and is only used
3477 by sv_true() or its macro equivalent.
3478 bool sv_2bool(SV *const sv)
3480 sv_2cv Using various gambits, try to get a CV from an SV; in addition,
3482 try if possible to set *st and *gvp to the stash and GV
3483 associated with it. The flags in "lref" are passed to
3484 gv_fetchsv.
3485 CV* sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)
3487 sv_2io Using various gambits, try to get an IO from an SV: the IO slot
3489 if its a GV; or the recursive result if we're an RV; or the IO
3490 slot of the symbol named after the PV if we're a string.
3491 IO* sv_2io(SV *const sv)
3493 sv_2iv_flags
3495 Return the integer value of an SV, doing any necessary string
3496 conversion. If flags includes SV_GMAGIC, does an mg_get()
3497 first. Normally used via the "SvIV(sv)" and "SvIVx(sv)"
3498 macros.
3499 IV sv_2iv_flags(SV *const sv, const I32 flags)
3501 sv_2mortal
3503 Marks an existing SV as mortal. The SV will be destroyed
3504 "soon", either by an explicit call to FREETMPS, or by an
3505 implicit call at places such as statement boundaries. SvTEMP()
3506 is turned on which means that the SV's string buffer can be
3507 "stolen" if this SV is copied. See also "sv_newmortal" and
3508 "sv_mortalcopy".
3509 SV* sv_2mortal(SV *const sv)
3511 sv_2nv Return the num value of an SV, doing any necessary string or
3513 integer conversion, magic etc. Normally used via the "SvNV(sv)"
3514 and "SvNVx(sv)" macros.
3515 NV sv_2nv(SV *const sv)
3517 sv_2pvbyte
3519 Return a pointer to the byte-encoded representation of the SV,
3520 and set *lp to its length. May cause the SV to be downgraded
3521 from UTF-8 as a side-effect.
3522 Usually accessed via the "SvPVbyte" macro.
3524 char* sv_2pvbyte(SV *const sv, STRLEN *const lp)
3526 sv_2pvutf8
3528 Return a pointer to the UTF-8-encoded representation of the SV,
3529 and set *lp to its length. May cause the SV to be upgraded to
3530 UTF-8 as a side-effect.
3531 Usually accessed via the "SvPVutf8" macro.
3533 char* sv_2pvutf8(SV *const sv, STRLEN *const lp)
3535 sv_2pv_flags
3537 Returns a pointer to the string value of an SV, and sets *lp to
3538 its length. If flags includes SV_GMAGIC, does an mg_get()
3539 first. Coerces sv to a string if necessary. Normally invoked
3540 via the "SvPV_flags" macro. "sv_2pv()" and "sv_2pv_nomg"
3541 usually end up here too.
3542 char* sv_2pv_flags(SV *const sv, STRLEN *const lp, const I32 flags)
3544 sv_2uv_flags
3546 Return the unsigned integer value of an SV, doing any necessary
3547 string conversion. If flags includes SV_GMAGIC, does an
3548 mg_get() first. Normally used via the "SvUV(sv)" and
3549 "SvUVx(sv)" macros.
3550 UV sv_2uv_flags(SV *const sv, const I32 flags)
3552 sv_backoff
3554 Remove any string offset. You should normally use the
3555 "SvOOK_off" macro wrapper instead.
3556 int sv_backoff(SV *const sv)
3558 sv_bless
3560 Blesses an SV into a specified package. The SV must be an RV.
3561 The package must be designated by its stash (see
3562 "gv_stashpv()"). The reference count of the SV is unaffected.
3563 SV* sv_bless(SV *const sv, HV *const stash)
3565 sv_catpv
3567 Concatenates the string onto the end of the string which is in
3568 the SV. If the SV has the UTF-8 status set, then the bytes
3569 appended should be valid UTF-8. Handles 'get' magic, but not
3570 'set' magic. See "sv_catpv_mg".
3571 void sv_catpv(SV *const sv, const char* ptr)
3573 sv_catpvf
3575 Processes its arguments like "sprintf" and appends the
3576 formatted output to an SV. If the appended data contains
3577 "wide" characters (including, but not limited to, SVs with a
3578 UTF-8 PV formatted with %s, and characters >255 formatted with
3579 %c), the original SV might get upgraded to UTF-8. Handles
3580 'get' magic, but not 'set' magic. See "sv_catpvf_mg". If the
3581 original SV was UTF-8, the pattern should be valid UTF-8; if
3582 the original SV was bytes, the pattern should be too.
3583 void sv_catpvf(SV *const sv, const char *const pat, ...)
3585 sv_catpvf_mg
3587 Like "sv_catpvf", but also handles 'set' magic.
3588 void sv_catpvf_mg(SV *const sv, const char *const pat, ...)
3590 sv_catpvn
3592 Concatenates the string onto the end of the string which is in
3593 the SV. The "len" indicates number of bytes to copy. If the
3594 SV has the UTF-8 status set, then the bytes appended should be
3595 valid UTF-8. Handles 'get' magic, but not 'set' magic. See
3596 "sv_catpvn_mg".
3597 void sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
3599 sv_catpvn_flags
3601 Concatenates the string onto the end of the string which is in
3602 the SV. The "len" indicates number of bytes to copy. If the
3603 SV has the UTF-8 status set, then the bytes appended should be
3604 valid UTF-8. If "flags" has "SV_GMAGIC" bit set, will "mg_get"
3605 on "dsv" if appropriate, else not. "sv_catpvn" and
3606 "sv_catpvn_nomg" are implemented in terms of this function.
3607 void sv_catpvn_flags(SV *const dstr, const char *sstr, const STRLEN len, const I32 flags)
3609 sv_catpvs
3611 Like "sv_catpvn", but takes a literal string instead of a
3612 string/length pair.
3613 void sv_catpvs(SV* sv, const char* s)
3615 sv_catpv_mg
3617 Like "sv_catpv", but also handles 'set' magic.
3618 void sv_catpv_mg(SV *const sv, const char *const ptr)
3620 sv_catsv
3622 Concatenates the string from SV "ssv" onto the end of the
3623 string in SV "dsv". Modifies "dsv" but not "ssv". Handles
3624 'get' magic, but not 'set' magic. See "sv_catsv_mg".
3625 void sv_catsv(SV *dstr, SV *sstr)
3627 sv_catsv_flags
3629 Concatenates the string from SV "ssv" onto the end of the
3630 string in SV "dsv". Modifies "dsv" but not "ssv". If "flags"
3631 has "SV_GMAGIC" bit set, will "mg_get" on the SVs if
3632 appropriate, else not. "sv_catsv" and "sv_catsv_nomg" are
3633 implemented in terms of this function.
3634 void sv_catsv_flags(SV *const dsv, SV *const ssv, const I32 flags)
3636 sv_chop Efficient removal of characters from the beginning of the
3638 string buffer. SvPOK(sv) must be true and the "ptr" must be a
3639 pointer to somewhere inside the string buffer. The "ptr"
3640 becomes the first character of the adjusted string. Uses the
3641 "OOK hack". Beware: after this function returns, "ptr" and
3642 SvPVX_const(sv) may no longer refer to the same chunk of data.
3643 void sv_chop(SV *const sv, const char *const ptr)
3645 sv_clear
3647 Clear an SV: call any destructors, free up any memory used by
3648 the body, and free the body itself. The SV's head is not freed,
3649 although its type is set to all 1's so that it won't
3650 inadvertently be assumed to be live during global destruction
3651 etc. This function should only be called when REFCNT is zero.
3652 Most of the time you'll want to call "sv_free()" (or its macro
3653 wrapper "SvREFCNT_dec") instead.
3654 void sv_clear(SV *const sv)
3656 sv_cmp Compares the strings in two SVs. Returns -1, 0, or 1
3658 indicating whether the string in "sv1" is less than, equal to,
3659 or greater than the string in "sv2". Is UTF-8 and 'use bytes'
3660 aware, handles get magic, and will coerce its args to strings
3661 if necessary. See also "sv_cmp_locale".
3662 I32 sv_cmp(SV *const sv1, SV *const sv2)
3664 sv_cmp_locale
3666 Compares the strings in two SVs in a locale-aware manner. Is
3667 UTF-8 and 'use bytes' aware, handles get magic, and will coerce
3668 its args to strings if necessary. See also "sv_cmp".
3669 I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
3671 sv_collxfrm
3673 Add Collate Transform magic to an SV if it doesn't already have
3674 it.
3675 Any scalar variable may carry PERL_MAGIC_collxfrm magic that
3677 contains the scalar data of the variable, but transformed to
3678 such a format that a normal memory comparison can be used to
3679 compare the data according to the locale settings.
3680 char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
3682 sv_copypv
3684 Copies a stringified representation of the source SV into the
3685 destination SV. Automatically performs any necessary mg_get
3686 and coercion of numeric values into strings. Guaranteed to
3687 preserve UTF8 flag even from overloaded objects. Similar in
3688 nature to sv_2pv[_flags] but operates directly on an SV instead
3689 of just the string. Mostly uses sv_2pv_flags to do its work,
3690 except when that would lose the UTF-8'ness of the PV.
3691 void sv_copypv(SV *const dsv, SV *const ssv)
3693 sv_dec Auto-decrement of the value in the SV, doing string to numeric
3695 conversion if necessary. Handles 'get' magic.
3696 void sv_dec(SV *const sv)
3698 sv_eq Returns a boolean indicating whether the strings in the two SVs
3700 are identical. Is UTF-8 and 'use bytes' aware, handles get
3701 magic, and will coerce its args to strings if necessary.
3702 I32 sv_eq(SV* sv1, SV* sv2)
3704 sv_force_normal_flags
3706 Undo various types of fakery on an SV: if the PV is a shared
3707 string, make a private copy; if we're a ref, stop refing; if
3708 we're a glob, downgrade to an xpvmg; if we're a copy-on-write
3709 scalar, this is the on-write time when we do the copy, and is
3710 also used locally. If "SV_COW_DROP_PV" is set then a copy-on-
3711 write scalar drops its PV buffer (if any) and becomes SvPOK_off
3712 rather than making a copy. (Used where this scalar is about to
3713 be set to some other value.) In addition, the "flags" parameter
3714 gets passed to "sv_unref_flags()" when unrefing.
3715 "sv_force_normal" calls this function with flags set to 0.
3716 void sv_force_normal_flags(SV *const sv, const U32 flags)
3718 sv_free Decrement an SV's reference count, and if it drops to zero,
3720 call "sv_clear" to invoke destructors and free up any memory
3721 used by the body; finally, deallocate the SV's head itself.
3722 Normally called via a wrapper macro "SvREFCNT_dec".
3723 void sv_free(SV *const sv)
3725 sv_gets Get a line from the filehandle and store it into the SV,
3727 optionally appending to the currently-stored string.
3728 char* sv_gets(SV *const sv, PerlIO *const fp, I32 append)
3730 sv_grow Expands the character buffer in the SV. If necessary, uses
3732 "sv_unref" and upgrades the SV to "SVt_PV". Returns a pointer
3733 to the character buffer. Use the "SvGROW" wrapper instead.
3734 char* sv_grow(SV *const sv, STRLEN newlen)
3736 sv_inc Auto-increment of the value in the SV, doing string to numeric
3738 conversion if necessary. Handles 'get' magic.
3739 void sv_inc(SV *const sv)
3741 sv_insert
3743 Inserts a string at the specified offset/length within the SV.
3744 Similar to the Perl substr() function. Handles get magic.
3745 void sv_insert(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen)
3747 sv_insert_flags
3749 Same as "sv_insert", but the extra "flags" are passed the
3750 "SvPV_force_flags" that applies to "bigstr".
3751 void sv_insert_flags(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen, const U32 flags)
3753 sv_isa Returns a boolean indicating whether the SV is blessed into the
3755 specified class. This does not check for subtypes; use
3756 "sv_derived_from" to verify an inheritance relationship.
3757 int sv_isa(SV* sv, const char *const name)
3759 sv_isobject
3761 Returns a boolean indicating whether the SV is an RV pointing
3762 to a blessed object. If the SV is not an RV, or if the object
3763 is not blessed, then this will return false.
3764 int sv_isobject(SV* sv)
3766 sv_len Returns the length of the string in the SV. Handles magic and
3768 type coercion. See also "SvCUR", which gives raw access to the
3769 xpv_cur slot.
3770 STRLEN sv_len(SV *const sv)
3772 sv_len_utf8
3774 Returns the number of characters in the string in an SV,
3775 counting wide UTF-8 bytes as a single character. Handles magic
3776 and type coercion.
3777 STRLEN sv_len_utf8(SV *const sv)
3779 sv_magic
3781 Adds magic to an SV. First upgrades "sv" to type "SVt_PVMG" if
3782 necessary, then adds a new magic item of type "how" to the head
3783 of the magic list.
3784 See "sv_magicext" (which "sv_magic" now calls) for a
3786 description of the handling of the "name" and "namlen"
3787 arguments.
3788 You need to use "sv_magicext" to add magic to SvREADONLY SVs
3790 and also to add more than one instance of the same 'how'.
3791 void sv_magic(SV *const sv, SV *const obj, const int how, const char *const name, const I32 namlen)
3793 sv_magicext
3795 Adds magic to an SV, upgrading it if necessary. Applies the
3796 supplied vtable and returns a pointer to the magic added.
3797 Note that "sv_magicext" will allow things that "sv_magic" will
3799 not. In particular, you can add magic to SvREADONLY SVs, and
3800 add more than one instance of the same 'how'.
3801 If "namlen" is greater than zero then a "savepvn" copy of
3803 "name" is stored, if "namlen" is zero then "name" is stored as-
3804 is and - as another special case - if "(name && namlen ==
3805 HEf_SVKEY)" then "name" is assumed to contain an "SV*" and is
3806 stored as-is with its REFCNT incremented.
3807 (This is now used as a subroutine by "sv_magic".)
3809 MAGIC * sv_magicext(SV *const sv, SV *const obj, const int how, const MGVTBL *const vtbl, const char *const name, const I32 namlen)
3811 sv_mortalcopy
3813 Creates a new SV which is a copy of the original SV (using
3814 "sv_setsv"). The new SV is marked as mortal. It will be
3815 destroyed "soon", either by an explicit call to FREETMPS, or by
3816 an implicit call at places such as statement boundaries. See
3817 also "sv_newmortal" and "sv_2mortal".
3818 SV* sv_mortalcopy(SV *const oldsv)
3820 sv_newmortal
3822 Creates a new null SV which is mortal. The reference count of
3823 the SV is set to 1. It will be destroyed "soon", either by an
3824 explicit call to FREETMPS, or by an implicit call at places
3825 such as statement boundaries. See also "sv_mortalcopy" and
3826 "sv_2mortal".
3827 SV* sv_newmortal()
3829 sv_newref
3831 Increment an SV's reference count. Use the "SvREFCNT_inc()"
3832 wrapper instead.
3833 SV* sv_newref(SV *const sv)
3835 sv_pos_b2u
3837 Converts the value pointed to by offsetp from a count of bytes
3838 from the start of the string, to a count of the equivalent
3839 number of UTF-8 chars. Handles magic and type coercion.
3840 void sv_pos_b2u(SV *const sv, I32 *const offsetp)
3842 sv_pos_u2b
3844 Converts the value pointed to by offsetp from a count of UTF-8
3845 chars from the start of the string, to a count of the
3846 equivalent number of bytes; if lenp is non-zero, it does the
3847 same to lenp, but this time starting from the offset, rather
3848 than from the start of the string. Handles magic and type
3849 coercion.
3850 Use "sv_pos_u2b_flags" in preference, which correctly handles
3852 strings longer than 2Gb.
3853 void sv_pos_u2b(SV *const sv, I32 *const offsetp, I32 *const lenp)
3855 sv_pos_u2b_flags
3857 Converts the value pointed to by offsetp from a count of UTF-8
3858 chars from the start of the string, to a count of the
3859 equivalent number of bytes; if lenp is non-zero, it does the
3860 same to lenp, but this time starting from the offset, rather
3861 than from the start of the string. Handles type coercion.
3862 flags is passed to "SvPV_flags", and usually should be
3863 "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
3864 STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset, STRLEN *const lenp, U32 flags)
3866 sv_pvbyten_force
3868 The backend for the "SvPVbytex_force" macro. Always use the
3869 macro instead.
3870 char* sv_pvbyten_force(SV *const sv, STRLEN *const lp)
3872 sv_pvn_force
3874 Get a sensible string out of the SV somehow. A private
3875 implementation of the "SvPV_force" macro for compilers which
3876 can't cope with complex macro expressions. Always use the macro
3877 instead.
3878 char* sv_pvn_force(SV* sv, STRLEN* lp)
3880 sv_pvn_force_flags
3882 Get a sensible string out of the SV somehow. If "flags" has
3883 "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate, else
3884 not. "sv_pvn_force" and "sv_pvn_force_nomg" are implemented in
3885 terms of this function. You normally want to use the various
3886 wrapper macros instead: see "SvPV_force" and "SvPV_force_nomg"
3887 char* sv_pvn_force_flags(SV *const sv, STRLEN *const lp, const I32 flags)
3889 sv_pvutf8n_force
3891 The backend for the "SvPVutf8x_force" macro. Always use the
3892 macro instead.
3893 char* sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
3895 sv_reftype
3897 Returns a string describing what the SV is a reference to.
3898 const char* sv_reftype(const SV *const sv, const int ob)
3900 sv_replace
3902 Make the first argument a copy of the second, then delete the
3903 original. The target SV physically takes over ownership of the
3904 body of the source SV and inherits its flags; however, the
3905 target keeps any magic it owns, and any magic in the source is
3906 discarded. Note that this is a rather specialist SV copying
3907 operation; most of the time you'll want to use "sv_setsv" or
3908 one of its many macro front-ends.
3909 void sv_replace(SV *const sv, SV *const nsv)
3911 sv_reset
3913 Underlying implementation for the "reset" Perl function. Note
3914 that the perl-level function is vaguely deprecated.
3915 void sv_reset(const char* s, HV *const stash)
3917 sv_rvweaken
3919 Weaken a reference: set the "SvWEAKREF" flag on this RV; give
3920 the referred-to SV "PERL_MAGIC_backref" magic if it hasn't
3921 already; and push a back-reference to this RV onto the array of
3922 backreferences associated with that magic. If the RV is
3923 magical, set magic will be called after the RV is cleared.
3924 SV* sv_rvweaken(SV *const sv)
3926 sv_setiv
3928 Copies an integer into the given SV, upgrading first if
3929 necessary. Does not handle 'set' magic. See also
3930 "sv_setiv_mg".
3931 void sv_setiv(SV *const sv, const IV num)
3933 sv_setiv_mg
3935 Like "sv_setiv", but also handles 'set' magic.
3936 void sv_setiv_mg(SV *const sv, const IV i)
3938 sv_setnv
3940 Copies a double into the given SV, upgrading first if
3941 necessary. Does not handle 'set' magic. See also
3942 "sv_setnv_mg".
3943 void sv_setnv(SV *const sv, const NV num)
3945 sv_setnv_mg
3947 Like "sv_setnv", but also handles 'set' magic.
3948 void sv_setnv_mg(SV *const sv, const NV num)
3950 sv_setpv
3952 Copies a string into an SV. The string must be null-
3953 terminated. Does not handle 'set' magic. See "sv_setpv_mg".
3954 void sv_setpv(SV *const sv, const char *const ptr)
3956 sv_setpvf
3958 Works like "sv_catpvf" but copies the text into the SV instead
3959 of appending it. Does not handle 'set' magic. See
3960 "sv_setpvf_mg".
3961 void sv_setpvf(SV *const sv, const char *const pat, ...)
3963 sv_setpvf_mg
3965 Like "sv_setpvf", but also handles 'set' magic.
3966 void sv_setpvf_mg(SV *const sv, const char *const pat, ...)
3968 sv_setpviv
3970 Copies an integer into the given SV, also updating its string
3971 value. Does not handle 'set' magic. See "sv_setpviv_mg".
3972 void sv_setpviv(SV *const sv, const IV num)
3974 sv_setpviv_mg
3976 Like "sv_setpviv", but also handles 'set' magic.
3977 void sv_setpviv_mg(SV *const sv, const IV iv)
3979 sv_setpvn
3981 Copies a string into an SV. The "len" parameter indicates the
3982 number of bytes to be copied. If the "ptr" argument is NULL
3983 the SV will become undefined. Does not handle 'set' magic.
3984 See "sv_setpvn_mg".
3985 void sv_setpvn(SV *const sv, const char *const ptr, const STRLEN len)
3987 sv_setpvn_mg
3989 Like "sv_setpvn", but also handles 'set' magic.
3990 void sv_setpvn_mg(SV *const sv, const char *const ptr, const STRLEN len)
3992 sv_setpvs
3994 Like "sv_setpvn", but takes a literal string instead of a
3995 string/length pair.
3996 void sv_setpvs(SV* sv, const char* s)
3998 sv_setpv_mg
4000 Like "sv_setpv", but also handles 'set' magic.
4001 void sv_setpv_mg(SV *const sv, const char *const ptr)
4003 sv_setref_iv
4005 Copies an integer into a new SV, optionally blessing the SV.
4006 The "rv" argument will be upgraded to an RV. That RV will be
4007 modified to point to the new SV. The "classname" argument
4008 indicates the package for the blessing. Set "classname" to
4009 "NULL" to avoid the blessing. The new SV will have a reference
4010 count of 1, and the RV will be returned.
4011 SV* sv_setref_iv(SV *const rv, const char *const classname, const IV iv)
4013 sv_setref_nv
4015 Copies a double into a new SV, optionally blessing the SV. The
4016 "rv" argument will be upgraded to an RV. That RV will be
4017 modified to point to the new SV. The "classname" argument
4018 indicates the package for the blessing. Set "classname" to
4019 "NULL" to avoid the blessing. The new SV will have a reference
4020 count of 1, and the RV will be returned.
4021 SV* sv_setref_nv(SV *const rv, const char *const classname, const NV nv)
4023 sv_setref_pv
4025 Copies a pointer into a new SV, optionally blessing the SV.
4026 The "rv" argument will be upgraded to an RV. That RV will be
4027 modified to point to the new SV. If the "pv" argument is NULL
4028 then "PL_sv_undef" will be placed into the SV. The "classname"
4029 argument indicates the package for the blessing. Set
4030 "classname" to "NULL" to avoid the blessing. The new SV will
4031 have a reference count of 1, and the RV will be returned.
4032 Do not use with other Perl types such as HV, AV, SV, CV,
4034 because those objects will become corrupted by the pointer copy
4035 process.
4036 Note that "sv_setref_pvn" copies the string while this copies
4038 the pointer.
4039 SV* sv_setref_pv(SV *const rv, const char *const classname, void *const pv)
4041 sv_setref_pvn
4043 Copies a string into a new SV, optionally blessing the SV. The
4044 length of the string must be specified with "n". The "rv"
4045 argument will be upgraded to an RV. That RV will be modified
4046 to point to the new SV. The "classname" argument indicates the
4047 package for the blessing. Set "classname" to "NULL" to avoid
4048 the blessing. The new SV will have a reference count of 1, and
4049 the RV will be returned.
4050 Note that "sv_setref_pv" copies the pointer while this copies
4052 the string.
4053 SV* sv_setref_pvn(SV *const rv, const char *const classname, const char *const pv, const STRLEN n)
4055 sv_setref_uv
4057 Copies an unsigned integer into a new SV, optionally blessing
4058 the SV. The "rv" argument will be upgraded to an RV. That RV
4059 will be modified to point to the new SV. The "classname"
4060 argument indicates the package for the blessing. Set
4061 "classname" to "NULL" to avoid the blessing. The new SV will
4062 have a reference count of 1, and the RV will be returned.
4063 SV* sv_setref_uv(SV *const rv, const char *const classname, const UV uv)
4065 sv_setsv
4067 Copies the contents of the source SV "ssv" into the destination
4068 SV "dsv". The source SV may be destroyed if it is mortal, so
4069 don't use this function if the source SV needs to be reused.
4070 Does not handle 'set' magic. Loosely speaking, it performs a
4071 copy-by-value, obliterating any previous content of the
4072 destination.
4073 You probably want to use one of the assortment of wrappers,
4075 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
4076 "SvSetMagicSV_nosteal".
4077 void sv_setsv(SV *dstr, SV *sstr)
4079 sv_setsv_flags
4081 Copies the contents of the source SV "ssv" into the destination
4082 SV "dsv". The source SV may be destroyed if it is mortal, so
4083 don't use this function if the source SV needs to be reused.
4084 Does not handle 'set' magic. Loosely speaking, it performs a
4085 copy-by-value, obliterating any previous content of the
4086 destination. If the "flags" parameter has the "SV_GMAGIC" bit
4087 set, will "mg_get" on "ssv" if appropriate, else not. If the
4088 "flags" parameter has the "NOSTEAL" bit set then the buffers of
4089 temps will not be stolen. <sv_setsv> and "sv_setsv_nomg" are
4090 implemented in terms of this function.
4091 You probably want to use one of the assortment of wrappers,
4093 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
4094 "SvSetMagicSV_nosteal".
4095 This is the primary function for copying scalars, and most
4097 other copy-ish functions and macros use this underneath.
4098 void sv_setsv_flags(SV *dstr, SV *sstr, const I32 flags)
4100 sv_setsv_mg
4102 Like "sv_setsv", but also handles 'set' magic.
4103 void sv_setsv_mg(SV *const dstr, SV *const sstr)
4105 sv_setuv
4107 Copies an unsigned integer into the given SV, upgrading first
4108 if necessary. Does not handle 'set' magic. See also
4109 "sv_setuv_mg".
4110 void sv_setuv(SV *const sv, const UV num)
4112 sv_setuv_mg
4114 Like "sv_setuv", but also handles 'set' magic.
4115 void sv_setuv_mg(SV *const sv, const UV u)
4117 sv_tainted
4119 Test an SV for taintedness. Use "SvTAINTED" instead.
4120 bool sv_tainted(SV *const sv)
4121 sv_true Returns true if the SV has a true value by Perl's rules. Use
4123 the "SvTRUE" macro instead, which may call "sv_true()" or may
4124 instead use an in-line version.
4125 I32 sv_true(SV *const sv)
4127 sv_unmagic
4129 Removes all magic of type "type" from an SV.
4130 int sv_unmagic(SV *const sv, const int type)
4132 sv_unref_flags
4134 Unsets the RV status of the SV, and decrements the reference
4135 count of whatever was being referenced by the RV. This can
4136 almost be thought of as a reversal of "newSVrv". The "cflags"
4137 argument can contain "SV_IMMEDIATE_UNREF" to force the
4138 reference count to be decremented (otherwise the decrementing
4139 is conditional on the reference count being different from one
4140 or the reference being a readonly SV). See "SvROK_off".
4141 void sv_unref_flags(SV *const ref, const U32 flags)
4143 sv_untaint
4145 Untaint an SV. Use "SvTAINTED_off" instead.
4146 void sv_untaint(SV *const sv)
4147 sv_upgrade
4149 Upgrade an SV to a more complex form. Generally adds a new
4150 body type to the SV, then copies across as much information as
4151 possible from the old body. You generally want to use the
4152 "SvUPGRADE" macro wrapper. See also "svtype".
4153 void sv_upgrade(SV *const sv, svtype new_type)
4155 sv_usepvn_flags
4157 Tells an SV to use "ptr" to find its string value. Normally
4158 the string is stored inside the SV but sv_usepvn allows the SV
4159 to use an outside string. The "ptr" should point to memory
4160 that was allocated by "malloc". The string length, "len", must
4161 be supplied. By default this function will realloc (i.e. move)
4162 the memory pointed to by "ptr", so that pointer should not be
4163 freed or used by the programmer after giving it to sv_usepvn,
4164 and neither should any pointers from "behind" that pointer
4165 (e.g. ptr + 1) be used.
4166 If "flags" & SV_SMAGIC is true, will call SvSETMAGIC. If
4168 "flags" & SV_HAS_TRAILING_NUL is true, then "ptr[len]" must be
4169 NUL, and the realloc will be skipped. (i.e. the buffer is
4170 actually at least 1 byte longer than "len", and already meets
4171 the requirements for storing in "SvPVX")
4172 void sv_usepvn_flags(SV *const sv, char* ptr, const STRLEN len, const U32 flags)
4174 sv_utf8_decode
4176 If the PV of the SV is an octet sequence in UTF-8 and contains
4177 a multiple-byte character, the "SvUTF8" flag is turned on so
4178 that it looks like a character. If the PV contains only single-
4179 byte characters, the "SvUTF8" flag stays being off. Scans PV
4180 for validity and returns false if the PV is invalid UTF-8.
4181 NOTE: this function is experimental and may change or be
4183 removed without notice.
4184 bool sv_utf8_decode(SV *const sv)
4186 sv_utf8_downgrade
4188 Attempts to convert the PV of an SV from characters to bytes.
4189 If the PV contains a character that cannot fit in a byte, this
4190 conversion will fail; in this case, either returns false or, if
4191 "fail_ok" is not true, croaks.
4192 This is not as a general purpose Unicode to byte encoding
4194 interface: use the Encode extension for that.
4195 NOTE: this function is experimental and may change or be
4197 removed without notice.
4198 bool sv_utf8_downgrade(SV *const sv, const bool fail_ok)
4200 sv_utf8_encode
4202 Converts the PV of an SV to UTF-8, but then turns the "SvUTF8"
4203 flag off so that it looks like octets again.
4204 void sv_utf8_encode(SV *const sv)
4206 sv_utf8_upgrade
4208 Converts the PV of an SV to its UTF-8-encoded form. Forces the
4209 SV to string form if it is not already. Will "mg_get" on "sv"
4210 if appropriate. Always sets the SvUTF8 flag to avoid future
4211 validity checks even if the whole string is the same in UTF-8
4212 as not. Returns the number of bytes in the converted string
4213 This is not as a general purpose byte encoding to Unicode
4215 interface: use the Encode extension for that.
4216 STRLEN sv_utf8_upgrade(SV *sv)
4218 sv_utf8_upgrade_flags
4220 Converts the PV of an SV to its UTF-8-encoded form. Forces the
4221 SV to string form if it is not already. Always sets the SvUTF8
4222 flag to avoid future validity checks even if all the bytes are
4223 invariant in UTF-8. If "flags" has "SV_GMAGIC" bit set, will
4224 "mg_get" on "sv" if appropriate, else not. Returns the number
4225 of bytes in the converted string "sv_utf8_upgrade" and
4226 "sv_utf8_upgrade_nomg" are implemented in terms of this
4227 function.
4228 This is not as a general purpose byte encoding to Unicode
4230 interface: use the Encode extension for that.
4231 STRLEN sv_utf8_upgrade_flags(SV *const sv, const I32 flags)
4233 sv_utf8_upgrade_nomg
4235 Like sv_utf8_upgrade, but doesn't do magic on "sv"
4236 STRLEN sv_utf8_upgrade_nomg(SV *sv)
4238 sv_vcatpvf
4240 Processes its arguments like "vsprintf" and appends the
4241 formatted output to an SV. Does not handle 'set' magic. See
4242 "sv_vcatpvf_mg".
4243 Usually used via its frontend "sv_catpvf".
4245 void sv_vcatpvf(SV *const sv, const char *const pat, va_list *const args)
4247 sv_vcatpvfn
4249 Processes its arguments like "vsprintf" and appends the
4250 formatted output to an SV. Uses an array of SVs if the C style
4251 variable argument list is missing (NULL). When running with
4252 taint checks enabled, indicates via "maybe_tainted" if results
4253 are untrustworthy (often due to the use of locales).
4254 Usually used via one of its frontends "sv_vcatpvf" and
4256 "sv_vcatpvf_mg".
4257 void sv_vcatpvfn(SV *const sv, const char *const pat, const STRLEN patlen, va_list *const args, SV **const svargs, const I32 svmax, bool *const maybe_tainted)
4259 sv_vcatpvf_mg
4261 Like "sv_vcatpvf", but also handles 'set' magic.
4262 Usually used via its frontend "sv_catpvf_mg".
4264 void sv_vcatpvf_mg(SV *const sv, const char *const pat, va_list *const args)
4266 sv_vsetpvf
4268 Works like "sv_vcatpvf" but copies the text into the SV instead
4269 of appending it. Does not handle 'set' magic. See
4270 "sv_vsetpvf_mg".
4271 Usually used via its frontend "sv_setpvf".
4273 void sv_vsetpvf(SV *const sv, const char *const pat, va_list *const args)
4275 sv_vsetpvfn
4277 Works like "sv_vcatpvfn" but copies the text into the SV
4278 instead of appending it.
4279 Usually used via one of its frontends "sv_vsetpvf" and
4281 "sv_vsetpvf_mg".
4282 void sv_vsetpvfn(SV *const sv, const char *const pat, const STRLEN patlen, va_list *const args, SV **const svargs, const I32 svmax, bool *const maybe_tainted)
4284 sv_vsetpvf_mg
4286 Like "sv_vsetpvf", but also handles 'set' magic.
4287 Usually used via its frontend "sv_setpvf_mg".
4289 void sv_vsetpvf_mg(SV *const sv, const char *const pat, va_list *const args)
4291
4293 bytes_from_utf8
4294 Converts a string "s" of length "len" from UTF-8 into native
4295 byte encoding. Unlike "utf8_to_bytes" but like
4296 "bytes_to_utf8", returns a pointer to the newly-created string,
4297 and updates "len" to contain the new length. Returns the
4298 original string if no conversion occurs, "len" is unchanged. Do
4299 nothing if "is_utf8" points to 0. Sets "is_utf8" to 0 if "s" is
4300 converted or consisted entirely of characters that are
4301 invariant in utf8 (i.e., US-ASCII on non-EBCDIC machines).
4302 NOTE: this function is experimental and may change or be
4304 removed without notice.
4305 U8* bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)
4307 bytes_to_utf8
4309 Converts a string "s" of length "len" from the native encoding
4310 into UTF-8. Returns a pointer to the newly-created string, and
4311 sets "len" to reflect the new length.
4312 A NUL character will be written after the end of the string.
4314 If you want to convert to UTF-8 from encodings other than the
4316 native (Latin1 or EBCDIC), see sv_recode_to_utf8().
4317 NOTE: this function is experimental and may change or be
4319 removed without notice.
4320 U8* bytes_to_utf8(const U8 *s, STRLEN *len)
4322 ibcmp_utf8
4324 Return true if the strings s1 and s2 differ case-insensitively,
4325 false if not (if they are equal case-insensitively). If u1 is
4326 true, the string s1 is assumed to be in UTF-8-encoded Unicode.
4327 If u2 is true, the string s2 is assumed to be in UTF-8-encoded
4328 Unicode. If u1 or u2 are false, the respective string is
4329 assumed to be in native 8-bit encoding.
4330 If the pe1 and pe2 are non-NULL, the scanning pointers will be
4332 copied in there (they will point at the beginning of the next
4333 character). If the pointers behind pe1 or pe2 are non-NULL,
4334 they are the end pointers beyond which scanning will not
4335 continue under any circumstances. If the byte lengths l1 and
4336 l2 are non-zero, s1+l1 and s2+l2 will be used as goal end
4337 pointers that will also stop the scan, and which qualify
4338 towards defining a successful match: all the scans that define
4339 an explicit length must reach their goal pointers for a match
4340 to succeed).
4341 For case-insensitiveness, the "casefolding" of Unicode is used
4343 instead of upper/lowercasing both the characters, see
4344 http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
4345 I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1, const char *s2, char **pe2, UV l2, bool u2)
4347 is_ascii_string
4349 Returns true if first "len" bytes of the given string are ASCII
4350 (i.e. none of them even raise the question of UTF-8-ness).
4351 See also is_utf8_string(), is_utf8_string_loclen(), and
4353 is_utf8_string_loc().
4354 bool is_ascii_string(const U8 *s, STRLEN len)
4356 is_utf8_char
4358 Tests if some arbitrary number of bytes begins in a valid UTF-8
4359 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC
4360 machines) character is a valid UTF-8 character. The actual
4361 number of bytes in the UTF-8 character will be returned if it
4362 is valid, otherwise 0.
4363 STRLEN is_utf8_char(const U8 *s)
4365 is_utf8_string
4367 Returns true if first "len" bytes of the given string form a
4368 valid UTF-8 string, false otherwise. Note that 'a valid UTF-8
4369 string' does not mean 'a string that contains code points above
4370 0x7F encoded in UTF-8' because a valid ASCII string is a valid
4371 UTF-8 string.
4372 See also is_ascii_string(), is_utf8_string_loclen(), and
4374 is_utf8_string_loc().
4375 bool is_utf8_string(const U8 *s, STRLEN len)
4377 is_utf8_string_loc
4379 Like is_utf8_string() but stores the location of the failure
4380 (in the case of "utf8ness failure") or the location s+len (in
4381 the case of "utf8ness success") in the "ep".
4382 See also is_utf8_string_loclen() and is_utf8_string().
4384 bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
4386 is_utf8_string_loclen
4388 Like is_utf8_string() but stores the location of the failure
4389 (in the case of "utf8ness failure") or the location s+len (in
4390 the case of "utf8ness success") in the "ep", and the number of
4391 UTF-8 encoded characters in the "el".
4392 See also is_utf8_string_loc() and is_utf8_string().
4394 bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
4396 pv_uni_display
4398 Build to the scalar dsv a displayable version of the string
4399 spv, length len, the displayable version being at most pvlim
4400 bytes long (if longer, the rest is truncated and "..." will be
4401 appended).
4402 The flags argument can have UNI_DISPLAY_ISPRINT set to display
4404 isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
4405 to display the \\[nrfta\\] as the backslashed versions (like
4406 '\n') (UNI_DISPLAY_BACKSLASH is preferred over
4407 UNI_DISPLAY_ISPRINT for \\). UNI_DISPLAY_QQ (and its alias
4408 UNI_DISPLAY_REGEX) have both UNI_DISPLAY_BACKSLASH and
4409 UNI_DISPLAY_ISPRINT turned on.
4410 The pointer to the PV of the dsv is returned.
4412 char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
4414 sv_cat_decode
4416 The encoding is assumed to be an Encode object, the PV of the
4417 ssv is assumed to be octets in that encoding and decoding the
4418 input starts from the position which (PV + *offset) pointed to.
4419 The dsv will be concatenated the decoded UTF-8 string from ssv.
4420 Decoding will terminate when the string tstr appears in
4421 decoding output or the input ends on the PV of the ssv. The
4422 value which the offset points will be modified to the last
4423 input position on the ssv.
4424 Returns TRUE if the terminator was found, else returns FALSE.
4426 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
4428 sv_recode_to_utf8
4430 The encoding is assumed to be an Encode object, on entry the PV
4431 of the sv is assumed to be octets in that encoding, and the sv
4432 will be converted into Unicode (and UTF-8).
4433 If the sv already is UTF-8 (or if it is not POK), or if the
4435 encoding is not a reference, nothing is done to the sv. If the
4436 encoding is not an "Encode::XS" Encoding object, bad things
4437 will happen. (See lib/encoding.pm and Encode).
4438 The PV of the sv is returned.
4440 char* sv_recode_to_utf8(SV* sv, SV *encoding)
4442 sv_uni_display
4444 Build to the scalar dsv a displayable version of the scalar sv,
4445 the displayable version being at most pvlim bytes long (if
4446 longer, the rest is truncated and "..." will be appended).
4447 The flags argument is as in pv_uni_display().
4449 The pointer to the PV of the dsv is returned.
4451 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
4453 to_utf8_case
4455 The "p" contains the pointer to the UTF-8 string encoding the
4456 character that is being converted.
4457 The "ustrp" is a pointer to the character buffer to put the
4459 conversion result to. The "lenp" is a pointer to the length of
4460 the result.
4461 The "swashp" is a pointer to the swash to use.
4463 Both the special and normal mappings are stored
4465 lib/unicore/To/Foo.pl, and loaded by SWASHNEW, using
4466 lib/utf8_heavy.pl. The special (usually, but not always, a
4467 multicharacter mapping), is tried first.
4468 The "special" is a string like "utf8::ToSpecLower", which means
4470 the hash %utf8::ToSpecLower. The access to the hash is through
4471 Perl_to_utf8_case().
4472 The "normal" is a string like "ToLower" which means the swash
4474 %utf8::ToLower.
4475 UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special)
4477 to_utf8_fold
4479 Convert the UTF-8 encoded character at p to its foldcase
4480 version and store that in UTF-8 in ustrp and its length in
4481 bytes in lenp. Note that the ustrp needs to be at least
4482 UTF8_MAXBYTES_CASE+1 bytes since the foldcase version may be
4483 longer than the original character (up to three characters).
4484 The first character of the foldcased version is returned (but
4486 note, as explained above, that there may be more.)
4487 UV to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)
4489 to_utf8_lower
4491 Convert the UTF-8 encoded character at p to its lowercase
4492 version and store that in UTF-8 in ustrp and its length in
4493 bytes in lenp. Note that the ustrp needs to be at least
4494 UTF8_MAXBYTES_CASE+1 bytes since the lowercase version may be
4495 longer than the original character.
4496 The first character of the lowercased version is returned (but
4498 note, as explained above, that there may be more.)
4499 UV to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)
4501 to_utf8_title
4503 Convert the UTF-8 encoded character at p to its titlecase
4504 version and store that in UTF-8 in ustrp and its length in
4505 bytes in lenp. Note that the ustrp needs to be at least
4506 UTF8_MAXBYTES_CASE+1 bytes since the titlecase version may be
4507 longer than the original character.
4508 The first character of the titlecased version is returned (but
4510 note, as explained above, that there may be more.)
4511 UV to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)
4513 to_utf8_upper
4515 Convert the UTF-8 encoded character at p to its uppercase
4516 version and store that in UTF-8 in ustrp and its length in
4517 bytes in lenp. Note that the ustrp needs to be at least
4518 UTF8_MAXBYTES_CASE+1 bytes since the uppercase version may be
4519 longer than the original character.
4520 The first character of the uppercased version is returned (but
4522 note, as explained above, that there may be more.)
4523 UV to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)
4525 utf8n_to_uvchr
4527 flags
4528 Returns the native character value of the first character in
4530 the string "s" which is assumed to be in UTF-8 encoding;
4531 "retlen" will be set to the length, in bytes, of that
4532 character.
4533 Allows length and flags to be passed to low level routine.
4535 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
4537 utf8n_to_uvuni
4539 Bottom level UTF-8 decode routine. Returns the Unicode code
4540 point value of the first character in the string "s" which is
4541 assumed to be in UTF-8 encoding and no longer than "curlen";
4542 "retlen" will be set to the length, in bytes, of that
4543 character.
4544 If "s" does not point to a well-formed UTF-8 character, the
4546 behaviour is dependent on the value of "flags": if it contains
4547 UTF8_CHECK_ONLY, it is assumed that the caller will raise a
4548 warning, and this function will silently just set "retlen" to
4549 "-1" and return zero. If the "flags" does not contain
4550 UTF8_CHECK_ONLY, warnings about malformations will be given,
4551 "retlen" will be set to the expected length of the UTF-8
4552 character in bytes, and zero will be returned.
4553 The "flags" can also contain various flags to allow deviations
4555 from the strict UTF-8 encoding (see utf8.h).
4556 Most code should use utf8_to_uvchr() rather than call this
4558 directly.
4559 UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
4561 utf8_distance
4563 Returns the number of UTF-8 characters between the UTF-8
4564 pointers "a" and "b".
4565 WARNING: use only if you *know* that the pointers point inside
4567 the same UTF-8 buffer.
4568 IV utf8_distance(const U8 *a, const U8 *b)
4570 utf8_hop
4572 Return the UTF-8 pointer "s" displaced by "off" characters,
4573 either forward or backward.
4574 WARNING: do not use the following unless you *know* "off" is
4576 within the UTF-8 data pointed to by "s" *and* that on entry "s"
4577 is aligned on the first byte of character or just after the
4578 last byte of a character.
4579 U8* utf8_hop(const U8 *s, I32 off)
4581 utf8_length
4583 Return the length of the UTF-8 char encoded string "s" in
4584 characters. Stops at "e" (inclusive). If "e < s" or if the
4585 scan would end up past "e", croaks.
4586 STRLEN utf8_length(const U8* s, const U8 *e)
4588 utf8_to_bytes
4590 Converts a string "s" of length "len" from UTF-8 into native
4591 byte encoding. Unlike "bytes_to_utf8", this over-writes the
4592 original string, and updates len to contain the new length.
4593 Returns zero on failure, setting "len" to -1.
4594 If you need a copy of the string, see "bytes_from_utf8".
4596 NOTE: this function is experimental and may change or be
4598 removed without notice.
4599 U8* utf8_to_bytes(U8 *s, STRLEN *len)
4601 utf8_to_uvchr
4603 Returns the native character value of the first character in
4604 the string "s" which is assumed to be in UTF-8 encoding;
4605 "retlen" will be set to the length, in bytes, of that
4606 character.
4607 If "s" does not point to a well-formed UTF-8 character, zero is
4609 returned and retlen is set, if possible, to -1.
4610 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
4612 utf8_to_uvuni
4614 Returns the Unicode code point of the first character in the
4615 string "s" which is assumed to be in UTF-8 encoding; "retlen"
4616 will be set to the length, in bytes, of that character.
4617 This function should only be used when the returned UV is
4619 considered an index into the Unicode semantic tables (e.g.
4620 swashes).
4621 If "s" does not point to a well-formed UTF-8 character, zero is
4623 returned and retlen is set, if possible, to -1.
4624 UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
4626 uvchr_to_utf8
4628 Adds the UTF-8 representation of the Native codepoint "uv" to
4629 the end of the string "d"; "d" should be have at least
4630 "UTF8_MAXBYTES+1" free bytes available. The return value is the
4631 pointer to the byte after the end of the new character. In
4632 other words,
4633 d = uvchr_to_utf8(d, uv);
4635 is the recommended wide native character-aware way of saying
4637 *(d++) = uv;
4639 U8* uvchr_to_utf8(U8 *d, UV uv)
4641 uvuni_to_utf8_flags
4643 Adds the UTF-8 representation of the Unicode codepoint "uv" to
4644 the end of the string "d"; "d" should be have at least
4645 "UTF8_MAXBYTES+1" free bytes available. The return value is the
4646 pointer to the byte after the end of the new character. In
4647 other words,
4648 d = uvuni_to_utf8_flags(d, uv, flags);
4650 or, in most cases,
4652 d = uvuni_to_utf8(d, uv);
4654 (which is equivalent to)
4656 d = uvuni_to_utf8_flags(d, uv, 0);
4658 is the recommended Unicode-aware way of saying
4660 *(d++) = uv;
4662 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
4664
4666 ax Variable which is setup by "xsubpp" to indicate the stack base
4667 offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros.
4668 The "dMARK" macro must be called prior to setup the "MARK"
4669 variable.
4670 I32 ax
4672 CLASS Variable which is setup by "xsubpp" to indicate the class name
4674 for a C++ XS constructor. This is always a "char*". See
4675 "THIS".
4676 char* CLASS
4678 dAX Sets up the "ax" variable. This is usually handled
4680 automatically by "xsubpp" by calling "dXSARGS".
4681 dAX;
4683 dAXMARK Sets up the "ax" variable and stack marker variable "mark".
4685 This is usually handled automatically by "xsubpp" by calling
4686 "dXSARGS".
4687 dAXMARK;
4689 dITEMS Sets up the "items" variable. This is usually handled
4691 automatically by "xsubpp" by calling "dXSARGS".
4692 dITEMS;
4694 dUNDERBAR
4696 Sets up the "padoff_du" variable for an XSUB that wishes to use
4697 "UNDERBAR".
4698 dUNDERBAR;
4700 dXSARGS Sets up stack and mark pointers for an XSUB, calling dSP and
4702 dMARK. Sets up the "ax" and "items" variables by calling "dAX"
4703 and "dITEMS". This is usually handled automatically by
4704 "xsubpp".
4705 dXSARGS;
4707 dXSI32 Sets up the "ix" variable for an XSUB which has aliases. This
4709 is usually handled automatically by "xsubpp".
4710 dXSI32;
4712 items Variable which is setup by "xsubpp" to indicate the number of
4714 items on the stack. See "Variable-length Parameter Lists" in
4715 perlxs.
4716 I32 items
4718 ix Variable which is setup by "xsubpp" to indicate which of an
4720 XSUB's aliases was used to invoke it. See "The ALIAS: Keyword"
4721 in perlxs.
4722 I32 ix
4724 newXSproto
4726 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl
4727 prototypes to the subs.
4728 RETVAL Variable which is setup by "xsubpp" to hold the return value
4730 for an XSUB. This is always the proper type for the XSUB. See
4731 "The RETVAL Variable" in perlxs.
4732 (whatever) RETVAL
4734 ST Used to access elements on the XSUB's stack.
4736 SV* ST(int ix)
4738 THIS Variable which is setup by "xsubpp" to designate the object in
4740 a C++ XSUB. This is always the proper type for the C++ object.
4741 See "CLASS" and "Using XS With C++" in perlxs.
4742 (whatever) THIS
4744 UNDERBAR
4746 The SV* corresponding to the $_ variable. Works even if there
4747 is a lexical $_ in scope.
4748 XS Macro to declare an XSUB and its C parameter list. This is
4750 handled by "xsubpp".
4751 XS_VERSION
4753 The version identifier for an XS module. This is usually
4754 handled automatically by "ExtUtils::MakeMaker". See
4755 "XS_VERSION_BOOTCHECK".
4756 XS_VERSION_BOOTCHECK
4758 Macro to verify that a PM module's $VERSION variable matches
4759 the XS module's "XS_VERSION" variable. This is usually handled
4760 automatically by "xsubpp". See "The VERSIONCHECK: Keyword" in
4761 perlxs.
4762 XS_VERSION_BOOTCHECK;
4764
4766 croak This is the XSUB-writer's interface to Perl's "die" function.
4767 Normally call this function the same way you call the C
4768 "printf" function. Calling "croak" returns control directly to
4769 Perl, sidestepping the normal C order of execution. See "warn".
4770 If you want to throw an exception object, assign the object to
4772 $@ and then pass "NULL" to croak():
4773 errsv = get_sv("@", GV_ADD);
4775 sv_setsv(errsv, exception_object);
4776 croak(NULL);
4777 void croak(const char* pat, ...)
4779 warn This is the XSUB-writer's interface to Perl's "warn" function.
4781 Call this function the same way you call the C "printf"
4782 function. See "croak".
4783 void warn(const char* pat, ...)
4785
4787 These functions are currently undocumented:
4788 GetVars
4790 Gv_AMupdate
4791 PerlIO_clearerr
4792 PerlIO_close
4793 PerlIO_context_layers
4794 PerlIO_eof
4795 PerlIO_error
4796 PerlIO_fileno
4797 PerlIO_fill
4798 PerlIO_flush
4799 PerlIO_get_base
4800 PerlIO_get_bufsiz
4801 PerlIO_get_cnt
4802 PerlIO_get_ptr
4803 PerlIO_read
4804 PerlIO_seek
4805 PerlIO_set_cnt
4806 PerlIO_set_ptrcnt
4807 PerlIO_setlinebuf
4808 PerlIO_stderr
4809 PerlIO_stdin
4810 PerlIO_stdout
4811 PerlIO_tell
4812 PerlIO_unread
4813 PerlIO_write
4814 Slab_Alloc
4815 Slab_Free
4816 amagic_call
4817 any_dup
4818 apply_attrs_string
4819 atfork_lock
4820 atfork_unlock
4821 av_arylen_p
4822 av_iter_p
4823 block_gimme
4824 call_atexit
4825 call_list
4826 calloc
4827 cast_i32
4828 cast_iv
4829 cast_ulong
4830 cast_uv
4831 ck_warner
4832 ck_warner_d
4833 ckwarn
4834 ckwarn_d
4835 croak_nocontext
4836 csighandler
4837 custom_op_desc
4838 custom_op_name
4839 cx_dump
4840 cx_dup
4841 cxinc
4842 deb
4843 deb_nocontext
4844 debop
4845 debprofdump
4846 debstack
4847 debstackptrs
4848 delimcpy
4849 despatch_signals
4850 die
4851 die_nocontext
4852 dirp_dup
4853 do_aspawn
4854 do_binmode
4855 do_close
4856 do_gv_dump
4857 do_gvgv_dump
4858 do_hv_dump
4859 do_join
4860 do_magic_dump
4861 do_op_dump
4862 do_open
4863 do_open9
4864 do_openn
4865 do_pmop_dump
4866 do_spawn
4867 do_spawn_nowait
4868 do_sprintf
4869 do_sv_dump
4870 doing_taint
4871 doref
4872 dounwind
4873 dowantarray
4874 dump_all
4875 dump_eval
4876 dump_fds
4877 dump_form
4878 dump_indent
4879 dump_mstats
4880 dump_packsubs
4881 dump_sub
4882 dump_vindent
4883 fetch_cop_label
4884 filter_add
4885 filter_del
4886 filter_read
4887 find_rundefsvoffset
4888 form_nocontext
4889 fp_dup
4890 fprintf_nocontext
4891 free_global_struct
4892 free_tmps
4893 get_context
4894 get_mstats
4895 get_op_descs
4896 get_op_names
4897 get_ppaddr
4898 get_vtbl
4899 gp_dup
4900 gp_free
4901 gp_ref
4902 gv_AVadd
4903 gv_HVadd
4904 gv_IOadd
4905 gv_SVadd
4906 gv_add_by_type
4907 gv_autoload4
4908 gv_check
4909 gv_dump
4910 gv_efullname
4911 gv_efullname3
4912 gv_efullname4
4913 gv_fetchfile
4914 gv_fetchfile_flags
4915 gv_fetchmethod_flags
4916 gv_fetchpv
4917 gv_fetchpvn_flags
4918 gv_fetchsv
4919 gv_fullname
4920 gv_fullname3
4921 gv_fullname4
4922 gv_handler
4923 gv_init
4924 gv_name_set
4925 he_dup
4926 hek_dup
4927 hv_common
4928 hv_common_key_len
4929 hv_delayfree_ent
4930 hv_eiter_p
4931 hv_eiter_set
4932 hv_free_ent
4933 hv_ksplit
4934 hv_name_set
4935 hv_placeholders_get
4936 hv_placeholders_p
4937 hv_placeholders_set
4938 hv_riter_p
4939 hv_riter_set
4940 hv_store_flags
4941 ibcmp
4942 ibcmp_locale
4943 init_global_struct
4944 init_i18nl10n
4945 init_i18nl14n
4946 init_stacks
4947 init_tm
4948 instr
4949 is_lvalue_sub
4950 is_uni_alnum
4951 is_uni_alnum_lc
4952 is_uni_alpha
4953 is_uni_alpha_lc
4954 is_uni_ascii
4955 is_uni_ascii_lc
4956 is_uni_cntrl
4957 is_uni_cntrl_lc
4958 is_uni_digit
4959 is_uni_digit_lc
4960 is_uni_graph
4961 is_uni_graph_lc
4962 is_uni_idfirst
4963 is_uni_idfirst_lc
4964 is_uni_lower
4965 is_uni_lower_lc
4966 is_uni_print
4967 is_uni_print_lc
4968 is_uni_punct
4969 is_uni_punct_lc
4970 is_uni_space
4971 is_uni_space_lc
4972 is_uni_upper
4973 is_uni_upper_lc
4974 is_uni_xdigit
4975 is_uni_xdigit_lc
4976 is_utf8_alnum
4977 is_utf8_alpha
4978 is_utf8_ascii
4979 is_utf8_cntrl
4980 is_utf8_digit
4981 is_utf8_graph
4982 is_utf8_idcont
4983 is_utf8_idfirst
4984 is_utf8_lower
4985 is_utf8_mark
4986 is_utf8_perl_space
4987 is_utf8_perl_word
4988 is_utf8_posix_digit
4989 is_utf8_print
4990 is_utf8_punct
4991 is_utf8_space
4992 is_utf8_upper
4993 is_utf8_xdigit
4994 leave_scope
4995 load_module_nocontext
4996 magic_dump
4997 malloc
4998 markstack_grow
4999 mess
5000 mess_nocontext
5001 mfree
5002 mg_dup
5003 mg_size
5004 mini_mktime
5005 moreswitches
5006 mro_get_from_name
5007 mro_get_private_data
5008 mro_register
5009 mro_set_mro
5010 mro_set_private_data
5011 my_atof
5012 my_atof2
5013 my_bcopy
5014 my_bzero
5015 my_chsize
5016 my_cxt_index
5017 my_cxt_init
5018 my_dirfd
5019 my_exit
5020 my_failure_exit
5021 my_fflush_all
5022 my_fork
5023 my_htonl
5024 my_lstat
5025 my_memcmp
5026 my_memset
5027 my_ntohl
5028 my_pclose
5029 my_popen
5030 my_popen_list
5031 my_setenv
5032 my_socketpair
5033 my_stat
5034 my_strftime
5035 my_strlcat
5036 my_strlcpy
5037 my_swap
5038 newANONATTRSUB
5039 newANONHASH
5040 newANONLIST
5041 newANONSUB
5042 newASSIGNOP
5043 newATTRSUB
5044 newAVREF
5045 newBINOP
5046 newCONDOP
5047 newCVREF
5048 newFORM
5049 newFOROP
5050 newGIVENOP
5051 newGVOP
5052 newGVREF
5053 newGVgen
5054 newHVREF
5055 newHVhv
5056 newIO
5057 newLISTOP
5058 newLOGOP
5059 newLOOPEX
5060 newLOOPOP
5061 newMYSUB
5062 newNULLLIST
5063 newOP
5064 newPADOP
5065 newPMOP
5066 newPROG
5067 newPVOP
5068 newRANGE
5069 newRV
5070 newSLICEOP
5071 newSTATEOP
5072 newSUB
5073 newSVOP
5074 newSVREF
5075 newSVpvf_nocontext
5076 newUNOP
5077 newWHENOP
5078 newWHILEOP
5079 newXS_flags
5080 new_collate
5081 new_ctype
5082 new_numeric
5083 new_stackinfo
5084 ninstr
5085 op_dump
5086 op_free
5087 op_null
5088 op_refcnt_lock
5089 op_refcnt_unlock
5090 parser_dup
5091 perl_alloc_using
5092 perl_clone_using
5093 pmop_dump
5094 pop_scope
5095 pregcomp
5096 pregexec
5097 pregfree
5098 pregfree2
5099 printf_nocontext
5100 ptr_table_clear
5101 ptr_table_fetch
5102 ptr_table_free
5103 ptr_table_new
5104 ptr_table_split
5105 ptr_table_store
5106 push_scope
5107 re_compile
5108 re_dup_guts
5109 re_intuit_start
5110 re_intuit_string
5111 realloc
5112 reentrant_free
5113 reentrant_init
5114 reentrant_retry
5115 reentrant_size
5116 ref
5117 reg_named_buff_all
5118 reg_named_buff_exists
5119 reg_named_buff_fetch
5120 reg_named_buff_firstkey
5121 reg_named_buff_nextkey
5122 reg_named_buff_scalar
5123 regclass_swash
5124 regdump
5125 regdupe_internal
5126 regexec_flags
5127 regfree_internal
5128 reginitcolors
5129 regnext
5130 repeatcpy
5131 rninstr
5132 rsignal
5133 rsignal_state
5134 runops_debug
5135 runops_standard
5136 rvpv_dup
5137 safesyscalloc
5138 safesysfree
5139 safesysmalloc
5140 safesysrealloc
5141 save_I16
5142 save_I32
5143 save_I8
5144 save_adelete
5145 save_aelem
5146 save_aelem_flags
5147 save_alloc
5148 save_aptr
5149 save_ary
5150 save_bool
5151 save_clearsv
5152 save_delete
5153 save_destructor
5154 save_destructor_x
5155 save_freepv
5156 save_freesv
5157 save_generic_pvref
5158 save_generic_svref
5159 save_gp
5160 save_hash
5161 save_hdelete
5162 save_helem
5163 save_helem_flags
5164 save_hptr
5165 save_int
5166 save_item
5167 save_iv
5168 save_list
5169 save_long
5170 save_mortalizesv
5171 save_nogv
5172 save_padsv_and_mortalize
5173 save_pptr
5174 save_pushptr
5175 save_re_context
5176 save_scalar
5177 save_set_svflags
5178 save_shared_pvref
5179 save_sptr
5180 save_svref
5181 save_vptr
5182 savestack_grow
5183 savestack_grow_cnt
5184 scan_num
5185 scan_vstring
5186 screaminstr
5187 seed
5188 set_context
5189 set_numeric_local
5190 set_numeric_radix
5191 set_numeric_standard
5192 share_hek
5193 si_dup
5194 ss_dup
5195 stack_grow
5196 start_subparse
5197 stashpv_hvname_match
5198 str_to_version
5199 sv_2iv
5200 sv_2pv
5201 sv_2uv
5202 sv_catpvf_mg_nocontext
5203 sv_catpvf_nocontext
5204 sv_compile_2op
5205 sv_dump
5206 sv_dup
5207 sv_peek
5208 sv_pvn_nomg
5209 sv_setpvf_mg_nocontext
5210 sv_setpvf_nocontext
5211 sv_utf8_upgrade_flags_grow
5212 swash_fetch
5213 swash_init
5214 sys_init
5215 sys_init3
5216 sys_intern_clear
5217 sys_intern_dup
5218 sys_intern_init
5219 sys_term
5220 taint_env
5221 taint_proper
5222 tmps_grow
5223 to_uni_fold
5224 to_uni_lower
5225 to_uni_lower_lc
5226 to_uni_title
5227 to_uni_title_lc
5228 to_uni_upper
5229 to_uni_upper_lc
5230 unlnk
5231 unsharepvn
5232 utf16_to_utf8
5233 utf16_to_utf8_reversed
5234 uvchr_to_utf8_flags
5235 uvuni_to_utf8
5236 vcroak
5237 vdeb
5238 vform
5239 vload_module
5240 vmess
5241 vnewSVpvf
5242 vwarn
5243 vwarner
5244 warn_nocontext
5245 warner
5246 warner_nocontext
5247 whichsig
5248
5250 Until May 1997, this document was maintained by Jeff Okamoto
5251 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
5252 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
5254 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
5255 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
5256 Stephen McCamant, and Gurusamy Sarathy.
5257 API Listing originally by Dean Roehrich <roehrich@cray.com>.
5259 Updated to be autogenerated from comments in the source by Benjamin
5261 Stuhl.
5262
5264 perlguts, perlxs, perlxstut, perlintern
5265perl v5.12.4 2011-11-04 PERLAPI(1)