Perlapi (1) Linux Manual Page

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. Anything not listed here is 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.

In Perl, unlike C, a string of characters may generally contain embedded "NUL" characters. Sometimes in the documentation a Perl string is referred to as a “buffer” to distinguish it from a C string, but sometimes they are both just referred to as strings.

Note that all Perl API global variables must be referenced with the "PL_" prefix. Again, those not listed here are not to be used by extension writers, and can be changed or removed without notice; same with macros. 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.

The non-ASCII characters below 256 can have various meanings, depending on various things. (See, most notably, perllocale.) But usually the whole range can be referred to as ISO-8859-1. Often, the term “Latin-1” (or “Latin1”) is used as an equivalent for ISO-8859-1. But some people treat “Latin1” as referring just to the characters in the range 128 through 255, or somethimes from 160 through 255. This documentation uses “Latin1” and “Latin-1” to refer to all 256 characters.

Note that Perl can be compiled and run under either ASCII or EBCDIC (See perlebcdic). 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 a different number of bytes than in UTF-8.

The listing below is alphabetical, case insensitive.

Array Manipulation Functions

av_clear

Frees the all the elements of an array, leaving it empty. The XS equivalent of "@array = ()". See also “av_undef”.

Note that it is possible that the actions of a destructor called directly or indirectly by freeing an element of the array could cause the reference count of the array itself to be reduced (e.g. by deleting an entry in the symbol table). So it is a possibility that the AV could have been freed (or even reallocated) on return from the call unless you hold a reference to it.

 void av_clear(AV *av)

av_create_and_push

NOTE: this function is experimental and may change or be removed without notice.

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.

 void av_create_and_push(AV **const avp,
 SV *const val)

av_create_and_unshift_one

NOTE: this function is experimental and may change or be removed without notice.

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.

 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. NULL is also returned if "key" is out of range.

