PERLAPI(1) Perl Programmers Reference Guide PERLAPI(1)
NAME
perlapi - autogenerated documentation for the perl public API
DESCRIPTION
This file contains the documentation of the perl public API generated by embed.pl, specifically a listing of functions, macros, flags, and
variables that may be used by extension writers. At the end is a list of functions which have yet to be documented. The interfaces of
those are subject to change without notice. Any functions not listed here are not part of the public API, and should not be used by
extension writers at all. For these reasons, blindly using functions listed in proto.h is to be avoided when writing extensions.
Note that all Perl API global variables must be referenced with the "PL_" prefix. Some macros are provided for compatibility with the
older, unadorned names, but this support may be disabled in a future release.
Perl was originally written to handle US-ASCII only (that is characters whose ordinal numbers are in the range 0 - 127). And documentation
and comments may still use the term ASCII, when sometimes in fact the entire range from 0 - 255 is meant.
Note that Perl can be compiled and run under EBCDIC (See perlebcdic) or ASCII. Most of the documentation (and even comments in the code)
ignore the EBCDIC possibility. For almost all purposes the differences are transparent. As an example, under EBCDIC, instead of UTF-8,
UTF-EBCDIC is used to encode Unicode strings, and so whenever this documentation refers to "utf8" (and variants of that name, including in
function names), it also (essentially transparently) means "UTF-EBCDIC". But the ordinals of characters differ between ASCII, EBCDIC, and
the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes than in UTF-8.
The listing below is alphabetical, case insensitive.
"Gimme" Values
GIMME A backward-compatible version of "GIMME_V" which can only return "G_SCALAR" or "G_ARRAY"; in a void context, it returns "G_SCALAR".
Deprecated. Use "GIMME_V" instead.
U32 GIMME
GIMME_V The XSUB-writer's equivalent to Perl's "wantarray". Returns "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list context,
respectively. See perlcall for a usage example.
U32 GIMME_V
G_ARRAY Used to indicate list context. See "GIMME_V", "GIMME" and perlcall.
G_DISCARD
Indicates that arguments returned from a callback should be discarded. See perlcall.
G_EVAL Used to force a Perl "eval" wrapper around a callback. See perlcall.
G_NOARGS
Indicates that no arguments are being sent to a callback. See perlcall.
G_SCALAR
Used to indicate scalar context. See "GIMME_V", "GIMME", and perlcall.
G_VOID Used to indicate void context. See "GIMME_V" and perlcall.
Array Manipulation Functions
AvFILL Same as "av_top_index()". Deprecated, use "av_top_index()" instead.
int AvFILL(AV* av)
av_clear
Clears an array, making it empty. Does not free the memory the av uses to store its list of scalars. If any destructors are
triggered as a result, the av itself may be freed when this function returns.
Perl equivalent: "@myarray = ();".
void av_clear(AV *av)
av_create_and_push
Push an SV onto the end of the array, creating the array if necessary. A small internal helper function to remove a commonly
duplicated idiom.
NOTE: this function is experimental and may change or be removed without notice.
void av_create_and_push(AV **const avp,
SV *const val)
av_create_and_unshift_one
Unshifts an SV onto the beginning of the array, creating the array if necessary. A small internal helper function to remove a
commonly duplicated idiom.
NOTE: this function is experimental and may change or be removed without notice.
SV** av_create_and_unshift_one(AV **const avp,
SV *const val)
av_delete
Deletes the element indexed by "key" from the array, makes the element mortal, and returns it. If "flags" equals "G_DISCARD", the
element is freed and null is returned. Perl equivalent: "my $elem = delete($myarray[$idx]);" for the non-"G_DISCARD" version and a
void-context "delete($myarray[$idx]);" for the "G_DISCARD" version.
SV* av_delete(AV *av, I32 key, I32 flags)
av_exists
Returns true if the element indexed by "key" has been initialized.
This relies on the fact that uninitialized array elements are set to &PL_sv_undef.
Perl equivalent: "exists($myarray[$key])".
bool av_exists(AV *av, I32 key)
av_extend
Pre-extend an array. The "key" is the index to which the array should be extended.
void av_extend(AV *av, I32 key)
av_fetch
Returns the SV at the specified index in the array. The "key" is the index. If lval is true, you are guaranteed to get a real SV
back (in case it wasn't real before), which you can then modify. Check that the return value is non-null before dereferencing it
to a "SV*".
See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more information on how to use this function on tied
arrays.
The rough perl equivalent is $myarray[$idx].
SV** av_fetch(AV *av, I32 key, I32 lval)
av_fill Set the highest index in the array to the given number, equivalent to Perl's "$#array = $fill;".
The number of elements in the an array will be "fill + 1" after av_fill() returns. If the array was previously shorter, then the
additional elements appended are set to "PL_sv_undef". If the array was longer, then the excess elements are freed. "av_fill(av,
-1)" is the same as "av_clear(av)".
void av_fill(AV *av, I32 fill)
av_len Same as "av_top_index". Returns the highest index in the array. Note that the return value is +1 what its name implies it
returns; and hence differs in meaning from what the similarly named "sv_len" returns.
I32 av_len(AV *av)
av_make Creates a new AV and populates it with a list of SVs. The SVs are copied into the array, so they may be freed after the call to
av_make. The new AV will have a reference count of 1.
Perl equivalent: "my @new_array = ($scalar1, $scalar2, $scalar3...);"
AV* av_make(I32 size, SV **strp)
av_pop Removes one SV from the end of the array, reducing its size by one and returning the SV (transferring control of one reference
count) to the caller. Returns &PL_sv_undef if the array is empty.
Perl equivalent: "pop(@myarray);"
SV* av_pop(AV *av)
av_push Pushes an SV onto the end of the array. The array will grow automatically to accommodate the addition. This takes ownership of
one reference count.
Perl equivalent: "push @myarray, $elem;".
void av_push(AV *av, SV *val)
av_shift
Shifts an SV off the beginning of the array. Returns &PL_sv_undef if the array is empty.
Perl equivalent: "shift(@myarray);"
SV* av_shift(AV *av)
av_store
Stores an SV in an array. The array index is specified as "key". The return value will be NULL if the operation failed or if the
value did not need to be actually stored within the array (as in the case of tied arrays). Otherwise, it can be dereferenced to get
the "SV*" that was stored there (= "val")).
Note that the caller is responsible for suitably incrementing the reference count of "val" before the call, and decrementing it if
the function returned NULL.
Approximate Perl equivalent: "$myarray[$key] = $val;".
See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more information on how to use this function on tied
arrays.
SV** av_store(AV *av, I32 key, SV *val)
av_tindex
Same as "av_top_index()".
int av_tindex(AV* av)
av_top_index
Returns the highest index in the array. The number of elements in the array is "av_top_index(av) + 1". Returns -1 if the array is
empty.
The Perl equivalent for this is $#myarray.
(A slightly shorter form is "av_tindex".)
I32 av_top_index(AV *av)
av_undef
Undefines the array. Frees the memory used by the av to store its list of scalars. If any destructors are triggered as a result,
the av itself may be freed.
void av_undef(AV *av)
av_unshift
Unshift the given number of "undef" values onto the beginning of the array. The array will grow automatically to accommodate the
addition. You must then use "av_store" to assign values to these new elements.
Perl equivalent: "unshift @myarray, ( (undef) x $n );"
void av_unshift(AV *av, I32 num)
get_av Returns the AV of the specified Perl global or package array with the given name (so it won't work on lexical variables). "flags"
are passed to "gv_fetchpv". If "GV_ADD" is set and the Perl variable does not exist then it will be created. If "flags" is zero
and the variable does not exist then NULL is returned.
Perl equivalent: "@{"$name"}".
NOTE: the perl_ form of this function is deprecated.
AV* get_av(const char *name, I32 flags)
newAV Creates a new AV. The reference count is set to 1.
Perl equivalent: "my @array;".
AV* newAV()
sortsv Sort an array. Here is an example:
sortsv(AvARRAY(av), av_top_index(av)+1, Perl_sv_cmp_locale);
Currently this always uses mergesort. See sortsv_flags for a more flexible routine.
void sortsv(SV** array, size_t num_elts,
SVCOMPARE_t cmp)
sortsv_flags
Sort an array, with various options.
void sortsv_flags(SV** array, size_t num_elts,
SVCOMPARE_t cmp, U32 flags)
Callback Functions
call_argv
Performs a callback to the specified named and package-scoped Perl subroutine with "argv" (a NULL-terminated array of strings) as
arguments. See perlcall.
Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
NOTE: the perl_ form of this function is deprecated.
I32 call_argv(const char* sub_name, I32 flags,
char** argv)
call_method
Performs a callback to the specified Perl method. The blessed object must be on the stack. See perlcall.
NOTE: the perl_ form of this function is deprecated.
I32 call_method(const char* methname, I32 flags)
call_pv Performs a callback to the specified Perl sub. See perlcall.
NOTE: the perl_ form of this function is deprecated.
I32 call_pv(const char* sub_name, I32 flags)
call_sv Performs a callback to the Perl sub whose name is in the SV. See perlcall.
NOTE: the perl_ form of this function is deprecated.
I32 call_sv(SV* sv, VOL I32 flags)
ENTER Opening bracket on a callback. See "LEAVE" and perlcall.
ENTER;
eval_pv Tells Perl to "eval" the given string and return an SV* result.
NOTE: the perl_ form of this function is deprecated.
SV* eval_pv(const char* p, I32 croak_on_error)
eval_sv Tells Perl to "eval" the string in the SV. It supports the same flags as "call_sv", with the obvious exception of G_EVAL. See
perlcall.
NOTE: the perl_ form of this function is deprecated.
I32 eval_sv(SV* sv, I32 flags)
FREETMPS
Closing bracket for temporaries on a callback. See "SAVETMPS" and perlcall.
FREETMPS;
LEAVE Closing bracket on a callback. See "ENTER" and perlcall.
LEAVE;
SAVETMPS
Opening bracket for temporaries on a callback. See "FREETMPS" and perlcall.
SAVETMPS;
Character case changing
toLOWER Converts the specified character to lowercase, if possible; otherwise returns the input character itself.
char toLOWER(char ch)
toUPPER Converts the specified character to uppercase, if possible; otherwise returns the input character itself.
char toUPPER(char ch)
Character classes
This section is about functions (really macros) that classify characters into types, such as punctuation versus alphabetic, etc. Most of
these are analogous to regular expression character classes. (See "POSIX Character Classes" in perlrecharclass.) There are several
variants for each class. (Not all macros have all variants; each item below lists the ones valid for it.) None are affected by "use
bytes", and only the ones with "LC" in the name are affected by the current locale.
The base function, e.g., "isALPHA()", takes an octet (either a "char" or a "U8") as input and returns a boolean as to whether or not the
character represented by that octet is (or on non-ASCII platforms, corresponds to) an ASCII character in the named class based on platform,
Unicode, and Perl rules. If the input is a number that doesn't fit in an octet, FALSE is returned.
Variant "isFOO_A" (e.g., "isALPHA_A()") is identical to the base function with no suffix "_A".
Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivlalent) character set onto the platform. That is, the code points that are ASCII
are unaffected, since ASCII is a subset of Latin-1. But the non-ASCII code points are treated as if they are Latin-1 characters. For
example, "isWORDCHAR_L1()" will return true when called with the code point 0xDF, which is a word character in both ASCII and EBCDIC
(though it represent different characters in each).
Variant "isFOO_uni" is like the "isFOO_L1" variant, but accepts any UV code point as input. If the code point is larger than 255, Unicode
rules are used to determine if it is in the character class. For example, "isWORDCHAR_uni(0x100)" returns TRUE, since 0x100 is LATIN
CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.
Variant "isFOO_utf8" is like "isFOO_uni", but the input is a pointer to a (known to be well-formed) UTF-8 encoded string ("U8*" or
"char*"). The classification of just the first (possibly multi-byte) character in the string is tested.
Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but uses the C library function that gives the named classification
instead of hard-coded rules. For example, "isDIGIT_LC()" returns the result of calling "isdigit()". This means that the result is based
on the current locale, which is what "LC" in the name stands for. FALSE is always returned if the input won't fit into an octet.
Variant "isFOO_LC_uvchr" is like "isFOO_LC", but is defined on any UV. It returns the same as "isFOO_LC" for input code points less than
256, and returns the hard-coded, not-affected-by-locale, Unicode results for larger ones.
Variant "isFOO_LC_utf8" is like "isFOO_LC_uvchr", but the input is a pointer to a (known to be well-formed) UTF-8 encoded string ("U8*" or
"char*"). The classification of just the first (possibly multi-byte) character in the string is tested.
isALPHA Returns a boolean indicating whether the specified character is an alphabetic character, analogous to "m/[[:alpha:]]/". See the
top of this section for an explanation of variants "isALPHA_A", "isALPHA_L1", "isALPHA_uni", "isALPHA_utf8", "isALPHA_LC",
"isALPHA_LC_uvchr", and "isALPHA_LC_utf8".
bool isALPHA(char ch)
isALPHANUMERIC
Returns a boolean indicating whether the specified character is a either an alphabetic character or decimal digit, analogous to
"m/[[:alnum:]]/". See the top of this section for an explanation of variants "isALPHANUMERIC_A", "isALPHANUMERIC_L1",
"isALPHANUMERIC_uni", "isALPHANUMERIC_utf8", "isALPHANUMERIC_LC", "isALPHANUMERIC_LC_uvchr", and "isALPHANUMERIC_LC_utf8".
bool isALPHANUMERIC(char ch)
isASCII Returns a boolean indicating whether the specified character is one of the 128 characters in the ASCII character set, analogous to
"m/[[:ascii:]]/". On non-ASCII platforms, it returns TRUE iff this character corresponds to an ASCII character. Variants
"isASCII_A()" and "isASCII_L1()" are identical to "isASCII()". See the top of this section for an explanation of variants
"isASCII_uni", "isASCII_utf8", "isASCII_LC", "isASCII_LC_uvchr", and "isASCII_LC_utf8". Note, however, that some platforms do not
have the C library routine "isascii()". In these cases, the variants whose names contain "LC" are the same as the corresponding
ones without.
bool isASCII(char ch)
isBLANK Returns a boolean indicating whether the specified character is a character considered to be a blank, analogous to
"m/[[:blank:]]/". See the top of this section for an explanation of variants "isBLANK_A", "isBLANK_L1", "isBLANK_uni",
"isBLANK_utf8", "isBLANK_LC", "isBLANK_LC_uvchr", and "isBLANK_LC_utf8". Note, however, that some platforms do not have the C
library routine "isblank()". In these cases, the variants whose names contain "LC" are the same as the corresponding ones without.
bool isBLANK(char ch)
isCNTRL Returns a boolean indicating whether the specified character is a control character, analogous to "m/[[:cntrl:]]/". See the top of
this section for an explanation of variants "isCNTRL_A", "isCNTRL_L1", "isCNTRL_uni", "isCNTRL_utf8", "isCNTRL_LC",
"isCNTRL_LC_uvchr", and "isCNTRL_LC_utf8" On EBCDIC platforms, you almost always want to use the "isCNTRL_L1" variant.
bool isCNTRL(char ch)
isDIGIT Returns a boolean indicating whether the specified character is a digit, analogous to "m/[[:digit:]]/". Variants "isDIGIT_A" and
"isDIGIT_L1" are identical to "isDIGIT". See the top of this section for an explanation of variants "isDIGIT_uni", "isDIGIT_utf8",
"isDIGIT_LC", "isDIGIT_LC_uvchr", and "isDIGIT_LC_utf8".
bool isDIGIT(char ch)
isGRAPH Returns a boolean indicating whether the specified character is a graphic character, analogous to "m/[[:graph:]]/". See the top of
this section for an explanation of variants "isGRAPH_A", "isGRAPH_L1", "isGRAPH_uni", "isGRAPH_utf8", "isGRAPH_LC",
"isGRAPH_LC_uvchr", and "isGRAPH_LC_utf8".
bool isGRAPH(char ch)
isIDCONT
Returns a boolean indicating whether the specified character can be the second or succeeding character of an identifier. This is
very close to, but not quite the same as the official Unicode property "XID_Continue". The difference is that this returns true
only if the input character also matches "isWORDCHAR". See the top of this section for an explanation of variants "isIDCONT_A",
"isIDCONT_L1", "isIDCONT_uni", "isIDCONT_utf8", "isIDCONT_LC", "isIDCONT_LC_uvchr", and "isIDCONT_LC_utf8".
bool isIDCONT(char ch)
isIDFIRST
Returns a boolean indicating whether the specified character can be the first character of an identifier. This is very close to,
but not quite the same as the official Unicode property "XID_Start". The difference is that this returns true only if the input
character also matches "isWORDCHAR". See the top of this section for an explanation of variants "isIDFIRST_A", "isIDFIRST_L1",
"isIDFIRST_uni", "isIDFIRST_utf8", "isIDFIRST_LC", "isIDFIRST_LC_uvchr", and "isIDFIRST_LC_utf8".
bool isIDFIRST(char ch)
isLOWER Returns a boolean indicating whether the specified character is a lowercase character, analogous to "m/[[:lower:]]/". See the top
of this section for an explanation of variants "isLOWER_A", "isLOWER_L1", "isLOWER_uni", "isLOWER_utf8", "isLOWER_LC",
"isLOWER_LC_uvchr", and "isLOWER_LC_utf8".
bool isLOWER(char ch)
isOCTAL Returns a boolean indicating whether the specified character is an octal digit, [0-7]. The only two variants are "isOCTAL_A" and
"isOCTAL_L1"; each is identical to "isOCTAL".
bool isOCTAL(char ch)
isPRINT Returns a boolean indicating whether the specified character is a printable character, analogous to "m/[[:print:]]/". See the top
of this section for an explanation of variants "isPRINT_A", "isPRINT_L1", "isPRINT_uni", "isPRINT_utf8", "isPRINT_LC",
"isPRINT_LC_uvchr", and "isPRINT_LC_utf8".
bool isPRINT(char ch)
isPSXSPC
(short for Posix Space) Starting in 5.18, this is identical (experimentally) in all its forms to the corresponding "isSPACE()"
macros. ("Experimentally" means that this change may be backed out in 5.20 or 5.22 if field experience indicates that it was
unwise.) The locale forms of this macro are identical to their corresponding "isSPACE()" forms in all Perl releases. In releases
prior to 5.18, the non-locale forms differ from their "isSPACE()" forms only in that the "isSPACE()" forms don't match a Vertical
Tab, and the "isPSXSPC()" forms do. Otherwise they are identical. Thus this macro is analogous to what "m/[[:space:]]/" matches
in a regular expression. See the top of this section for an explanation of variants "isPSXSPC_A", "isPSXSPC_L1", "isPSXSPC_uni",
"isPSXSPC_utf8", "isPSXSPC_LC", "isPSXSPC_LC_uvchr", and "isPSXSPC_LC_utf8".
bool isPSXSPC(char ch)
isPUNCT Returns a boolean indicating whether the specified character is a punctuation character, analogous to "m/[[:punct:]]/". Note that
the definition of what is punctuation isn't as straightforward as one might desire. See "POSIX Character Classes" in
perlrecharclass for details. See the top of this section for an explanation of variants "isPUNCT_A", "isPUNCT_L1", "isPUNCT_uni",
"isPUNCT_utf8", "isPUNCT_LC", "isPUNCT_LC_uvchr", and "isPUNCT_LC_utf8".
bool isPUNCT(char ch)
isSPACE Returns a boolean indicating whether the specified character is a whitespace character. This is analogous to what "m/s/" matches
in a regular expression. Starting in Perl 5.18 (experimentally), this also matches what "m/[[:space:]]/" does. ("Experimentally"
means that this change may be backed out in 5.20 or 5.22 if field experience indicates that it was unwise.) Prior to 5.18, only
the locale forms of this macro (the ones with "LC" in their names) matched precisely what "m/[[:space:]]/" does. In those
releases, the only difference, in the non-locale variants, was that "isSPACE()" did not match a vertical tab. (See "isPSXSPC" for
a macro that matches a vertical tab in all releases.) See the top of this section for an explanation of variants "isSPACE_A",
"isSPACE_L1", "isSPACE_uni", "isSPACE_utf8", "isSPACE_LC", "isSPACE_LC_uvchr", and "isSPACE_LC_utf8".
bool isSPACE(char ch)
isUPPER Returns a boolean indicating whether the specified character is an uppercase character, analogous to "m/[[:upper:]]/". See the top
of this section for an explanation of variants "isUPPER_A", "isUPPER_L1", "isUPPER_uni", "isUPPER_utf8", "isUPPER_LC",
"isUPPER_LC_uvchr", and "isUPPER_LC_utf8".
bool isUPPER(char ch)
isWORDCHAR
Returns a boolean indicating whether the specified character is a character that is a word character, analogous to what "m/w/" and
"m/[[:word:]]/" match in a regular expression. A word character is an alphabetic character, a decimal digit, a connecting
punctuation character (such as an underscore), or a "mark" character that attaches to one of those (like some sort of accent).
"isALNUM()" is a synonym provided for backward compatibility, even though a word character includes more than the standard C
language meaning of alphanumeric. See the top of this section for an explanation of variants "isWORDCHAR_A", "isWORDCHAR_L1",
"isWORDCHAR_uni", "isWORDCHAR_utf8", "isWORDCHAR_LC", "isWORDCHAR_LC_uvchr", and "isWORDCHAR_LC_utf8".
bool isWORDCHAR(char ch)
isXDIGIT
Returns a boolean indicating whether the specified character is a hexadecimal digit. In the ASCII range these are "[0-9A-Fa-f]".
Variants "isXDIGIT_A()" and "isXDIGIT_L1()" are identical to "isXDIGIT()". See the top of this section for an explanation of
variants "isXDIGIT_uni", "isXDIGIT_utf8", "isXDIGIT_LC", "isXDIGIT_LC_uvchr", and "isXDIGIT_LC_utf8".
bool isXDIGIT(char ch)
Cloning an interpreter
perl_clone
Create and return a new interpreter by cloning the current one.
perl_clone takes these flags as parameters:
CLONEf_COPY_STACKS - is used to, well, copy the stacks also, without it we only clone the data and zero the stacks, with it we copy
the stacks and the new perl interpreter is ready to run at the exact same point as the previous one. The pseudo-fork code uses
COPY_STACKS while the threads->create doesn't.
CLONEf_KEEP_PTR_TABLE - perl_clone keeps a ptr_table with the pointer of the old variable as a key and the new variable as a value,
this allows it to check if something has been cloned and not clone it again but rather just use the value and increase the
refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill the ptr_table using the function "ptr_table_free(PL_ptr_table);
PL_ptr_table = NULL;", reason to keep it around is if you want to dup some of your own variable who are outside the graph perl
scans, example of this code is in threads.xs create.
CLONEf_CLONE_HOST - This is a win32 thing, it is ignored on unix, it tells perls win32host code (which is c++) to clone itself,
this is needed on win32 if you want to run two threads at the same time, if you just want to do some stuff in a separate perl
interpreter and then throw it away and return to the original one, you don't need to do anything.
PerlInterpreter* perl_clone(
PerlInterpreter *proto_perl,
UV flags
)
Compile-time scope hooks
BhkDISABLE
Temporarily disable an entry in this BHK structure, by clearing the appropriate flag. which is a preprocessor token indicating
which entry to disable.
NOTE: this function is experimental and may change or be removed without notice.
void BhkDISABLE(BHK *hk, which)
BhkENABLE
Re-enable an entry in this BHK structure, by setting the appropriate flag. which is a preprocessor token indicating which entry to
enable. This will assert (under -DDEBUGGING) if the entry doesn't contain a valid pointer.
NOTE: this function is experimental and may change or be removed without notice.
void BhkENABLE(BHK *hk, which)
BhkENTRY_set
Set an entry in the BHK structure, and set the flags to indicate it is valid. which is a preprocessing token indicating which entry
to set. The type of ptr depends on the entry.
NOTE: this function is experimental and may change or be removed without notice.
void BhkENTRY_set(BHK *hk, which, void *ptr)
blockhook_register
Register a set of hooks to be called when the Perl lexical scope changes at compile time. See "Compile-time scope hooks" in
perlguts.
NOTE: this function is experimental and may change or be removed without notice.
NOTE: this function must be explicitly called as Perl_blockhook_register with an aTHX_ parameter.
void Perl_blockhook_register(pTHX_ BHK *hk)
COP Hint Hashes
cophh_2hv
Generates and returns a standard Perl hash representing the full set of key/value pairs in the cop hints hash cophh. flags is
currently unused and must be zero.
NOTE: this function is experimental and may change or be removed without notice.
HV * cophh_2hv(const COPHH *cophh, U32 flags)
cophh_copy
Make and return a complete copy of the cop hints hash cophh.
NOTE: this function is experimental and may change or be removed without notice.
COPHH * cophh_copy(COPHH *cophh)
cophh_delete_pv
Like "cophh_delete_pvn", but takes a nul-terminated string instead of a string/length pair.
NOTE: this function is experimental and may change or be removed without notice.
COPHH * cophh_delete_pv(const COPHH *cophh,
const char *key, U32 hash,
U32 flags)
cophh_delete_pvn
Delete a key and its associated value from the cop hints hash cophh, and returns the modified hash. The returned hash pointer is
in general not the same as the hash pointer that was passed in. The input hash is consumed by the function, and the pointer to it
must not be subsequently used. Use "cophh_copy" if you need both hashes.
The key is specified by keypv and keylen. If flags has the "COPHH_KEY_UTF8" bit set, the key octets are interpreted as UTF-8,
otherwise they are interpreted as Latin-1. hash is a precomputed hash of the key string, or zero if it has not been precomputed.
NOTE: this function is experimental and may change or be removed without notice.
COPHH * cophh_delete_pvn(COPHH *cophh,
const char *keypv,
STRLEN keylen, U32 hash,
U32 flags)
cophh_delete_pvs
Like "cophh_delete_pvn", but takes a literal string instead of a string/length pair, and no precomputed hash.
NOTE: this function is experimental and may change or be removed without notice.
COPHH * cophh_delete_pvs(const COPHH *cophh,
const char *key, U32 flags)
cophh_delete_sv
Like "cophh_delete_pvn", but takes a Perl scalar instead of a string/length pair.
NOTE: this function is experimental and may change or be removed without notice.
COPHH * cophh_delete_sv(const COPHH *cophh, SV *key,
U32 hash, U32 flags)
cophh_fetch_pv
Like "cophh_fetch_pvn", but takes a nul-terminated string instead of a string/length pair.
NOTE: this function is experimental and may change or be removed without notice.
SV * cophh_fetch_pv(const COPHH *cophh,
const char *key, U32 hash,
U32 flags)
cophh_fetch_pvn
Look up the entry in the cop hints hash cophh with the key specified by keypv and keylen. If flags has the "COPHH_KEY_UTF8" bit
set, the key octets are interpreted as UTF-8, otherwise they are interpreted as Latin-1. hash is a precomputed hash of the key
string, or zero if it has not been precomputed. Returns a mortal scalar copy of the value associated with the key, or
&PL_sv_placeholder if there is no value associated with the key.
NOTE: this function is experimental and may change or be removed without notice.
SV * cophh_fetch_pvn(const COPHH *cophh,
const char *keypv,
STRLEN keylen, U32 hash,
U32 flags)
cophh_fetch_pvs
Like "cophh_fetch_pvn", but takes a literal string instead of a string/length pair, and no precomputed hash.
NOTE: this function is experimental and may change or be removed without notice.
SV * cophh_fetch_pvs(const COPHH *cophh,
const char *key, U32 flags)
cophh_fetch_sv
Like "cophh_fetch_pvn", but takes a Perl scalar instead of a string/length pair.
NOTE: this function is experimental and may change or be removed without notice.
SV * cophh_fetch_sv(const COPHH *cophh, SV *key,
U32 hash, U32 flags)
cophh_free
Discard the cop hints hash cophh, freeing all resources associated with it.
NOTE: this function is experimental and may change or be removed without notice.
void cophh_free(COPHH *cophh)
cophh_new_empty
Generate and return a fresh cop hints hash containing no entries.
NOTE: this function is experimental and may change or be removed without notice.
COPHH * cophh_new_empty()
cophh_store_pv
Like "cophh_store_pvn", but takes a nul-terminated string instead of a string/length pair.
NOTE: this function is experimental and may change or be removed without notice.
COPHH * cophh_store_pv(const COPHH *cophh,
const char *key, U32 hash,
SV *value, U32 flags)
cophh_store_pvn
Stores a value, associated with a key, in the cop hints hash cophh, and returns the modified hash. The returned hash pointer is in
general not the same as the hash pointer that was passed in. The input hash is consumed by the function, and the pointer to it
must not be subsequently used. Use "cophh_copy" if you need both hashes.
The key is specified by keypv and keylen. If flags has the "COPHH_KEY_UTF8" bit set, the key octets are interpreted as UTF-8,
otherwise they are interpreted as Latin-1. hash is a precomputed hash of the key string, or zero if it has not been precomputed.
value is the scalar value to store for this key. value is copied by this function, which thus does not take ownership of any
reference to it, and later changes to the scalar will not be reflected in the value visible in the cop hints hash. Complex types
of scalar will not be stored with referential integrity, but will be coerced to strings.
NOTE: this function is experimental and may change or be removed without notice.
COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
STRLEN keylen, U32 hash,
SV *value, U32 flags)
cophh_store_pvs
Like "cophh_store_pvn", but takes a literal string instead of a string/length pair, and no precomputed hash.
NOTE: this function is experimental and may change or be removed without notice.
COPHH * cophh_store_pvs(const COPHH *cophh,
const char *key, SV *value,
U32 flags)
cophh_store_sv
Like "cophh_store_pvn", but takes a Perl scalar instead of a string/length pair.
NOTE: this function is experimental and may change or be removed without notice.
COPHH * cophh_store_sv(const COPHH *cophh, SV *key,
U32 hash, SV *value, U32 flags)
COP Hint Reading
cop_hints_2hv
Generates and returns a standard Perl hash representing the full set of hint entries in the cop cop. flags is currently unused and
must be zero.
HV * cop_hints_2hv(const COP *cop, U32 flags)
cop_hints_fetch_pv
Like "cop_hints_fetch_pvn", but takes a nul-terminated string instead of a string/length pair.
SV * cop_hints_fetch_pv(const COP *cop,
const char *key, U32 hash,
U32 flags)
cop_hints_fetch_pvn
Look up the hint entry in the cop cop with the key specified by keypv and keylen. If flags has the "COPHH_KEY_UTF8" bit set, the
key octets are interpreted as UTF-8, otherwise they are interpreted as Latin-1. hash is a precomputed hash of the key string, or
zero if it has not been precomputed. Returns a mortal scalar copy of the value associated with the key, or &PL_sv_placeholder if
there is no value associated with the key.
SV * cop_hints_fetch_pvn(const COP *cop,
const char *keypv,
STRLEN keylen, U32 hash,
U32 flags)
cop_hints_fetch_pvs
Like "cop_hints_fetch_pvn", but takes a literal string instead of a string/length pair, and no precomputed hash.
SV * cop_hints_fetch_pvs(const COP *cop,
const char *key, U32 flags)
cop_hints_fetch_sv
Like "cop_hints_fetch_pvn", but takes a Perl scalar instead of a string/length pair.
SV * cop_hints_fetch_sv(const COP *cop, SV *key,
U32 hash, U32 flags)
Custom Operators
custom_op_register
Register a custom op. See "Custom Operators" in perlguts.
NOTE: this function must be explicitly called as Perl_custom_op_register with an aTHX_ parameter.
void Perl_custom_op_register(pTHX_
Perl_ppaddr_t ppaddr,
const XOP *xop)
custom_op_xop
Return the XOP structure for a given custom op. This function should be considered internal to OP_NAME and the other access macros:
use them instead.
NOTE: this function must be explicitly called as Perl_custom_op_xop with an aTHX_ parameter.
const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
XopDISABLE
Temporarily disable a member of the XOP, by clearing the appropriate flag.
void XopDISABLE(XOP *xop, which)
XopENABLE
Reenable a member of the XOP which has been disabled.
void XopENABLE(XOP *xop, which)
XopENTRY
Return a member of the XOP structure. which is a cpp token indicating which entry to return. If the member is not set this will
return a default value. The return type depends on which.
XopENTRY(XOP *xop, which)
XopENTRY_set
Set a member of the XOP structure. which is a cpp token indicating which entry to set. See "Custom Operators" in perlguts for
details about the available members and how they are used.
void XopENTRY_set(XOP *xop, which, value)
XopFLAGS
Return the XOP's flags.
U32 XopFLAGS(XOP *xop)
CV Manipulation Functions
CvSTASH Returns the stash of the CV. A stash is the symbol table hash, containing the package-scoped variables in the package where the
subroutine was defined. For more information, see perlguts.
This also has a special use with XS AUTOLOAD subs. See "Autoloading with XSUBs" in perlguts.
HV* CvSTASH(CV* cv)
get_cv Uses "strlen" to get the length of "name", then calls "get_cvn_flags".
NOTE: the perl_ form of this function is deprecated.
CV* get_cv(const char* name, I32 flags)
get_cvn_flags
Returns the CV of the specified Perl subroutine. "flags" are passed to "gv_fetchpvn_flags". If "GV_ADD" is set and the Perl
subroutine does not exist then it will be declared (which has the same effect as saying "sub name;"). If "GV_ADD" is not set and
the subroutine does not exist then NULL is returned.
NOTE: the perl_ form of this function is deprecated.
CV* get_cvn_flags(const char* name, STRLEN len,
I32 flags)
Embedding Functions
cv_clone
Clone a CV, making a lexical closure. proto supplies the prototype of the function: its code, pad structure, and other attributes.
The prototype is combined with a capture of outer lexicals to which the code refers, which are taken from the currently-executing
instance of the immediately surrounding code.
CV * cv_clone(CV *proto)
cv_undef
Clear out all the active components of a CV. This can happen either by an explicit "undef &foo", or by the reference count going to
zero. In the former case, we keep the CvOUTSIDE pointer, so that any anonymous children can still follow the full lexical scope
chain.
void cv_undef(CV* cv)
find_rundefsv
Find and return the variable that is named $_ in the lexical scope of the currently-executing function. This may be a lexical $_,
or will otherwise be the global one.
SV * find_rundefsv()
find_rundefsvoffset
Find the position of the lexical $_ in the pad of the currently-executing function. Returns the offset in the current pad, or
"NOT_IN_PAD" if there is no lexical $_ in scope (in which case the global one should be used instead). "find_rundefsv" is likely
to be more convenient.
NOTE: the perl_ form of this function is deprecated.
PADOFFSET find_rundefsvoffset()
load_module
Loads the module whose name is pointed to by the string part of name. Note that the actual module name, not its filename, should
be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or
PERL_LOADMOD_IMPORT_OPS (or 0 for no flags). ver, if specified and not NULL, provides version semantics similar to "use Foo::Bar
VERSION". The optional trailing SV* arguments can be used to specify arguments to the module's import() method, similar to "use
Foo::Bar VERSION LIST". They must be terminated with a final NULL pointer. Note that this list can only be omitted when the
PERL_LOADMOD_NOIMPORT flag has been used. Otherwise at least a single NULL pointer to designate the default import list is
required.
The reference count for each specified "SV*" parameter is decremented.
void load_module(U32 flags, SV* name, SV* ver, ...)
nothreadhook
Stub that provides thread hook for perl_destruct when there are no threads.
int nothreadhook()
pad_add_anon
Allocates a place in the currently-compiling pad (via "pad_alloc") for an anonymous function that is lexically scoped inside the
currently-compiling function. The function func is linked into the pad, and its "CvOUTSIDE" link to the outer scope is weakened to
avoid a reference loop.
One reference count is stolen, so you may need to do "SvREFCNT_inc(func)".
optype should be an opcode indicating the type of operation that the pad entry is to support. This doesn't affect operational
semantics, but is used for debugging.
PADOFFSET pad_add_anon(CV *func, I32 optype)
pad_add_name_pv
Exactly like "pad_add_name_pvn", but takes a nul-terminated string instead of a string/length pair.
PADOFFSET pad_add_name_pv(const char *name, U32 flags,
HV *typestash, HV *ourstash)
pad_add_name_pvn
Allocates a place in the currently-compiling pad for a named lexical variable. Stores the name and other metadata in the name part
of the pad, and makes preparations to manage the variable's lexical scoping. Returns the offset of the allocated pad slot.
namepv/namelen specify the variable's name, including leading sigil. If typestash is non-null, the name is for a typed lexical,
and this identifies the type. If ourstash is non-null, it's a lexical reference to a package variable, and this identifies the
package. The following flags can be OR'ed together:
padadd_OUR redundantly specifies if it's a package var
padadd_STATE variable will retain value persistently
padadd_NO_DUP_CHECK skip check for lexical shadowing
PADOFFSET pad_add_name_pvn(const char *namepv,
STRLEN namelen, U32 flags,
HV *typestash, HV *ourstash)
pad_add_name_sv
Exactly like "pad_add_name_pvn", but takes the name string in the form of an SV instead of a string/length pair.
PADOFFSET pad_add_name_sv(SV *name, U32 flags,
HV *typestash, HV *ourstash)
pad_alloc
Allocates a place in the currently-compiling pad, returning the offset of the allocated pad slot. No name is initially attached to
the pad slot. tmptype is a set of flags indicating the kind of pad entry required, which will be set in the value SV for the
allocated pad entry:
SVs_PADMY named lexical variable ("my", "our", "state")
SVs_PADTMP unnamed temporary store
optype should be an opcode indicating the type of operation that the pad entry is to support. This doesn't affect operational
semantics, but is used for debugging.
NOTE: this function is experimental and may change or be removed without notice.
PADOFFSET pad_alloc(I32 optype, U32 tmptype)
pad_compname_type
Looks up the type of the lexical variable at position po in the currently-compiling pad. If the variable is typed, the stash of
the class to which it is typed is returned. If not, "NULL" is returned.
HV * pad_compname_type(PADOFFSET po)
pad_findmy_pv
Exactly like "pad_findmy_pvn", but takes a nul-terminated string instead of a string/length pair.
PADOFFSET pad_findmy_pv(const char *name, U32 flags)
pad_findmy_pvn
Given the name of a lexical variable, find its position in the currently-compiling pad. namepv/namelen specify the variable's
name, including leading sigil. flags is reserved and must be zero. If it is not in the current pad but appears in the pad of any
lexically enclosing scope, then a pseudo-entry for it is added in the current pad. Returns the offset in the current pad, or
"NOT_IN_PAD" if no such lexical is in scope.
PADOFFSET pad_findmy_pvn(const char *namepv,
STRLEN namelen, U32 flags)
pad_findmy_sv
Exactly like "pad_findmy_pvn", but takes the name string in the form of an SV instead of a string/length pair.
PADOFFSET pad_findmy_sv(SV *name, U32 flags)
pad_setsv
Set the value at offset po in the current (compiling or executing) pad. Use the macro PAD_SETSV() rather than calling this
function directly.
void pad_setsv(PADOFFSET po, SV *sv)
pad_sv Get the value at offset po in the current (compiling or executing) pad. Use macro PAD_SV instead of calling this function
directly.
SV * pad_sv(PADOFFSET po)
pad_tidy
Tidy up a pad at the end of compilation of the code to which it belongs. Jobs performed here are: remove most stuff from the pads
of anonsub prototypes; give it a @_; mark temporaries as such. type indicates the kind of subroutine:
padtidy_SUB ordinary subroutine
padtidy_SUBCLONE prototype for lexical closure
padtidy_FORMAT format
NOTE: this function is experimental and may change or be removed without notice.
void pad_tidy(padtidy_type type)
perl_alloc
Allocates a new Perl interpreter. See perlembed.
PerlInterpreter* perl_alloc()
perl_construct
Initializes a new Perl interpreter. See perlembed.
void perl_construct(PerlInterpreter *my_perl)
perl_destruct
Shuts down a Perl interpreter. See perlembed.
int perl_destruct(PerlInterpreter *my_perl)
perl_free
Releases a Perl interpreter. See perlembed.
void perl_free(PerlInterpreter *my_perl)
perl_parse
Tells a Perl interpreter to parse a Perl script. See perlembed.
int perl_parse(PerlInterpreter *my_perl,
XSINIT_t xsinit, int argc,
char** argv, char** env)
perl_run
Tells a Perl interpreter to run. See perlembed.
int perl_run(PerlInterpreter *my_perl)
require_pv
Tells Perl to "require" the file named by the string argument. It is analogous to the Perl code "eval "require '$file'"". It's
even implemented that way; consider using load_module instead.
NOTE: the perl_ form of this function is deprecated.
void require_pv(const char* pv)
Functions in file dump.c
pv_display
Similar to
pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
except that an additional "