1N/Aperlapi - autogenerated documentation for the perl public API
1N/AThis file contains the documentation of the perl public API generated by
1N/Aembed.pl, specifically a listing of functions, macros, flags, and variables
1N/Athat may be used by extension writers. The interfaces of any functions that
1N/Aare not listed here are subject to change without notice. For this reason,
1N/Ablindly using functions listed in
proto.h is to be avoided when writing
1N/ANote that all Perl API global variables must be referenced with the C<PL_>
1N/Aprefix. Some macros are provided for compatibility with the older,
1N/Aunadorned names, but this support may be disabled in a future release.
1N/AThe listing is alphabetical, case insensitive.
1N/A=head1 "Gimme" Values
1N/AA backward-compatible version of C<GIMME_V> which can only return
1N/AC<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
1N/ADeprecated. Use C<GIMME_V> instead.
1N/AThe XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
1N/AC<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
1N/AUsed to indicate list context. See C<GIMME_V>, C<GIMME> and
1N/AIndicates that arguments returned from a callback should be discarded. See
1N/AUsed to force a Perl C<eval> wrapper around a callback. See
1N/AIndicates that no arguments are being sent to a callback. See
1N/AUsed to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
1N/AUsed to indicate void context. See C<GIMME_V> and L<perlcall>.
1N/A=head1 Array Manipulation Functions
1N/ASame as C<av_len()>. Deprecated, use C<av_len()> instead.
1N/AClears an array, making it empty. Does not free the memory used by the
1N/A void av_clear(AV* ar)
1N/ADeletes the element indexed by C<key> from the array. Returns the
1N/Adeleted element. C<flags> is currently ignored.
1N/A SV* av_delete(AV* ar, I32 key, I32 flags)
1N/AReturns true if the element indexed by C<key> has been initialized.
1N/AThis relies on the fact that uninitialized array elements are set to
1N/A bool av_exists(AV* ar, I32 key)
1N/APre-extend an array. The C<key> is the index to which the array should be
1N/A void av_extend(AV* ar, I32 key)
1N/AReturns the SV at the specified index in the array. The C<key> is the
1N/Aindex. If C<lval> is set then the fetch will be part of a store. Check
1N/Athat the return value is non-null before dereferencing it to a C<SV*>.
1N/ASee L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
1N/Amore information on how to use this function on tied arrays.
1N/A SV** av_fetch(AV* ar, I32 key, I32 lval)
1N/AEnsure than an array has a given number of elements, equivalent to
1N/APerl's C<$#array = $fill;>.
1N/A void av_fill(AV* ar, I32 fill)
1N/AReturns the highest index in the array. Returns -1 if the array is
1N/ACreates a new AV and populates it with a list of SVs. The SVs are copied
1N/Ainto the array, so they may be freed after the call to av_make. The new AV
1N/Awill have a reference count of 1.
1N/A AV* av_make(I32 size, SV** svp)
1N/APops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
1N/APushes an SV onto the end of the array. The array will grow automatically
1N/Ato accommodate the addition.
1N/A void av_push(AV* ar, SV* val)
1N/AShifts an SV off the beginning of the array.
1N/A SV* av_shift(AV* ar)
1N/AStores an SV in an array. The array index is specified as C<key>. The
1N/Areturn value will be NULL if the operation failed or if the value did not
1N/Aneed to be actually stored within the array (as in the case of tied
1N/Aarrays). Otherwise it can be dereferenced to get the original C<SV*>. Note
1N/Athat the caller is responsible for suitably incrementing the reference
1N/Acount of C<val> before the call, and decrementing it if the function
1N/ASee L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
1N/Amore information on how to use this function on tied arrays.
1N/A SV** av_store(AV* ar, I32 key, SV* val)
1N/AUndefines the array. Frees the memory used by the array itself.
1N/A void av_undef(AV* ar)
1N/AUnshift the given number of C<undef> values onto the beginning of the
1N/Aarray. The array will grow automatically to accommodate the addition. You
1N/Amust then use C<av_store> to assign values to these new elements.
1N/A void av_unshift(AV* ar, I32 num)
1N/AReturns the AV of the specified Perl array. If C<create> is set and the
1N/APerl variable does not exist then it will be created. If C<create> is not
1N/Aset and the variable does not exist then NULL is returned.
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A AV* get_av(const char* name, I32 create)
1N/ACreates a new AV. The reference count is set to 1.
1N/ASort an array. Here is an example:
1N/A sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
1N/A void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp)
1N/A=head1 Callback Functions
1N/APerforms a callback to the specified Perl sub. See L<perlcall>.
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A I32 call_argv(const char* sub_name, I32 flags, char** argv)
1N/APerforms a callback to the specified Perl method. The blessed object must
1N/Abe on the stack. See L<perlcall>.
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A I32 call_method(const char* methname, I32 flags)
1N/APerforms a callback to the specified Perl sub. See L<perlcall>.
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A I32 call_pv(const char* sub_name, I32 flags)
1N/APerforms a callback to the Perl sub whose name is in the SV. See
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A I32 call_sv(SV* sv, I32 flags)
1N/AOpening bracket on a callback. See C<LEAVE> and L<perlcall>.
1N/ATells Perl to C<eval> the given string and return an SV* result.
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A SV* eval_pv(const char* p, I32 croak_on_error)
1N/ATells Perl to C<eval> the string in the SV.
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A I32 eval_sv(SV* sv, I32 flags)
1N/AClosing bracket for temporaries on a callback. See C<SAVETMPS> and
1N/AClosing bracket on a callback. See C<ENTER> and L<perlcall>.
1N/AOpening bracket for temporaries on a callback. See C<FREETMPS> and
1N/A=head1 Character classes
1N/AReturns a boolean indicating whether the C C<char> is an ASCII alphanumeric
1N/Acharacter (including underscore) or digit.
1N/A bool isALNUM(char ch)
1N/AReturns a boolean indicating whether the C C<char> is an ASCII alphabetic
1N/A bool isALPHA(char ch)
1N/AReturns a boolean indicating whether the C C<char> is an ASCII
1N/A bool isDIGIT(char ch)
1N/AReturns a boolean indicating whether the C C<char> is a lowercase
1N/A bool isLOWER(char ch)
1N/AReturns a boolean indicating whether the C C<char> is whitespace.
1N/A bool isSPACE(char ch)
1N/AReturns a boolean indicating whether the C C<char> is an uppercase
1N/A bool isUPPER(char ch)
1N/AConverts the specified character to lowercase.
1N/A char toLOWER(char ch)
1N/AConverts the specified character to uppercase.
1N/A char toUPPER(char ch)
1N/A=head1 Cloning an interpreter
1N/ACreate and return a new interpreter by cloning the current one.
1N/Aperl_clone takes these flags as parameters:
1N/ACLONEf_COPY_STACKS - is used to, well, copy the stacks also,
1N/Awithout it we only clone the data and zero the stacks,
1N/Awith it we copy the stacks and the new perl interpreter is
1N/Aready to run at the exact same point as the previous one.
1N/AThe pseudo-fork code uses COPY_STACKS while the
1N/Athreads->new doesn't.
1N/ACLONEf_KEEP_PTR_TABLE
1N/Aperl_clone keeps a ptr_table with the pointer of the old
1N/Avariable as a key and the new variable as a value,
1N/Athis allows it to check if something has been cloned and not
1N/Aclone it again but rather just use the value and increase the
1N/Arefcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
1N/Athe ptr_table using the function
1N/AC<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>,
1N/Areason to keep it around is if you want to dup some of your own
1N/Avariable who are outside the graph perl scans, example of this
1N/AThis is a win32 thing, it is ignored on unix, it tells perls
1N/Awin32host code (which is c++) to clone itself, this is needed on
1N/Awin32 if you want to run two threads at the same time,
1N/Aif you just want to do some stuff in a separate perl interpreter
1N/Aand then throw it away and return to the original one,
1N/Ayou don't need to do anything.
1N/A PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
1N/A=head1 CV Manipulation Functions
1N/AReturns the stash of the CV.
1N/AReturns the CV of the specified Perl subroutine. If C<create> is set and
1N/Athe Perl subroutine does not exist then it will be declared (which has the
1N/Asame effect as saying C<sub name;>). If C<create> is not set and the
1N/Asubroutine does not exist then NULL is returned.
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A CV* get_cv(const char* name, I32 create)
1N/A=head1 Embedding Functions
1N/AClear out all the active components of a CV. This can happen either
1N/Aby an explicit C<undef &foo>, or by the reference count going to zero.
1N/AIn the former case, we keep the CvOUTSIDE pointer, so that any anonymous
1N/Achildren can still follow the full lexical scope chain.
1N/A void cv_undef(CV* cv)
1N/ALoads the module whose name is pointed to by the string part of name.
1N/ANote that the actual module name, not its filename, should be given.
1N/APERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
1N/A(or 0 for no flags). ver, if specified, provides version semantics
1N/Asimilar to C<use Foo::Bar VERSION>. The optional trailing SV*
1N/Aarguments can be used to specify arguments to the module's import()
1N/Amethod, similar to C<use Foo::Bar VERSION LIST>.
1N/A void load_module(U32 flags, SV* name, SV* ver, ...)
1N/AStub that provides thread hook for perl_destruct when there are
1N/AAllocates a new Perl interpreter. See L<perlembed>.
1N/A PerlInterpreter* perl_alloc()
1N/AInitializes a new Perl interpreter. See L<perlembed>.
1N/A void perl_construct(PerlInterpreter* interp)
1N/AShuts down a Perl interpreter. See L<perlembed>.
1N/A int perl_destruct(PerlInterpreter* interp)
1N/AReleases a Perl interpreter. See L<perlembed>.
1N/A void perl_free(PerlInterpreter* interp)
1N/ATells a Perl interpreter to parse a Perl script. See L<perlembed>.
1N/A int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
1N/ATells a Perl interpreter to run. See L<perlembed>.
1N/A int perl_run(PerlInterpreter* interp)
1N/ATells Perl to C<require> the file named by the string argument. It is
1N/Aanalogous to the Perl code C<eval "require '$file'">. It's even
1N/Aimplemented that way; consider using load_module instead.
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A void require_pv(const char* pv)
1N/AThe engine implementing pack() Perl function.
1N/A void packlist(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist)
1N/AThe engine implementing pack() Perl function. Note: parameters next_in_list and
1N/Aflags are not used. This call should not be used; use packlist instead.
1N/A void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
1N/AThe engine implementing unpack() Perl function. C<unpackstring> puts the
1N/Aextracted list items on the stack and returns the number of elements.
1N/AIssue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
1N/A I32 unpackstring(char *pat, char *patend, char *s, char *strend, U32 flags)
1N/AThe engine implementing unpack() Perl function. Note: parameters strbeg, new_s
1N/Aand ocnt are not used. This call should not be used, use unpackstring instead.
1N/A I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags)
1N/A=head1 Global Variables
1N/AC<PL_modglobal> is a general purpose, interpreter global HV for use by
1N/Aextensions that need to keep information on a per-interpreter basis.
1N/AIn a pinch, it can also be used as a symbol table for extensions
1N/Ato share data among each other. It is a good idea to use keys
1N/Aprefixed by the package name of the extension that owns the data.
1N/AA convenience variable which is typically used with C<SvPV> when one
1N/Adoesn't care about the length of the string. It is usually more efficient
1N/Ato either declare a local variable and use that instead or to use the
1N/AThis is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
1N/AThis is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
1N/AThis is the C<true> SV. See C<PL_sv_no>. Always refer to this as
1N/AReturn the SV from the GV.
1N/AReturns the glob with the given C<name> and a defined subroutine or
1N/AC<NULL>. The glob lives in the given C<stash>, or in the stashes
1N/Aaccessible via @ISA and UNIVERSAL::.
1N/AThe argument C<level> should be either 0 or -1. If C<level==0>, as a
1N/Aside-effect creates a glob with the given C<name> in the given C<stash>
1N/Awhich in the case of success contains an alias for the subroutine, and sets
1N/Aup caching info for this glob. Similarly for all the searched stashes.
1N/AThis function grants C<"SUPER"> token as a postfix of the stash name. The
1N/AGV returned from C<gv_fetchmeth> may be a method cache entry, which is not
1N/Avisible to Perl code. So when calling C<call_sv>, you should not use
1N/Athe GV directly; instead, you should use the method's CV, which can be
1N/Aobtained from the GV with the C<GvCV> macro.
1N/A GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
1N/ASee L<gv_fetchmethod_autoload>.
1N/A GV* gv_fetchmethod(HV* stash, const char* name)
1N/A=item gv_fetchmethod_autoload
1N/AReturns the glob which contains the subroutine to call to invoke the method
1N/Aon the C<stash>. In fact in the presence of autoloading this may be the
1N/Aglob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
1N/AThe third parameter of C<gv_fetchmethod_autoload> determines whether
1N/AAUTOLOAD lookup is performed if the given method is not present: non-zero
1N/Ameans yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
1N/ACalling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
1N/Awith a non-zero C<autoload> parameter.
1N/AThese functions grant C<"SUPER"> token as a prefix of the method name. Note
1N/Athat if you want to keep the returned glob for a long time, you need to
1N/Acheck for it being "AUTOLOAD", since at the later time the call may load a
1N/Adifferent subroutine due to $AUTOLOAD changing its value. Use the glob
1N/Acreated via a side effect to do this.
1N/AThese functions have the same side-effects and as C<gv_fetchmeth> with
1N/AC<level==0>. C<name> should be writable if contains C<':'> or C<'
1N/A''>. The warning against passing the GV returned by C<gv_fetchmeth> to
1N/AC<call_sv> apply equally to these functions.
1N/A GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
1N/A=item gv_fetchmeth_autoload
1N/ASame as gv_fetchmeth(), but looks for autoloaded subroutines too.
1N/AReturns a glob for the subroutine.
1N/AFor an autoloaded subroutine without a GV, will create a GV even
1N/Aif C<level < 0>. For an autoloaded subroutine without a stub, GvCV()
1N/Aof the result may be zero.
1N/A GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
1N/AReturns a pointer to the stash for a specified package. C<name> should
1N/Abe a valid UTF-8 string. If C<create> is set then the package will be
1N/Acreated if it does not already exist. If C<create> is not set and the
1N/Apackage does not exist then NULL is returned.
1N/A HV* gv_stashpv(const char* name, I32 create)
1N/AReturns a pointer to the stash for a specified package, which must be a
1N/Avalid UTF-8 string. See C<gv_stashpv>.
1N/A HV* gv_stashsv(SV* sv, I32 create)
1N/AThis flag, used in the length slot of hash entries and magic structures,
1N/Aspecifies the structure contains an C<SV*> pointer where a C<char*> pointer
1N/Ais to be expected. (For information only--not to be used).
1N/ANull character pointer.
1N/A=head1 Hash Manipulation Functions
1N/AReturns the HV of the specified Perl hash. If C<create> is set and the
1N/APerl variable does not exist then it will be created. If C<create> is not
1N/Aset and the variable does not exist then NULL is returned.
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A HV* get_hv(const char* name, I32 create)
1N/AReturns the computed hash stored in the hash entry.
1N/AReturns the actual pointer stored in the key slot of the hash entry. The
1N/Apointer may be either C<char*> or C<SV*>, depending on the value of
1N/AC<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
1N/Ausually preferable for finding the value of a key.
1N/AIf this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
1N/Aholds an C<SV*> key. Otherwise, holds the actual length of the key. Can
1N/Abe assigned to. The C<HePV()> macro is usually preferable for finding key
1N/A STRLEN HeKLEN(HE* he)
1N/AReturns the key slot of the hash entry as a C<char*> value, doing any
1N/Anecessary dereferencing of possibly C<SV*> keys. The length of the string
1N/Ais placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
1N/Anot care about what the length of the key is, you may use the global
1N/Avariable C<PL_na>, though this is rather less efficient than using a local
1N/Avariable. Remember though, that hash keys in perl are free to contain
1N/Aembedded nulls, so using C<strlen()> or similar is not a good way to find
1N/Athe length of hash keys. This is very similar to the C<SvPV()> macro
1N/Adescribed elsewhere in this document.
1N/A char* HePV(HE* he, STRLEN len)
1N/AReturns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
1N/Acontain an C<SV*> key.
1N/AReturns the key as an C<SV*>. Will create and return a temporary mortal
1N/AC<SV*> if the hash entry contains only a C<char*> key.
1N/A SV* HeSVKEY_force(HE* he)
1N/ASets the key to a given C<SV*>, taking care to set the appropriate flags to
1N/Aindicate the presence of an C<SV*> key, and returns the same
1N/A SV* HeSVKEY_set(HE* he, SV* sv)
1N/AReturns the value slot (type C<SV*>) stored in the hash entry.
1N/AReturns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
1N/A char* HvNAME(HV* stash)
1N/AClears a hash, making it empty.
1N/A void hv_clear(HV* tb)
1N/A=item hv_clear_placeholders
1N/AClears any placeholders from a hash. If a restricted hash has any of its keys
1N/Amarked as readonly and the key is subsequently deleted, the key is not actually
1N/Adeleted but is marked by assigning it a value of &PL_sv_placeholder. This tags
1N/Ait so it will be ignored by future operations such as iterating over the hash,
1N/Abut will still allow the hash to have a value reaasigned to the key at some
1N/Afuture point. This function clears any such placeholder keys from the hash.
1N/ASee Hash::Util::lock_keys() for an example of its use.
1N/A void hv_clear_placeholders(HV* hb)
1N/ADeletes a
key/value pair in the hash. The value SV is removed from the
1N/Ahash and returned to the caller. The C<klen> is the length of the key.
1N/AThe C<flags> value will normally be zero; if set to G_DISCARD then NULL
1N/A SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
1N/ADeletes a
key/value pair in the hash. The value SV is removed from the
1N/Ahash and returned to the caller. The C<flags> value will normally be zero;
1N/Aif set to G_DISCARD then NULL will be returned. C<hash> can be a valid
1N/Aprecomputed hash value, or 0 to ask for it to be computed.
1N/A SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
1N/AReturns a boolean indicating whether the specified hash key exists. The
1N/AC<klen> is the length of the key.
1N/A bool hv_exists(HV* tb, const char* key, I32 klen)
1N/AReturns a boolean indicating whether the specified hash key exists. C<hash>
1N/Acan be a valid precomputed hash value, or 0 to ask for it to be
1N/A bool hv_exists_ent(HV* tb, SV* key, U32 hash)
1N/AReturns the SV which corresponds to the specified key in the hash. The
1N/AC<klen> is the length of the key. If C<lval> is set then the fetch will be
1N/Apart of a store. Check that the return value is non-null before
1N/Adereferencing it to an C<SV*>.
1N/ASee L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1N/Ainformation on how to use this function on tied hashes.
1N/A SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
1N/AReturns the hash entry which corresponds to the specified key in the hash.
1N/AC<hash> must be a valid precomputed hash number for the given C<key>, or 0
1N/Aif you want the function to compute it. IF C<lval> is set then the fetch
1N/Awill be part of a store. Make sure the return value is non-null before
1N/Aaccessing it. The return value when C<tb> is a tied hash is a pointer to a
1N/Astatic location, so be sure to make a copy of the structure if you need to
1N/ASee L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1N/Ainformation on how to use this function on tied hashes.
1N/A HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
1N/APrepares a starting point to traverse a hash table. Returns the number of
1N/Akeys in the hash (
i.e. the same as C<HvKEYS(tb)>). The return value is
1N/Acurrently only meaningful for hashes without tie magic.
1N/ANOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1N/Ahash buckets that happen to be in use. If you still need that esoteric
1N/Avalue, you can get it through the macro C<HvFILL(tb)>.
1N/A I32 hv_iterinit(HV* tb)
1N/AReturns the key from the current position of the hash iterator. See
1N/A char* hv_iterkey(HE* entry, I32* retlen)
1N/AReturns the key as an C<SV*> from the current position of the hash
1N/Aiterator. The return value will always be a mortal copy of the key. Also
1N/A SV* hv_iterkeysv(HE* entry)
1N/AReturns entries from a hash iterator. See C<hv_iterinit>.
1N/AYou may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
1N/Aiterator currently points to, without losing your place or invalidating your
1N/Aiterator. Note that in this case the current entry is deleted from the hash
1N/Awith your iterator holding the last reference to it. Your iterator is flagged
1N/Ato free the entry on the next call to C<hv_iternext>, so you must not discard
1N/Ayour iterator immediately else the entry will leak - call C<hv_iternext> to
1N/Atrigger the resource deallocation.
1N/A HE* hv_iternext(HV* tb)
1N/APerforms an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1N/A SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
1N/A=item hv_iternext_flags
1N/AReturns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
1N/AThe C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
1N/Aset the placeholders keys (for restricted hashes) will be returned in addition
1N/Ato normal keys. By default placeholders are automatically skipped over.
1N/ACurrently a placeholder is implemented with a value that is
1N/AC<&Perl_sv_placeholder>. Note that the implementation of placeholders and
1N/Arestricted hashes may change, and the implementation currently is
1N/Ainsufficiently abstracted for any change to be tidy.
1N/ANOTE: this function is experimental and may change or be
1N/Aremoved without notice.
1N/A HE* hv_iternext_flags(HV* tb, I32 flags)
1N/AReturns the value from the current position of the hash iterator. See
1N/A SV* hv_iterval(HV* tb, HE* entry)
1N/AAdds magic to a hash. See C<sv_magic>.
1N/A void hv_magic(HV* hv, GV* gv, int how)
1N/AEvaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
1N/A SV* hv_scalar(HV* hv)
1N/AStores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1N/Athe length of the key. The C<hash> parameter is the precomputed hash
1N/Avalue; if it is zero then Perl will compute it. The return value will be
1N/ANULL if the operation failed or if the value did not need to be actually
1N/Astored within the hash (as in the case of tied hashes). Otherwise it can
1N/Abe dereferenced to get the original C<SV*>. Note that the caller is
1N/Aresponsible for suitably incrementing the reference count of C<val> before
1N/Athe call, and decrementing it if the function returned NULL. Effectively
1N/Aa successful hv_store takes ownership of one reference to C<val>. This is
1N/Ausually what you want; a newly created SV has a reference count of one, so
1N/Aif all your code does is create SVs then store them in a hash, hv_store
1N/Awill own the only reference to the new SV, and your code doesn't need to do
1N/Aanything further to tidy up. hv_store is not implemented as a call to
1N/Ahv_store_ent, and does not create a temporary SV for the key, so if your
1N/Akey data is not already in SV form then use hv_store in preference to
1N/ASee L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1N/Ainformation on how to use this function on tied hashes.
1N/A SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
1N/AStores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
1N/Aparameter is the precomputed hash value; if it is zero then Perl will
1N/Acompute it. The return value is the new hash entry so created. It will be
1N/ANULL if the operation failed or if the value did not need to be actually
1N/Astored within the hash (as in the case of tied hashes). Otherwise the
1N/Acontents of the return value can be accessed using the C<He?> macros
1N/Adescribed here. Note that the caller is responsible for suitably
1N/Aincrementing the reference count of C<val> before the call, and
1N/Adecrementing it if the function returned NULL. Effectively a successful
1N/Ahv_store_ent takes ownership of one reference to C<val>. This is
1N/Ausually what you want; a newly created SV has a reference count of one, so
1N/Aif all your code does is create SVs then store them in a hash, hv_store
1N/Awill own the only reference to the new SV, and your code doesn't need to do
1N/Aanything further to tidy up. Note that hv_store_ent only reads the C<key>;
1N/Aunlike C<val> it does not take ownership of it, so maintaining the correct
1N/Areference count on C<key> is entirely the caller's responsibility. hv_store
1N/Ais not implemented as a call to hv_store_ent, and does not create a temporary
1N/ASV for the key, so if your key data is not already in SV form then use
1N/Ahv_store in preference to hv_store_ent.
1N/ASee L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1N/Ainformation on how to use this function on tied hashes.
1N/A HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
1N/A void hv_undef(HV* tb)
1N/ACreates a new HV. The reference count is set to 1.
1N/A=head1 Magical Functions
1N/AClear something magical that the SV represents. See C<sv_magic>.
1N/A int mg_clear(SV* sv)
1N/ACopies the magic from one SV to another. See C<sv_magic>.
1N/A int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
1N/AFinds the magic pointer for type matching the SV. See C<sv_magic>.
1N/A MAGIC* mg_find(SV* sv, int type)
1N/AFree any magic storage used by the SV. See C<sv_magic>.
1N/ADo magic after a value is retrieved from the SV. See C<sv_magic>.
1N/AReport on the SV's length. See C<sv_magic>.
1N/A U32 mg_length(SV* sv)
1N/ATurns on the magical status of an SV. See C<sv_magic>.
1N/A void mg_magical(SV* sv)
1N/ADo magic after a value is assigned to the SV. See C<sv_magic>.
1N/AInvokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
1N/Aargument more than once.
1N/A void SvGETMAGIC(SV* sv)
1N/AArranges for a mutual exclusion lock to be obtained on sv if a suitable module
1N/AInvokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
1N/Aargument more than once.
1N/A void SvSETMAGIC(SV* sv)
1N/ALike C<SvSetSV>, but does any set magic required afterwards.
1N/A void SvSetMagicSV(SV* dsb, SV* ssv)
1N/A=item SvSetMagicSV_nosteal
1N/ALike C<SvSetMagicSV>, but does any set magic required afterwards.
1N/A void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
1N/ACalls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
1N/A void SvSetSV(SV* dsb, SV* ssv)
1N/A=item SvSetSV_nosteal
1N/ACalls a non-destructive version of C<sv_setsv> if dsv is not the same as
1N/Assv. May evaluate arguments more than once.
1N/A void SvSetSV_nosteal(SV* dsv, SV* ssv)
1N/AArranges for sv to be shared between threads if a suitable module
1N/A void SvSHARE(SV* sv)
1N/A=head1 Memory Management
1N/AThe XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
1N/Asource, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1N/Athe type. May fail on overlapping copies. See also C<Move>.
1N/A void Copy(void* src, void* dest, int nitems, type)
1N/AThe XSUB-writer's interface to the C C<memmove> function. The C<src> is the
1N/Asource, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1N/Athe type. Can do overlapping moves. See also C<Copy>.
1N/A void Move(void* src, void* dest, int nitems, type)
1N/AThe XSUB-writer's interface to the C C<malloc> function.
1N/A void New(int id, void* ptr, int nitems, type)
1N/AThe XSUB-writer's interface to the C C<malloc> function, with
1N/A void Newc(int id, void* ptr, int nitems, type, cast)
1N/ACreates a new SV. A non-zero C<len> parameter indicates the number of
1N/Abytes of preallocated string space the SV should have. An extra byte for a
1N/Atailing NUL is also reserved. (SvPOK is not set for the SV even if string
1N/Aspace is allocated.) The reference count for the new SV is set to 1.
1N/AC<id> is an integer id between 0 and 1299 (used to identify leaks).
1N/A SV* NEWSV(int id, STRLEN len)
1N/AThe XSUB-writer's interface to the C C<malloc> function. The allocated
1N/Amemory is zeroed with C<memzero>.
1N/A void Newz(int id, void* ptr, int nitems, type)
1N/AFill up memory with a pattern (byte 0xAB over and over again) that
1N/Ahopefully catches attempts to access uninitialized memory.
1N/A void Poison(void* dest, int nitems, type)
1N/AThe XSUB-writer's interface to the C C<realloc> function.
1N/A void Renew(void* ptr, int nitems, type)
1N/AThe XSUB-writer's interface to the C C<realloc> function, with
1N/A void Renewc(void* ptr, int nitems, type, cast)
1N/AThe XSUB-writer's interface to the C C<free> function.
1N/A void Safefree(void* ptr)
1N/APerl's version of C<strdup()>. Returns a pointer to a newly allocated
1N/Astring which is a duplicate of C<pv>. The size of the string is
1N/Adetermined by C<strlen()>. The memory allocated for the new string can
1N/Abe freed with the C<Safefree()> function.
1N/A char* savepv(const char* pv)
1N/APerl's version of what C<strndup()> would be if it existed. Returns a
1N/Apointer to a newly allocated string which is a duplicate of the first
1N/AC<len> bytes from C<pv>. The memory allocated for the new string can be
1N/Afreed with the C<Safefree()> function.
1N/A char* savepvn(const char* pv, I32 len)
1N/AA version of C<savepv()> which allocates the duplicate string in memory
1N/Awhich is shared between threads.
1N/A char* savesharedpv(const char* pv)
1N/AThis is an architecture-independent macro to copy one structure to another.
1N/A void StructCopy(type src, type dest, type)
1N/AThe XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
1N/Adestination, C<nitems> is the number of items, and C<type> is the type.
1N/A void Zero(void* dest, int nitems, type)
1N/A=head1 Miscellaneous Functions
1N/AAnalyses the string in order to make fast searches on it using fbm_instr()
1N/A-- the Boyer-Moore algorithm.
1N/A void fbm_compile(SV* sv, U32 flags)
1N/AReturns the location of the SV in the string delimited by C<str> and
1N/AC<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
1N/Adoes not have to be fbm_compiled, but the search will not be as fast
1N/A char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
1N/ATakes a sprintf-style format pattern and conventional
1N/A(non-SV) arguments and returns the formatted string.
1N/A (char *) Perl_form(pTHX_ const char* pat, ...)
1N/Acan be used any place a string (char *) is required:
1N/A char * s = Perl_form("%d.%d",major,minor);
1N/AUses a single private buffer so if you want to format several strings you
1N/Amust explicitly copy the earlier strings away (and free the copies when you
1N/A char* form(const char* pat, ...)
1N/AFill the sv with current working directory
1N/A int getcwd_sv(SV* sv)
1N/ATest two strings to see if they are equal. Returns true or false.
1N/A bool strEQ(char* s1, char* s2)
1N/ATest two strings to see if the first, C<s1>, is greater than or equal to
1N/Athe second, C<s2>. Returns true or false.
1N/A bool strGE(char* s1, char* s2)
1N/ATest two strings to see if the first, C<s1>, is greater than the second,
1N/AC<s2>. Returns true or false.
1N/A bool strGT(char* s1, char* s2)
1N/ATest two strings to see if the first, C<s1>, is less than or equal to the
1N/Asecond, C<s2>. Returns true or false.
1N/A bool strLE(char* s1, char* s2)
1N/ATest two strings to see if the first, C<s1>, is less than the second,
1N/AC<s2>. Returns true or false.
1N/A bool strLT(char* s1, char* s2)
1N/ATest two strings to see if they are different. Returns true or
1N/A bool strNE(char* s1, char* s2)
1N/ATest two strings to see if they are equal. The C<len> parameter indicates
1N/Athe number of bytes to compare. Returns true or false. (A wrapper for
1N/A bool strnEQ(char* s1, char* s2, STRLEN len)
1N/ATest two strings to see if they are different. The C<len> parameter
1N/Aindicates the number of bytes to compare. Returns true or false. (A
1N/Awrapper for C<strncmp>).
1N/A bool strnNE(char* s1, char* s2, STRLEN len)
1N/ADummy routine which "locks" an SV when there is no locking module present.
1N/AExists to avoid test for a NULL function pointer and because it could potentially warn under
1N/Asome level of strict-ness.
1N/A void sv_nolocking(SV *)
1N/ADummy routine which "shares" an SV when there is no sharing module present.
1N/AExists to avoid test for a NULL function pointer and because it could potentially warn under
1N/Asome level of strict-ness.
1N/A void sv_nosharing(SV *)
1N/ADummy routine which "unlocks" an SV when there is no locking module present.
1N/AExists to avoid test for a NULL function pointer and because it could potentially warn under
1N/Asome level of strict-ness.
1N/A void sv_nounlocking(SV *)
1N/A=head1 Numeric functions
1N/Aconverts a string representing a binary number to numeric form.
1N/AOn entry I<start> and I<*len> give the string to scan, I<*flags> gives
1N/Aconversion flags, and I<result> should be NULL or a pointer to an NV.
1N/AThe scan stops at the end of the string, or the first invalid character.
1N/AOn return I<*len> is set to the length scanned string, and I<*flags> gives
1N/AIf the value is <= UV_MAX it is returned as a UV, the output flags are clear,
1N/Aand nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
1N/Areturns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
1N/Aand writes the value to I<*result> (or the value is discarded if I<result>
1N/AThe hex number may optionally be prefixed with "0b" or "b" unless
1N/AC<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
1N/AC<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
1N/Anumber may use '_' characters to separate digits.
1N/A UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
1N/Aconverts a string representing a hex number to numeric form.
1N/AOn entry I<start> and I<*len> give the string to scan, I<*flags> gives
1N/Aconversion flags, and I<result> should be NULL or a pointer to an NV.
1N/AThe scan stops at the end of the string, or the first non-hex-digit character.
1N/AOn return I<*len> is set to the length scanned string, and I<*flags> gives
1N/AIf the value is <= UV_MAX it is returned as a UV, the output flags are clear,
1N/Aand nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
1N/Areturns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
1N/Aand writes the value to I<*result> (or the value is discarded if I<result>
1N/AThe hex number may optionally be prefixed with "0x" or "x" unless
1N/AC<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
1N/AC<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
1N/Anumber may use '_' characters to separate digits.
1N/A UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
1N/ARecognise (or not) a number. The type of the number is returned
1N/A(0 if unrecognised), otherwise it is a bit-ORed combination of
1N/AIS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
1N/AIS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in
perl.h).
1N/AIf the value of the number can fit an in UV, it is returned in the *valuep
1N/AIS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
1N/Awill never be set unless *valuep is valid, but *valuep may have been assigned
1N/Ato during processing even though IS_NUMBER_IN_UV is not set on return.
1N/AIf valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
1N/Avaluep is non-NULL, but no actual assignment (or SEGV) will occur.
1N/AIS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
1N/Aseen (in which case *valuep gives the true value truncated to an integer), and
1N/AIS_NUMBER_NEG if the number is negative (in which case *valuep holds the
1N/Aabsolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
1N/Anumber is larger than a UV.
1N/A int grok_number(const char *pv, STRLEN len, UV *valuep)
1N/A=item grok_numeric_radix
1N/AScan and skip for a numeric decimal separator (radix).
1N/A bool grok_numeric_radix(const char **sp, const char *send)
1N/A UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
1N/AFor backwards compatibility. Use C<grok_bin> instead.
1N/A NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
1N/AFor backwards compatibility. Use C<grok_hex> instead.
1N/A NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
1N/AFor backwards compatibility. Use C<grok_oct> instead.
1N/A NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
1N/A=head1 Optree Manipulation Functions
1N/AIf C<cv> is a constant sub eligible for inlining. returns the constant
1N/Avalue returned by the sub. Otherwise, returns NULL.
1N/AConstant subs can be created with C<newCONSTSUB> or as described in
1N/AL<perlsub/"Constant Functions">.
1N/A SV* cv_const_sv(CV* cv)
1N/ACreates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
1N/Aeligible for inlining at compile-time.
1N/A CV* newCONSTSUB(HV* stash, char* name, SV* sv)
1N/AUsed by C<xsubpp> to hook up XSUBs as Perl subs.
1N/A=head1 Pad Data Structures
1N/AGet the value at offset po in the current pad.
1N/AUse macro PAD_SV instead of calling this function directly.
1N/A SV* pad_sv(PADOFFSET po)
1N/A=head1 Stack Manipulation Macros
1N/ADeclare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
1N/ASaves the original stack mark for the XSUB. See C<ORIGMARK>.
1N/ADeclares a local copy of perl's stack pointer for the XSUB, available via
1N/Athe C<SP> macro. See C<SP>.
1N/AUsed to extend the argument stack for an XSUB's return values. Once
1N/Aused, guarantees that there is room for at least C<nitems> to be pushed
1N/A void EXTEND(SP, int nitems)
1N/AStack marker variable for the XSUB. See C<dMARK>.
1N/AThe original stack mark for the XSUB. See C<dORIGMARK>.
1N/APops an integer off the stack.
1N/APops a long off the stack.
1N/APops a double off the stack.
1N/APops a string off the stack. Deprecated. New code should provide
1N/Aa STRLEN n_a and use POPpx.
1N/APops a string off the stack which must consist of bytes
i.e. characters < 256.
1N/ARequires a variable STRLEN n_a in scope.
1N/APops a string off the stack.
1N/ARequires a variable STRLEN n_a in scope.
1N/APops an SV off the stack.
1N/APush an integer onto the stack. The stack must have room for this element.
1N/AHandles 'set' magic. See C<XPUSHi>.
1N/AOpening bracket for arguments on a callback. See C<PUTBACK> and
1N/APush a double onto the stack. The stack must have room for this element.
1N/AHandles 'set' magic. See C<XPUSHn>.
1N/APush a string onto the stack. The stack must have room for this element.
1N/AThe C<len> indicates the length of the string. Handles 'set' magic. See
1N/A void PUSHp(char* str, STRLEN len)
1N/APush an SV onto the stack. The stack must have room for this element.
1N/ADoes not handle 'set' magic. See C<XPUSHs>.
1N/APush an unsigned integer onto the stack. The stack must have room for this
1N/Aelement. See C<XPUSHu>.
1N/AClosing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1N/ASee C<PUSHMARK> and L<perlcall> for other uses.
1N/AStack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
1N/ARefetch the stack pointer. Used after a callback. See L<perlcall>.
1N/APush an integer onto the stack, extending the stack if necessary. Handles
1N/A'set' magic. See C<PUSHi>.
1N/APush a double onto the stack, extending the stack if necessary. Handles
1N/A'set' magic. See C<PUSHn>.
1N/APush a string onto the stack, extending the stack if necessary. The C<len>
1N/Aindicates the length of the string. Handles 'set' magic. See
1N/A void XPUSHp(char* str, STRLEN len)
1N/APush an SV onto the stack, extending the stack if necessary. Does not
1N/Ahandle 'set' magic. See C<PUSHs>.
1N/APush an unsigned integer onto the stack, extending the stack if necessary.
1N/AReturn from XSUB, indicating number of items on the stack. This is usually
1N/Ahandled by C<xsubpp>.
1N/A void XSRETURN(int nitems)
1N/AReturn an integer from an XSUB immediately. Uses C<XST_mIV>.
1N/A void XSRETURN_IV(IV iv)
1N/AReturn C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
1N/AReturn a double from an XSUB immediately. Uses C<XST_mNV>.
1N/A void XSRETURN_NV(NV nv)
1N/AReturn a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
1N/A void XSRETURN_PV(char* str)
1N/AReturn C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
1N/AReturn an integer from an XSUB immediately. Uses C<XST_mUV>.
1N/A void XSRETURN_UV(IV uv)
1N/AReturn C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
1N/APlace an integer into the specified position C<pos> on the stack. The
1N/Avalue is stored in a new mortal SV.
1N/A void XST_mIV(int pos, IV iv)
1N/APlace C<&PL_sv_no> into the specified position C<pos> on the
1N/A void XST_mNO(int pos)
1N/APlace a double into the specified position C<pos> on the stack. The value
1N/Ais stored in a new mortal SV.
1N/A void XST_mNV(int pos, NV nv)
1N/APlace a copy of a string into the specified position C<pos> on the stack.
1N/AThe value is stored in a new mortal SV.
1N/A void XST_mPV(int pos, char* str)
1N/APlace C<&PL_sv_undef> into the specified position C<pos> on the
1N/A void XST_mUNDEF(int pos)
1N/APlace C<&PL_sv_yes> into the specified position C<pos> on the
1N/A void XST_mYES(int pos)
1N/AAn enum of flags for Perl types. These are found in the file B<
sv.h>
1N/Ain the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
1N/AInteger type flag for scalars. See C<svtype>.
1N/ADouble type flag for scalars. See C<svtype>.
1N/APointer type flag for scalars. See C<svtype>.
1N/AType flag for arrays. See C<svtype>.
1N/AType flag for code refs. See C<svtype>.
1N/AType flag for hashes. See C<svtype>.
1N/AType flag for blessed scalars. See C<svtype>.
1N/A=head1 SV Manipulation Functions
1N/AReturns the SV of the specified Perl scalar. If C<create> is set and the
1N/APerl variable does not exist then it will be created. If C<create> is not
1N/Aset and the variable does not exist then NULL is returned.
1N/ANOTE: the perl_ form of this function is deprecated.
1N/A SV* get_sv(const char* name, I32 create)
1N/A=item looks_like_number
1N/ATest if the content of an SV looks like a number (or is a number).
1N/AC<Inf> and C<Infinity> are treated as numbers (so will not issue a
1N/Anon-numeric warning), even if your atof() doesn't grok them.
1N/A I32 looks_like_number(SV* sv)
1N/ACreates an RV wrapper for an SV. The reference count for the original SV is
1N/A SV* newRV_inc(SV* sv)
1N/ACreates an RV wrapper for an SV. The reference count for the original
1N/ASV is B<not> incremented.
1N/A SV* newRV_noinc(SV *sv)
1N/ACreate a new null SV, or if len > 0, create a new empty SVt_PV type SV
1N/Awith an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
1N/A SV* newSV(STRLEN len)
1N/ACreates a new SV and copies an integer into it. The reference count for the
1N/ACreates a new SV and copies a floating point value into it.
1N/AThe reference count for the SV is set to 1.
1N/ACreates a new SV and copies a string into it. The reference count for the
1N/ASV is set to 1. If C<len> is zero, Perl will compute the length using
1N/Astrlen(). For efficiency, consider using C<newSVpvn> instead.
1N/A SV* newSVpv(const char* s, STRLEN len)
1N/ACreates a new SV and initializes it with the string formatted like
1N/A SV* newSVpvf(const char* pat, ...)
1N/ACreates a new SV and copies a string into it. The reference count for the
1N/ASV is set to 1. Note that if C<len> is zero, Perl will create a zero length
1N/Astring. You are responsible for ensuring that the source string is at least
1N/A SV* newSVpvn(const char* s, STRLEN len)
1N/ACreates a new SV with its SvPVX pointing to a shared string in the string
1N/Atable. If the string does not already exist in the table, it is created
1N/Afirst. Turns on READONLY and FAKE. The string's hash is stored in the UV
1N/Aslot of the SV; if the C<hash> parameter is non-zero, that value is used;
1N/Aotherwise the hash is computed. The idea here is that as the string table
1N/Ais used for shared hash keys these strings will have SvPVX == HeKEY and
1N/Ahash lookup will avoid string compare.
1N/A SV* newSVpvn_share(const char* s, I32 len, U32 hash)
1N/ACreates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
1N/Ait will be upgraded to one. If C<classname> is non-null then the new SV will
1N/Abe blessed in the specified package. The new SV is returned and its
1N/Areference count is 1.
1N/A SV* newSVrv(SV* rv, const char* classname)
1N/ACreates a new SV which is an exact duplicate of the original SV.
1N/A SV* newSVsv(SV* old)
1N/ACreates a new SV and copies an unsigned integer into it.
1N/AThe reference count for the SV is set to 1.
1N/AReturns the length of the string which is in the SV. See C<SvLEN>.
1N/A STRLEN SvCUR(SV* sv)
1N/ASet the length of the string which is in the SV. See C<SvCUR>.
1N/A void SvCUR_set(SV* sv, STRLEN len)
1N/AReturns a pointer to the last character in the string which is in the SV.
1N/ASee C<SvCUR>. Access the character as *(SvEND(sv)).
1N/AExpands the character buffer in the SV so that it has room for the
1N/Aindicated number of bytes (remember to reserve space for an extra trailing
1N/ANUL character). Calls C<sv_grow> to perform the expansion if necessary.
1N/AReturns a pointer to the character buffer.
1N/A char * SvGROW(SV* sv, STRLEN len)
1N/AReturns a boolean indicating whether the SV contains an integer.
1N/AReturns a boolean indicating whether the SV contains an integer. Checks
1N/Athe B<private> setting. Use C<SvIOK>.
1N/AReturns a boolean indicating whether the SV contains a signed integer.
1N/A bool SvIOK_notUV(SV* sv)
1N/AUnsets the IV status of an SV.
1N/A void SvIOK_off(SV* sv)
1N/ATells an SV that it is an integer.
1N/A void SvIOK_on(SV* sv)
1N/ATells an SV that it is an integer and disables all other OK bits.
1N/A void SvIOK_only(SV* sv)
1N/ATells and SV that it is an unsigned integer and disables all other OK bits.
1N/A void SvIOK_only_UV(SV* sv)
1N/AReturns a boolean indicating whether the SV contains an unsigned integer.
1N/A bool SvIOK_UV(SV* sv)
1N/AReturns a boolean indicating whether the SV is Copy-On-Write. (either shared
1N/Ahash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
1N/A bool SvIsCOW(SV* sv)
1N/A=item SvIsCOW_shared_hash
1N/AReturns a boolean indicating whether the SV is Copy-On-Write shared hash key
1N/A bool SvIsCOW_shared_hash(SV* sv)
1N/ACoerces the given SV to an integer and returns it. See C<SvIVx> for a
1N/Aversion which guarantees to evaluate sv only once.
1N/ACoerces the given SV to an integer and returns it. Guarantees to evaluate
1N/Asv only once. Use the more efficient C<SvIV> otherwise.
1N/AReturns the raw value in the SV's IV slot, without checks or conversions.
1N/AOnly use when you are sure SvIOK is true. See also C<SvIV()>.
1N/AReturns the size of the string buffer in the SV, not including any part
1N/Aattributable to C<SvOOK>. See C<SvCUR>.
1N/A STRLEN SvLEN(SV* sv)
1N/AReturns a boolean indicating whether the SV contains a number, integer or
1N/AReturns a boolean indicating whether the SV contains a number, integer or
1N/Adouble. Checks the B<private> setting. Use C<SvNIOK>.
1N/A bool SvNIOKp(SV* sv)
1N/A void SvNIOK_off(SV* sv)
1N/AReturns a boolean indicating whether the SV contains a double.
1N/AReturns a boolean indicating whether the SV contains a double. Checks the
1N/AB<private> setting. Use C<SvNOK>.
1N/AUnsets the NV status of an SV.
1N/A void SvNOK_off(SV* sv)
1N/ATells an SV that it is a double.
1N/A void SvNOK_on(SV* sv)
1N/ATells an SV that it is a double and disables all other OK bits.
1N/A void SvNOK_only(SV* sv)
1N/ACoerce the given SV to a double and return it. See C<SvNVx> for a version
1N/Awhich guarantees to evaluate sv only once.
1N/ACoerces the given SV to a double and returns it. Guarantees to evaluate
1N/Asv only once. Use the more efficient C<SvNV> otherwise.
1N/AReturns the raw value in the SV's NV slot, without checks or conversions.
1N/AOnly use when you are sure SvNOK is true. See also C<SvNV()>.
1N/AReturns a boolean indicating whether the value is an SV.
1N/AReturns a boolean indicating whether the SvIVX is a valid offset value for
1N/Athe SvPVX. This hack is used internally to speed up removal of characters
1N/Afrom the beginning of a SvPV. When SvOOK is true, then the start of the
1N/Aallocated string buffer is really (SvPVX - SvIVX).
1N/AReturns a boolean indicating whether the SV contains a character
1N/AReturns a boolean indicating whether the SV contains a character string.
1N/AChecks the B<private> setting. Use C<SvPOK>.
1N/AUnsets the PV status of an SV.
1N/A void SvPOK_off(SV* sv)
1N/ATells an SV that it is a string.
1N/A void SvPOK_on(SV* sv)
1N/ATells an SV that it is a string and disables all other OK bits.
1N/AWill also turn off the UTF-8 status.
1N/A void SvPOK_only(SV* sv)
1N/A=item SvPOK_only_UTF8
1N/ATells an SV that it is a string and disables all other OK bits,
1N/Aand leaves the UTF-8 status as it was.
1N/A void SvPOK_only_UTF8(SV* sv)
1N/AReturns a pointer to the string in the SV, or a stringified form of
1N/Athe SV if the SV does not contain a string. The SV may cache the
1N/Astringified version becoming C<SvPOK>. Handles 'get' magic. See also
1N/AC<SvPVx> for a version which guarantees to evaluate sv only once.
1N/A char* SvPV(SV* sv, STRLEN len)
1N/ALike C<SvPV>, but converts sv to byte representation first if necessary.
1N/A char* SvPVbyte(SV* sv, STRLEN len)
1N/ALike C<SvPV>, but converts sv to byte representation first if necessary.
1N/AGuarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
1N/A char* SvPVbytex(SV* sv, STRLEN len)
1N/A=item SvPVbytex_force
1N/ALike C<SvPV_force>, but converts sv to byte representation first if necessary.
1N/AGuarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
1N/A char* SvPVbytex_force(SV* sv, STRLEN len)
1N/ALike C<SvPV_force>, but converts sv to byte representation first if necessary.
1N/A char* SvPVbyte_force(SV* sv, STRLEN len)
1N/ALike C<SvPV_nolen>, but converts sv to byte representation first if necessary.
1N/A char* SvPVbyte_nolen(SV* sv)
1N/ALike C<SvPV>, but converts sv to utf8 first if necessary.
1N/A char* SvPVutf8(SV* sv, STRLEN len)
1N/ALike C<SvPV>, but converts sv to utf8 first if necessary.
1N/AGuarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
1N/A char* SvPVutf8x(SV* sv, STRLEN len)
1N/A=item SvPVutf8x_force
1N/ALike C<SvPV_force>, but converts sv to utf8 first if necessary.
1N/AGuarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
1N/A char* SvPVutf8x_force(SV* sv, STRLEN len)
1N/ALike C<SvPV_force>, but converts sv to utf8 first if necessary.
1N/A char* SvPVutf8_force(SV* sv, STRLEN len)
1N/ALike C<SvPV_nolen>, but converts sv to utf8 first if necessary.
1N/A char* SvPVutf8_nolen(SV* sv)
1N/AReturns a pointer to the physical string in the SV. The SV must contain a
1N/AA version of C<SvPV> which guarantees to evaluate sv only once.
1N/A char* SvPVx(SV* sv, STRLEN len)
1N/ALike C<SvPV> but will force the SV into containing just a string
1N/A(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
1N/A char* SvPV_force(SV* sv, STRLEN len)
1N/A=item SvPV_force_nomg
1N/ALike C<SvPV> but will force the SV into containing just a string
1N/A(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
1N/Adirectly. Doesn't process magic.
1N/A char* SvPV_force_nomg(SV* sv, STRLEN len)
1N/AReturns a pointer to the string in the SV, or a stringified form of
1N/Athe SV if the SV does not contain a string. The SV may cache the
1N/Astringified form becoming C<SvPOK>. Handles 'get' magic.
1N/A char* SvPV_nolen(SV* sv)
1N/AReturns the value of the object's reference count.
1N/A U32 SvREFCNT(SV* sv)
1N/ADecrements the reference count of the given SV.
1N/A void SvREFCNT_dec(SV* sv)
1N/AIncrements the reference count of the given SV.
1N/A SV* SvREFCNT_inc(SV* sv)
1N/ATests if the SV is an RV.
1N/AUnsets the RV status of an SV.
1N/A void SvROK_off(SV* sv)
1N/ATells an SV that it is an RV.
1N/A void SvROK_on(SV* sv)
1N/ADereferences an RV to return the SV.
1N/AReturns the stash of the SV.
1N/ATaints an SV if tainting is enabled.
1N/A void SvTAINT(SV* sv)
1N/AChecks to see if an SV is tainted. Returns TRUE if it is, FALSE if
1N/A bool SvTAINTED(SV* sv)
1N/AUntaints an SV. Be I<very> careful with this routine, as it short-circuits
1N/Asome of Perl's fundamental security features. XS module authors should not
1N/Ause this function unless they fully understand all the implications of
1N/Aunconditionally untainting the value. Untainting should be done in the
1N/Astandard perl fashion, via a carefully crafted regexp, rather than directly
1N/Auntainting variables.
1N/A void SvTAINTED_off(SV* sv)
1N/AMarks an SV as tainted if tainting is enabled.
1N/A void SvTAINTED_on(SV* sv)
1N/AReturns a boolean indicating whether Perl would evaluate the SV as true or
1N/Afalse, defined or undefined. Does not handle 'get' magic.
1N/AReturns the type of the SV. See C<svtype>.
1N/A svtype SvTYPE(SV* sv)
1N/AReleases a mutual exclusion lock on sv if a suitable module
1N/A void SvUNLOCK(SV* sv)
1N/AReturns a boolean indicating whether the SV contains an unsigned integer.
1N/AUsed to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
1N/Aperform the upgrade if necessary. See C<svtype>.
1N/A void SvUPGRADE(SV* sv, svtype type)
1N/AReturns a boolean indicating whether the SV contains UTF-8 encoded data.
1N/AUnsets the UTF-8 status of an SV.
1N/A void SvUTF8_off(SV *sv)
1N/ATurn on the UTF-8 status of an SV (the data is not changed, just the flag).
1N/ADo not use frivolously.
1N/A void SvUTF8_on(SV *sv)
1N/ACoerces the given SV to an unsigned integer and returns it. See C<SvUVx>
1N/Afor a version which guarantees to evaluate sv only once.
1N/ACoerces the given SV to an unsigned integer and returns it. Guarantees to
1N/Aevaluate sv only once. Use the more efficient C<SvUV> otherwise.
1N/AReturns the raw value in the SV's UV slot, without checks or conversions.
1N/AOnly use when you are sure SvIOK is true. See also C<SvUV()>.
1N/AThis function is only called on magical items, and is only used by
1N/Asv_true() or its macro equivalent.
1N/A bool sv_2bool(SV* sv)
1N/AUsing various gambits, try to get a CV from an SV; in addition, try if
1N/Apossible to set C<*st> and C<*gvp> to the stash and GV associated with it.
1N/A CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
1N/AUsing various gambits, try to get an IO from an SV: the IO slot if its a
1N/AGV; or the recursive result if we're an RV; or the IO slot of the symbol
1N/Anamed after the PV if we're a string.
1N/AReturn the integer value of an SV, doing any necessary string conversion,
1N/Amagic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
1N/AMarks an existing SV as mortal. The SV will be destroyed "soon", either
1N/Aby an explicit call to FREETMPS, or by an implicit call at places such as
1N/Astatement boundaries. See also C<sv_newmortal> and C<sv_mortalcopy>.
1N/A SV* sv_2mortal(SV* sv)
1N/AReturn the num value of an SV, doing any necessary string or integer
1N/Aconversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
1N/AReturn a pointer to the byte-encoded representation of the SV, and set *lp
1N/Ato its length. May cause the SV to be downgraded from UTF-8 as a
1N/AUsually accessed via the C<SvPVbyte> macro.
1N/A char* sv_2pvbyte(SV* sv, STRLEN* lp)
1N/A=item sv_2pvbyte_nolen
1N/AReturn a pointer to the byte-encoded representation of the SV.
1N/AMay cause the SV to be downgraded from UTF-8 as a side-effect.
1N/AUsually accessed via the C<SvPVbyte_nolen> macro.
1N/A char* sv_2pvbyte_nolen(SV* sv)
1N/AReturn a pointer to the UTF-8-encoded representation of the SV, and set *lp
1N/Ato its length. May cause the SV to be upgraded to UTF-8 as a side-effect.
1N/AUsually accessed via the C<SvPVutf8> macro.
1N/A char* sv_2pvutf8(SV* sv, STRLEN* lp)
1N/A=item sv_2pvutf8_nolen
1N/AReturn a pointer to the UTF-8-encoded representation of the SV.
1N/AMay cause the SV to be upgraded to UTF-8 as a side-effect.
1N/AUsually accessed via the C<SvPVutf8_nolen> macro.
1N/A char* sv_2pvutf8_nolen(SV* sv)
1N/AReturns a pointer to the string value of an SV, and sets *lp to its length.
1N/AIf flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
1N/ANormally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
1N/Ausually end up here too.
1N/A char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
1N/ALike C<sv_2pv()>, but doesn't return the length too. You should usually
1N/Ause the macro wrapper C<SvPV_nolen(sv)> instead.
1N/A char* sv_2pv_nolen(SV* sv)
1N/AReturn the unsigned integer value of an SV, doing any necessary string
1N/Aconversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
1N/ARemove any string offset. You should normally use the C<SvOOK_off> macro
1N/A int sv_backoff(SV* sv)
1N/ABlesses an SV into a specified package. The SV must be an RV. The package
1N/Amust be designated by its stash (see C<gv_stashpv()>). The reference count
1N/Aof the SV is unaffected.
1N/A SV* sv_bless(SV* sv, HV* stash)
1N/AConcatenates the string onto the end of the string which is in the SV.
1N/AIf the SV has the UTF-8 status set, then the bytes appended should be
1N/Avalid UTF-8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
1N/A void sv_catpv(SV* sv, const char* ptr)
1N/AProcesses its arguments like C<sprintf> and appends the formatted
1N/Aoutput to an SV. If the appended data contains "wide" characters
1N/A(including, but not limited to, SVs with a UTF-8 PV formatted with %s,
1N/Aand characters >255 formatted with %c), the original SV might get
1N/Aupgraded to UTF-8. Handles 'get' magic, but not 'set' magic.
1N/AC<SvSETMAGIC()> must typically be called after calling this function
1N/Ato handle 'set' magic.
1N/A void sv_catpvf(SV* sv, const char* pat, ...)
1N/ALike C<sv_catpvf>, but also handles 'set' magic.
1N/A void sv_catpvf_mg(SV *sv, const char* pat, ...)
1N/AConcatenates the string onto the end of the string which is in the SV. The
1N/AC<len> indicates number of bytes to copy. If the SV has the UTF-8
1N/Astatus set, then the bytes appended should be valid UTF-8.
1N/AHandles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
1N/A void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
1N/A=item sv_catpvn_flags
1N/AConcatenates the string onto the end of the string which is in the SV. The
1N/AC<len> indicates number of bytes to copy. If the SV has the UTF-8
1N/Astatus set, then the bytes appended should be valid UTF-8.
1N/AIf C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
1N/Aappropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
1N/Ain terms of this function.
1N/A void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
1N/ALike C<sv_catpvn>, but also handles 'set' magic.
1N/A void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
1N/ALike C<sv_catpv>, but also handles 'set' magic.
1N/A void sv_catpv_mg(SV *sv, const char *ptr)
1N/AConcatenates the string from SV C<ssv> onto the end of the string in
1N/ASV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
1N/Anot 'set' magic. See C<sv_catsv_mg>.
1N/A void sv_catsv(SV* dsv, SV* ssv)
1N/AConcatenates the string from SV C<ssv> onto the end of the string in
1N/ASV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC>
1N/Abit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
1N/Aand C<sv_catsv_nomg> are implemented in terms of this function.
1N/A void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
1N/ALike C<sv_catsv>, but also handles 'set' magic.
1N/A void sv_catsv_mg(SV *dstr, SV *sstr)
1N/AEfficient removal of characters from the beginning of the string buffer.
1N/ASvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
1N/Athe string buffer. The C<ptr> becomes the first character of the adjusted
1N/Astring. Uses the "OOK hack".
1N/ABeware: after this function returns, C<ptr> and SvPVX(sv) may no longer
1N/Arefer to the same chunk of data.
1N/A void sv_chop(SV* sv, char* ptr)
1N/AClear an SV: call any destructors, free up any memory used by the body,
1N/Aand free the body itself. The SV's head is I<not> freed, although
1N/Aits type is set to all 1's so that it won't inadvertently be assumed
1N/Ato be live during global destruction etc.
1N/AThis function should only be called when REFCNT is zero. Most of the time
1N/Ayou'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
1N/A void sv_clear(SV* sv)
1N/ACompares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
1N/Astring in C<sv1> is less than, equal to, or greater than the string in
1N/AC<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
1N/Acoerce its args to strings if necessary. See also C<sv_cmp_locale>.
1N/A I32 sv_cmp(SV* sv1, SV* sv2)
1N/ACompares the strings in two SVs in a locale-aware manner. Is UTF-8 and
1N/A'use bytes' aware, handles get magic, and will coerce its args to strings
1N/Aif necessary. See also C<sv_cmp_locale>. See also C<sv_cmp>.
1N/A I32 sv_cmp_locale(SV* sv1, SV* sv2)
1N/AAdd Collate Transform magic to an SV if it doesn't already have it.
1N/AAny scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
1N/Ascalar data of the variable, but transformed to such a format that a normal
1N/Amemory comparison can be used to compare the data according to the locale
1N/A char* sv_collxfrm(SV* sv, STRLEN* nxp)
1N/ACopies a stringified representation of the source SV into the
1N/Adestination SV. Automatically performs any necessary mg_get and
1N/Acoercion of numeric values into strings. Guaranteed to preserve
1N/AUTF-8 flag even from overloaded objects. Similar in nature to
1N/Asv_2pv[_flags] but operates directly on an SV instead of just the
1N/Astring. Mostly uses sv_2pv_flags to do its work, except when that
1N/Awould lose the UTF-8'ness of the PV.
1N/A void sv_copypv(SV* dsv, SV* ssv)
1N/AAuto-decrement of the value in the SV, doing string to numeric conversion
1N/Aif necessary. Handles 'get' magic.
1N/A=item sv_derived_from
1N/AReturns a boolean indicating whether the SV is derived from the specified
1N/Aclass. This is the function that implements C<UNIVERSAL::isa>. It works
1N/Afor class names as well as for objects.
1N/A bool sv_derived_from(SV* sv, const char* name)
1N/AReturns a boolean indicating whether the strings in the two SVs are
1N/Aidentical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
1N/Acoerce its args to strings if necessary.
1N/A I32 sv_eq(SV* sv1, SV* sv2)
1N/A=item sv_force_normal
1N/AUndo various types of fakery on an SV: if the PV is a shared string, make
1N/Aa private copy; if we're a ref, stop refing; if we're a glob, downgrade to
1N/Aan xpvmg. See also C<sv_force_normal_flags>.
1N/A void sv_force_normal(SV *sv)
1N/A=item sv_force_normal_flags
1N/AUndo various types of fakery on an SV: if the PV is a shared string, make
1N/Aa private copy; if we're a ref, stop refing; if we're a glob, downgrade to
1N/Aan xpvmg. The C<flags> parameter gets passed to C<sv_unref_flags()>
1N/Awhen unrefing. C<sv_force_normal> calls this function with flags set to 0.
1N/A void sv_force_normal_flags(SV *sv, U32 flags)
1N/ADecrement an SV's reference count, and if it drops to zero, call
1N/AC<sv_clear> to invoke destructors and free up any memory used by
1N/Athe body; finally, deallocate the SV's head itself.
1N/ANormally called via a wrapper macro C<SvREFCNT_dec>.
1N/A void sv_free(SV* sv)
1N/AGet a line from the filehandle and store it into the SV, optionally
1N/Aappending to the currently-stored string.
1N/A char* sv_gets(SV* sv, PerlIO* fp, I32 append)
1N/AExpands the character buffer in the SV. If necessary, uses C<sv_unref> and
1N/Aupgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer.
1N/AUse the C<SvGROW> wrapper instead.
1N/A char* sv_grow(SV* sv, STRLEN newlen)
1N/AAuto-increment of the value in the SV, doing string to numeric conversion
1N/Aif necessary. Handles 'get' magic.
1N/Athe Perl substr() function.
1N/A void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
1N/AReturns a boolean indicating whether the SV is blessed into the specified
1N/Aclass. This does not check for subtypes; use C<sv_derived_from> to verify
1N/Aan inheritance relationship.
1N/A int sv_isa(SV* sv, const char* name)
1N/AReturns a boolean indicating whether the SV is an RV pointing to a blessed
1N/Aobject. If the SV is not an RV, or if the object is not blessed, then this
1N/A int sv_isobject(SV* sv)
1N/AA private implementation of the C<SvIVx> macro for compilers which can't
1N/Acope with complex macro expressions. Always use the macro instead.
1N/AReturns the length of the string in the SV. Handles magic and type
1N/Acoercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot.
1N/A STRLEN sv_len(SV* sv)
1N/AReturns the number of characters in the string in an SV, counting wide
1N/AUTF-8 bytes as a single character. Handles magic and type coercion.
1N/A STRLEN sv_len_utf8(SV* sv)
1N/AAdds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
1N/Athen adds a new magic item of type C<how> to the head of the magic list.
1N/A void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
1N/AAdds magic to an SV, upgrading it if necessary. Applies the
1N/Asupplied vtable and returns pointer to the magic added.
1N/ANote that sv_magicext will allow things that sv_magic will not.
1N/AIn particular you can add magic to SvREADONLY SVs and and more than
1N/Aone instance of the same 'how'
1N/AI C<namelen> is greater then zero then a savepvn() I<copy> of C<name> is stored,
1N/Aif C<namelen> is zero then C<name> is stored as-is and - as another special
1N/Acase - if C<(name && namelen == HEf_SVKEY)> then C<name> is assumed to contain
1N/Aan C<SV*> and has its REFCNT incremented
1N/A(This is now used as a subroutine by sv_magic.)
1N/A MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen )
1N/ACreates a new SV which is a copy of the original SV (using C<sv_setsv>).
1N/AThe new SV is marked as mortal. It will be destroyed "soon", either by an
1N/Aexplicit call to FREETMPS, or by an implicit call at places such as
1N/Astatement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
1N/A SV* sv_mortalcopy(SV* oldsv)
1N/ACreates a new null SV which is mortal. The reference count of the SV is
1N/Aset to 1. It will be destroyed "soon", either by an explicit call to
1N/AFREETMPS, or by an implicit call at places such as statement boundaries.
1N/ASee also C<sv_mortalcopy> and C<sv_2mortal>.
1N/AIncrement an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
1N/A SV* sv_newref(SV* sv)
1N/AA private implementation of the C<SvNVx> macro for compilers which can't
1N/Acope with complex macro expressions. Always use the macro instead.
1N/AConverts the value pointed to by offsetp from a count of bytes from the
1N/Astart of the string, to a count of the equivalent number of UTF-8 chars.
1N/AHandles magic and type coercion.
1N/A void sv_pos_b2u(SV* sv, I32* offsetp)
1N/AConverts the value pointed to by offsetp from a count of UTF-8 chars from
1N/Athe start of the string, to a count of the equivalent number of bytes; if
1N/Alenp is non-zero, it does the same to lenp, but this time starting from
1N/Athe offset, rather than from the start of the string. Handles magic and
1N/A void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
1N/AUse the C<SvPV_nolen> macro instead
1N/AUse C<SvPVbyte_nolen> instead.
1N/A char* sv_pvbyte(SV *sv)
1N/AA private implementation of the C<SvPVbyte> macro for compilers
1N/Awhich can't cope with complex macro expressions. Always use the macro
1N/A char* sv_pvbyten(SV *sv, STRLEN *len)
1N/A=item sv_pvbyten_force
1N/AA private implementation of the C<SvPVbytex_force> macro for compilers
1N/Awhich can't cope with complex macro expressions. Always use the macro
1N/A char* sv_pvbyten_force(SV* sv, STRLEN* lp)
1N/AA private implementation of the C<SvPV> macro for compilers which can't
1N/Acope with complex macro expressions. Always use the macro instead.
1N/A char* sv_pvn(SV *sv, STRLEN *len)
1N/AGet a sensible string out of the SV somehow.
1N/AA private implementation of the C<SvPV_force> macro for compilers which
1N/Acan't cope with complex macro expressions. Always use the macro instead.
1N/A char* sv_pvn_force(SV* sv, STRLEN* lp)
1N/A=item sv_pvn_force_flags
1N/AGet a sensible string out of the SV somehow.
1N/AIf C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
1N/Aappropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
1N/Aimplemented in terms of this function.
1N/AYou normally want to use the various wrapper macros instead: see
1N/AC<SvPV_force> and C<SvPV_force_nomg>
1N/A char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
1N/AUse the C<SvPVutf8_nolen> macro instead
1N/A char* sv_pvutf8(SV *sv)
1N/AA private implementation of the C<SvPVutf8> macro for compilers
1N/Awhich can't cope with complex macro expressions. Always use the macro
1N/A char* sv_pvutf8n(SV *sv, STRLEN *len)
1N/A=item sv_pvutf8n_force
1N/AA private implementation of the C<SvPVutf8_force> macro for compilers
1N/Awhich can't cope with complex macro expressions. Always use the macro
1N/A char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
1N/AReturns a string describing what the SV is a reference to.
1N/A char* sv_reftype(SV* sv, int ob)
1N/AMake the first argument a copy of the second, then delete the original.
1N/AThe target SV physically takes over ownership of the body of the source SV
1N/Aand inherits its flags; however, the target keeps any magic it owns,
1N/Aand any magic in the source is discarded.
1N/ANote that this is a rather specialist SV copying operation; most of the
1N/Atime you'll want to use C<sv_setsv> or one of its many macro front-ends.
1N/A void sv_replace(SV* sv, SV* nsv)
1N/ADump the contents of all SVs not yet freed. (Debugging aid).
1N/A void sv_report_used()
1N/AUnderlying implementation for the C<reset> Perl function.
1N/ANote that the perl-level function is vaguely deprecated.
1N/A void sv_reset(char* s, HV* stash)
1N/AWeaken a reference: set the C<SvWEAKREF> flag on this RV; give the
1N/Areferred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
1N/Apush a back-reference to this RV onto the array of backreferences
1N/Aassociated with that magic.
1N/A SV* sv_rvweaken(SV *sv)
1N/ACopies an integer into the given SV, upgrading first if necessary.
1N/ADoes not handle 'set' magic. See also C<sv_setiv_mg>.
1N/A void sv_setiv(SV* sv, IV num)
1N/ALike C<sv_setiv>, but also handles 'set' magic.
1N/A void sv_setiv_mg(SV *sv, IV i)
1N/ACopies a double into the given SV, upgrading first if necessary.
1N/ADoes not handle 'set' magic. See also C<sv_setnv_mg>.
1N/A void sv_setnv(SV* sv, NV num)
1N/ALike C<sv_setnv>, but also handles 'set' magic.
1N/A void sv_setnv_mg(SV *sv, NV num)
1N/ACopies a string into an SV. The string must be null-terminated. Does not
1N/Ahandle 'set' magic. See C<sv_setpv_mg>.
1N/A void sv_setpv(SV* sv, const char* ptr)
1N/AProcesses its arguments like C<sprintf> and sets an SV to the formatted
1N/Aoutput. Does not handle 'set' magic. See C<sv_setpvf_mg>.
1N/A void sv_setpvf(SV* sv, const char* pat, ...)
1N/ALike C<sv_setpvf>, but also handles 'set' magic.
1N/A void sv_setpvf_mg(SV *sv, const char* pat, ...)
1N/ACopies an integer into the given SV, also updating its string value.
1N/ADoes not handle 'set' magic. See C<sv_setpviv_mg>.
1N/A void sv_setpviv(SV* sv, IV num)
1N/ALike C<sv_setpviv>, but also handles 'set' magic.
1N/A void sv_setpviv_mg(SV *sv, IV iv)
1N/ACopies a string into an SV. The C<len> parameter indicates the number of
1N/Abytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
1N/A void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
1N/ALike C<sv_setpvn>, but also handles 'set' magic.
1N/A void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
1N/ALike C<sv_setpv>, but also handles 'set' magic.
1N/A void sv_setpv_mg(SV *sv, const char *ptr)
1N/ACopies an integer into a new SV, optionally blessing the SV. The C<rv>
1N/Aargument will be upgraded to an RV. That RV will be modified to point to
1N/Athe new SV. The C<classname> argument indicates the package for the
1N/Ablessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
1N/Awill have a reference count of 1, and the RV will be returned.
1N/A SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
1N/ACopies a double into a new SV, optionally blessing the SV. The C<rv>
1N/Aargument will be upgraded to an RV. That RV will be modified to point to
1N/Athe new SV. The C<classname> argument indicates the package for the
1N/Ablessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
1N/Awill have a reference count of 1, and the RV will be returned.
1N/A SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
1N/ACopies a pointer into a new SV, optionally blessing the SV. The C<rv>
1N/Aargument will be upgraded to an RV. That RV will be modified to point to
1N/Athe new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
1N/Ainto the SV. The C<classname> argument indicates the package for the
1N/Ablessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
1N/Awill have a reference count of 1, and the RV will be returned.
1N/ADo not use with other Perl types such as HV, AV, SV, CV, because those
1N/Aobjects will become corrupted by the pointer copy process.
1N/ANote that C<sv_setref_pvn> copies the string while this copies the pointer.
1N/A SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
1N/ACopies a string into a new SV, optionally blessing the SV. The length of the
1N/Astring must be specified with C<n>. The C<rv> argument will be upgraded to
1N/Aan RV. That RV will be modified to point to the new SV. The C<classname>
1N/Aargument indicates the package for the blessing. Set C<classname> to
1N/AC<Nullch> to avoid the blessing. The new SV will have a reference count
1N/Aof 1, and the RV will be returned.
1N/ANote that C<sv_setref_pv> copies the pointer while this copies the string.
1N/A SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
1N/ACopies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
1N/Aargument will be upgraded to an RV. That RV will be modified to point to
1N/Athe new SV. The C<classname> argument indicates the package for the
1N/Ablessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
1N/Awill have a reference count of 1, and the RV will be returned.
1N/A SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
1N/ACopies the contents of the source SV C<ssv> into the destination SV
1N/AC<dsv>. The source SV may be destroyed if it is mortal, so don't use this
1N/Afunction if the source SV needs to be reused. Does not handle 'set' magic.
1N/ALoosely speaking, it performs a copy-by-value, obliterating any previous
1N/Acontent of the destination.
1N/AYou probably want to use one of the assortment of wrappers, such as
1N/AC<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
1N/AC<SvSetMagicSV_nosteal>.
1N/A void sv_setsv(SV* dsv, SV* ssv)
1N/ACopies the contents of the source SV C<ssv> into the destination SV
1N/AC<dsv>. The source SV may be destroyed if it is mortal, so don't use this
1N/Afunction if the source SV needs to be reused. Does not handle 'set' magic.
1N/ALoosely speaking, it performs a copy-by-value, obliterating any previous
1N/Acontent of the destination.
1N/AIf the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
1N/AC<ssv> if appropriate, else not. C<sv_setsv> and C<sv_setsv_nomg> are
1N/Aimplemented in terms of this function.
1N/AYou probably want to use one of the assortment of wrappers, such as
1N/AC<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
1N/AC<SvSetMagicSV_nosteal>.
1N/AThis is the primary function for copying scalars, and most other
1N/Acopy-ish functions and macros use this underneath.
1N/A void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
1N/ALike C<sv_setsv>, but also handles 'set' magic.
1N/A void sv_setsv_mg(SV *dstr, SV *sstr)
1N/ACopies an unsigned integer into the given SV, upgrading first if necessary.
1N/ADoes not handle 'set' magic. See also C<sv_setuv_mg>.
1N/A void sv_setuv(SV* sv, UV num)
1N/ALike C<sv_setuv>, but also handles 'set' magic.
1N/A void sv_setuv_mg(SV *sv, UV u)
1N/ATaint an SV. Use C<SvTAINTED_on> instead.
1N/A void sv_taint(SV* sv)
1N/ATest an SV for taintedness. Use C<SvTAINTED> instead.
1N/A bool sv_tainted(SV* sv)
1N/AReturns true if the SV has a true value by Perl's rules.
1N/AUse the C<SvTRUE> macro instead, which may call C<sv_true()> or may
1N/Ainstead use an in-line version.
1N/ARemoves all magic of type C<type> from an SV.
1N/A int sv_unmagic(SV* sv, int type)
1N/AUnsets the RV status of the SV, and decrements the reference count of
1N/Awhatever was being referenced by the RV. This can almost be thought of
1N/Aas a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
1N/Abeing zero. See C<SvROK_off>.
1N/A void sv_unref(SV* sv)
1N/AUnsets the RV status of the SV, and decrements the reference count of
1N/Awhatever was being referenced by the RV. This can almost be thought of
1N/Aas a reversal of C<newSVrv>. The C<cflags> argument can contain
1N/AC<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
1N/A(otherwise the decrementing is conditional on the reference count being
1N/Adifferent from one or the reference being a readonly SV).
1N/A void sv_unref_flags(SV* sv, U32 flags)
1N/AUntaint an SV. Use C<SvTAINTED_off> instead.
1N/A void sv_untaint(SV* sv)
1N/AUpgrade an SV to a more complex form. Generally adds a new body type to the
1N/ASV, then copies across as much information as possible from the old body.
1N/AYou generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
1N/A bool sv_upgrade(SV* sv, U32 mt)
1N/ATells an SV to use C<ptr> to find its string value. Normally the string is
1N/Astored inside the SV but sv_usepvn allows the SV to use an outside string.
1N/AThe C<ptr> should point to memory that was allocated by C<malloc>. The
1N/Astring length, C<len>, must be supplied. This function will realloc the
1N/Amemory pointed to by C<ptr>, so that pointer should not be freed or used by
1N/Athe programmer after giving it to sv_usepvn. Does not handle 'set' magic.
1N/A void sv_usepvn(SV* sv, char* ptr, STRLEN len)
1N/ALike C<sv_usepvn>, but also handles 'set' magic.
1N/A void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
1N/AConvert the octets in the PV from UTF-8 to chars. Scan for validity and then
1N/Aturn off SvUTF8 if needed so that we see characters. Used as a building block
1N/ANOTE: this function is experimental and may change or be
1N/Aremoved without notice.
1N/A bool sv_utf8_decode(SV *sv)
1N/A=item sv_utf8_downgrade
1N/AAttempt to convert the PV of an SV from UTF-8-encoded to byte encoding.
1N/AThis may not be possible if the PV contains non-byte encoding characters;
1N/Aif this is the case, either returns false or, if C<fail_ok> is not
1N/AThis is not as a general purpose Unicode to byte encoding interface:
1N/Ause the Encode extension for that.
1N/ANOTE: this function is experimental and may change or be
1N/Aremoved without notice.
1N/A bool sv_utf8_downgrade(SV *sv, bool fail_ok)
1N/AConvert the PV of an SV to UTF-8-encoded, but then turn off the C<SvUTF8>
1N/Aflag so that it looks like octets again. Used as a building block
1N/A void sv_utf8_encode(SV *sv)
1N/A=item sv_utf8_upgrade
1N/AConvert the PV of an SV to its UTF-8-encoded form.
1N/AForces the SV to string form if it is not already.
1N/AAlways sets the SvUTF8 flag to avoid future validity checks even
1N/Aif all the bytes have hibit clear.
1N/AThis is not as a general purpose byte encoding to Unicode interface:
1N/Ause the Encode extension for that.
1N/A STRLEN sv_utf8_upgrade(SV *sv)
1N/A=item sv_utf8_upgrade_flags
1N/AConvert the PV of an SV to its UTF-8-encoded form.
1N/AForces the SV to string form if it is not already.
1N/AAlways sets the SvUTF8 flag to avoid future validity checks even
1N/Aif all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
1N/Awill C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and
1N/AC<sv_utf8_upgrade_nomg> are implemented in terms of this function.
1N/AThis is not as a general purpose byte encoding to Unicode interface:
1N/Ause the Encode extension for that.
1N/A STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags)
1N/AA private implementation of the C<SvUVx> macro for compilers which can't
1N/Acope with complex macro expressions. Always use the macro instead.
1N/AProcesses its arguments like C<vsprintf> and appends the formatted output
1N/Ato an SV. Uses an array of SVs if the C style variable argument list is
1N/Amissing (NULL). When running with taint checks enabled, indicates via
1N/AC<maybe_tainted> if results are untrustworthy (often due to the use of
1N/AUsually used via one of its frontends C<sv_catpvf> and C<sv_catpvf_mg>.
1N/A void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
1N/AWorks like C<vcatpvfn> but copies the text into the SV instead of
1N/AUsually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
1N/A void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
1N/A=head1 Unicode Support
1N/A=item bytes_from_utf8
1N/AConverts a string C<s> of length C<len> from UTF-8 into byte encoding.
1N/AUnlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
1N/Athe newly-created string, and updates C<len> to contain the new
1N/Alength. Returns the original string if no conversion occurs, C<len>
1N/Ais unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
1N/A0 if C<s> is converted or contains all 7bit characters.
1N/ANOTE: this function is experimental and may change or be
1N/Aremoved without notice.
1N/A U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
1N/AConverts a string C<s> of length C<len> from ASCII into UTF-8 encoding.
1N/AReturns a pointer to the newly-created string, and sets C<len> to
1N/Areflect the new length.
1N/AIf you want to convert to UTF-8 from other encodings than ASCII,
1N/Asee sv_recode_to_utf8().
1N/ANOTE: this function is experimental and may change or be
1N/Aremoved without notice.
1N/A U8* bytes_to_utf8(U8 *s, STRLEN *len)
1N/AReturn true if the strings s1 and s2 differ case-insensitively, false
1N/Aif not (if they are equal case-insensitively). If u1 is true, the
1N/Astring s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true,
1N/Athe string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2
1N/Aare false, the respective string is assumed to be in native 8-bit
1N/AIf the pe1 and pe2 are non-NULL, the scanning pointers will be copied
1N/Ain there (they will point at the beginning of the I<next> character).
1N/AIf the pointers behind pe1 or pe2 are non-NULL, they are the end
1N/Apointers beyond which scanning will not continue under any
1N/Acircustances. If the byte lengths l1 and l2 are non-zero, s1+l1 and
1N/As2+l2 will be used as goal end pointers that will also stop the scan,
1N/Aand which qualify towards defining a successful match: all the scans
1N/Athat define an explicit length must reach their goal pointers for
1N/AFor case-insensitiveness, the "casefolding" of Unicode is used
1N/A I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
1N/ATests if some arbitrary number of bytes begins in a valid UTF-8
1N/Acharacter. Note that an INVARIANT (
i.e. ASCII) character is a valid
1N/AUTF-8 character. The actual number of bytes in the UTF-8 character
1N/Awill be returned if it is valid, otherwise 0.
1N/A STRLEN is_utf8_char(U8 *p)
1N/AReturns true if first C<len> bytes of the given string form a valid
1N/AUTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does
1N/Anot mean 'a string that contains code points above 0x7F encoded in UTF-8'
1N/Abecause a valid ASCII string is a valid UTF-8 string.
1N/A bool is_utf8_string(U8 *s, STRLEN len)
1N/A=item is_utf8_string_loc
1N/ALike is_ut8_string but store the location of the failure in
1N/A bool is_utf8_string_loc(U8 *s, STRLEN len, U8 **p)
1N/ABuild to the scalar dsv a displayable version of the string spv,
1N/Alength len, the displayable version being at most pvlim bytes long
1N/A(if longer, the rest is truncated and "..." will be appended).
1N/AThe flags argument can have UNI_DISPLAY_ISPRINT set to display
1N/AisPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
1N/Ato display the \\[nrfta\\] as the backslashed versions (like '\n')
1N/A(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
1N/AUNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
1N/AUNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
1N/AThe pointer to the PV of the dsv is returned.
1N/A char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
1N/AThe encoding is assumed to be an Encode object, the PV of the ssv is
1N/Aassumed to be octets in that encoding and decoding the input starts
1N/Afrom the position which (PV + *offset) pointed to. The dsv will be
1N/Aconcatenated the decoded UTF-8 string from ssv. Decoding will terminate
1N/Awhen the string tstr appears in decoding output or the input ends on
1N/Athe PV of the ssv. The value which the offset points will be modified
1N/Ato the last input position on the ssv.
1N/AReturns TRUE if the terminator was found, else returns FALSE.
1N/A bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
1N/A=item sv_recode_to_utf8
1N/AThe encoding is assumed to be an Encode object, on entry the PV
1N/Aof the sv is assumed to be octets in that encoding, and the sv
1N/Awill be converted into Unicode (and UTF-8).
1N/AIf the sv already is UTF-8 (or if it is not POK), or if the encoding
1N/Ais not a reference, nothing is done to the sv. If the encoding is not
1N/Aan C<Encode::XS> Encoding object, bad things will happen.
1N/AThe PV of the sv is returned.
1N/A char* sv_recode_to_utf8(SV* sv, SV *encoding)
1N/ABuild to the scalar dsv a displayable version of the scalar sv,
1N/Athe displayable version being at most pvlim bytes long
1N/A(if longer, the rest is truncated and "..." will be appended).
1N/AThe flags argument is as in pv_uni_display().
1N/AThe pointer to the PV of the dsv is returned.
1N/A char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
1N/AThe "p" contains the pointer to the UTF-8 string encoding
1N/Athe character that is being converted.
1N/AThe "ustrp" is a pointer to the character buffer to put the
1N/Aconversion result to. The "lenp" is a pointer to the length
1N/AThe "swashp" is a pointer to the swash to use.
1N/Abut not always, a multicharacter mapping), is tried first.
1N/AThe "special" is a string like "utf8::ToSpecLower", which means the
1N/Ahash %utf8::ToSpecLower. The access to the hash is through
1N/AThe "normal" is a string like "ToLower" which means the swash
1N/A UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
1N/AConvert the UTF-8 encoded character at p to its foldcase version and
1N/Astore that in UTF-8 in ustrp and its length in bytes in lenp. Note
1N/Athat the ustrp needs to be at least UTF8_MAXLEN_FOLD+1 bytes since the
1N/Afoldcase version may be longer than the original character (up to
1N/AThe first character of the foldcased version is returned
1N/A(but note, as explained above, that there may be more.)
1N/A UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)
1N/AConvert the UTF-8 encoded character at p to its lowercase version and
1N/Astore that in UTF-8 in ustrp and its length in bytes in lenp. Note
1N/Athat the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
1N/Alowercase version may be longer than the original character (up to two
1N/AThe first character of the lowercased version is returned
1N/A(but note, as explained above, that there may be more.)
1N/A UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)
1N/AConvert the UTF-8 encoded character at p to its titlecase version and
1N/Astore that in UTF-8 in ustrp and its length in bytes in lenp. Note
1N/Athat the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
1N/Atitlecase version may be longer than the original character (up to two
1N/AThe first character of the titlecased version is returned
1N/A(but note, as explained above, that there may be more.)
1N/A UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)
1N/AConvert the UTF-8 encoded character at p to its uppercase version and
1N/Astore that in UTF-8 in ustrp and its length in bytes in lenp. Note
1N/Athat the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
1N/Auppercase version may be longer than the original character (up to two
1N/AThe first character of the uppercased version is returned
1N/A(but note, as explained above, that there may be more.)
1N/A UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)
1N/AReturns the native character value of the first character in the string C<s>
1N/Awhich is assumed to be in UTF-8 encoding; C<retlen> will be set to the
1N/Alength, in bytes, of that character.
1N/AAllows length and flags to be passed to low level routine.
1N/A UV utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
1N/ABottom level UTF-8 decode routine.
1N/AReturns the unicode code point value of the first character in the string C<s>
1N/Awhich is assumed to be in UTF-8 encoding and no longer than C<curlen>;
1N/AC<retlen> will be set to the length, in bytes, of that character.
1N/AIf C<s> does not point to a well-formed UTF-8 character, the behaviour
1N/Ais dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
1N/Ait is assumed that the caller will raise a warning, and this function
1N/Awill silently just set C<retlen> to C<-1> and return zero. If the
1N/AC<flags> does not contain UTF8_CHECK_ONLY, warnings about
1N/Amalformations will be given, C<retlen> will be set to the expected
1N/Alength of the UTF-8 character in bytes, and zero will be returned.
1N/AThe C<flags> can also contain various flags to allow deviations from
1N/AMost code should use utf8_to_uvchr() rather than call this directly.
1N/A UV utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
1N/AReturns the number of UTF-8 characters between the UTF-8 pointers C<a>
1N/AWARNING: use only if you *know* that the pointers point inside the
1N/A IV utf8_distance(U8 *a, U8 *b)
1N/AReturn the UTF-8 pointer C<s> displaced by C<off> characters, either
1N/AWARNING: do not use the following unless you *know* C<off> is within
1N/Athe UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
1N/Aon the first byte of character or just after the last byte of a character.
1N/A U8* utf8_hop(U8 *s, I32 off)
1N/AReturn the length of the UTF-8 char encoded string C<s> in characters.
1N/AStops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end
1N/Aup past C<e>, croaks.
1N/A STRLEN utf8_length(U8* s, U8 *e)
1N/AConverts a string C<s> of length C<len> from UTF-8 into byte encoding.
1N/AUnlike C<bytes_to_utf8>, this over-writes the original string, and
1N/Aupdates len to contain the new length.
1N/AReturns zero on failure, setting C<len> to -1.
1N/ANOTE: this function is experimental and may change or be
1N/Aremoved without notice.
1N/A U8* utf8_to_bytes(U8 *s, STRLEN *len)
1N/AReturns the native character value of the first character in the string C<s>
1N/Awhich is assumed to be in UTF-8 encoding; C<retlen> will be set to the
1N/Alength, in bytes, of that character.
1N/AIf C<s> does not point to a well-formed UTF-8 character, zero is
1N/Areturned and retlen is set, if possible, to -1.
1N/A UV utf8_to_uvchr(U8 *s, STRLEN* retlen)
1N/AReturns the Unicode code point of the first character in the string C<s>
1N/Awhich is assumed to be in UTF-8 encoding; C<retlen> will be set to the
1N/Alength, in bytes, of that character.
1N/AThis function should only be used when returned UV is considered
1N/Aan index into the Unicode semantic tables (
e.g. swashes).
1N/AIf C<s> does not point to a well-formed UTF-8 character, zero is
1N/Areturned and retlen is set, if possible, to -1.
1N/A UV utf8_to_uvuni(U8 *s, STRLEN* retlen)
1N/AAdds the UTF-8 representation of the Native codepoint C<uv> to the end
1N/Aof the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
1N/Abytes available. The return value is the pointer to the byte after the
1N/Aend of the new character. In other words,
1N/A d = uvchr_to_utf8(d, uv);
1N/Ais the recommended wide native character-aware way of saying
1N/A U8* uvchr_to_utf8(U8 *d, UV uv)
1N/A=item uvuni_to_utf8_flags
1N/AAdds the UTF-8 representation of the Unicode codepoint C<uv> to the end
1N/Aof the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
1N/Abytes available. The return value is the pointer to the byte after the
1N/Aend of the new character. In other words,
1N/A d = uvuni_to_utf8_flags(d, uv, flags);
1N/A d = uvuni_to_utf8(d, uv);
1N/A(which is equivalent to)
1N/A d = uvuni_to_utf8_flags(d, uv, 0);
1N/Ais the recommended Unicode-aware way of saying
1N/A U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
1N/A=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
1N/AVariable which is setup by C<xsubpp> to indicate the stack base offset,
1N/Aused by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
1N/Amust be called prior to setup the C<MARK> variable.
1N/AVariable which is setup by C<xsubpp> to indicate the
1N/Aclass name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
1N/ASets up the C<ax> variable.
1N/AThis is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
1N/ASets up the C<items> variable.
1N/AThis is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
1N/ASets up stack and mark pointers for an XSUB, calling dSP and dMARK.
1N/ASets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
1N/AThis is usually handled automatically by C<xsubpp>.
1N/ASets up the C<ix> variable for an XSUB which has aliases. This is usually
1N/Ahandled automatically by C<xsubpp>.
1N/AVariable which is setup by C<xsubpp> to indicate the number of
1N/Aitems on the stack. See L<perlxs/"Variable-length Parameter Lists">.
1N/AVariable which is setup by C<xsubpp> to indicate which of an
1N/AXSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
1N/AUsed by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
1N/AVariable which is setup by C<xsubpp> to hold the return value for an
1N/AXSUB. This is always the proper type for the XSUB. See
1N/AL<perlxs/"The RETVAL Variable">.
1N/AUsed to access elements on the XSUB's stack.
1N/AVariable which is setup by C<xsubpp> to designate the object in a C++
1N/AXSUB. This is always the proper type for the C++ object. See C<CLASS> and
1N/AL<perlxs/"Using XS With C++">.
1N/AMacro to declare an XSUB and its C parameter list. This is handled by
1N/AReturn an empty list from an XSUB immediately.
1N/AThe version identifier for an XS module. This is usually
1N/Ahandled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
1N/A=item XS_VERSION_BOOTCHECK
1N/AMacro to verify that a PM module's $VERSION variable matches the XS
1N/Amodule's C<XS_VERSION> variable. This is usually handled automatically by
1N/AC<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
1N/A XS_VERSION_BOOTCHECK;
1N/A=head1 Warning and Dieing
1N/AThis is the XSUB-writer's interface to Perl's C<die> function.
1N/ANormally call this function the same way you call the C C<printf>
1N/Afunction. Calling C<croak> returns control directly to Perl,
1N/Asidestepping the normal C order of execution. See C<warn>.
1N/AIf you want to throw an exception object, assign the object to
1N/AC<$@> and then pass C<Nullch> to croak():
1N/A errsv = get_sv("@", TRUE);
1N/A sv_setsv(errsv, exception_object);
1N/A void croak(const char* pat, ...)
1N/AThis is the XSUB-writer's interface to Perl's C<warn> function. Call this
1N/Afunction the same way you call the C C<printf> function. See C<croak>.
1N/A void warn(const char* pat, ...)
1N/AUntil May 1997, this document was maintained by Jeff Okamoto
1N/A<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
1N/AWith lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
1N/AAndreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
1N/ABowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
1N/AStephen McCamant, and Gurusamy Sarathy.
1N/AAPI Listing originally by Dean Roehrich <roehrich@cray.com>.
1N/AUpdated to be autogenerated from comments in the source by Benjamin Stuhl.
1N/Aperlguts(1), perlxs(1), perlxstut(1), perlintern(1)