Perl equivalent: "splice(@myarray, $key, 1, undef)" (with the "splice" in void context if "G_DISCARD" is present).

 SV* av_delete(AV *av, SSize_t 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 "NULL".

Perl equivalent: "exists($myarray[$key])".

 bool av_exists(AV *av, SSize_t key)

av_extend

Pre-extend an array. The "key" is the index to which the array should be extended.

 void av_extend(AV *av, SSize_t 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[$key].

 SV** av_fetch(AV *av, SSize_t key, I32 lval)

AvFILL

Same as "av_top_index()" or "av_tindex()".

 int AvFILL(AV* av)

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 array will be "fill + 1" after "av_fill()" returns. If the array was previously shorter, then the additional elements appended are set to NULL. 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, SSize_t fill)

av_len

Same as “av_top_index”. Note that, unlike what the name implies, it returns the highest index in the array, so to get the size of the array you need to use "av_len(av) + 1". This is unlike “sv_len”, which returns what you would expect.

 SSize_t 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(SSize_t 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 (transferring control of one reference count) onto the end of the array. The array will grow automatically to accommodate the addition.

Perl equivalent: "push @myarray, $val;".

 void av_push(AV *av, SV *val)

av_shift

Removes one SV from the start 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: "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: "splice(@myarray, $key, 1, $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, SSize_t 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".)

 SSize_t av_top_index(AV *av)

av_undef

Undefines the array. The XS equivalent of "undef(@array)".

As well as freeing all the elements of the array (like "av_clear()"), this also frees the memory used by the av to store its list of scalars.

See “av_clear” for a note about the array possibly being invalid on return.

 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.

Perl equivalent: "unshift @myarray, ((undef) x $num);"

 void av_unshift(AV *av, SSize_t 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

In-place sort an array of SV pointers with the given comparison routine.

Currently this always uses mergesort. See "sortsv_flags" for a more flexible routine.

 void sortsv(SV** array, size_t num_elts,
 SVCOMPARE_t cmp)

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 specified by the SV.

If neither the "G_METHOD" nor "G_METHOD_NAMED" flag is supplied, the SV may be any of a CV, a GV, a reference to a CV, a reference to a GV or "SvPV(sv)" will be used as the name of the sub to call.

If the "G_METHOD" flag is supplied, the SV may be a reference to a CV or "SvPV(sv)" will be used as the name of the method to call.

If the "G_METHOD_NAMED" flag is supplied, "SvPV(sv)" will be used as the name of the method to call.

Some other values are treated specially for internal use and should not be depended on.

See perlcall.

NOTE: the perl_ form of this function is deprecated.

 I32 call_sv(SV* sv, volatile I32 flags)

ENTER

Opening bracket on a callback. See "LEAVE" and perlcall.

 ENTER;

ENTER_with_name(name)

Same as "ENTER", but when debugging is enabled it also associates the given literal string with the new scope.

 ENTER_with_name(name);

eval_pv

Tells Perl to "eval" the given string in scalar context 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;

LEAVE_with_name(name)

Same as "LEAVE", but when debugging is enabled it first checks that the scope has the given name. "name" must be a literal string.

 LEAVE_with_name(name);

SAVETMPS

Opening bracket for temporaries on a callback. See "FREETMPS" and perlcall.

 SAVETMPS;

Character case changing

Perl uses “full” Unicode case mappings. This means that converting a single character to another case may result in a sequence of more than one character. For example, the uppercase of "ß" (LATIN SMALL LETTER SHARP S) is the two character sequence "SS". This presents some complications The lowercase of all characters in the range 0..255 is a single character, and thus "toLOWER_L1" is furnished. But, "toUPPER_L1" can’t exist, as it couldn’t return a valid result for all legal inputs. Instead "toUPPER_uvchr" has an API that does allow every possible legal result to be returned.) Likewise no other function that is crippled by not being able to give the correct results for the full range of possible inputs has been implemented here.

toFOLD

Converts the specified character to foldcase. If the input is anything but an ASCII uppercase character, that input character itself is returned. Variant "toFOLD_A" is equivalent. (There is no equivalent "to_FOLD_L1" for the full Latin1 range, as the full generality of “toFOLD_uvchr” is needed there.)

 U8 toFOLD(U8 ch)

toFOLD_utf8

This is like "toFOLD_utf8_safe", but doesn’t have the "e" parameter The function therefore can’t check if it is reading beyond the end of the string. Starting in Perl v5.30, it will take the "e" parameter, becoming a synonym for "toFOLD_utf8_safe". At that time every program that uses it will have to be changed to successfully compile. In the meantime, the first runtime call to "toFOLD_utf8" from each call point in the program will raise a deprecation warning, enabled by default. You can convert your program now to use "toFOLD_utf8_safe", and avoid the warnings, and get an extra measure of protection, or you can wait until v5.30, when you’ll be forced to add the "e" parameter.

 UV toFOLD_utf8(U8* p, U8* s, STRLEN* lenp)

toFOLD_utf8_safe

Converts the first UTF-8 encoded character in the sequence starting at "p" and extending no further than "e - 1" to its foldcase version, and stores that in UTF-8 in "s", and its length in bytes in "lenp". Note that the buffer pointed to by "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the foldcase version may be longer than the original character.

The first code point of the foldcased version is returned (but note, as explained at the top of this section, that there may be more).

The suffix "_safe" in the function’s name indicates that it will not attempt to read beyond "e - 1", provided that the constraint "s < e" is true (this is asserted for in "-DDEBUGGING" builds). If the UTF-8 for the input character is malformed in some way, the program may croak, or the function may return the REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to change in future releases.

 UV toFOLD_utf8_safe(U8* p, U8* e, U8* s,
 STRLEN* lenp)

toFOLD_uvchr

Converts the code point "cp" to its foldcase version, and stores that in UTF-8 in "s", and its length in bytes in "lenp". The code point is interpreted as native if less than 256; otherwise as Unicode. Note that the buffer pointed to by "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the foldcase version may be longer than the original character.

The first code point of the foldcased version is returned (but note, as explained at the top of this section, that there may be more).

 UV toFOLD_uvchr(UV cp, U8* s, STRLEN* lenp)

toLOWER

Converts the specified character to lowercase. If the input is anything but an ASCII uppercase character, that input character itself is returned. Variant "toLOWER_A" is equivalent.

 U8 toLOWER(U8 ch)

toLOWER_L1

Converts the specified Latin1 character to lowercase. The results are undefined if the input doesn’t fit in a byte.

 U8 toLOWER_L1(U8 ch)

toLOWER_LC

Converts the specified character to lowercase using the current locale’s rules, if possible; otherwise returns the input character itself.

 U8 toLOWER_LC(U8 ch)

toLOWER_utf8

This is like "toLOWER_utf8_safe", but doesn’t have the "e" parameter The function therefore can’t check if it is reading beyond the end of the string. Starting in Perl v5.30, it will take the "e" parameter, becoming a synonym for "toLOWER_utf8_safe". At that time every program that uses it will have to be changed to successfully compile. In the meantime, the first runtime call to "toLOWER_utf8" from each call point in the program will raise a deprecation warning, enabled by default. You can convert your program now to use "toLOWER_utf8_safe", and avoid the warnings, and get an extra measure of protection, or you can wait until v5.30, when you’ll be forced to add the "e" parameter.

 UV toLOWER_utf8(U8* p, U8* s, STRLEN* lenp)

toLOWER_utf8_safe

Converts the first UTF-8 encoded character in the sequence starting at "p" and extending no further than "e - 1" to its lowercase version, and stores that in UTF-8 in "s", and its length in bytes in "lenp". Note that the buffer pointed to by "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the lowercase version may be longer than the original character.

The first code point of the lowercased version is returned (but note, as explained at the top of this section, that there may be more).

 UV toLOWER_utf8_safe(U8* p, U8* e, U8* s,
 STRLEN* lenp)

toLOWER_uvchr

Converts the code point "cp" to its lowercase version, and stores that in UTF-8 in "s", and its length in bytes in "lenp". The code point is interpreted as native if less than 256; otherwise as Unicode. Note that the buffer pointed to by "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the lowercase version may be longer than the original character.

The first code point of the lowercased version is returned (but note, as explained at the top of this section, that there may be more).

 UV toLOWER_uvchr(UV cp, U8* s, STRLEN* lenp)

toTITLE

Converts the specified character to titlecase. If the input is anything but an ASCII lowercase character, that input character itself is returned. Variant "toTITLE_A" is equivalent. (There is no "toTITLE_L1" for the full Latin1 range, as the full generality of “toTITLE_uvchr” is needed there. Titlecase is not a concept used in locale handling, so there is no functionality for that.)

 U8 toTITLE(U8 ch)

toTITLE_utf8

This is like "toLOWER_utf8_safe", but doesn’t have the "e" parameter The function therefore can’t check if it is reading beyond the end of the string. Starting in Perl v5.30, it will take the "e" parameter, becoming a synonym for "toTITLE_utf8_safe". At that time every program that uses it will have to be changed to successfully compile. In the meantime, the first runtime call to "toTITLE_utf8" from each call point in the program will raise a deprecation warning, enabled by default. You can convert your program now to use "toTITLE_utf8_safe", and avoid the warnings, and get an extra measure of protection, or you can wait until v5.30, when you’ll be forced to add the "e" parameter.

 UV toTITLE_utf8(U8* p, U8* s, STRLEN* lenp)

toTITLE_utf8_safe

Converts the first UTF-8 encoded character in the sequence starting at "p" and extending no further than "e - 1" to its titlecase version, and stores that in UTF-8 in "s", and its length in bytes in "lenp". Note that the buffer pointed to by "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the titlecase version may be longer than the original character.

The first code point of the titlecased version is returned (but note, as explained at the top of this section, that there may be more).

 UV toTITLE_utf8_safe(U8* p, U8* e, U8* s,
 STRLEN* lenp)

toTITLE_uvchr

Converts the code point "cp" to its titlecase version, and stores that in UTF-8 in "s", and its length in bytes in "lenp". The code point is interpreted as native if less than 256; otherwise as Unicode. Note that the buffer pointed to by "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the titlecase version may be longer than the original character.

The first code point of the titlecased version is returned (but note, as explained at the top of this section, that there may be more).

 UV toTITLE_uvchr(UV cp, U8* s, STRLEN* lenp)

toUPPER

Converts the specified character to uppercase. If the input is anything but an ASCII lowercase character, that input character itself is returned. Variant "toUPPER_A" is equivalent.

 U8 toUPPER(U8 ch)

toUPPER_utf8

This is like "toUPPER_utf8_safe", but doesn’t have the "e" parameter The function therefore can’t check if it is reading beyond the end of the string. Starting in Perl v5.30, it will take the "e" parameter, becoming a synonym for "toUPPER_utf8_safe". At that time every program that uses it will have to be changed to successfully compile. In the meantime, the first runtime call to "toUPPER_utf8" from each call point in the program will raise a deprecation warning, enabled by default. You can convert your program now to use "toUPPER_utf8_safe", and avoid the warnings, and get an extra measure of protection, or you can wait until v5.30, when you’ll be forced to add the "e" parameter.

 UV toUPPER_utf8(U8* p, U8* s, STRLEN* lenp)

toUPPER_utf8_safe

Converts the first UTF-8 encoded character in the sequence starting at "p" and extending no further than "e - 1" to its uppercase version, and stores that in UTF-8 in "s", and its length in bytes in "lenp". Note that the buffer pointed to by "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the uppercase version may be longer than the original character.

The first code point of the uppercased version is returned (but note, as explained at the top of this section, that there may be more).

 UV toUPPER_utf8_safe(U8* p, U8* e, U8* s,
 STRLEN* lenp)

toUPPER_uvchr

Converts the code point "cp" to its uppercase version, and stores that in UTF-8 in "s", and its length in bytes in "lenp". The code point is interpreted as native if less than 256; otherwise as Unicode. Note that the buffer pointed to by "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the uppercase version may be longer than the original character.

The first code point of the uppercased version is returned (but note, as explained at the top of this section, that there may be more.)

 UV toUPPER_uvchr(UV cp, U8* s, STRLEN* lenp)

Character classification

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". This variant is used to emphasize by its name that only ASCII-range characters can return TRUE.

Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivalent) 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 represents different characters in each).

Variant "isFOO_uvchr" 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_uvchr(0x100)" returns TRUE, since 0x100 is LATIN CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.

Variant "isFOO_utf8_safe" is like "isFOO_uvchr", but is used for UTF-8 encoded strings. Each call classifies one character, even if the string contains many. This variant takes two parameters. The first, "p", is a pointer to the first byte of the character to be classified. (Recall that it may take more than one byte to represent a character in UTF-8 strings.) The second parameter, "e", points to anywhere in the string beyond the first character, up to one byte past the end of the entire string. The suffix "_safe" in the function’s name indicates that it will not attempt to read beyond "e - 1", provided that the constraint "s < e" is true (this is asserted for in "-DDEBUGGING" builds). If the UTF-8 for the input character is malformed in some way, the program may croak, or the function may return FALSE, at the discretion of the implementation, and subject to change in future releases.

Variant "isFOO_utf8" is like "isFOO_utf8_safe", but takes just a single parameter, "p", which has the same meaning as the corresponding parameter does in "isFOO_utf8_safe". The function therefore can’t check if it is reading beyond the end of the string. Starting in Perl v5.30, it will take a second parameter, becoming a synonym for "isFOO_utf8_safe". At that time every program that uses it will have to be changed to successfully compile. In the meantime, the first runtime call to "isFOO_utf8" from each call point in the program will raise a deprecation warning, enabled by default. You can convert your program now to use "isFOO_utf8_safe", and avoid the warnings, and get an extra measure of protection, or you can wait until v5.30, when you’ll be forced to add the "e" parameter.

Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but the result is based on the current locale, which is what "LC" in the name stands for. If Perl can determine that the current locale is a UTF-8 locale, it uses the published Unicode rules; otherwise, it uses the C library function that gives the named classification. For example, "isDIGIT_LC()" when not in a UTF-8 locale returns the result of calling "isdigit()". FALSE is always returned if the input won’t fit into an octet. On some platforms where the C library function is known to be defective, Perl changes its result to follow the POSIX standard’s rules.

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_safe" is like "isFOO_LC_uvchr", but is used for UTF-8 encoded strings. Each call classifies one character, even if the string contains many. This variant takes two parameters. The first, "p", is a pointer to the first byte of the character to be classified. (Recall that it may take more than one byte to represent a character in UTF-8 strings.) The second parameter, "e", points to anywhere in the string beyond the first character, up to one byte past the end of the entire string. The suffix "_safe" in the function’s name indicates that it will not attempt to read beyond "e - 1", provided that the constraint "s < e" is true (this is asserted for in "-DDEBUGGING" builds). If the UTF-8 for the input character is malformed in some way, the program may croak, or the function may return FALSE, at the discretion of the implementation, and subject to change in future releases.

Variant "isFOO_LC_utf8" is like "isFOO_LC_utf8_safe", but takes just a single parameter, "p", which has the same meaning as the corresponding parameter does in "isFOO_LC_utf8_safe". The function therefore can’t check if it is reading beyond the end of the string. Starting in Perl v5.30, it will take a second parameter, becoming a synonym for "isFOO_LC_utf8_safe". At that time every program that uses it will have to be changed to successfully compile. In the meantime, the first runtime call to "isFOO_LC_utf8" from each call point in the program will raise a deprecation warning, enabled by default. You can convert your program now to use "isFOO_LC_utf8_safe", and avoid the warnings, and get an extra measure of protection, or you can wait until v5.30, when you’ll be forced to add the "e" parameter.

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_uvchr", "isALPHA_utf8_safe", "isALPHA_LC", "isALPHA_LC_uvchr", and "isALPHA_LC_utf8_safe".

 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_uvchr", "isALPHANUMERIC_utf8_safe", "isALPHANUMERIC_LC", "isALPHANUMERIC_LC_uvchr", and "isALPHANUMERIC_LC_utf8_safe".

 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_uvchr", "isASCII_utf8_safe", "isASCII_LC", "isASCII_LC_uvchr", and "isASCII_LC_utf8_safe". 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.

Also note, that because all ASCII characters are UTF-8 invariant (meaning they have the exact same representation (always a single byte) whether encoded in UTF-8 or not), "isASCII" will give the correct results when called with any byte in any string encoded or not in UTF-8. And similarly "isASCII_utf8_safe" will work properly on any string encoded or not in UTF-8.

 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_uvchr", "isBLANK_utf8_safe", "isBLANK_LC", "isBLANK_LC_uvchr", and "isBLANK_LC_utf8_safe". 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_uvchr", "isCNTRL_utf8_safe", "isCNTRL_LC", "isCNTRL_LC_uvchr", and "isCNTRL_LC_utf8_safe" 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_uvchr", "isDIGIT_utf8_safe", "isDIGIT_LC", "isDIGIT_LC_uvchr", and "isDIGIT_LC_utf8_safe".

 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_uvchr", "isGRAPH_utf8_safe", "isGRAPH_LC", "isGRAPH_LC_uvchr", and "isGRAPH_LC_utf8_safe".

 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_uvchr", "isIDCONT_utf8_safe", "isIDCONT_LC", "isIDCONT_LC_uvchr", and "isIDCONT_LC_utf8_safe".

 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_uvchr", "isIDFIRST_utf8_safe", "isIDFIRST_LC", "isIDFIRST_LC_uvchr", and "isIDFIRST_LC_utf8_safe".

 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_uvchr", "isLOWER_utf8_safe", "isLOWER_LC", "isLOWER_LC_uvchr", and "isLOWER_LC_utf8_safe".

 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_uvchr", "isPRINT_utf8_safe", "isPRINT_LC", "isPRINT_LC_uvchr", and "isPRINT_LC_utf8_safe".

 bool isPRINT(char ch)

isPSXSPC

(short for Posix Space) Starting in 5.18, this is identical in all its forms to the corresponding "isSPACE()" macros. 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_uvchr", "isPSXSPC_utf8_safe", "isPSXSPC_LC", "isPSXSPC_LC_uvchr", and "isPSXSPC_LC_utf8_safe".

 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_uvchr", "isPUNCT_utf8_safe", "isPUNCT_LC", "isPUNCT_LC_uvchr", and "isPUNCT_LC_utf8_safe".

 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 this also matches what "m/[[:space:]]/" does. 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_uvchr", "isSPACE_utf8_safe", "isSPACE_LC", "isSPACE_LC_uvchr", and "isSPACE_LC_utf8_safe".

 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_uvchr", "isUPPER_utf8_safe", "isUPPER_LC", "isUPPER_LC_uvchr", and "isUPPER_LC_utf8_safe".

 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_uvchr", and "isWORDCHAR_utf8_safe". "isWORDCHAR_LC", "isWORDCHAR_LC_uvchr", and "isWORDCHAR_LC_utf8_safe" are also as described there, but additionally include the platform’s native underscore.

 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_uvchr", "isXDIGIT_utf8_safe", "isXDIGIT_LC", "isXDIGIT_LC_uvchr", and "isXDIGIT_LC_utf8_safe".

 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, an 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

NOTE: this function is experimental and may change or be removed without notice.

Temporarily disable an entry in this BHK structure, by clearing the appropriate flag. "which" is a preprocessor token indicating which entry to disable.

 void BhkDISABLE(BHK *hk, which)

BhkENABLE

NOTE: this function is experimental and may change or be removed without notice.

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.

 void BhkENABLE(BHK *hk, which)

BhkENTRY_set

NOTE: this function is experimental and may change or be removed without notice.

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.

 void BhkENTRY_set(BHK *hk, which, void *ptr)

blockhook_register

NOTE: this function is experimental and may change or be removed without notice.

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 must be explicitly called as Perl_blockhook_register with an aTHX_ parameter.

 void Perl_blockhook_register(pTHX_ BHK *hk)

COP Hint Hashes

cophh_2hv

NOTE: this function is experimental and may change or be removed without notice.

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.

 HV * cophh_2hv(const COPHH *cophh, U32 flags)

cophh_copy

NOTE: this function is experimental and may change or be removed without notice.

Make and return a complete copy of the cop hints hash "cophh".

 COPHH * cophh_copy(COPHH *cophh)

cophh_delete_pv

NOTE: this function is experimental and may change or be removed without notice.

Like “cophh_delete_pvn”, but takes a nul-terminated string instead of a string/length pair.

 COPHH * cophh_delete_pv(const COPHH *cophh,
 const char *key, U32 hash,
 U32 flags)

cophh_delete_pvn

NOTE: this function is experimental and may change or be removed without notice.

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.

 COPHH * cophh_delete_pvn(COPHH *cophh,
 const char *keypv,
 STRLEN keylen, U32 hash,
 U32 flags)

cophh_delete_pvs

NOTE: this function is experimental and may change or be removed without notice.

Like “cophh_delete_pvn”, but takes a literal string instead of a string/length pair, and no precomputed hash.

 COPHH * cophh_delete_pvs(const COPHH *cophh,
 "literal string" key,
 U32 flags)

cophh_delete_sv

NOTE: this function is experimental and may change or be removed without notice.

Like “cophh_delete_pvn”, but takes a Perl scalar instead of a string/length pair.

 COPHH * cophh_delete_sv(const COPHH *cophh, SV *key,
 U32 hash, U32 flags)

cophh_fetch_pv

NOTE: this function is experimental and may change or be removed without notice.

Like “cophh_fetch_pvn”, but takes a nul-terminated string instead of a string/length pair.

 SV * cophh_fetch_pv(const COPHH *cophh,
 const char *key, U32 hash,
 U32 flags)

cophh_fetch_pvn

NOTE: this function is experimental and may change or be removed without notice.

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.

 SV * cophh_fetch_pvn(const COPHH *cophh,
 const char *keypv,
 STRLEN keylen, U32 hash,
 U32 flags)

cophh_fetch_pvs

NOTE: this function is experimental and may change or be removed without notice.

Like “cophh_fetch_pvn”, but takes a literal string instead of a string/length pair, and no precomputed hash.

 SV * cophh_fetch_pvs(const COPHH *cophh,
 "literal string" key, U32 flags)

cophh_fetch_sv

NOTE: this function is experimental and may change or be removed without notice.

Like “cophh_fetch_pvn”, but takes a Perl scalar instead of a string/length pair.

 SV * cophh_fetch_sv(const COPHH *cophh, SV *key,
 U32 hash, U32 flags)

cophh_free

NOTE: this function is experimental and may change or be removed without notice.

Discard the cop hints hash "cophh", freeing all resources associated with it.

 void cophh_free(COPHH *cophh)

cophh_new_empty

NOTE: this function is experimental and may change or be removed without notice.

Generate and return a fresh cop hints hash containing no entries.

 COPHH * cophh_new_empty()

cophh_store_pv

NOTE: this function is experimental and may change or be removed without notice.

Like “cophh_store_pvn”, but takes a nul-terminated string instead of a string/length pair.

 COPHH * cophh_store_pv(const COPHH *cophh,
 const char *key, U32 hash,
 SV *value, U32 flags)

cophh_store_pvn

NOTE: this function is experimental and may change or be removed without notice.

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.

"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.

 COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
 STRLEN keylen, U32 hash,
 SV *value, U32 flags)

