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. The interfaces of any functions that are not listed here are subject to change without
notice. For this reason, 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.
Also, on some EBCDIC machines, functions that are documented as operating on US-ASCII (or Basic Latin in Unicode terminology) may in fact
operate on all 256 characters in the EBCDIC range, not just the subset corresponding to US-ASCII.
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.
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_len()". Deprecated, use "av_len()" instead.
int AvFILL(AV* av)
av_clear
Clears an array, making it empty. Does not free the memory used by the array itself.
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. Returns the deleted element. If "flags" equals "G_DISCARD", the element is
freed and null is returned.
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.
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 set then the fetch will be part of a
store. 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.
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 Returns the highest index in the array. The number of elements in the array is "av_len(av) + 1". Returns -1 if the array is
empty.
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.
AV* av_make(I32 size, SV **strp)
av_pop Pops an SV off the end of the array. Returns &PL_sv_undef if the array is empty.
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. Like "av_store", this takes
ownership of one reference count.
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.
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 original "SV*". 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.
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_undef
Undefines the array. Frees the memory used by the array itself.
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.
void av_unshift(AV *av, I32 num)
get_av Returns the AV of the specified Perl array. "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.
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.
AV* newAV()
sortsv Sort an array. Here is an example:
sortsv(AvARRAY(av), av_len(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 Perl sub. See perlcall.
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.
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 classes
isALNUM Returns a boolean indicating whether the C "char" is a US-ASCII (Basic Latin) alphanumeric character (including underscore) or
digit.
bool isALNUM(char ch)
isALPHA Returns a boolean indicating whether the C "char" is a US-ASCII (Basic Latin) alphabetic character.
bool isALPHA(char ch)
isDIGIT Returns a boolean indicating whether the C "char" is a US-ASCII (Basic Latin) digit.
bool isDIGIT(char ch)
isLOWER Returns a boolean indicating whether the C "char" is a US-ASCII (Basic Latin) lowercase character.
bool isLOWER(char ch)
isSPACE Returns a boolean indicating whether the C "char" is a US-ASCII (Basic Latin) whitespace.
bool isSPACE(char ch)
isUPPER Returns a boolean indicating whether the C "char" is a US-ASCII (Basic Latin) uppercase character.
bool isUPPER(char ch)
toLOWER Converts the specified character to lowercase. Characters outside the US-ASCII (Basic Latin) range are viewed as not having any
case.
char toLOWER(char ch)
toUPPER Converts the specified character to uppercase. Characters outside the US-ASCII (Basic Latin) range are viewed as not having any
case.
char toUPPER(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)
CV Manipulation Functions
CvSTASH Returns the stash of the CV.
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_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)
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, 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.
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()
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 "