diff options
Diffstat (limited to 'pod/perlapi.pod')
| -rw-r--r-- | pod/perlapi.pod | 2225 |
1 files changed, 2225 insertions, 0 deletions
diff --git a/pod/perlapi.pod b/pod/perlapi.pod new file mode 100644 index 0000000000..897fcdc9da --- /dev/null +++ b/pod/perlapi.pod @@ -0,0 +1,2225 @@ +=head1 NAME + +perlapi - autogenerated documentation for the perl public API + +=head1 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 C<PL_> +prefix. Some macros are provided for compatibility with the older, +unadorned names, but this support may be disabled in a future release. + +The listing is alphabetical, case insensitive. + +=over 8 + +=item AvFILL + +Same as C<av_len()>. Deprecated, use C<av_len()> instead. + + int AvFILL(AV* av) + +=item av_clear + +Clears an array, making it empty. Does not free the memory used by the +array itself. + + void av_clear(AV* ar) + +=item av_extend + +Pre-extend an array. The C<key> is the index to which the array should be +extended. + + void av_extend(AV* ar, I32 key) + +=item av_fetch + +Returns the SV at the specified index in the array. The C<key> is the +index. If C<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 C<SV*>. + +See L<Understanding the Magic of Tied Hashes and Arrays> for more information +on how to use this function on tied arrays. + + SV** av_fetch(AV* ar, I32 key, I32 lval) + +=item av_len + +Returns the highest index in the array. Returns -1 if the array is +empty. + + I32 av_len(AV* ar) + +=item 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** svp) + +=item av_pop + +Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array +is empty. + + SV* av_pop(AV* ar) + +=item av_push + +Pushes an SV onto the end of the array. The array will grow automatically +to accommodate the addition. + + void av_push(AV* ar, SV* val) + +=item av_shift + +Shifts an SV off the beginning of the array. + + SV* av_shift(AV* ar) + +=item av_store + +Stores an SV in an array. The array index is specified as C<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 C<SV*>. Note +that the caller is responsible for suitably incrementing the reference +count of C<val> before the call, and decrementing it if the function +returned NULL. + +See L<Understanding the Magic of Tied Hashes and Arrays> for +more information on how to use this function on tied arrays. + + SV** av_store(AV* ar, I32 key, SV* val) + +=item av_undef + +Undefines the array. Frees the memory used by the array itself. + + void av_undef(AV* ar) + +=item av_unshift + +Unshift the given number of C<undef> values onto the beginning of the +array. The array will grow automatically to accommodate the addition. You +must then use C<av_store> to assign values to these new elements. + + void av_unshift(AV* ar, I32 num) + +=item call_argv + +Performs a callback to the specified Perl sub. See L<perlcall>. + +NOTE: the perl_ form of this function is deprecated. + + I32 call_argv(const char* sub_name, I32 flags, char** argv) + +=item call_method + +Performs a callback to the specified Perl method. The blessed object must +be on the stack. See L<perlcall>. + +NOTE: the perl_ form of this function is deprecated. + + I32 call_method(const char* methname, I32 flags) + +=item call_pv + +Performs a callback to the specified Perl sub. See L<perlcall>. + +NOTE: the perl_ form of this function is deprecated. + + I32 call_pv(const char* sub_name, I32 flags) + +=item call_sv + +Performs a callback to the Perl sub whose name is in the SV. See +L<perlcall>. + +NOTE: the perl_ form of this function is deprecated. + + I32 call_sv(SV* sv, I32 flags) + +=item CLASS + +Variable which is setup by C<xsubpp> to indicate the +class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>. + + char* CLASS + +=item Copy + +The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the +source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is +the type. May fail on overlapping copies. See also C<Move>. + + void Copy(void* src, void* dest, int nitems, type) + +=item croak + +This is the XSUB-writer's interface to Perl's C<die> function. Use this +function the same way you use the C C<printf> function. See +C<warn>. + + void croak(const char* pat, ...) + +=item CvSTASH + +Returns the stash of the CV. + + HV* CvSTASH(CV* cv) + +=item dMARK + +Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and +C<dORIGMARK>. + + dMARK; + +=item dORIGMARK + +Saves the original stack mark for the XSUB. See C<ORIGMARK>. + + dORIGMARK; + +=item dSP + +Declares a local copy of perl's stack pointer for the XSUB, available via +the C<SP> macro. See C<SP>. + + dSP; + +=item dXSARGS + +Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This +is usually handled automatically by C<xsubpp>. Declares the C<items> +variable to indicate the number of items on the stack. + + dXSARGS; + +=item dXSI32 + +Sets up the C<ix> variable for an XSUB which has aliases. This is usually +handled automatically by C<xsubpp>. + + dXSI32; + +=item ENTER + +Opening bracket on a callback. See C<LEAVE> and L<perlcall>. + + ENTER; + +=item eval_pv + +Tells Perl to C<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) + +=item eval_sv + +Tells Perl to C<eval> the string in the SV. + +NOTE: the perl_ form of this function is deprecated. + + I32 eval_sv(SV* sv, I32 flags) + +=item EXTEND + +Used to extend the argument stack for an XSUB's return values. Once +used, guarrantees that there is room for at least C<nitems> to be pushed +onto the stack. + + void EXTEND(SP, int nitems) + +=item fbm_compile + +Analyses the string in order to make fast searches on it using fbm_instr() +-- the Boyer-Moore algorithm. + + void fbm_compile(SV* sv, U32 flags) + +=item fbm_instr + +Returns the location of the SV in the string delimited by C<str> and +C<strend>. It returns C<Nullch> if the string can't be found. The C<sv> +does not have to be fbm_compiled, but the search will not be as fast +then. + + char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) + +=item FREETMPS + +Closing bracket for temporaries on a callback. See C<SAVETMPS> and +L<perlcall>. + + FREETMPS; + +=item get_av + +Returns the AV of the specified Perl array. If C<create> is set and the +Perl variable does not exist then it will be created. If C<create> is not +set 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 create) + +=item get_cv + +Returns the CV of the specified Perl subroutine. If C<create> is set and +the Perl subroutine does not exist then it will be declared (which has the +same effect as saying C<sub name;>). If C<create> is not set and the +subroutine does not exist then NULL is returned. + +NOTE: the perl_ form of this function is deprecated. + + CV* get_cv(const char* name, I32 create) + +=item get_hv + +Returns the HV of the specified Perl hash. If C<create> is set and the +Perl variable does not exist then it will be created. If C<create> is not +set and the variable does not exist then NULL is returned. + +NOTE: the perl_ form of this function is deprecated. + + HV* get_hv(const char* name, I32 create) + +=item get_sv + +Returns the SV of the specified Perl scalar. If C<create> is set and the +Perl variable does not exist then it will be created. If C<create> is not +set and the variable does not exist then NULL is returned. + +NOTE: the perl_ form of this function is deprecated. + + SV* get_sv(const char* name, I32 create) + +=item GIMME + +A backward-compatible version of C<GIMME_V> which can only return +C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>. +Deprecated. Use C<GIMME_V> instead. + + U32 GIMME + +=item GIMME_V + +The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>, +C<G_SCALAR> or C<G_ARRAY> for void, scalar or array context, +respectively. + + U32 GIMME_V + +=item GvSV + +Return the SV from the GV. + + SV* GvSV(GV* gv) + +=item gv_fetchmeth + +Returns the glob with the given C<name> and a defined subroutine or +C<NULL>. The glob lives in the given C<stash>, or in the stashes +accessible via @ISA and @UNIVERSAL. + +The argument C<level> should be either 0 or -1. If C<level==0>, as a +side-effect creates a glob with the given C<name> in the given C<stash> +which in the case of success contains an alias for the subroutine, and sets +up caching info for this glob. Similarly for all the searched stashes. + +This function grants C<"SUPER"> token as a postfix of the stash name. The +GV returned from C<gv_fetchmeth> may be a method cache entry, which is not +visible to Perl code. So when calling C<perl_call_sv>, you should not use +the GV directly; instead, you should use the method's CV, which can be +obtained from the GV with the C<GvCV> macro. + + GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level) + +=item gv_fetchmethod + +See L<gv_fetchmethod_autoload. + + GV* gv_fetchmethod(HV* stash, const char* name) + +=item gv_fetchmethod_autoload + +Returns the glob which contains the subroutine to call to invoke the method +on the C<stash>. In fact in the presence of autoloading this may be the +glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is +already setup. + +The third parameter of C<gv_fetchmethod_autoload> determines whether +AUTOLOAD lookup is performed if the given method is not present: non-zero +means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. +Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> +with a non-zero C<autoload> parameter. + +These functions grant C<"SUPER"> token as a prefix of the method name. Note +that if you want to keep the returned glob for a long time, you need to +check for it being "AUTOLOAD", since at the later time the call may load a +different subroutine due to $AUTOLOAD changing its value. Use the glob +created via a side effect to do this. + +These functions have the same side-effects and as C<gv_fetchmeth> with +C<level==0>. C<name> should be writable if contains C<':'> or C<' +''>. The warning against passing the GV returned by C<gv_fetchmeth> to +C<perl_call_sv> apply equally to these functions. + + GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload) + +=item gv_stashpv + +Returns a pointer to the stash for a specified package. If C<create> is +set then the package will be created if it does not already exist. If +C<create> is not set and the package does not exist then NULL is +returned. + + HV* gv_stashpv(const char* name, I32 create) + +=item gv_stashsv + +Returns a pointer to the stash for a specified package. See +C<gv_stashpv>. + + HV* gv_stashsv(SV* sv, I32 create) + +=item G_ARRAY + +Used to indicate array context. See C<GIMME_V>, C<GIMME> and +L<perlcall>. + +=item G_DISCARD + +Indicates that arguments returned from a callback should be discarded. See +L<perlcall>. + +=item G_EVAL + +Used to force a Perl C<eval> wrapper around a callback. See +L<perlcall>. + +=item G_NOARGS + +Indicates that no arguments are being sent to a callback. See +L<perlcall>. + +=item G_SCALAR + +Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and +L<perlcall>. + +=item G_VOID + +Used to indicate void context. See C<GIMME_V> and L<perlcall>. + +=item HEf_SVKEY + +This flag, used in the length slot of hash entries and magic structures, +specifies the structure contains a C<SV*> pointer where a C<char*> pointer +is to be expected. (For information only--not to be used). + +=item HeHASH + +Returns the computed hash stored in the hash entry. + + U32 HeHASH(HE* he) + +=item HeKEY + +Returns the actual pointer stored in the key slot of the hash entry. The +pointer may be either C<char*> or C<SV*>, depending on the value of +C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are +usually preferable for finding the value of a key. + + void* HeKEY(HE* he) + +=item HeKLEN + +If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry +holds an C<SV*> key. Otherwise, holds the actual length of the key. Can +be assigned to. The C<HePV()> macro is usually preferable for finding key +lengths. + + STRLEN HeKLEN(HE* he) + +=item HePV + +Returns the key slot of the hash entry as a C<char*> value, doing any +necessary dereferencing of possibly C<SV*> keys. The length of the string +is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do +not care about what the length of the key is, you may use the global +variable C<PL_na>, though this is rather less efficient than using a local +variable. Remember though, that hash keys in perl are free to contain +embedded nulls, so using C<strlen()> or similar is not a good way to find +the length of hash keys. This is very similar to the C<SvPV()> macro +described elsewhere in this document. + + char* HePV(HE* he, STRLEN len) + +=item HeSVKEY + +Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not +contain an C<SV*> key. + + SV* HeSVKEY(HE* he) + +=item HeSVKEY_force + +Returns the key as an C<SV*>. Will create and return a temporary mortal +C<SV*> if the hash entry contains only a C<char*> key. + + SV* HeSVKEY_force(HE* he) + +=item HeSVKEY_set + +Sets the key to a given C<SV*>, taking care to set the appropriate flags to +indicate the presence of an C<SV*> key, and returns the same +C<SV*>. + + SV* HeSVKEY_set(HE* he, SV* sv) + +=item HeVAL + +Returns the value slot (type C<SV*>) stored in the hash entry. + + SV* HeVAL(HE* he) + +=item HvNAME + +Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>. + + char* HvNAME(HV* stash) + +=item hv_clear + +Clears a hash, making it empty. + + void hv_clear(HV* tb) + +=item hv_delete + +Deletes a key/value pair in the hash. The value SV is removed from the +hash and returned to the caller. The C<klen> is the length of the key. +The C<flags> value will normally be zero; if set to G_DISCARD then NULL +will be returned. + + SV* hv_delete(HV* tb, const char* key, U32 klen, I32 flags) + +=item hv_delete_ent + +Deletes a key/value pair in the hash. The value SV is removed from the +hash and returned to the caller. The C<flags> value will normally be zero; +if set to G_DISCARD then NULL will be returned. C<hash> can be a valid +precomputed hash value, or 0 to ask for it to be computed. + + SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash) + +=item hv_exists + +Returns a boolean indicating whether the specified hash key exists. The +C<klen> is the length of the key. + + bool hv_exists(HV* tb, const char* key, U32 klen) + +=item hv_exists_ent + +Returns a boolean indicating whether the specified hash key exists. C<hash> +can be a valid precomputed hash value, or 0 to ask for it to be +computed. + + bool hv_exists_ent(HV* tb, SV* key, U32 hash) + +=item hv_fetch + +Returns the SV which corresponds to the specified key in the hash. The +C<klen> is the length of the key. If C<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 C<SV*>. + +See L<Understanding the Magic of Tied Hashes and Arrays> for more +information on how to use this function on tied hashes. + + SV** hv_fetch(HV* tb, const char* key, U32 klen, I32 lval) + +=item hv_fetch_ent + +Returns the hash entry which corresponds to the specified key in the hash. +C<hash> must be a valid precomputed hash number for the given C<key>, or 0 +if you want the function to compute it. IF C<lval> is set then the fetch +will be part of a store. Make sure the return value is non-null before +accessing it. The return value when C<tb> is a tied hash is a pointer to a +static location, so be sure to make a copy of the structure if you need to +store it somewhere. + +See L<Understanding the Magic of Tied Hashes and Arrays> for more +information on how to use this function on tied hashes. + + HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash) + +=item hv_iterinit + +Prepares a starting point to traverse a hash table. Returns the number of +keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is +currently only meaningful for hashes without tie magic. + +NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of +hash buckets that happen to be in use. If you still need that esoteric +value, you can get it through the macro C<HvFILL(tb)>. + + I32 hv_iterinit(HV* tb) + +=item hv_iterkey + +Returns the key from the current position of the hash iterator. See +C<hv_iterinit>. + + char* hv_iterkey(HE* entry, I32* retlen) + +=item hv_iterkeysv + +Returns the key as an C<SV*> from the current position of the hash +iterator. The return value will always be a mortal copy of the key. Also +see C<hv_iterinit>. + + SV* hv_iterkeysv(HE* entry) + +=item hv_iternext + +Returns entries from a hash iterator. See C<hv_iterinit>. + + HE* hv_iternext(HV* tb) + +=item hv_iternextsv + +Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one +operation. + + SV* hv_iternextsv(HV* hv, char** key, I32* retlen) + +=item hv_iterval + +Returns the value from the current position of the hash iterator. See +C<hv_iterkey>. + + SV* hv_iterval(HV* tb, HE* entry) + +=item hv_magic + +Adds magic to a hash. See C<sv_magic>. + + void hv_magic(HV* hv, GV* gv, int how) + +=item hv_store + +Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is +the length of the key. The C<hash> parameter is the precomputed hash +value; if it is zero then Perl will compute it. The return value will be +NULL if the operation failed or if the value did not need to be actually +stored within the hash (as in the case of tied hashes). Otherwise it can +be dereferenced to get the original C<SV*>. Note that the caller is +responsible for suitably incrementing the reference count of C<val> before +the call, and decrementing it if the function returned NULL. + +See L<Understanding the Magic of Tied Hashes and Arrays> for more +information on how to use this function on tied hashes. + + SV** hv_store(HV* tb, const char* key, U32 klen, SV* val, U32 hash) + +=item hv_store_ent + +Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash> +parameter is the precomputed hash value; if it is zero then Perl will +compute it. The return value is the new hash entry so created. It will be +NULL if the operation failed or if the value did not need to be actually +stored within the hash (as in the case of tied hashes). Otherwise the +contents of the return value can be accessed using the C<He???> macros +described here. Note that the caller is responsible for suitably +incrementing the reference count of C<val> before the call, and +decrementing it if the function returned NULL. + +See L<Understanding the Magic of Tied Hashes and Arrays> for more +information on how to use this function on tied hashes. + + HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash) + +=item hv_undef + +Undefines the hash. + + void hv_undef(HV* tb) + +=item isALNUM + +Returns a boolean indicating whether the C C<char> is an ascii alphanumeric +character or digit. + + bool isALNUM(char ch) + +=item isALPHA + +Returns a boolean indicating whether the C C<char> is an ascii alphabetic +character. + + bool isALPHA(char ch) + +=item isDIGIT + +Returns a boolean indicating whether the C C<char> is an ascii +digit. + + bool isDIGIT(char ch) + +=item isLOWER + +Returns a boolean indicating whether the C C<char> is a lowercase +character. + + bool isLOWER(char ch) + +=item isSPACE + +Returns a boolean indicating whether the C C<char> is whitespace. + + bool isSPACE(char ch) + +=item isUPPER + +Returns a boolean indicating whether the C C<char> is an uppercase +character. + + bool isUPPER(char ch) + +=item items + +Variable which is setup by C<xsubpp> to indicate the number of +items on the stack. See L<perlxs/"Variable-length Parameter Lists">. + + I32 items + +=item ix + +Variable which is setup by C<xsubpp> to indicate which of an +XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">. + + I32 ix + +=item LEAVE + +Closing bracket on a callback. See C<ENTER> and L<perlcall>. + + LEAVE; + +=item looks_like_number + +Test if an the content of an SV looks like a number (or is a +number). + + I32 looks_like_number(SV* sv) + +=item MARK + +Stack marker variable for the XSUB. See C<dMARK>. + +=item mg_clear + +Clear something magical that the SV represents. See C<sv_magic>. + + int mg_clear(SV* sv) + +=item mg_copy + +Copies the magic from one SV to another. See C<sv_magic>. + + int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen) + +=item mg_find + +Finds the magic pointer for type matching the SV. See C<sv_magic>. + + MAGIC* mg_find(SV* sv, int type) + +=item mg_free + +Free any magic storage used by the SV. See C<sv_magic>. + + int mg_free(SV* sv) + +=item mg_get + +Do magic after a value is retrieved from the SV. See C<sv_magic>. + + int mg_get(SV* sv) + +=item mg_length + +Report on the SV's length. See C<sv_magic>. + + U32 mg_length(SV* sv) + +=item mg_magical + +Turns on the magical status of an SV. See C<sv_magic>. + + void mg_magical(SV* sv) + +=item mg_set + +Do magic after a value is assigned to the SV. See C<sv_magic>. + + int mg_set(SV* sv) + +=item Move + +The XSUB-writer's interface to the C C<memmove> function. The C<src> is the +source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is +the type. Can do overlapping moves. See also C<Copy>. + + void Move(void* src, void* dest, int nitems, type) + +=item New + +The XSUB-writer's interface to the C C<malloc> function. + + void New(int id, void* ptr, int nitems, type) + +=item newAV + +Creates a new AV. The reference count is set to 1. + + AV* newAV() + +=item Newc + +The XSUB-writer's interface to the C C<malloc> function, with +cast. + + void Newc(int id, void* ptr, int nitems, type, cast) + +=item newCONSTSUB + +Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is +eligible for inlining at compile-time. + + void newCONSTSUB(HV* stash, char* name, SV* sv) + +=item newHV + +Creates a new HV. The reference count is set to 1. + + HV* newHV() + +=item newRV_inc + +Creates an RV wrapper for an SV. The reference count for the original SV is +incremented. + + SV* newRV_inc(SV* sv) + +=item newRV_noinc + +Creates an RV wrapper for an SV. The reference count for the original +SV is B<not> incremented. + + SV* newRV_noinc(SV *sv) + +=item NEWSV + +Creates a new SV. A non-zero C<len> parameter indicates the number of +bytes of preallocated string space the SV should have. An extra byte for a +tailing NUL is also reserved. (SvPOK is not set for the SV even if string +space is allocated.) The reference count for the new SV is set to 1. +C<id> is an integer id between 0 and 1299 (used to identify leaks). + + SV* NEWSV(int id, STRLEN len) + +=item newSViv + +Creates a new SV and copies an integer into it. The reference count for the +SV is set to 1. + + SV* newSViv(IV i) + +=item newSVnv + +Creates a new SV and copies a floating point value into it. +The reference count for the SV is set to 1. + + SV* newSVnv(NV n) + +=item newSVpv + +Creates a new SV and copies a string into it. The reference count for the +SV is set to 1. If C<len> is zero, Perl will compute the length using +strlen(). For efficiency, consider using C<newSVpvn> instead. + + SV* newSVpv(const char* s, STRLEN len) + +=item newSVpvf + +Creates a new SV an initialize it with the string formatted like +C<sprintf>. + + SV* newSVpvf(const char* pat, ...) + +=item newSVpvn + +Creates a new SV and copies a string into it. The reference count for the +SV is set to 1. Note that if C<len> is zero, Perl will create a zero length +string. You are responsible for ensuring that the source string is at least +C<len> bytes long. + + SV* newSVpvn(const char* s, STRLEN len) + +=item newSVrv + +Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then +it will be upgraded to one. If C<classname> is non-null then the new SV will +be blessed in the specified package. The new SV is returned and its +reference count is 1. + + SV* newSVrv(SV* rv, const char* classname) + +=item newSVsv + +Creates a new SV which is an exact duplicate of the original SV. + + SV* newSVsv(SV* old) + +=item newXS + +Used by C<xsubpp> to hook up XSUBs as Perl subs. + +=item newXSproto + +Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to +the subs. + +=item Newz + +The XSUB-writer's interface to the C C<malloc> function. The allocated +memory is zeroed with C<memzero>. + + void Newz(int id, void* ptr, int nitems, type) + +=item Nullav + +Null AV pointer. + +=item Nullch + +Null character pointer. + +=item Nullcv + +Null CV pointer. + +=item Nullhv + +Null HV pointer. + +=item Nullsv + +Null SV pointer. + +=item ORIGMARK + +The original stack mark for the XSUB. See C<dORIGMARK>. + +=item perl_alloc + +Allocates a new Perl interpreter. See L<perlembed>. + + PerlInterpreter* perl_alloc() + +=item perl_construct + +Initializes a new Perl interpreter. See L<perlembed>. + + void perl_construct(PerlInterpreter* interp) + +=item perl_destruct + +Shuts down a Perl interpreter. See L<perlembed>. + + void perl_destruct(PerlInterpreter* interp) + +=item perl_free + +Releases a Perl interpreter. See L<perlembed>. + + void perl_free(PerlInterpreter* interp) + +=item perl_parse + +Tells a Perl interpreter to parse a Perl script. See L<perlembed>. + + int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) + +=item perl_run + +Tells a Perl interpreter to run. See L<perlembed>. + + int perl_run(PerlInterpreter* interp) + +=item PL_DBsingle + +When Perl is run in debugging mode, with the B<-d> switch, this SV is a +boolean which indicates whether subs are being single-stepped. +Single-stepping is automatically turned on after every step. This is the C +variable which corresponds to Perl's $DB::single variable. See +C<PL_DBsub>. + + SV * PL_DBsingle + +=item PL_DBsub + +When Perl is run in debugging mode, with the B<-d> switch, this GV contains +the SV which holds the name of the sub being debugged. This is the C +variable which corresponds to Perl's $DB::sub variable. See +C<PL_DBsingle>. + + GV * PL_DBsub + +=item PL_DBtrace + +Trace variable used when Perl is run in debugging mode, with the B<-d> +switch. This is the C variable which corresponds to Perl's $DB::trace +variable. See C<PL_DBsingle>. + + SV * PL_DBtrace + +=item PL_dowarn + +The C variable which corresponds to Perl's $^W warning variable. + + bool PL_dowarn + +=item PL_modglobal + +C<PL_modglobal> is a general purpose, interpreter global HV for use by +extensions that need to keep information on a per-interpreter basis. +In a pinch, it can also be used as a symbol table for extensions +to share data among each other. It is a good idea to use keys +prefixed by the package name of the extension that owns the data. + + HV* PL_modglobal + +=item PL_na + +A convenience variable which is typically used with C<SvPV> when one +doesn't care about the length of the string. It is usually more efficient +to either declare a local variable and use that instead or to use the +C<SvPV_nolen> macro. + + STRLEN PL_na + +=item PL_sv_no + +This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as +C<&PL_sv_no>. + + SV PL_sv_no + +=item PL_sv_undef + +This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>. + + SV PL_sv_undef + +=item PL_sv_yes + +This is the C<true> SV. See C<PL_sv_no>. Always refer to this as +C<&PL_sv_yes>. + + SV PL_sv_yes + +=item POPi + +Pops an integer off the stack. + + IV POPi + +=item POPl + +Pops a long off the stack. + + long POPl + +=item POPn + +Pops a double off the stack. + + NV POPn + +=item POPp + +Pops a string off the stack. + + char* POPp + +=item POPs + +Pops an SV off the stack. + + SV* POPs + +=item PUSHi + +Push an integer onto the stack. The stack must have room for this element. +Handles 'set' magic. See C<XPUSHi>. + + void PUSHi(IV iv) + +=item PUSHMARK + +Opening bracket for arguments on a callback. See C<PUTBACK> and +L<perlcall>. + + PUSHMARK; + +=item PUSHn + +Push a double onto the stack. The stack must have room for this element. +Handles 'set' magic. See C<XPUSHn>. + + void PUSHn(NV nv) + +=item PUSHp + +Push a string onto the stack. The stack must have room for this element. +The C<len> indicates the length of the string. Handles 'set' magic. See +C<XPUSHp>. + + void PUSHp(char* str, STRLEN len) + +=item PUSHs + +Push an SV onto the stack. The stack must have room for this element. +Does not handle 'set' magic. See C<XPUSHs>. + + void PUSHs(SV* sv) + +=item PUSHu + +Push an unsigned integer onto the stack. The stack must have room for this +element. See C<XPUSHu>. + + void PUSHu(UV uv) + +=item PUTBACK + +Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>. +See C<PUSHMARK> and L<perlcall> for other uses. + + PUTBACK; + +=item Renew + +The XSUB-writer's interface to the C C<realloc> function. + + void Renew(void* ptr, int nitems, type) + +=item Renewc + +The XSUB-writer's interface to the C C<realloc> function, with +cast. + + void Renewc(void* ptr, int nitems, type, cast) + +=item require_pv + +Tells Perl to C<require> a module. + +NOTE: the perl_ form of this function is deprecated. + + void require_pv(const char* pv) + +=item RETVAL + +Variable which is setup by C<xsubpp> to hold the return value for an +XSUB. This is always the proper type for the XSUB. See +L<perlxs/"The RETVAL Variable">. + + (whatever) RETVAL + +=item Safefree + +The XSUB-writer's interface to the C C<free> function. + + void Safefree(void* src, void* dest, int nitems, type) + +=item savepv + +Copy a string to a safe spot. This does not use an SV. + + char* savepv(const char* sv) + +=item savepvn + +Copy a string to a safe spot. The C<len> indicates number of bytes to +copy. This does not use an SV. + + char* savepvn(const char* sv, I32 len) + +=item SAVETMPS + +Opening bracket for temporaries on a callback. See C<FREETMPS> and +L<perlcall>. + + SAVETMPS; + +=item SP + +Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and +C<SPAGAIN>. + +=item SPAGAIN + +Refetch the stack pointer. Used after a callback. See L<perlcall>. + + SPAGAIN; + +=item ST + +Used to access elements on the XSUB's stack. + + SV* ST(int ix) + +=item strEQ + +Test two strings to see if they are equal. Returns true or false. + + bool strEQ(char* s1, char* s2) + +=item strGE + +Test two strings to see if the first, C<s1>, is greater than or equal to +the second, C<s2>. Returns true or false. + + bool strGE(char* s1, char* s2) + +=item strGT + +Test two strings to see if the first, C<s1>, is greater than the second, +C<s2>. Returns true or false. + + bool strGT(char* s1, char* s2) + +=item strLE + +Test two strings to see if the first, C<s1>, is less than or equal to the +second, C<s2>. Returns true or false. + + bool strLE(char* s1, char* s2) + +=item strLT + +Test two strings to see if the first, C<s1>, is less than the second, +C<s2>. Returns true or false. + + bool strLT(char* s1, char* s2) + +=item strNE + +Test two strings to see if they are different. Returns true or +false. + + bool strNE(char* s1, char* s2) + +=item strnEQ + +Test two strings to see if they are equal. The C<len> parameter indicates +the number of bytes to compare. Returns true or false. (A wrapper for +C<strncmp>). + + bool strnEQ(char* s1, char* s2, STRLEN len) + +=item strnNE + +Test two strings to see if they are different. The C<len> parameter +indicates the number of bytes to compare. Returns true or false. (A +wrapper for C<strncmp>). + + bool strnNE(char* s1, char* s2, STRLEN len) + +=item StructCopy + +This is an architecture-independant macro to copy one structure to another. + + void StructCopy(type src, type dest, type) + +=item SvCUR + +Returns the length of the string which is in the SV. See C<SvLEN>. + + STRLEN SvCUR(SV* sv) + +=item SvCUR_set + +Set the length of the string which is in the SV. See C<SvCUR>. + + void SvCUR_set(SV* sv, STRLEN len) + +=item SvEND + +Returns a pointer to the last character in the string which is in the SV. +See C<SvCUR>. Access the character as *(SvEND(sv)). + + char* SvEND(SV* sv) + +=item SvGETMAGIC + +Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its +argument more than once. + + void SvGETMAGIC(SV* sv) + +=item SvGROW + +Expands the character buffer in the SV so that it has room for the +indicated number of bytes (remember to reserve space for an extra trailing +NUL character). Calls C<sv_grow> to perform the expansion if necessary. +Returns a pointer to the character buffer. + + void SvGROW(SV* sv, STRLEN len) + +=item SvIOK + +Returns a boolean indicating whether the SV contains an integer. + + bool SvIOK(SV* sv) + +=item SvIOKp + +Returns a boolean indicating whether the SV contains an integer. Checks +the B<private> setting. Use C<SvIOK>. + + bool SvIOKp(SV* sv) + +=item SvIOK_off + +Unsets the IV status of an SV. + + void SvIOK_off(SV* sv) + +=item SvIOK_on + +Tells an SV that it is an integer. + + void SvIOK_on(SV* sv) + +=item SvIOK_only + +Tells an SV that it is an integer and disables all other OK bits. + + void SvIOK_only(SV* sv) + +=item SvIV + +Coerces the given SV to an integer and returns it. + + IV SvIV(SV* sv) + +=item SvIVX + +Returns the integer which is stored in the SV, assuming SvIOK is +true. + + IV SvIVX(SV* sv) + +=item SvLEN + +Returns the size of the string buffer in the SV. See C<SvCUR>. + + STRLEN SvLEN(SV* sv) + +=item SvNIOK + +Returns a boolean indicating whether the SV contains a number, integer or +double. + + bool SvNIOK(SV* sv) + +=item SvNIOKp + +Returns a boolean indicating whether the SV contains a number, integer or +double. Checks the B<private> setting. Use C<SvNIOK>. + + bool SvNIOKp(SV* sv) + +=item SvNIOK_off + +Unsets the NV/IV status of an SV. + + void SvNIOK_off(SV* sv) + +=item SvNOK + +Returns a boolean indicating whether the SV contains a double. + + bool SvNOK(SV* sv) + +=item SvNOKp + +Returns a boolean indicating whether the SV contains a double. Checks the +B<private> setting. Use C<SvNOK>. + + bool SvNOKp(SV* sv) + +=item SvNOK_off + +Unsets the NV status of an SV. + + void SvNOK_off(SV* sv) + +=item SvNOK_on + +Tells an SV that it is a double. + + void SvNOK_on(SV* sv) + +=item SvNOK_only + +Tells an SV that it is a double and disables all other OK bits. + + void SvNOK_only(SV* sv) + +=item SvNV + +Coerce the given SV to a double and return it. + + NV SvNV(SV* sv) + +=item SvNVX + +Returns the double which is stored in the SV, assuming SvNOK is +true. + + NV SvNVX(SV* sv) + +=item SvOK + +Returns a boolean indicating whether the value is an SV. + + bool SvOK(SV* sv) + +=item SvOOK + +Returns a boolean indicating whether the SvIVX is a valid offset value for +the SvPVX. This hack is used internally to speed up removal of characters +from the beginning of a SvPV. When SvOOK is true, then the start of the +allocated string buffer is really (SvPVX - SvIVX). + + bool SvOOK(SV* sv) + +=item SvPOK + +Returns a boolean indicating whether the SV contains a character +string. + + bool SvPOK(SV* sv) + +=item SvPOKp + +Returns a boolean indicating whether the SV contains a character string. +Checks the B<private> setting. Use C<SvPOK>. + + bool SvPOKp(SV* sv) + +=item SvPOK_off + +Unsets the PV status of an SV. + + void SvPOK_off(SV* sv) + +=item SvPOK_on + +Tells an SV that it is a string. + + void SvPOK_on(SV* sv) + +=item SvPOK_only + +Tells an SV that it is a string and disables all other OK bits. + + void SvPOK_only(SV* sv) + +=item SvPV + +Returns a pointer to the string in the SV, or a stringified form of the SV +if the SV does not contain a string. Handles 'get' magic. + + char* SvPV(SV* sv, STRLEN len) + +=item SvPVX + +Returns a pointer to the string in the SV. The SV must contain a +string. + + char* SvPVX(SV* sv) + +=item SvPV_force + +Like <SvPV> but will force the SV into becoming a string (SvPOK). You want +force if you are going to update the SvPVX directly. + + char* SvPV_force(SV* sv, STRLEN len) + +=item SvPV_nolen + +Returns a pointer to the string in the SV, or a stringified form of the SV +if the SV does not contain a string. Handles 'get' magic. + + char* SvPV_nolen(SV* sv) + +=item SvREFCNT + +Returns the value of the object's reference count. + + U32 SvREFCNT(SV* sv) + +=item SvREFCNT_dec + +Decrements the reference count of the given SV. + + void SvREFCNT_dec(SV* sv) + +=item SvREFCNT_inc + +Increments the reference count of the given SV. + + SV* SvREFCNT_inc(SV* sv) + +=item SvROK + +Tests if the SV is an RV. + + bool SvROK(SV* sv) + +=item SvROK_off + +Unsets the RV status of an SV. + + void SvROK_off(SV* sv) + +=item SvROK_on + +Tells an SV that it is an RV. + + void SvROK_on(SV* sv) + +=item SvRV + +Dereferences an RV to return the SV. + + SV* SvRV(SV* sv) + +=item SvSETMAGIC + +Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its +argument more than once. + + void SvSETMAGIC(SV* sv) + +=item SvSetSV + +Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments +more than once. + + void SvSetSV(SV* dsb, SV* ssv) + +=item SvSetSV_nosteal + +Calls a non-destructive version of C<sv_setsv> if dsv is not the same as +ssv. May evaluate arguments more than once. + + void SvSetSV_nosteal(SV* dsv, SV* ssv) + +=item SvSTASH + +Returns the stash of the SV. + + HV* SvSTASH(SV* sv) + +=item SvTAINT + +Taints an SV if tainting is enabled + + void SvTAINT(SV* sv) + +=item SvTAINTED + +Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if +not. + + bool SvTAINTED(SV* sv) + +=item SvTAINTED_off + +Untaints an SV. Be I<very> careful with this routine, as it short-circuits +some of Perl's fundamental security features. XS module authors should not +use this function unless they fully understand all the implications of +unconditionally untainting the value. Untainting should be done in the +standard perl fashion, via a carefully crafted regexp, rather than directly +untainting variables. + + void SvTAINTED_off(SV* sv) + +=item SvTAINTED_on + +Marks an SV as tainted. + + void SvTAINTED_on(SV* sv) + +=item SvTRUE + +Returns a boolean indicating whether Perl would evaluate the SV as true or +false, defined or undefined. Does not handle 'get' magic. + + bool SvTRUE(SV* sv) + +=item SvTYPE + +Returns the type of the SV. See C<svtype>. + + svtype SvTYPE(SV* sv) + +=item svtype + +An enum of flags for Perl types. These are found in the file B<sv.h> +in the C<svtype> enum. Test these flags with the C<SvTYPE> macro. + +=item SVt_IV + +Integer type flag for scalars. See C<svtype>. + +=item SVt_NV + +Double type flag for scalars. See C<svtype>. + +=item SVt_PV + +Pointer type flag for scalars. See C<svtype>. + +=item SVt_PVAV + +Type flag for arrays. See C<svtype>. + +=item SVt_PVCV + +Type flag for code refs. See C<svtype>. + +=item SVt_PVHV + +Type flag for hashes. See C<svtype>. + +=item SVt_PVMG + +Type flag for blessed scalars. See C<svtype>. + +=item SvUPGRADE + +Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to +perform the upgrade if necessary. See C<svtype>. + + void SvUPGRADE(SV* sv, svtype type) + +=item SvUV + +Coerces the given SV to an unsigned integer and returns it. + + UV SvUV(SV* sv) + +=item SvUVX + +Returns the unsigned integer which is stored in the SV, assuming SvIOK is +true. + + UV SvUVX(SV* sv) + +=item sv_2mortal + +Marks an SV as mortal. The SV will be destroyed when the current context +ends. + + SV* sv_2mortal(SV* sv) + +=item sv_bless + +Blesses an SV into a specified package. The SV must be an RV. The package +must be designated by its stash (see C<gv_stashpv()>). The reference count +of the SV is unaffected. + + SV* sv_bless(SV* sv, HV* stash) + +=item sv_catpv + +Concatenates the string onto the end of the string which is in the SV. +Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>. + + void sv_catpv(SV* sv, const char* ptr) + +=item sv_catpvf + +Processes its arguments like C<sprintf> and appends the formatted output +to an SV. Handles 'get' magic, but not 'set' magic. C<SvSETMAGIC()> must +typically be called after calling this function to handle 'set' magic. + + void sv_catpvf(SV* sv, const char* pat, ...) + +=item sv_catpvf_mg + +Like C<sv_catpvf>, but also handles 'set' magic. + + void sv_catpvf_mg(SV *sv, const char* pat, ...) + +=item sv_catpvn + +Concatenates the string onto the end of the string which is in the SV. The +C<len> indicates number of bytes to copy. Handles 'get' magic, but not +'set' magic. See C<sv_catpvn_mg>. + + void sv_catpvn(SV* sv, const char* ptr, STRLEN len) + +=item sv_catpvn_mg + +Like C<sv_catpvn>, but also handles 'set' magic. + + void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len) + +=item sv_catpv_mg + +Like C<sv_catpv>, but also handles 'set' magic. + + void sv_catpv_mg(SV *sv, const char *ptr) + +=item sv_catsv + +Concatenates the string from SV C<ssv> onto the end of the string in SV +C<dsv>. Handles 'get' magic, but not 'set' magic. See C<sv_catsv_mg>. + + void sv_catsv(SV* dsv, SV* ssv) + +=item sv_catsv_mg + +Like C<sv_catsv>, but also handles 'set' magic. + + void sv_catsv_mg(SV *dstr, SV *sstr) + +=item sv_chop + +Efficient removal of characters from the beginning of the string buffer. +SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside +the string buffer. The C<ptr> becomes the first character of the adjusted +string. + + void sv_chop(SV* sv, char* ptr) + +=item sv_cmp + +Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the +string in C<sv1> is less than, equal to, or greater than the string in +C<sv2>. + + I32 sv_cmp(SV* sv1, SV* sv2) + +=item sv_dec + +Auto-decrement of the value in the SV. + + void sv_dec(SV* sv) + +=item sv_derived_from + +Returns a boolean indicating whether the SV is derived from the specified +class. This is the function that implements C<UNIVERSAL::isa>. It works +for class names as well as for objects. + + bool sv_derived_from(SV* sv, const char* name) + +=item sv_eq + +Returns a boolean indicating whether the strings in the two SVs are +identical. + + I32 sv_eq(SV* sv1, SV* sv2) + +=item sv_grow + +Expands the character buffer in the SV. This will use C<sv_unref> and will +upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer. +Use C<SvGROW>. + + char* sv_grow(SV* sv, STRLEN newlen) + +=item sv_inc + +Auto-increment of the value in the SV. + + void sv_inc(SV* sv) + +=item sv_insert + +Inserts a string at the specified offset/length within the SV. Similar to +the Perl substr() function. + + void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen) + +=item sv_isa + +Returns a boolean indicating whether the SV is blessed into the specified +class. This does not check for subtypes; use C<sv_derived_from> to verify +an inheritance relationship. + + int sv_isa(SV* sv, const char* name) + +=item sv_isobject + +Returns a boolean indicating whether the SV is an RV pointing to a blessed +object. If the SV is not an RV, or if the object is not blessed, then this +will return false. + + int sv_isobject(SV* sv) + +=item sv_len + +Returns the length of the string in the SV. See also C<SvCUR>. + + STRLEN sv_len(SV* sv) + +=item sv_magic + +Adds magic to an SV. + + void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) + +=item sv_mortalcopy + +Creates a new SV which is a copy of the original SV. The new SV is marked +as mortal. + + SV* sv_mortalcopy(SV* oldsv) + +=item sv_newmortal + +Creates a new SV which is mortal. The reference count of the SV is set to 1. + + SV* sv_newmortal() + +=item sv_setiv + +Copies an integer into the given SV. Does not handle 'set' magic. See +C<sv_setiv_mg>. + + void sv_setiv(SV* sv, IV num) + +=item sv_setiv_mg + +Like C<sv_setiv>, but also handles 'set' magic. + + void sv_setiv_mg(SV *sv, IV i) + +=item sv_setnv + +Copies a double into the given SV. Does not handle 'set' magic. See +C<sv_setnv_mg>. + + void sv_setnv(SV* sv, NV num) + +=item sv_setnv_mg + +Like C<sv_setnv>, but also handles 'set' magic. + + void sv_setnv_mg(SV *sv, NV num) + +=item sv_setpv + +Copies a string into an SV. The string must be null-terminated. Does not +handle 'set' magic. See C<sv_setpv_mg>. + + void sv_setpv(SV* sv, const char* ptr) + +=item sv_setpvf + +Processes its arguments like C<sprintf> and sets an SV to the formatted +output. Does not handle 'set' magic. See C<sv_setpvf_mg>. + + void sv_setpvf(SV* sv, const char* pat, ...) + +=item sv_setpvf_mg + +Like C<sv_setpvf>, but also handles 'set' magic. + + void sv_setpvf_mg(SV *sv, const char* pat, ...) + +=item sv_setpviv + +Copies an integer into the given SV, also updating its string value. +Does not handle 'set' magic. See C<sv_setpviv_mg>. + + void sv_setpviv(SV* sv, IV num) + +=item sv_setpviv_mg + +Like C<sv_setpviv>, but also handles 'set' magic. + + void sv_setpviv_mg(SV *sv, IV iv) + +=item sv_setpvn + +Copies a string into an SV. The C<len> parameter indicates the number of +bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>. + + void sv_setpvn(SV* sv, const char* ptr, STRLEN len) + +=item sv_setpvn_mg + +Like C<sv_setpvn>, but also handles 'set' magic. + + void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len) + +=item sv_setpv_mg + +Like C<sv_setpv>, but also handles 'set' magic. + + void sv_setpv_mg(SV *sv, const char *ptr) + +=item sv_setref_iv + +Copies an integer into a new SV, optionally blessing the SV. The C<rv> +argument will be upgraded to an RV. That RV will be modified to point to +the new SV. The C<classname> argument indicates the package for the +blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV +will be returned and will have a reference count of 1. + + SV* sv_setref_iv(SV* rv, const char* classname, IV iv) + +=item sv_setref_nv + +Copies a double into a new SV, optionally blessing the SV. The C<rv> +argument will be upgraded to an RV. That RV will be modified to point to +the new SV. The C<classname> argument indicates the package for the +blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV +will be returned and will have a reference count of 1. + + SV* sv_setref_nv(SV* rv, const char* classname, NV nv) + +=item sv_setref_pv + +Copies a pointer into a new SV, optionally blessing the SV. The C<rv> +argument will be upgraded to an RV. That RV will be modified to point to +the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed +into the SV. The C<classname> argument indicates the package for the +blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV +will be returned and will have a reference count of 1. + +Do not use with other Perl types such as HV, AV, SV, CV, because those +objects will become corrupted by the pointer copy process. + +Note that C<sv_setref_pvn> copies the string while this copies the pointer. + + SV* sv_setref_pv(SV* rv, const char* classname, void* pv) + +=item sv_setref_pvn + +Copies a string into a new SV, optionally blessing the SV. The length of the +string must be specified with C<n>. The C<rv> argument will be upgraded to +an RV. That RV will be modified to point to the new SV. The C<classname> +argument indicates the package for the blessing. Set C<classname> to +C<Nullch> to avoid the blessing. The new SV will be returned and will have +a reference count of 1. + +Note that C<sv_setref_pv> copies the pointer while this copies the string. + + SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n) + +=item sv_setsv + +Copies the contents of the source SV C<ssv> into the destination SV C<dsv>. +The source SV may be destroyed if it is mortal. Does not handle 'set' +magic. See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and +C<sv_setsv_mg>. + + void sv_setsv(SV* dsv, SV* ssv) + +=item sv_setsv_mg + +Like C<sv_setsv>, but also handles 'set' magic. + + void sv_setsv_mg(SV *dstr, SV *sstr) + +=item sv_setuv + +Copies an unsigned integer into the given SV. Does not handle 'set' magic. +See C<sv_setuv_mg>. + + void sv_setuv(SV* sv, UV num) + +=item sv_setuv_mg + +Like C<sv_setuv>, but also handles 'set' magic. + + void sv_setuv_mg(SV *sv, UV u) + +=item sv_unref + +Unsets the RV status of the SV, and decrements the reference count of +whatever was being referenced by the RV. This can almost be thought of +as a reversal of C<newSVrv>. See C<SvROK_off>. + + void sv_unref(SV* sv) + +=item sv_upgrade + +Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See +C<svtype>. + + bool sv_upgrade(SV* sv, U32 mt) + +=item sv_usepvn + +Tells an SV to use C<ptr> to find its string value. Normally the string is +stored inside the SV but sv_usepvn allows the SV to use an outside string. +The C<ptr> should point to memory that was allocated by C<malloc>. The +string length, C<len>, must be supplied. This function will realloc the +memory pointed to by C<ptr>, so that pointer should not be freed or used by +the programmer after giving it to sv_usepvn. Does not handle 'set' magic. +See C<sv_usepvn_mg>. + + void sv_usepvn(SV* sv, char* ptr, STRLEN len) + +=item sv_usepvn_mg + +Like C<sv_usepvn>, but also handles 'set' magic. + + void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) + +=item sv_vcatpvfn + +Processes its arguments like C<vsprintf> and appends the formatted output +to an SV. Uses an array of SVs if the C style variable argument list is +missing (NULL). When running with taint checks enabled, indicates via +C<maybe_tainted> if results are untrustworthy (often due to the use of +locales). + + void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) + +=item sv_vsetpvfn + +Works like C<vcatpvfn> but copies the text into the SV instead of +appending it. + + void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) + +=item THIS + +Variable which is setup by C<xsubpp> to designate the object in a C++ +XSUB. This is always the proper type for the C++ object. See C<CLASS> and +L<perlxs/"Using XS With C++">. + + (whatever) THIS + +=item toLOWER + +Converts the specified character to lowercase. + + char toLOWER(char ch) + +=item toUPPER + +Converts the specified character to uppercase. + + char toUPPER(char ch) + +=item warn + +This is the XSUB-writer's interface to Perl's C<warn> function. Use this +function the same way you use the C C<printf> function. See +C<croak>. + + void warn(const char* pat, ...) + +=item XPUSHi + +Push an integer onto the stack, extending the stack if necessary. Handles +'set' magic. See C<PUSHi>. + + void XPUSHi(IV iv) + +=item XPUSHn + +Push a double onto the stack, extending the stack if necessary. Handles +'set' magic. See C<PUSHn>. + + void XPUSHn(NV nv) + +=item XPUSHp + +Push a string onto the stack, extending the stack if necessary. The C<len> +indicates the length of the string. Handles 'set' magic. See +C<PUSHp>. + + void XPUSHp(char* str, STRLEN len) + +=item XPUSHs + +Push an SV onto the stack, extending the stack if necessary. Does not +handle 'set' magic. See C<PUSHs>. + + void XPUSHs(SV* sv) + +=item XPUSHu + +Push an unsigned integer onto the stack, extending the stack if necessary. +See C<PUSHu>. + + void XPUSHu(UV uv) + +=item XS + +Macro to declare an XSUB and its C parameter list. This is handled by +C<xsubpp>. + +=item XSRETURN + +Return from XSUB, indicating number of items on the stack. This is usually +handled by C<xsubpp>. + + void XSRETURN(int nitems) + +=item XSRETURN_EMPTY + +Return an empty list from an XSUB immediately. + + XSRETURN_EMPTY; + +=item XSRETURN_IV + +Return an integer from an XSUB immediately. Uses C<XST_mIV>. + + void XSRETURN_IV(IV iv) + +=item XSRETURN_NO + +Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>. + + XSRETURN_NO; + +=item XSRETURN_NV + +Return an double from an XSUB immediately. Uses C<XST_mNV>. + + void XSRETURN_NV(NV nv) + +=item XSRETURN_PV + +Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>. + + void XSRETURN_PV(char* str) + +=item XSRETURN_UNDEF + +Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>. + + XSRETURN_UNDEF; + +=item XSRETURN_YES + +Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>. + + XSRETURN_YES; + +=item XST_mIV + +Place an integer into the specified position C<pos> on the stack. The +value is stored in a new mortal SV. + + void XST_mIV(int pos, IV iv) + +=item XST_mNO + +Place C<&PL_sv_no> into the specified position C<pos> on the +stack. + + void XST_mNO(int pos) + +=item XST_mNV + +Place a double into the specified position C<pos> on the stack. The value +is stored in a new mortal SV. + + void XST_mNV(int pos, NV nv) + +=item XST_mPV + +Place a copy of a string into the specified position C<pos> on the stack. +The value is stored in a new mortal SV. + + void XST_mPV(int pos, char* str) + +=item XST_mUNDEF + +Place C<&PL_sv_undef> into the specified position C<pos> on the +stack. + + void XST_mUNDEF(int pos) + +=item XST_mYES + +Place C<&PL_sv_yes> into the specified position C<pos> on the +stack. + + void XST_mYES(int pos) + +=item XS_VERSION + +The version identifier for an XS module. This is usually +handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>. + +=item XS_VERSION_BOOTCHECK + +Macro to verify that a PM module's $VERSION variable matches the XS +module's C<XS_VERSION> variable. This is usually handled automatically by +C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">. + + XS_VERSION_BOOTCHECK; + +=item Zero + +The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the +destination, C<nitems> is the number of items, and C<type> is the type. + + void Zero(void* dest, int nitems, type) + +=back + +=head1 AUTHORS + +Until May 1997, this document was maintained by Jeff Okamoto +<okamoto@corp.hp.com>. It is now maintained as part of Perl itself. + +With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, +Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil +Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, +Stephen McCamant, and Gurusamy Sarathy. + +API Listing originally by Dean Roehrich <roehrich@cray.com>. + +Updated to be autogenerated from comments in the source by Benjamin Stuhl. + +=head1 SEE ALSO + +perlguts(1), perlxs(1), perlxstut(1), perlintern(1) + |