cophh_store_pvs

NOTE: this function is experimental and may change or be removed without notice.

Like “cophh_store_pvn”, but takes a literal string instead of a string/length pair, and no precomputed hash.

 COPHH * cophh_store_pvs(const COPHH *cophh,
 "literal string" key, SV *value,
 U32 flags)

cophh_store_sv

NOTE: this function is experimental and may change or be removed without notice.

Like “cophh_store_pvn”, but takes a Perl scalar instead of a string/length pair.

 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,
 "literal string" 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

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 macro should be considered internal to "OP_NAME" and the other access macros: use them instead. This macro does call a function. Prior to 5.19.6, this was implemented as a function.

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". This macro evaluates its arguments more than once. If you are using "Perl_custom_op_xop" to retreive a "XOP *" from a "OP *", use the more efficient “XopENTRYCUSTOM” instead.

 XopENTRY(XOP *xop, which)

XopENTRYCUSTOM

Exactly like "XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o), which)" but more efficient. The "which" parameter is identical to “XopENTRY”.

 XopENTRYCUSTOM(const OP *o, 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. This macro evaluates its argument more than once.

 void XopENTRY_set(XOP *xop, which, value)

XopFLAGS

Return the XOP‘s flags.

 U32 XopFLAGS(XOP *xop)

CV Manipulation Functions

This section documents functions to manipulate CVs which are code-values, or subroutines. For more information, see perlguts.

caller_cx

The XSUB-writer’s equivalent of caller(). The returned "PERL_CONTEXT" structure can be interrogated to find all the information returned to Perl by "caller". Note that XSUBs don’t get a stack frame, so "caller_cx(0, NULL)" will return information for the immediately-surrounding Perl code.

This function skips over the automatic calls to &DB::sub made on the behalf of the debugger. If the stack frame requested was a sub called by "DB::sub", the return value will be the frame for the call to "DB::sub", since that has the correct line number/etc. for the call site. If dbcxp is non-"NULL", it will be set to a pointer to the frame for the sub call itself.

 const PERL_CONTEXT * caller_cx(
 I32 level,
 const PERL_CONTEXT **dbcxp
 )

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)

find_runcv

Locate the CV corresponding to the currently executing sub or eval. If "db_seqp" is non_null, skip CVs that are in the DB package and populate *db_seqp with the cop sequence number at the point that the DB:: code was entered. (This allows debuggers to eval in the scope of the breakpoint rather than in the scope of the debugger itself.)

 CV* find_runcv(U32 *db_seqp)

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)

xsubpp variables and internal functions

ax

Variable which is setup by "xsubpp" to indicate the stack base offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros. The "dMARK" macro must be called prior to setup the "MARK" variable.

 I32 ax

CLASS

Variable which is setup by "xsubpp" to indicate the class name for a C++ XS constructor. This is always a "char*". See "THIS".

 char* CLASS

dAX

Sets up the "ax" variable. This is usually handled automatically by "xsubpp" by calling "dXSARGS".

 dAX;

dAXMARK

Sets up the "ax" variable and stack marker variable "mark". This is usually handled automatically by "xsubpp" by calling "dXSARGS".

 dAXMARK;

dITEMS

Sets up the "items" variable. This is usually handled automatically by "xsubpp" by calling "dXSARGS".

 dITEMS;

dUNDERBAR

Sets up any variable needed by the "UNDERBAR" macro. It used to define "padoff_du", but it is currently a noop. However, it is strongly advised to still use it for ensuring past and future compatibility.

 dUNDERBAR;

dXSARGS

Sets up stack and mark pointers for an XSUB, calling "dSP" and "dMARK". Sets up the "ax" and "items" variables by calling "dAX" and "dITEMS". This is usually handled automatically by "xsubpp".

 dXSARGS;

dXSI32

Sets up the "ix" variable for an XSUB which has aliases. This is usually handled automatically by "xsubpp".

 dXSI32;

items

Variable which is setup by "xsubpp" to indicate the number of items on the stack. See “Variable-length Parameter Lists” in perlxs.

 I32 items

ix

Variable which is setup by "xsubpp" to indicate which of an XSUB‘s aliases was used to invoke it. See “The ALIAS: Keyword” in perlxs.

 I32 ix

RETVAL

Variable which is setup by "xsubpp" to hold the return value for an XSUB. This is always the proper type for the XSUB. See “The RETVAL Variable” in perlxs.

 (whatever) RETVAL

ST

Used to access elements on the XSUB‘s stack.

 SV* ST(int ix)

THIS

Variable which is setup by "xsubpp" to designate the object in a C++ XSUB. This is always the proper type for the C++ object. See "CLASS" and “Using XS With C++” in perlxs.

 (whatever) THIS

UNDERBAR

The SV* corresponding to the $_ variable. Works even if there is a lexical $_ in scope.

XS

Macro to declare an XSUB and its C parameter list. This is handled by "xsubpp". It is the same as using the more explicit "XS_EXTERNAL" macro.

XS_EXTERNAL

Macro to declare an XSUB and its C parameter list explicitly exporting the symbols.

XS_INTERNAL

Macro to declare an XSUB and its C parameter list without exporting the symbols. This is handled by "xsubpp" and generally preferable over exporting the XSUB symbols unnecessarily.

Debugging Utilities

dump_all

Dumps the entire optree of the current program starting at "PL_main_root" to "STDERR". Also dumps the optrees for all visible subroutines in "PL_defstash".

 void dump_all()

dump_packsubs

Dumps the optrees for all visible subroutines in "stash".

 void dump_packsubs(const HV* stash)

op_class

Given an op, determine what type of struct it has been allocated as. Returns one of the OPclass enums, such as OPclass_LISTOP.

 OPclass op_class(const OP *o)

op_dump

Dumps the optree starting at OP "o" to "STDERR".

 void op_dump(const OP *o)

sv_dump

Dumps the contents of an SV to the "STDERR" filehandle.

For an example of its output, see Devel::Peek.

 void sv_dump(SV* sv)

Display and Dump functions

pv_display

Similar to

 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);

except that an additional “

perlapi (1) Linux Manual Page

Description

Array Manipulation Functions

Callback Functions

Character case changing

Character classification

Cloning an interpreter

Compile-time scope hooks

COP Hint Hashes

COP Hint Reading

Custom Operators

CV Manipulation Functions

xsubpp variables and internal functions

Debugging Utilities

Display and Dump functions

Leave a Reply Cancel reply