The listing is alphabetical, case insensitive.
+
+=head1 "Gimme" Values
+
+=over 8
+
+=item GIMME
+
+A backward-compatible version of C<GIMME_V> which can only return
+C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
+Deprecated. Use C<GIMME_V> instead.
+
+ U32 GIMME
+
+=for hackers
+Found in file op.h
+
+=item GIMME_V
+
+The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
+C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
+respectively.
+
+ U32 GIMME_V
+
+=for hackers
+Found in file op.h
+
+=item G_ARRAY
+
+Used to indicate list context. See C<GIMME_V>, C<GIMME> and
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_DISCARD
+
+Indicates that arguments returned from a callback should be discarded. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_EVAL
+
+Used to force a Perl C<eval> wrapper around a callback. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_NOARGS
+
+Indicates that no arguments are being sent to a callback. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_SCALAR
+
+Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_VOID
+
+Used to indicate void context. See C<GIMME_V> and L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+
+=back
+
+=head1 Array Manipulation Functions
+
=over 8
=item AvFILL
=for hackers
Found in file av.c
-=item ax
+=item get_av
-Variable which is setup by C<xsubpp> to indicate the stack base offset,
-used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
-must be called prior to setup the C<MARK> variable.
+Returns the AV of the specified Perl array. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
- I32 ax
+NOTE: the perl_ form of this function is deprecated.
+
+ AV* get_av(const char* name, I32 create)
=for hackers
-Found in file XSUB.h
+Found in file perl.c
-=item bytes_from_utf8
+=item newAV
-Converts a string C<s> of length C<len> from UTF8 into byte encoding.
-Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
-the newly-created string, and updates C<len> to contain the new
-length. Returns the original string if no conversion occurs, C<len>
-is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
-0 if C<s> is converted or contains all 7bit characters.
+Creates a new AV. The reference count is set to 1.
-NOTE: this function is experimental and may change or be
-removed without notice.
+ AV* newAV()
+
+=for hackers
+Found in file av.c
+
+=item Nullav
+
+Null AV pointer.
- U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
=for hackers
-Found in file utf8.c
+Found in file av.h
-=item bytes_to_utf8
+=item sortsv
-Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
-Returns a pointer to the newly-created string, and sets C<len> to
-reflect the new length.
+Sort an array. Here is an example:
-NOTE: this function is experimental and may change or be
-removed without notice.
+ sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
- U8* bytes_to_utf8(U8 *s, STRLEN *len)
+See lib/sort.pm for details about controlling the sorting algorithm.
+
+ void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp)
=for hackers
-Found in file utf8.c
+Found in file pp_sort.c
+
+
+=back
+
+=head1 Callback Functions
+
+=over 8
=item call_argv
=for hackers
Found in file perl.c
-=item CLASS
+=item ENTER
-Variable which is setup by C<xsubpp> to indicate the
-class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
+Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
- char* CLASS
+ ENTER;
=for hackers
-Found in file XSUB.h
+Found in file scope.h
-=item Copy
+=item eval_pv
-The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
-source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
-the type. May fail on overlapping copies. See also C<Move>.
+Tells Perl to C<eval> the given string and return an SV* result.
- void Copy(void* src, void* dest, int nitems, type)
+NOTE: the perl_ form of this function is deprecated.
-=for hackers
-Found in file handy.h
+ SV* eval_pv(const char* p, I32 croak_on_error)
-=item croak
+=for hackers
+Found in file perl.c
-This is the XSUB-writer's interface to Perl's C<die> function.
-Normally use this function the same way you use the C C<printf>
-function. See C<warn>.
+=item eval_sv
-If you want to throw an exception object, assign the object to
-C<$@> and then pass C<Nullch> to croak():
+Tells Perl to C<eval> the string in the SV.
- errsv = get_sv("@", TRUE);
- sv_setsv(errsv, exception_object);
- croak(Nullch);
+NOTE: the perl_ form of this function is deprecated.
- void croak(const char* pat, ...)
+ I32 eval_sv(SV* sv, I32 flags)
=for hackers
-Found in file util.c
+Found in file perl.c
-=item CvSTASH
+=item FREETMPS
-Returns the stash of the CV.
+Closing bracket for temporaries on a callback. See C<SAVETMPS> and
+L<perlcall>.
- HV* CvSTASH(CV* cv)
+ FREETMPS;
=for hackers
-Found in file cv.h
-
-=item cv_const_sv
+Found in file scope.h
-If C<cv> is a constant sub eligible for inlining. returns the constant
-value returned by the sub. Otherwise, returns NULL.
+=item LEAVE
-Constant subs can be created with C<newCONSTSUB> or as described in
-L<perlsub/"Constant Functions">.
+Closing bracket on a callback. See C<ENTER> and L<perlcall>.
- SV* cv_const_sv(CV* cv)
+ LEAVE;
=for hackers
-Found in file op.c
+Found in file scope.h
-=item dAX
+=item SAVETMPS
-Sets up the C<ax> variable.
-This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+Opening bracket for temporaries on a callback. See C<FREETMPS> and
+L<perlcall>.
- dAX;
+ SAVETMPS;
=for hackers
-Found in file XSUB.h
+Found in file scope.h
-=item dITEMS
-Sets up the C<items> variable.
-This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+=back
- dITEMS;
+=head1 Character classes
-=for hackers
-Found in file XSUB.h
+=over 8
-=item dMARK
+=item isALNUM
-Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
-C<dORIGMARK>.
+Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
+character (including underscore) or digit.
- dMARK;
+ bool isALNUM(char ch)
=for hackers
-Found in file pp.h
+Found in file handy.h
-=item dORIGMARK
+=item isALPHA
-Saves the original stack mark for the XSUB. See C<ORIGMARK>.
+Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
+character.
- dORIGMARK;
+ bool isALPHA(char ch)
=for hackers
-Found in file pp.h
+Found in file handy.h
-=item dSP
+=item isDIGIT
-Declares a local copy of perl's stack pointer for the XSUB, available via
-the C<SP> macro. See C<SP>.
+Returns a boolean indicating whether the C C<char> is an ASCII
+digit.
- dSP;
+ bool isDIGIT(char ch)
=for hackers
-Found in file pp.h
+Found in file handy.h
-=item dXSARGS
+=item isLOWER
-Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
-Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
-This is usually handled automatically by C<xsubpp>.
+Returns a boolean indicating whether the C C<char> is a lowercase
+character.
- dXSARGS;
+ bool isLOWER(char ch)
=for hackers
-Found in file XSUB.h
+Found in file handy.h
-=item dXSI32
+=item isSPACE
-Sets up the C<ix> variable for an XSUB which has aliases. This is usually
-handled automatically by C<xsubpp>.
+Returns a boolean indicating whether the C C<char> is whitespace.
- dXSI32;
+ bool isSPACE(char ch)
=for hackers
-Found in file XSUB.h
+Found in file handy.h
-=item ENTER
+=item isUPPER
-Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
-
- ENTER;
-
-=for hackers
-Found in file scope.h
-
-=item eval_pv
-
-Tells Perl to C<eval> the given string and return an SV* result.
-
-NOTE: the perl_ form of this function is deprecated.
-
- SV* eval_pv(const char* p, I32 croak_on_error)
-
-=for hackers
-Found in file perl.c
-
-=item eval_sv
-
-Tells Perl to C<eval> the string in the SV.
-
-NOTE: the perl_ form of this function is deprecated.
+Returns a boolean indicating whether the C C<char> is an uppercase
+character.
- I32 eval_sv(SV* sv, I32 flags)
+ bool isUPPER(char ch)
=for hackers
-Found in file perl.c
+Found in file handy.h
-=item EXTEND
+=item toLOWER
-Used to extend the argument stack for an XSUB's return values. Once
-used, guarantees that there is room for at least C<nitems> to be pushed
-onto the stack.
+Converts the specified character to lowercase.
- void EXTEND(SP, int nitems)
+ char toLOWER(char ch)
=for hackers
-Found in file pp.h
+Found in file handy.h
-=item fbm_compile
+=item toUPPER
-Analyses the string in order to make fast searches on it using fbm_instr()
--- the Boyer-Moore algorithm.
+Converts the specified character to uppercase.
- void fbm_compile(SV* sv, U32 flags)
+ char toUPPER(char ch)
=for hackers
-Found in file util.c
+Found in file handy.h
-=item fbm_instr
-Returns the location of the SV in the string delimited by C<str> and
-C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
-does not have to be fbm_compiled, but the search will not be as fast
-then.
+=back
- char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
+=head1 Cloning an interpreter
-=for hackers
-Found in file util.c
+=over 8
-=item FREETMPS
+=item perl_clone
-Closing bracket for temporaries on a callback. See C<SAVETMPS> and
-L<perlcall>.
+Create and return a new interpreter by cloning the current one.
- FREETMPS;
+ PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
=for hackers
-Found in file scope.h
-
-=item getcwd_sv
+Found in file sv.c
-Fill the sv with current working directory
- int getcwd_sv(SV* sv)
+=back
-=for hackers
-Found in file util.c
+=head1 CV Manipulation Functions
-=item get_av
+=over 8
-Returns the AV of the specified Perl array. If C<create> is set and the
-Perl variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then NULL is returned.
+=item CvSTASH
-NOTE: the perl_ form of this function is deprecated.
+Returns the stash of the CV.
- AV* get_av(const char* name, I32 create)
+ HV* CvSTASH(CV* cv)
=for hackers
-Found in file perl.c
+Found in file cv.h
=item get_cv
=for hackers
Found in file perl.c
-=item get_hv
-
-Returns the HV of the specified Perl hash. If C<create> is set and the
-Perl variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then NULL is returned.
+=item Nullcv
-NOTE: the perl_ form of this function is deprecated.
+Null CV pointer.
- HV* get_hv(const char* name, I32 create)
=for hackers
-Found in file perl.c
-
-=item get_sv
+Found in file cv.h
-Returns the SV of the specified Perl scalar. If C<create> is set and the
-Perl variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then NULL is returned.
-NOTE: the perl_ form of this function is deprecated.
+=back
- SV* get_sv(const char* name, I32 create)
+=head1 Embedding Functions
-=for hackers
-Found in file perl.c
+=over 8
-=item GIMME
+=item load_module
-A backward-compatible version of C<GIMME_V> which can only return
-C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
-Deprecated. Use C<GIMME_V> instead.
+Loads the module whose name is pointed to by the string part of name.
+Note that the actual module name, not its filename, should be given.
+Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
+PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
+(or 0 for no flags). ver, if specified, provides version semantics
+similar to C<use Foo::Bar VERSION>. The optional trailing SV*
+arguments can be used to specify arguments to the module's import()
+method, similar to C<use Foo::Bar VERSION LIST>.
- U32 GIMME
+ void load_module(U32 flags, SV* name, SV* ver, ...)
=for hackers
-Found in file op.h
+Found in file op.c
-=item GIMME_V
+=item nothreadhook
-The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
-C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
-respectively.
+Stub that provides thread hook for perl_destruct when there are
+no threads.
- U32 GIMME_V
+ int nothreadhook()
=for hackers
-Found in file op.h
-
-=item grok_number
-
-Recognise (or not) a number. The type of the number is returned
-(0 if unrecognised), otherwise it is a bit-ORed combination of
-IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
-IS_NUMBER_NEG, IS_NUMBER_INFINITY (defined in perl.h).
+Found in file perl.c
-If the value of the number can fit an in UV, it is returned in the *valuep
-IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
-will never be set unless *valuep is valid, but *valuep may have been assigned
-to during processing even though IS_NUMBER_IN_UV is not set on return.
-If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
-valuep is non-NULL, but no actual assignment (or SEGV) will occur.
+=item perl_alloc
-IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
-seen (in which case *valuep gives the true value truncated to an integer), and
-IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
-absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
-number is larger than a UV.
+Allocates a new Perl interpreter. See L<perlembed>.
- int grok_number(const char *pv, STRLEN len, UV *valuep)
+ PerlInterpreter* perl_alloc()
=for hackers
-Found in file numeric.c
+Found in file perl.c
-=item grok_numeric_radix
+=item perl_construct
-Scan and skip for a numeric decimal separator (radix).
+Initializes a new Perl interpreter. See L<perlembed>.
- bool grok_numeric_radix(const char **sp, const char *send)
+ void perl_construct(PerlInterpreter* interp)
=for hackers
-Found in file numeric.c
+Found in file perl.c
-=item GvSV
+=item perl_destruct
-Return the SV from the GV.
+Shuts down a Perl interpreter. See L<perlembed>.
- SV* GvSV(GV* gv)
+ int perl_destruct(PerlInterpreter* interp)
=for hackers
-Found in file gv.h
-
-=item gv_fetchmeth
-
-Returns the glob with the given C<name> and a defined subroutine or
-C<NULL>. The glob lives in the given C<stash>, or in the stashes
-accessible via @ISA and UNIVERSAL::.
+Found in file perl.c
-The argument C<level> should be either 0 or -1. If C<level==0>, as a
-side-effect creates a glob with the given C<name> in the given C<stash>
-which in the case of success contains an alias for the subroutine, and sets
-up caching info for this glob. Similarly for all the searched stashes.
+=item perl_free
-This function grants C<"SUPER"> token as a postfix of the stash name. The
-GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
-visible to Perl code. So when calling C<call_sv>, you should not use
-the GV directly; instead, you should use the method's CV, which can be
-obtained from the GV with the C<GvCV> macro.
+Releases a Perl interpreter. See L<perlembed>.
- GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
+ void perl_free(PerlInterpreter* interp)
=for hackers
-Found in file gv.c
+Found in file perl.c
-=item gv_fetchmethod
+=item perl_parse
-See L<gv_fetchmethod_autoload>.
+Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
- GV* gv_fetchmethod(HV* stash, const char* name)
+ int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
=for hackers
-Found in file gv.c
+Found in file perl.c
-=item gv_fetchmethod_autoload
+=item perl_run
-Returns the glob which contains the subroutine to call to invoke the method
-on the C<stash>. In fact in the presence of autoloading this may be the
-glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
-already setup.
+Tells a Perl interpreter to run. See L<perlembed>.
-The third parameter of C<gv_fetchmethod_autoload> determines whether
-AUTOLOAD lookup is performed if the given method is not present: non-zero
-means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
-Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
-with a non-zero C<autoload> parameter.
+ int perl_run(PerlInterpreter* interp)
-These functions grant C<"SUPER"> token as a prefix of the method name. Note
-that if you want to keep the returned glob for a long time, you need to
-check for it being "AUTOLOAD", since at the later time the call may load a
-different subroutine due to $AUTOLOAD changing its value. Use the glob
-created via a side effect to do this.
+=for hackers
+Found in file perl.c
-These functions have the same side-effects and as C<gv_fetchmeth> with
-C<level==0>. C<name> should be writable if contains C<':'> or C<'
-''>. The warning against passing the GV returned by C<gv_fetchmeth> to
-C<call_sv> apply equally to these functions.
+=item require_pv
- GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
+Tells Perl to C<require> the file named by the string argument. It is
+analogous to the Perl code C<eval "require '$file'">. It's even
+implemented that way; consider using Perl_load_module instead.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ void require_pv(const char* pv)
=for hackers
-Found in file gv.c
+Found in file perl.c
-=item gv_stashpv
-Returns a pointer to the stash for a specified package. C<name> should
-be a valid UTF-8 string. If C<create> is set then the package will be
-created if it does not already exist. If C<create> is not set and the
-package does not exist then NULL is returned.
+=back
- HV* gv_stashpv(const char* name, I32 create)
+=head1 Functions in file pp_pack.c
-=for hackers
-Found in file gv.c
-=item gv_stashsv
+=over 8
-Returns a pointer to the stash for a specified package, which must be a
-valid UTF-8 string. See C<gv_stashpv>.
+=item pack_cat
- HV* gv_stashsv(SV* sv, I32 create)
+The engine implementing pack() Perl function.
+
+ void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
=for hackers
-Found in file gv.c
+Found in file pp_pack.c
-=item G_ARRAY
+=item unpack_str
-Used to indicate list context. See C<GIMME_V>, C<GIMME> and
-L<perlcall>.
+The engine implementing unpack() Perl function.
+
+ I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags)
=for hackers
-Found in file cop.h
+Found in file pp_pack.c
-=item G_DISCARD
-Indicates that arguments returned from a callback should be discarded. See
-L<perlcall>.
+=back
+
+=head1 Global Variables
+
+=over 8
+
+=item PL_modglobal
+
+C<PL_modglobal> is a general purpose, interpreter global HV for use by
+extensions that need to keep information on a per-interpreter basis.
+In a pinch, it can also be used as a symbol table for extensions
+to share data among each other. It is a good idea to use keys
+prefixed by the package name of the extension that owns the data.
+
+ HV* PL_modglobal
=for hackers
-Found in file cop.h
+Found in file intrpvar.h
-=item G_EVAL
+=item PL_na
-Used to force a Perl C<eval> wrapper around a callback. See
-L<perlcall>.
+A convenience variable which is typically used with C<SvPV> when one
+doesn't care about the length of the string. It is usually more efficient
+to either declare a local variable and use that instead or to use the
+C<SvPV_nolen> macro.
+
+ STRLEN PL_na
=for hackers
-Found in file cop.h
+Found in file thrdvar.h
-=item G_NOARGS
+=item PL_sv_no
-Indicates that no arguments are being sent to a callback. See
-L<perlcall>.
+This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
+C<&PL_sv_no>.
+
+ SV PL_sv_no
=for hackers
-Found in file cop.h
+Found in file intrpvar.h
-=item G_SCALAR
+=item PL_sv_undef
-Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
-L<perlcall>.
+This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
+
+ SV PL_sv_undef
=for hackers
-Found in file cop.h
+Found in file intrpvar.h
-=item G_VOID
+=item PL_sv_yes
-Used to indicate void context. See C<GIMME_V> and L<perlcall>.
+This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
+C<&PL_sv_yes>.
+
+ SV PL_sv_yes
=for hackers
-Found in file cop.h
+Found in file intrpvar.h
+
+
+=back
+
+=head1 GV Functions
+
+=over 8
+
+=item GvSV
+
+Return the SV from the GV.
+
+ SV* GvSV(GV* gv)
+
+=for hackers
+Found in file gv.h
+
+=item gv_fetchmeth
+
+Returns the glob with the given C<name> and a defined subroutine or
+C<NULL>. The glob lives in the given C<stash>, or in the stashes
+accessible via @ISA and UNIVERSAL::.
+
+The argument C<level> should be either 0 or -1. If C<level==0>, as a
+side-effect creates a glob with the given C<name> in the given C<stash>
+which in the case of success contains an alias for the subroutine, and sets
+up caching info for this glob. Similarly for all the searched stashes.
+
+This function grants C<"SUPER"> token as a postfix of the stash name. The
+GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
+visible to Perl code. So when calling C<call_sv>, you should not use
+the GV directly; instead, you should use the method's CV, which can be
+obtained from the GV with the C<GvCV> macro.
+
+ GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
+
+=for hackers
+Found in file gv.c
+
+=item gv_fetchmethod
+
+See L<gv_fetchmethod_autoload>.
+
+ GV* gv_fetchmethod(HV* stash, const char* name)
+
+=for hackers
+Found in file gv.c
+
+=item gv_fetchmethod_autoload
+
+Returns the glob which contains the subroutine to call to invoke the method
+on the C<stash>. In fact in the presence of autoloading this may be the
+glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
+already setup.
+
+The third parameter of C<gv_fetchmethod_autoload> determines whether
+AUTOLOAD lookup is performed if the given method is not present: non-zero
+means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
+Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
+with a non-zero C<autoload> parameter.
+
+These functions grant C<"SUPER"> token as a prefix of the method name. Note
+that if you want to keep the returned glob for a long time, you need to
+check for it being "AUTOLOAD", since at the later time the call may load a
+different subroutine due to $AUTOLOAD changing its value. Use the glob
+created via a side effect to do this.
+
+These functions have the same side-effects and as C<gv_fetchmeth> with
+C<level==0>. C<name> should be writable if contains C<':'> or C<'
+''>. The warning against passing the GV returned by C<gv_fetchmeth> to
+C<call_sv> apply equally to these functions.
+
+ GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
+
+=for hackers
+Found in file gv.c
+
+=item gv_fetchmeth_autoload
+
+Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
+Returns a glob for the subroutine.
+
+For an autoloaded subroutine without a GV, will create a GV even
+if C<level < 0>. For an autoloaded subroutine without a stub, GvCV()
+of the result may be zero.
+
+ GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
+
+=for hackers
+Found in file gv.c
+
+=item gv_stashpv
+
+Returns a pointer to the stash for a specified package. C<name> should
+be a valid UTF-8 string. If C<create> is set then the package will be
+created if it does not already exist. If C<create> is not set and the
+package does not exist then NULL is returned.
+
+ HV* gv_stashpv(const char* name, I32 create)
+
+=for hackers
+Found in file gv.c
+
+=item gv_stashsv
+
+Returns a pointer to the stash for a specified package, which must be a
+valid UTF-8 string. See C<gv_stashpv>.
+
+ HV* gv_stashsv(SV* sv, I32 create)
+
+=for hackers
+Found in file gv.c
+
+
+=back
+
+=head1 Handy Values
+
+=over 8
=item HEf_SVKEY
This flag, used in the length slot of hash entries and magic structures,
-specifies the structure contains a C<SV*> pointer where a C<char*> pointer
+specifies the structure contains an C<SV*> pointer where a C<char*> pointer
is to be expected. (For information only--not to be used).
+
=for hackers
Found in file hv.h
+=item Nullch
+
+Null character pointer.
+=for hackers
+Found in file handy.h
+
+=item Nullsv
+
+Null SV pointer.
+
+=for hackers
+Found in file handy.h
+
+
+=back
+
+=head1 Hash Manipulation Functions
+
+=over 8
+
+=item get_hv
+
+Returns the HV of the specified Perl hash. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ HV* get_hv(const char* name, I32 create)
+
+=for hackers
+Found in file perl.c
+
=item HeHASH
Returns the computed hash stored in the hash entry.
C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
usually preferable for finding the value of a key.
- void* HeKEY(HE* he)
+ void* HeKEY(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeKLEN
+
+If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
+holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
+be assigned to. The C<HePV()> macro is usually preferable for finding key
+lengths.
+
+ STRLEN HeKLEN(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HePV
+
+Returns the key slot of the hash entry as a C<char*> value, doing any
+necessary dereferencing of possibly C<SV*> keys. The length of the string
+is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
+not care about what the length of the key is, you may use the global
+variable C<PL_na>, though this is rather less efficient than using a local
+variable. Remember though, that hash keys in perl are free to contain
+embedded nulls, so using C<strlen()> or similar is not a good way to find
+the length of hash keys. This is very similar to the C<SvPV()> macro
+described elsewhere in this document.
+
+ char* HePV(HE* he, STRLEN len)
+
+=for hackers
+Found in file hv.h
+
+=item HeSVKEY
+
+Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
+contain an C<SV*> key.
+
+ SV* HeSVKEY(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeSVKEY_force
+
+Returns the key as an C<SV*>. Will create and return a temporary mortal
+C<SV*> if the hash entry contains only a C<char*> key.
+
+ SV* HeSVKEY_force(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeSVKEY_set
+
+Sets the key to a given C<SV*>, taking care to set the appropriate flags to
+indicate the presence of an C<SV*> key, and returns the same
+C<SV*>.
+
+ SV* HeSVKEY_set(HE* he, SV* sv)
+
+=for hackers
+Found in file hv.h
+
+=item HeVAL
+
+Returns the value slot (type C<SV*>) stored in the hash entry.
+
+ SV* HeVAL(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HvNAME
+
+Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
+
+ char* HvNAME(HV* stash)
+
+=for hackers
+Found in file hv.h
+
+=item hv_clear
+
+Clears a hash, making it empty.
+
+ void hv_clear(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_delete
+
+Deletes a key/value pair in the hash. The value SV is removed from the
+hash and returned to the caller. The C<klen> is the length of the key.
+The C<flags> value will normally be zero; if set to G_DISCARD then NULL
+will be returned.
+
+ SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
+
+=for hackers
+Found in file hv.c
+
+=item hv_delete_ent
+
+Deletes a key/value pair in the hash. The value SV is removed from the
+hash and returned to the caller. The C<flags> value will normally be zero;
+if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
+precomputed hash value, or 0 to ask for it to be computed.
+
+ SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_exists
+
+Returns a boolean indicating whether the specified hash key exists. The
+C<klen> is the length of the key.
+
+ bool hv_exists(HV* tb, const char* key, I32 klen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_exists_ent
+
+Returns a boolean indicating whether the specified hash key exists. C<hash>
+can be a valid precomputed hash value, or 0 to ask for it to be
+computed.
+
+ bool hv_exists_ent(HV* tb, SV* key, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_fetch
+
+Returns the SV which corresponds to the specified key in the hash. The
+C<klen> is the length of the key. If C<lval> is set then the fetch will be
+part of a store. Check that the return value is non-null before
+dereferencing it to an C<SV*>.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
+
+=for hackers
+Found in file hv.c
+
+=item hv_fetch_ent
+
+Returns the hash entry which corresponds to the specified key in the hash.
+C<hash> must be a valid precomputed hash number for the given C<key>, or 0
+if you want the function to compute it. IF C<lval> is set then the fetch
+will be part of a store. Make sure the return value is non-null before
+accessing it. The return value when C<tb> is a tied hash is a pointer to a
+static location, so be sure to make a copy of the structure if you need to
+store it somewhere.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterinit
+
+Prepares a starting point to traverse a hash table. Returns the number of
+keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
+currently only meaningful for hashes without tie magic.
+
+NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
+hash buckets that happen to be in use. If you still need that esoteric
+value, you can get it through the macro C<HvFILL(tb)>.
+
+
+ I32 hv_iterinit(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterkey
+
+Returns the key from the current position of the hash iterator. See
+C<hv_iterinit>.
+
+ char* hv_iterkey(HE* entry, I32* retlen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterkeysv
+
+Returns the key as an C<SV*> from the current position of the hash
+iterator. The return value will always be a mortal copy of the key. Also
+see C<hv_iterinit>.
+
+ SV* hv_iterkeysv(HE* entry)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternext
+
+Returns entries from a hash iterator. See C<hv_iterinit>.
+
+You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
+iterator currently points to, without losing your place or invalidating your
+iterator. Note that in this case the current entry is deleted from the hash
+with your iterator holding the last reference to it. Your iterator is flagged
+to free the entry on the next call to C<hv_iternext>, so you must not discard
+your iterator immediately else the entry will leak - call C<hv_iternext> to
+trigger the resource deallocation.
+
+ HE* hv_iternext(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternextsv
+
+Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
+operation.
+
+ SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternext_flags
+
+Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
+The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
+set the placeholders keys (for restricted hashes) will be returned in addition
+to normal keys. By default placeholders are automatically skipped over.
+Currently a placeholder is implemented with a value that is literally
+<&Perl_sv_undef> (a regular C<undef> value is a normal read-write SV for which
+C<!SvOK> is false). Note that the implementation of placeholders and
+restricted hashes may change, and the implementation currently is
+insufficiently abstracted for any change to be tidy.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ HE* hv_iternext_flags(HV* tb, I32 flags)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterval
+
+Returns the value from the current position of the hash iterator. See
+C<hv_iterkey>.
+
+ SV* hv_iterval(HV* tb, HE* entry)
+
+=for hackers
+Found in file hv.c
+
+=item hv_magic
+
+Adds magic to a hash. See C<sv_magic>.
+
+ void hv_magic(HV* hv, GV* gv, int how)
+
+=for hackers
+Found in file hv.c
+
+=item hv_store
+
+Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
+the length of the key. The C<hash> parameter is the precomputed hash
+value; if it is zero then Perl will compute it. The return value will be
+NULL if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes). Otherwise it can
+be dereferenced to get the original C<SV*>. Note that the caller is
+responsible for suitably incrementing the reference count of C<val> before
+the call, and decrementing it if the function returned NULL.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_store_ent
+
+Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
+parameter is the precomputed hash value; if it is zero then Perl will
+compute it. The return value is the new hash entry so created. It will be
+NULL if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes). Otherwise the
+contents of the return value can be accessed using the C<He?> macros
+described here. Note that the caller is responsible for suitably
+incrementing the reference count of C<val> before the call, and
+decrementing it if the function returned NULL.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_undef
+
+Undefines the hash.
+
+ void hv_undef(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item newHV
+
+Creates a new HV. The reference count is set to 1.
+
+ HV* newHV()
+
+=for hackers
+Found in file hv.c
+
+=item Nullhv
+
+Null HV pointer.
+
+
+=for hackers
+Found in file hv.h
+
+
+=back
+
+=head1 Magical Functions
+
+=over 8
+
+=item mg_clear
+
+Clear something magical that the SV represents. See C<sv_magic>.
+
+ int mg_clear(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_copy
+
+Copies the magic from one SV to another. See C<sv_magic>.
+
+ int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
+
+=for hackers
+Found in file mg.c
+
+=item mg_find
+
+Finds the magic pointer for type matching the SV. See C<sv_magic>.
+
+ MAGIC* mg_find(SV* sv, int type)
+
+=for hackers
+Found in file mg.c
+
+=item mg_free
+
+Free any magic storage used by the SV. See C<sv_magic>.
+
+ int mg_free(SV* sv)
=for hackers
-Found in file hv.h
+Found in file mg.c
-=item HeKLEN
+=item mg_get
-If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
-holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
-be assigned to. The C<HePV()> macro is usually preferable for finding key
-lengths.
+Do magic after a value is retrieved from the SV. See C<sv_magic>.
- STRLEN HeKLEN(HE* he)
+ int mg_get(SV* sv)
=for hackers
-Found in file hv.h
+Found in file mg.c
-=item HePV
+=item mg_length
-Returns the key slot of the hash entry as a C<char*> value, doing any
-necessary dereferencing of possibly C<SV*> keys. The length of the string
-is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
-not care about what the length of the key is, you may use the global
-variable C<PL_na>, though this is rather less efficient than using a local
-variable. Remember though, that hash keys in perl are free to contain
-embedded nulls, so using C<strlen()> or similar is not a good way to find
-the length of hash keys. This is very similar to the C<SvPV()> macro
-described elsewhere in this document.
+Report on the SV's length. See C<sv_magic>.
- char* HePV(HE* he, STRLEN len)
+ U32 mg_length(SV* sv)
=for hackers
-Found in file hv.h
+Found in file mg.c
-=item HeSVKEY
+=item mg_magical
-Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
-contain an C<SV*> key.
+Turns on the magical status of an SV. See C<sv_magic>.
- SV* HeSVKEY(HE* he)
+ void mg_magical(SV* sv)
=for hackers
-Found in file hv.h
+Found in file mg.c
-=item HeSVKEY_force
+=item mg_set
-Returns the key as an C<SV*>. Will create and return a temporary mortal
-C<SV*> if the hash entry contains only a C<char*> key.
+Do magic after a value is assigned to the SV. See C<sv_magic>.
- SV* HeSVKEY_force(HE* he)
+ int mg_set(SV* sv)
=for hackers
-Found in file hv.h
+Found in file mg.c
-=item HeSVKEY_set
+=item SvGETMAGIC
-Sets the key to a given C<SV*>, taking care to set the appropriate flags to
-indicate the presence of an C<SV*> key, and returns the same
-C<SV*>.
+Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
+argument more than once.
- SV* HeSVKEY_set(HE* he, SV* sv)
+ void SvGETMAGIC(SV* sv)
=for hackers
-Found in file hv.h
+Found in file sv.h
-=item HeVAL
+=item SvLOCK
-Returns the value slot (type C<SV*>) stored in the hash entry.
+Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
+has been loaded.
- SV* HeVAL(HE* he)
+ void SvLOCK(SV* sv)
=for hackers
-Found in file hv.h
+Found in file sv.h
-=item HvNAME
+=item SvSETMAGIC
-Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
+Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
+argument more than once.
- char* HvNAME(HV* stash)
+ void SvSETMAGIC(SV* sv)
=for hackers
-Found in file hv.h
+Found in file sv.h
-=item hv_clear
+=item SvSetMagicSV
-Clears a hash, making it empty.
+Like C<SvSetSV>, but does any set magic required afterwards.
- void hv_clear(HV* tb)
+ void SvSetMagicSV(SV* dsb, SV* ssv)
=for hackers
-Found in file hv.c
+Found in file sv.h
-=item hv_delete
+=item SvSetMagicSV_nosteal
-Deletes a key/value pair in the hash. The value SV is removed from the
-hash and returned to the caller. The C<klen> is the length of the key.
-The C<flags> value will normally be zero; if set to G_DISCARD then NULL
-will be returned.
+Like C<SvSetMagicSV>, but does any set magic required afterwards.
- SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
+ void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
=for hackers
-Found in file hv.c
+Found in file sv.h
-=item hv_delete_ent
+=item SvSetSV
-Deletes a key/value pair in the hash. The value SV is removed from the
-hash and returned to the caller. The C<flags> value will normally be zero;
-if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
-precomputed hash value, or 0 to ask for it to be computed.
+Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
+more than once.
- SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
+ void SvSetSV(SV* dsb, SV* ssv)
=for hackers
-Found in file hv.c
+Found in file sv.h
-=item hv_exists
+=item SvSetSV_nosteal
-Returns a boolean indicating whether the specified hash key exists. The
-C<klen> is the length of the key.
+Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
+ssv. May evaluate arguments more than once.
- bool hv_exists(HV* tb, const char* key, I32 klen)
+ void SvSetSV_nosteal(SV* dsv, SV* ssv)
=for hackers
-Found in file hv.c
+Found in file sv.h
-=item hv_exists_ent
+=item SvSHARE
-Returns a boolean indicating whether the specified hash key exists. C<hash>
-can be a valid precomputed hash value, or 0 to ask for it to be
-computed.
+Arranges for sv to be shared between threads if a suitable module
+has been loaded.
- bool hv_exists_ent(HV* tb, SV* key, U32 hash)
+ void SvSHARE(SV* sv)
=for hackers
-Found in file hv.c
-
-=item hv_fetch
-
-Returns the SV which corresponds to the specified key in the hash. The
-C<klen> is the length of the key. If C<lval> is set then the fetch will be
-part of a store. Check that the return value is non-null before
-dereferencing it to a C<SV*>.
+Found in file sv.h
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
- SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
+=back
-=for hackers
-Found in file hv.c
+=head1 Memory Management
-=item hv_fetch_ent
+=over 8
-Returns the hash entry which corresponds to the specified key in the hash.
-C<hash> must be a valid precomputed hash number for the given C<key>, or 0
-if you want the function to compute it. IF C<lval> is set then the fetch
-will be part of a store. Make sure the return value is non-null before
-accessing it. The return value when C<tb> is a tied hash is a pointer to a
-static location, so be sure to make a copy of the structure if you need to
-store it somewhere.
+=item Copy
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
+The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
+source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
+the type. May fail on overlapping copies. See also C<Move>.
- HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
+ void Copy(void* src, void* dest, int nitems, type)
=for hackers
-Found in file hv.c
-
-=item hv_iterinit
+Found in file handy.h
-Prepares a starting point to traverse a hash table. Returns the number of
-keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
-currently only meaningful for hashes without tie magic.
+=item Move
-NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
-hash buckets that happen to be in use. If you still need that esoteric
-value, you can get it through the macro C<HvFILL(tb)>.
+The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
+source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
+the type. Can do overlapping moves. See also C<Copy>.
- I32 hv_iterinit(HV* tb)
+ void Move(void* src, void* dest, int nitems, type)
=for hackers
-Found in file hv.c
+Found in file handy.h
-=item hv_iterkey
+=item New
-Returns the key from the current position of the hash iterator. See
-C<hv_iterinit>.
+The XSUB-writer's interface to the C C<malloc> function.
- char* hv_iterkey(HE* entry, I32* retlen)
+ void New(int id, void* ptr, int nitems, type)
=for hackers
-Found in file hv.c
+Found in file handy.h
-=item hv_iterkeysv
+=item Newc
-Returns the key as an C<SV*> from the current position of the hash
-iterator. The return value will always be a mortal copy of the key. Also
-see C<hv_iterinit>.
+The XSUB-writer's interface to the C C<malloc> function, with
+cast.
- SV* hv_iterkeysv(HE* entry)
+ void Newc(int id, void* ptr, int nitems, type, cast)
=for hackers
-Found in file hv.c
+Found in file handy.h
-=item hv_iternext
+=item NEWSV
-Returns entries from a hash iterator. See C<hv_iterinit>.
+Creates a new SV. A non-zero C<len> parameter indicates the number of
+bytes of preallocated string space the SV should have. An extra byte for a
+tailing NUL is also reserved. (SvPOK is not set for the SV even if string
+space is allocated.) The reference count for the new SV is set to 1.
+C<id> is an integer id between 0 and 1299 (used to identify leaks).
- HE* hv_iternext(HV* tb)
+
+ SV* NEWSV(int id, STRLEN len)
=for hackers
-Found in file hv.c
+Found in file handy.h
-=item hv_iternextsv
+=item Newz
-Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
-operation.
+The XSUB-writer's interface to the C C<malloc> function. The allocated
+memory is zeroed with C<memzero>.
- SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
+ void Newz(int id, void* ptr, int nitems, type)
=for hackers
-Found in file hv.c
+Found in file handy.h
-=item hv_iterval
+=item Poison
-Returns the value from the current position of the hash iterator. See
-C<hv_iterkey>.
+Fill up memory with a pattern (byte 0xAB over and over again) that
+hopefully catches attempts to access uninitialized memory.
- SV* hv_iterval(HV* tb, HE* entry)
+ void Poison(void* dest, int nitems, type)
=for hackers
-Found in file hv.c
+Found in file handy.h
-=item hv_magic
+=item Renew
-Adds magic to a hash. See C<sv_magic>.
+The XSUB-writer's interface to the C C<realloc> function.
- void hv_magic(HV* hv, GV* gv, int how)
+ void Renew(void* ptr, int nitems, type)
=for hackers
-Found in file hv.c
-
-=item hv_store
+Found in file handy.h
-Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
-the length of the key. The C<hash> parameter is the precomputed hash
-value; if it is zero then Perl will compute it. The return value will be
-NULL if the operation failed or if the value did not need to be actually
-stored within the hash (as in the case of tied hashes). Otherwise it can
-be dereferenced to get the original C<SV*>. Note that the caller is
-responsible for suitably incrementing the reference count of C<val> before
-the call, and decrementing it if the function returned NULL.
+=item Renewc
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
+The XSUB-writer's interface to the C C<realloc> function, with
+cast.
- SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
+ void Renewc(void* ptr, int nitems, type, cast)
=for hackers
-Found in file hv.c
-
-=item hv_store_ent
+Found in file handy.h
-Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
-parameter is the precomputed hash value; if it is zero then Perl will
-compute it. The return value is the new hash entry so created. It will be
-NULL if the operation failed or if the value did not need to be actually
-stored within the hash (as in the case of tied hashes). Otherwise the
-contents of the return value can be accessed using the C<He?> macros
-described here. Note that the caller is responsible for suitably
-incrementing the reference count of C<val> before the call, and
-decrementing it if the function returned NULL.
+=item Safefree
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
+The XSUB-writer's interface to the C C<free> function.
- HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
+ void Safefree(void* ptr)
=for hackers
-Found in file hv.c
+Found in file handy.h
-=item hv_undef
+=item savepv
-Undefines the hash.
+Perl's version of C<strdup()>. Returns a pointer to a newly allocated
+string which is a duplicate of C<pv>. The size of the string is
+determined by C<strlen()>. The memory allocated for the new string can
+be freed with the C<Safefree()> function.
- void hv_undef(HV* tb)
+ char* savepv(const char* pv)
=for hackers
-Found in file hv.c
+Found in file util.c
-=item isALNUM
+=item savepvn
-Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
-character (including underscore) or digit.
+Perl's version of what C<strndup()> would be if it existed. Returns a
+pointer to a newly allocated string which is a duplicate of the first
+C<len> bytes from C<pv>. The memory allocated for the new string can be
+freed with the C<Safefree()> function.
- bool isALNUM(char ch)
+ char* savepvn(const char* pv, I32 len)
=for hackers
-Found in file handy.h
+Found in file util.c
-=item isALPHA
+=item savesharedpv
-Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
-character.
+A version of C<savepv()> which allocates the duplicate string in memory
+which is shared between threads.
- bool isALPHA(char ch)
+ char* savesharedpv(const char* pv)
=for hackers
-Found in file handy.h
+Found in file util.c
-=item isDIGIT
+=item StructCopy
-Returns a boolean indicating whether the C C<char> is an ASCII
-digit.
+This is an architecture-independent macro to copy one structure to another.
- bool isDIGIT(char ch)
+ void StructCopy(type src, type dest, type)
=for hackers
Found in file handy.h
-=item isLOWER
+=item Zero
-Returns a boolean indicating whether the C C<char> is a lowercase
-character.
+The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
+destination, C<nitems> is the number of items, and C<type> is the type.
- bool isLOWER(char ch)
+ void Zero(void* dest, int nitems, type)
=for hackers
Found in file handy.h
-=item isSPACE
-Returns a boolean indicating whether the C C<char> is whitespace.
+=back
- bool isSPACE(char ch)
+=head1 Miscellaneous Functions
-=for hackers
-Found in file handy.h
+=over 8
-=item isUPPER
+=item fbm_compile
-Returns a boolean indicating whether the C C<char> is an uppercase
-character.
+Analyses the string in order to make fast searches on it using fbm_instr()
+-- the Boyer-Moore algorithm.
- bool isUPPER(char ch)
+ void fbm_compile(SV* sv, U32 flags)
=for hackers
-Found in file handy.h
+Found in file util.c
-=item is_utf8_char
+=item fbm_instr
-Tests if some arbitrary number of bytes begins in a valid UTF-8
-character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character.
-The actual number of bytes in the UTF-8 character will be returned if
-it is valid, otherwise 0.
+Returns the location of the SV in the string delimited by C<str> and
+C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
+does not have to be fbm_compiled, but the search will not be as fast
+then.
- STRLEN is_utf8_char(U8 *p)
+ char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
=for hackers
-Found in file utf8.c
+Found in file util.c
-=item is_utf8_string
+=item form
-Returns true if first C<len> bytes of the given string form a valid UTF8
-string, false otherwise. Note that 'a valid UTF8 string' does not mean
-'a string that contains UTF8' because a valid ASCII string is a valid
-UTF8 string.
+Takes a sprintf-style format pattern and conventional
+(non-SV) arguments and returns the formatted string.
- bool is_utf8_string(U8 *s, STRLEN len)
+ (char *) Perl_form(pTHX_ const char* pat, ...)
+
+can be used any place a string (char *) is required:
+
+ char * s = Perl_form("%d.%d",major,minor);
+
+Uses a single private buffer so if you want to format several strings you
+must explicitly copy the earlier strings away (and free the copies when you
+are done).
+
+ char* form(const char* pat, ...)
=for hackers
-Found in file utf8.c
+Found in file util.c
-=item items
+=item getcwd_sv
-Variable which is setup by C<xsubpp> to indicate the number of
-items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
+Fill the sv with current working directory
- I32 items
+ int getcwd_sv(SV* sv)
=for hackers
-Found in file XSUB.h
+Found in file util.c
-=item ix
+=item strEQ
-Variable which is setup by C<xsubpp> to indicate which of an
-XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
+Test two strings to see if they are equal. Returns true or false.
- I32 ix
+ bool strEQ(char* s1, char* s2)
=for hackers
-Found in file XSUB.h
+Found in file handy.h
-=item LEAVE
+=item strGE
-Closing bracket on a callback. See C<ENTER> and L<perlcall>.
+Test two strings to see if the first, C<s1>, is greater than or equal to
+the second, C<s2>. Returns true or false.
- LEAVE;
+ bool strGE(char* s1, char* s2)
=for hackers
-Found in file scope.h
+Found in file handy.h
-=item load_module
+=item strGT
-Loads the module whose name is pointed to by the string part of name.
-Note that the actual module name, not its filename, should be given.
-Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
-PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
-(or 0 for no flags). ver, if specified, provides version semantics
-similar to C<use Foo::Bar VERSION>. The optional trailing SV*
-arguments can be used to specify arguments to the module's import()
-method, similar to C<use Foo::Bar VERSION LIST>.
+Test two strings to see if the first, C<s1>, is greater than the second,
+C<s2>. Returns true or false.
- void load_module(U32 flags, SV* name, SV* ver, ...)
+ bool strGT(char* s1, char* s2)
=for hackers
-Found in file op.c
+Found in file handy.h
-=item looks_like_number
+=item strLE
-Test if the content of an SV looks like a number (or is a number).
-C<Inf> and C<Infinity> are treated as numbers (so will not issue a
-non-numeric warning), even if your atof() doesn't grok them.
+Test two strings to see if the first, C<s1>, is less than or equal to the
+second, C<s2>. Returns true or false.
- I32 looks_like_number(SV* sv)
+ bool strLE(char* s1, char* s2)
=for hackers
-Found in file sv.c
+Found in file handy.h
-=item MARK
+=item strLT
-Stack marker variable for the XSUB. See C<dMARK>.
+Test two strings to see if the first, C<s1>, is less than the second,
+C<s2>. Returns true or false.
+
+ bool strLT(char* s1, char* s2)
=for hackers
-Found in file pp.h
+Found in file handy.h
-=item mg_clear
+=item strNE
-Clear something magical that the SV represents. See C<sv_magic>.
+Test two strings to see if they are different. Returns true or
+false.
- int mg_clear(SV* sv)
+ bool strNE(char* s1, char* s2)
=for hackers
-Found in file mg.c
+Found in file handy.h
-=item mg_copy
+=item strnEQ
-Copies the magic from one SV to another. See C<sv_magic>.
+Test two strings to see if they are equal. The C<len> parameter indicates
+the number of bytes to compare. Returns true or false. (A wrapper for
+C<strncmp>).
- int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
+ bool strnEQ(char* s1, char* s2, STRLEN len)
=for hackers
-Found in file mg.c
+Found in file handy.h
-=item mg_find
+=item strnNE
-Finds the magic pointer for type matching the SV. See C<sv_magic>.
+Test two strings to see if they are different. The C<len> parameter
+indicates the number of bytes to compare. Returns true or false. (A
+wrapper for C<strncmp>).
- MAGIC* mg_find(SV* sv, int type)
+ bool strnNE(char* s1, char* s2, STRLEN len)
=for hackers
-Found in file mg.c
+Found in file handy.h
-=item mg_free
-Free any magic storage used by the SV. See C<sv_magic>.
+=back
- int mg_free(SV* sv)
+=head1 Numeric functions
+
+=over 8
+
+=item grok_bin
+
+converts a string representing a binary number to numeric form.
+
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first invalid character.
+On return I<*len> is set to the length scanned string, and I<*flags> gives
+output flags.
+
+If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
+returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+and writes the value to I<*result> (or the value is discarded if I<result>
+is NULL).
+
+The hex number may optionally be prefixed with "0b" or "b" unless
+C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
+C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
+number may use '_' characters to separate digits.
+
+ UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
=for hackers
-Found in file mg.c
+Found in file numeric.c
-=item mg_get
+=item grok_hex
-Do magic after a value is retrieved from the SV. See C<sv_magic>.
+converts a string representing a hex number to numeric form.
- int mg_get(SV* sv)
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first non-hex-digit character.
+On return I<*len> is set to the length scanned string, and I<*flags> gives
+output flags.
+
+If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
+returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+and writes the value to I<*result> (or the value is discarded if I<result>
+is NULL).
+
+The hex number may optionally be prefixed with "0x" or "x" unless
+C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
+C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
+number may use '_' characters to separate digits.
+
+ UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
=for hackers
-Found in file mg.c
+Found in file numeric.c
-=item mg_length
+=item grok_number
-Report on the SV's length. See C<sv_magic>.
+Recognise (or not) a number. The type of the number is returned
+(0 if unrecognised), otherwise it is a bit-ORed combination of
+IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
+IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
- U32 mg_length(SV* sv)
+If the value of the number can fit an in UV, it is returned in the *valuep
+IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
+will never be set unless *valuep is valid, but *valuep may have been assigned
+to during processing even though IS_NUMBER_IN_UV is not set on return.
+If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
+valuep is non-NULL, but no actual assignment (or SEGV) will occur.
+
+IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
+seen (in which case *valuep gives the true value truncated to an integer), and
+IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
+absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
+number is larger than a UV.
+
+ int grok_number(const char *pv, STRLEN len, UV *valuep)
=for hackers
-Found in file mg.c
+Found in file numeric.c
-=item mg_magical
+=item grok_numeric_radix
-Turns on the magical status of an SV. See C<sv_magic>.
+Scan and skip for a numeric decimal separator (radix).
- void mg_magical(SV* sv)
+ bool grok_numeric_radix(const char **sp, const char *send)
=for hackers
-Found in file mg.c
+Found in file numeric.c
-=item mg_set
+=item grok_oct
-Do magic after a value is assigned to the SV. See C<sv_magic>.
- int mg_set(SV* sv)
+ UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
=for hackers
-Found in file mg.c
+Found in file numeric.c
-=item Move
+=item scan_bin
-The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
-source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
-the type. Can do overlapping moves. See also C<Copy>.
+For backwards compatibility. Use C<grok_bin> instead.
- void Move(void* src, void* dest, int nitems, type)
+ NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
=for hackers
-Found in file handy.h
+Found in file numeric.c
-=item New
+=item scan_hex
-The XSUB-writer's interface to the C C<malloc> function.
+For backwards compatibility. Use C<grok_hex> instead.
- void New(int id, void* ptr, int nitems, type)
+ NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
=for hackers
-Found in file handy.h
+Found in file numeric.c
-=item newAV
+=item scan_oct
-Creates a new AV. The reference count is set to 1.
+For backwards compatibility. Use C<grok_oct> instead.
- AV* newAV()
+ NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
=for hackers
-Found in file av.c
+Found in file numeric.c
+
+
+=back
+
+=head1 Optree Manipulation Functions
+
+=over 8
+
+=item cv_const_sv
-=item Newc
+If C<cv> is a constant sub eligible for inlining. returns the constant
+value returned by the sub. Otherwise, returns NULL.
-The XSUB-writer's interface to the C C<malloc> function, with
-cast.
+Constant subs can be created with C<newCONSTSUB> or as described in
+L<perlsub/"Constant Functions">.
- void Newc(int id, void* ptr, int nitems, type, cast)
+ SV* cv_const_sv(CV* cv)
=for hackers
-Found in file handy.h
+Found in file op.c
=item newCONSTSUB
=for hackers
Found in file op.c
-=item newHV
-
-Creates a new HV. The reference count is set to 1.
+=item newXS
- HV* newHV()
+Used by C<xsubpp> to hook up XSUBs as Perl subs.
=for hackers
-Found in file hv.c
+Found in file op.c
-=item newRV_inc
-Creates an RV wrapper for an SV. The reference count for the original SV is
-incremented.
+=back
- SV* newRV_inc(SV* sv)
+=head1 Stack Manipulation Macros
-=for hackers
-Found in file sv.h
+=over 8
-=item newRV_noinc
+=item dMARK
-Creates an RV wrapper for an SV. The reference count for the original
-SV is B<not> incremented.
+Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
+C<dORIGMARK>.
- SV* newRV_noinc(SV *sv)
+ dMARK;
=for hackers
-Found in file sv.c
+Found in file pp.h
-=item newSV
+=item dORIGMARK
-Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
-with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
-macro.
+Saves the original stack mark for the XSUB. See C<ORIGMARK>.
- SV* newSV(STRLEN len)
+ dORIGMARK;
=for hackers
-Found in file sv.c
+Found in file pp.h
-=item NEWSV
+=item dSP
-Creates a new SV. A non-zero C<len> parameter indicates the number of
-bytes of preallocated string space the SV should have. An extra byte for a
-tailing NUL is also reserved. (SvPOK is not set for the SV even if string
-space is allocated.) The reference count for the new SV is set to 1.
-C<id> is an integer id between 0 and 1299 (used to identify leaks).
+Declares a local copy of perl's stack pointer for the XSUB, available via
+the C<SP> macro. See C<SP>.
- SV* NEWSV(int id, STRLEN len)
+ dSP;
=for hackers
-Found in file handy.h
+Found in file pp.h
-=item newSViv
+=item EXTEND
-Creates a new SV and copies an integer into it. The reference count for the
-SV is set to 1.
+Used to extend the argument stack for an XSUB's return values. Once
+used, guarantees that there is room for at least C<nitems> to be pushed
+onto the stack.
- SV* newSViv(IV i)
+ void EXTEND(SP, int nitems)
=for hackers
-Found in file sv.c
-
-=item newSVnv
+Found in file pp.h
-Creates a new SV and copies a floating point value into it.
-The reference count for the SV is set to 1.
+=item MARK
- SV* newSVnv(NV n)
+Stack marker variable for the XSUB. See C<dMARK>.
=for hackers
-Found in file sv.c
-
-=item newSVpv
+Found in file pp.h
-Creates a new SV and copies a string into it. The reference count for the
-SV is set to 1. If C<len> is zero, Perl will compute the length using
-strlen(). For efficiency, consider using C<newSVpvn> instead.
+=item ORIGMARK
- SV* newSVpv(const char* s, STRLEN len)
+The original stack mark for the XSUB. See C<dORIGMARK>.
=for hackers
-Found in file sv.c
+Found in file pp.h
-=item newSVpvf
+=item POPi
-Creates a new SV and initializes it with the string formatted like
-C<sprintf>.
+Pops an integer off the stack.
- SV* newSVpvf(const char* pat, ...)
+ IV POPi
=for hackers
-Found in file sv.c
+Found in file pp.h
-=item newSVpvn
+=item POPl
-Creates a new SV and copies a string into it. The reference count for the
-SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
-string. You are responsible for ensuring that the source string is at least
-C<len> bytes long.
+Pops a long off the stack.
- SV* newSVpvn(const char* s, STRLEN len)
+ long POPl
=for hackers
-Found in file sv.c
+Found in file pp.h
-=item newSVpvn_share
+=item POPn
-Creates a new SV with its SvPVX pointing to a shared string in the string
-table. If the string does not already exist in the table, it is created
-first. Turns on READONLY and FAKE. The string's hash is stored in the UV
-slot of the SV; if the C<hash> parameter is non-zero, that value is used;
-otherwise the hash is computed. The idea here is that as the string table
-is used for shared hash keys these strings will have SvPVX == HeKEY and
-hash lookup will avoid string compare.
+Pops a double off the stack.
- SV* newSVpvn_share(const char* s, I32 len, U32 hash)
+ NV POPn
=for hackers
-Found in file sv.c
+Found in file pp.h
-=item newSVrv
+=item POPp
-Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
-it will be upgraded to one. If C<classname> is non-null then the new SV will
-be blessed in the specified package. The new SV is returned and its
-reference count is 1.
+Pops a string off the stack. Deprecated. New code should provide
+a STRLEN n_a and use POPpx.
- SV* newSVrv(SV* rv, const char* classname)
+ char* POPp
=for hackers
-Found in file sv.c
+Found in file pp.h
-=item newSVsv
+=item POPpbytex
-Creates a new SV which is an exact duplicate of the original SV.
-(Uses C<sv_setsv>).
+Pops a string off the stack which must consist of bytes i.e. characters < 256.
+Requires a variable STRLEN n_a in scope.
- SV* newSVsv(SV* old)
+ char* POPpbytex
=for hackers
-Found in file sv.c
+Found in file pp.h
-=item newSVuv
+=item POPpx
-Creates a new SV and copies an unsigned integer into it.
-The reference count for the SV is set to 1.
+Pops a string off the stack.
+Requires a variable STRLEN n_a in scope.
- SV* newSVuv(UV u)
+ char* POPpx
=for hackers
-Found in file sv.c
-
-=item newXS
-
-Used by C<xsubpp> to hook up XSUBs as Perl subs.
+Found in file pp.h
-=for hackers
-Found in file op.c
+=item POPs
-=item newXSproto
+Pops an SV off the stack.
-Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
-the subs.
+ SV* POPs
=for hackers
-Found in file XSUB.h
+Found in file pp.h
-=item Newz
+=item PUSHi
-The XSUB-writer's interface to the C C<malloc> function. The allocated
-memory is zeroed with C<memzero>.
+Push an integer onto the stack. The stack must have room for this element.
+Handles 'set' magic. See C<XPUSHi>.
- void Newz(int id, void* ptr, int nitems, type)
+ void PUSHi(IV iv)
=for hackers
-Found in file handy.h
-
-=item Nullav
-
-Null AV pointer.
+Found in file pp.h
-=for hackers
-Found in file av.h
+=item PUSHMARK
-=item Nullch
+Opening bracket for arguments on a callback. See C<PUTBACK> and
+L<perlcall>.
-Null character pointer.
+ PUSHMARK;
=for hackers
-Found in file handy.h
+Found in file pp.h
-=item Nullcv
+=item PUSHn
-Null CV pointer.
+Push a double onto the stack. The stack must have room for this element.
+Handles 'set' magic. See C<XPUSHn>.
+
+ void PUSHn(NV nv)
=for hackers
-Found in file cv.h
+Found in file pp.h
-=item Nullhv
+=item PUSHp
-Null HV pointer.
+Push a string onto the stack. The stack must have room for this element.
+The C<len> indicates the length of the string. Handles 'set' magic. See
+C<XPUSHp>.
+
+ void PUSHp(char* str, STRLEN len)
=for hackers
-Found in file hv.h
+Found in file pp.h
-=item Nullsv
+=item PUSHs
-Null SV pointer.
+Push an SV onto the stack. The stack must have room for this element.
+Does not handle 'set' magic. See C<XPUSHs>.
+
+ void PUSHs(SV* sv)
=for hackers
-Found in file handy.h
+Found in file pp.h
-=item ORIGMARK
+=item PUSHu
-The original stack mark for the XSUB. See C<dORIGMARK>.
+Push an unsigned integer onto the stack. The stack must have room for this
+element. See C<XPUSHu>.
+
+ void PUSHu(UV uv)
=for hackers
Found in file pp.h
-=item perl_alloc
+=item PUTBACK
-Allocates a new Perl interpreter. See L<perlembed>.
+Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
+See C<PUSHMARK> and L<perlcall> for other uses.
- PerlInterpreter* perl_alloc()
+ PUTBACK;
=for hackers
-Found in file perl.c
-
-=item perl_clone
+Found in file pp.h
-Create and return a new interpreter by cloning the current one.
+=item SP
- PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
+Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
+C<SPAGAIN>.
=for hackers
-Found in file sv.c
+Found in file pp.h
-=item perl_construct
+=item SPAGAIN
-Initializes a new Perl interpreter. See L<perlembed>.
+Refetch the stack pointer. Used after a callback. See L<perlcall>.
- void perl_construct(PerlInterpreter* interp)
+ SPAGAIN;
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item perl_destruct
+=item XPUSHi
-Shuts down a Perl interpreter. See L<perlembed>.
+Push an integer onto the stack, extending the stack if necessary. Handles
+'set' magic. See C<PUSHi>.
- void perl_destruct(PerlInterpreter* interp)
+ void XPUSHi(IV iv)
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item perl_free
+=item XPUSHn
-Releases a Perl interpreter. See L<perlembed>.
+Push a double onto the stack, extending the stack if necessary. Handles
+'set' magic. See C<PUSHn>.
- void perl_free(PerlInterpreter* interp)
+ void XPUSHn(NV nv)
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item perl_parse
+=item XPUSHp
-Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
+Push a string onto the stack, extending the stack if necessary. The C<len>
+indicates the length of the string. Handles 'set' magic. See
+C<PUSHp>.
- int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
+ void XPUSHp(char* str, STRLEN len)
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item perl_run
+=item XPUSHs
-Tells a Perl interpreter to run. See L<perlembed>.
+Push an SV onto the stack, extending the stack if necessary. Does not
+handle 'set' magic. See C<PUSHs>.
- int perl_run(PerlInterpreter* interp)
+ void XPUSHs(SV* sv)
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item PL_modglobal
+=item XPUSHu
-C<PL_modglobal> is a general purpose, interpreter global HV for use by
-extensions that need to keep information on a per-interpreter basis.
-In a pinch, it can also be used as a symbol table for extensions
-to share data among each other. It is a good idea to use keys
-prefixed by the package name of the extension that owns the data.
+Push an unsigned integer onto the stack, extending the stack if necessary.
+See C<PUSHu>.
- HV* PL_modglobal
+ void XPUSHu(UV uv)
=for hackers
-Found in file intrpvar.h
+Found in file pp.h
-=item PL_na
+=item XSRETURN
-A convenience variable which is typically used with C<SvPV> when one
-doesn't care about the length of the string. It is usually more efficient
-to either declare a local variable and use that instead or to use the
-C<SvPV_nolen> macro.
+Return from XSUB, indicating number of items on the stack. This is usually
+handled by C<xsubpp>.
- STRLEN PL_na
+ void XSRETURN(int nitems)
=for hackers
-Found in file thrdvar.h
+Found in file XSUB.h
-=item PL_sv_no
+=item XSRETURN_IV
-This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
-C<&PL_sv_no>.
+Return an integer from an XSUB immediately. Uses C<XST_mIV>.
- SV PL_sv_no
+ void XSRETURN_IV(IV iv)
=for hackers
-Found in file intrpvar.h
+Found in file XSUB.h
-=item PL_sv_undef
+=item XSRETURN_NO
-This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
+Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
- SV PL_sv_undef
+ XSRETURN_NO;
=for hackers
-Found in file intrpvar.h
+Found in file XSUB.h
-=item PL_sv_yes
+=item XSRETURN_NV
-This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
-C<&PL_sv_yes>.
+Return a double from an XSUB immediately. Uses C<XST_mNV>.
- SV PL_sv_yes
+ void XSRETURN_NV(NV nv)
=for hackers
-Found in file intrpvar.h
+Found in file XSUB.h
-=item POPi
+=item XSRETURN_PV
-Pops an integer off the stack.
+Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
- IV POPi
+ void XSRETURN_PV(char* str)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item POPl
+=item XSRETURN_UNDEF
-Pops a long off the stack.
+Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
- long POPl
+ XSRETURN_UNDEF;
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item POPn
+=item XSRETURN_YES
-Pops a double off the stack.
+Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
- NV POPn
+ XSRETURN_YES;
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item POPp
+=item XST_mIV
-Pops a string off the stack. Deprecated. New code should provide
-a STRLEN n_a and use POPpx.
+Place an integer into the specified position C<pos> on the stack. The
+value is stored in a new mortal SV.
- char* POPp
+ void XST_mIV(int pos, IV iv)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item POPpbytex
+=item XST_mNO
-Pops a string off the stack which must consist of bytes i.e. characters < 256.
-Requires a variable STRLEN n_a in scope.
+Place C<&PL_sv_no> into the specified position C<pos> on the
+stack.
- char* POPpbytex
+ void XST_mNO(int pos)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item POPpx
+=item XST_mNV
-Pops a string off the stack.
-Requires a variable STRLEN n_a in scope.
+Place a double into the specified position C<pos> on the stack. The value
+is stored in a new mortal SV.
- char* POPpx
+ void XST_mNV(int pos, NV nv)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item POPs
+=item XST_mPV
-Pops an SV off the stack.
+Place a copy of a string into the specified position C<pos> on the stack.
+The value is stored in a new mortal SV.
- SV* POPs
+ void XST_mPV(int pos, char* str)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item PUSHi
+=item XST_mUNDEF
-Push an integer onto the stack. The stack must have room for this element.
-Handles 'set' magic. See C<XPUSHi>.
+Place C<&PL_sv_undef> into the specified position C<pos> on the
+stack.
- void PUSHi(IV iv)
+ void XST_mUNDEF(int pos)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item PUSHMARK
+=item XST_mYES
-Opening bracket for arguments on a callback. See C<PUTBACK> and
-L<perlcall>.
+Place C<&PL_sv_yes> into the specified position C<pos> on the
+stack.
- PUSHMARK;
+ void XST_mYES(int pos)
=for hackers
-Found in file pp.h
-
-=item PUSHn
+Found in file XSUB.h
-Push a double onto the stack. The stack must have room for this element.
-Handles 'set' magic. See C<XPUSHn>.
- void PUSHn(NV nv)
+=back
-=for hackers
-Found in file pp.h
+=head1 SV Flags
-=item PUSHp
+=over 8
-Push a string onto the stack. The stack must have room for this element.
-The C<len> indicates the length of the string. Handles 'set' magic. See
-C<XPUSHp>.
+=item svtype
- void PUSHp(char* str, STRLEN len)
+An enum of flags for Perl types. These are found in the file B<sv.h>
+in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
=for hackers
-Found in file pp.h
-
-=item PUSHs
+Found in file sv.h
-Push an SV onto the stack. The stack must have room for this element.
-Does not handle 'set' magic. See C<XPUSHs>.
+=item SVt_IV
- void PUSHs(SV* sv)
+Integer type flag for scalars. See C<svtype>.
=for hackers
-Found in file pp.h
-
-=item PUSHu
+Found in file sv.h
-Push an unsigned integer onto the stack. The stack must have room for this
-element. See C<XPUSHu>.
+=item SVt_NV
- void PUSHu(UV uv)
+Double type flag for scalars. See C<svtype>.
=for hackers
-Found in file pp.h
-
-=item PUTBACK
+Found in file sv.h
-Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
-See C<PUSHMARK> and L<perlcall> for other uses.
+=item SVt_PV
- PUTBACK;
+Pointer type flag for scalars. See C<svtype>.
=for hackers
-Found in file pp.h
-
-=item Renew
+Found in file sv.h
-The XSUB-writer's interface to the C C<realloc> function.
+=item SVt_PVAV
- void Renew(void* ptr, int nitems, type)
+Type flag for arrays. See C<svtype>.
=for hackers
-Found in file handy.h
-
-=item Renewc
+Found in file sv.h
-The XSUB-writer's interface to the C C<realloc> function, with
-cast.
+=item SVt_PVCV
- void Renewc(void* ptr, int nitems, type, cast)
+Type flag for code refs. See C<svtype>.
=for hackers
-Found in file handy.h
+Found in file sv.h
-=item require_pv
+=item SVt_PVHV
-Tells Perl to C<require> the file named by the string argument. It is
-analogous to the Perl code C<eval "require '$file'">. It's even
-implemented that way; consider using Perl_load_module instead.
+Type flag for hashes. See C<svtype>.
-NOTE: the perl_ form of this function is deprecated.
+=for hackers
+Found in file sv.h
- void require_pv(const char* pv)
+=item SVt_PVMG
+
+Type flag for blessed scalars. See C<svtype>.
=for hackers
-Found in file perl.c
+Found in file sv.h
-=item RETVAL
-Variable which is setup by C<xsubpp> to hold the return value for an
-XSUB. This is always the proper type for the XSUB. See
-L<perlxs/"The RETVAL Variable">.
+=back
- (whatever) RETVAL
+=head1 SV Manipulation Functions
-=for hackers
-Found in file XSUB.h
+=over 8
+
+=item get_sv
-=item Safefree
+Returns the SV of the specified Perl scalar. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
-The XSUB-writer's interface to the C C<free> function.
+NOTE: the perl_ form of this function is deprecated.
- void Safefree(void* ptr)
+ SV* get_sv(const char* name, I32 create)
=for hackers
-Found in file handy.h
+Found in file perl.c
-=item savepv
+=item looks_like_number
-Copy a string to a safe spot. This does not use an SV.
+Test if the content of an SV looks like a number (or is a number).
+C<Inf> and C<Infinity> are treated as numbers (so will not issue a
+non-numeric warning), even if your atof() doesn't grok them.
- char* savepv(const char* sv)
+ I32 looks_like_number(SV* sv)
=for hackers
-Found in file util.c
+Found in file sv.c
-=item savepvn
+=item newRV_inc
-Copy a string to a safe spot. The C<len> indicates number of bytes to
-copy. This does not use an SV.
+Creates an RV wrapper for an SV. The reference count for the original SV is
+incremented.
- char* savepvn(const char* sv, I32 len)
+ SV* newRV_inc(SV* sv)
=for hackers
-Found in file util.c
+Found in file sv.h
-=item SAVETMPS
+=item newRV_noinc
-Opening bracket for temporaries on a callback. See C<FREETMPS> and
-L<perlcall>.
+Creates an RV wrapper for an SV. The reference count for the original
+SV is B<not> incremented.
- SAVETMPS;
+ SV* newRV_noinc(SV *sv)
=for hackers
-Found in file scope.h
+Found in file sv.c
-=item SP
+=item newSV
-Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
-C<SPAGAIN>.
+Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
+with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
+macro.
+
+ SV* newSV(STRLEN len)
=for hackers
-Found in file pp.h
+Found in file sv.c
-=item SPAGAIN
+=item newSViv
-Refetch the stack pointer. Used after a callback. See L<perlcall>.
+Creates a new SV and copies an integer into it. The reference count for the
+SV is set to 1.
- SPAGAIN;
+ SV* newSViv(IV i)
=for hackers
-Found in file pp.h
+Found in file sv.c
-=item ST
+=item newSVnv
-Used to access elements on the XSUB's stack.
+Creates a new SV and copies a floating point value into it.
+The reference count for the SV is set to 1.
- SV* ST(int ix)
+ SV* newSVnv(NV n)
=for hackers
-Found in file XSUB.h
+Found in file sv.c
-=item strEQ
+=item newSVpv
-Test two strings to see if they are equal. Returns true or false.
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. If C<len> is zero, Perl will compute the length using
+strlen(). For efficiency, consider using C<newSVpvn> instead.
- bool strEQ(char* s1, char* s2)
+ SV* newSVpv(const char* s, STRLEN len)
=for hackers
-Found in file handy.h
+Found in file sv.c
-=item strGE
+=item newSVpvf
-Test two strings to see if the first, C<s1>, is greater than or equal to
-the second, C<s2>. Returns true or false.
+Creates a new SV and initializes it with the string formatted like
+C<sprintf>.
- bool strGE(char* s1, char* s2)
+ SV* newSVpvf(const char* pat, ...)
=for hackers
-Found in file handy.h
+Found in file sv.c
-=item strGT
+=item newSVpvn
-Test two strings to see if the first, C<s1>, is greater than the second,
-C<s2>. Returns true or false.
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
+string. You are responsible for ensuring that the source string is at least
+C<len> bytes long.
- bool strGT(char* s1, char* s2)
+ SV* newSVpvn(const char* s, STRLEN len)
=for hackers
-Found in file handy.h
+Found in file sv.c
-=item strLE
+=item newSVpvn_share
-Test two strings to see if the first, C<s1>, is less than or equal to the
-second, C<s2>. Returns true or false.
+Creates a new SV with its SvPVX pointing to a shared string in the string
+table. If the string does not already exist in the table, it is created
+first. Turns on READONLY and FAKE. The string's hash is stored in the UV
+slot of the SV; if the C<hash> parameter is non-zero, that value is used;
+otherwise the hash is computed. The idea here is that as the string table
+is used for shared hash keys these strings will have SvPVX == HeKEY and
+hash lookup will avoid string compare.
- bool strLE(char* s1, char* s2)
+ SV* newSVpvn_share(const char* s, I32 len, U32 hash)
=for hackers
-Found in file handy.h
+Found in file sv.c
-=item strLT
+=item newSVrv
-Test two strings to see if the first, C<s1>, is less than the second,
-C<s2>. Returns true or false.
+Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
+it will be upgraded to one. If C<classname> is non-null then the new SV will
+be blessed in the specified package. The new SV is returned and its
+reference count is 1.
- bool strLT(char* s1, char* s2)
+ SV* newSVrv(SV* rv, const char* classname)
=for hackers
-Found in file handy.h
+Found in file sv.c
-=item strNE
+=item newSVsv
-Test two strings to see if they are different. Returns true or
-false.
+Creates a new SV which is an exact duplicate of the original SV.
+(Uses C<sv_setsv>).
- bool strNE(char* s1, char* s2)
+ SV* newSVsv(SV* old)
=for hackers
-Found in file handy.h
+Found in file sv.c
-=item strnEQ
+=item newSVuv
-Test two strings to see if they are equal. The C<len> parameter indicates
-the number of bytes to compare. Returns true or false. (A wrapper for
-C<strncmp>).
+Creates a new SV and copies an unsigned integer into it.
+The reference count for the SV is set to 1.
- bool strnEQ(char* s1, char* s2, STRLEN len)
+ SV* newSVuv(UV u)
=for hackers
-Found in file handy.h
-
-=item strnNE
+Found in file sv.c
-Test two strings to see if they are different. The C<len> parameter
-indicates the number of bytes to compare. Returns true or false. (A
-wrapper for C<strncmp>).
+=item new_vstring
- bool strnNE(char* s1, char* s2, STRLEN len)
+Returns a pointer to the next character after the parsed
+vstring, as well as updating the passed in sv.
-=for hackers
-Found in file handy.h
+Function must be called like
-=item StructCopy
+ sv = NEWSV(92,5);
+ s = new_vstring(s,sv);
-This is an architecture-independent macro to copy one structure to another.
+The sv must already be large enough to store the vstring
+passed in.
- void StructCopy(type src, type dest, type)
+ char* new_vstring(char *vstr, SV *sv)
=for hackers
-Found in file handy.h
+Found in file util.c
=item SvCUR
=for hackers
Found in file sv.h
-=item SvGETMAGIC
-
-Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
-argument more than once.
-
- void SvGETMAGIC(SV* sv)
-
-=for hackers
-Found in file sv.h
-
=item SvGROW
Expands the character buffer in the SV so that it has room for the
indicated number of bytes (remember to reserve space for an extra trailing
-NUL character). Calls C<sv_grow> to perform the expansion if necessary.
+NUL character). Calls C<sv_grow> to perform the expansion if necessary.
Returns a pointer to the character buffer.
char * SvGROW(SV* sv, STRLEN len)
=item SvIOK_notUV
-Returns a boolean indicating whether the SV contains an signed integer.
+Returns a boolean indicating whether the SV contains a signed integer.
void SvIOK_notUV(SV* sv)
=for hackers
Found in file sv.h
-=item SvIVX
+=item SvIVx
-Returns the raw value in the SV's IV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvIV()>.
+Coerces the given SV to an integer and returns it. Guarantees to evaluate
+sv only once. Use the more efficient C<SvIV> otherwise.
- IV SvIVX(SV* sv)
+ IV SvIVx(SV* sv)
=for hackers
Found in file sv.h
-=item SvIVx
+=item SvIVX
-Coerces the given SV to an integer and returns it. Guarantees to evaluate
-sv only once. Use the more efficent C<SvIV> otherwise.
+Returns the raw value in the SV's IV slot, without checks or conversions.
+Only use when you are sure SvIOK is true. See also C<SvIV()>.
- IV SvIVx(SV* sv)
+ IV SvIVX(SV* sv)
=for hackers
Found in file sv.h
=for hackers
Found in file sv.h
-=item SvNVx
+=item SvNVX
-Coerces the given SV to a double and returns it. Guarantees to evaluate
-sv only once. Use the more efficent C<SvNV> otherwise.
+Returns the raw value in the SV's NV slot, without checks or conversions.
+Only use when you are sure SvNOK is true. See also C<SvNV()>.
- NV SvNVx(SV* sv)
+ NV SvNVX(SV* sv)
=for hackers
Found in file sv.h
-=item SvNVX
+=item SvNVx
-Returns the raw value in the SV's NV slot, without checks or conversions.
-Only use when you are sure SvNOK is true. See also C<SvNV()>.
+Coerces the given SV to a double and returns it. Guarantees to evaluate
+sv only once. Use the more efficient C<SvNV> otherwise.
- NV SvNVX(SV* sv)
+ NV SvNVx(SV* sv)
=for hackers
Found in file sv.h
=item SvPV
-Returns a pointer to the string in the SV, or a stringified form of the SV
-if the SV does not contain a string. Handles 'get' magic. See also
+Returns a pointer to the string in the SV, or a stringified form of
+the SV if the SV does not contain a string. The SV may cache the
+stringified version becoming C<SvPOK>. Handles 'get' magic. See also
C<SvPVx> for a version which guarantees to evaluate sv only once.
char* SvPV(SV* sv, STRLEN len)
=item SvPVbytex
Like C<SvPV>, but converts sv to byte representation first if necessary.
-Guarantees to evalute sv only once; use the more efficient C<SvPVbyte>
+Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
otherwise.
=item SvPVbytex_force
Like C<SvPV_force>, but converts sv to byte representation first if necessary.
-Guarantees to evalute sv only once; use the more efficient C<SvPVbyte_force>
+Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
otherwise.
char* SvPVbytex_force(SV* sv, STRLEN len)
Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
- char* SvPVbyte_nolen(SV* sv, STRLEN len)
+ char* SvPVbyte_nolen(SV* sv)
=for hackers
Found in file sv.h
=item SvPVutf8
-Like C<SvPV>, but converts sv to uft8 first if necessary.
+Like C<SvPV>, but converts sv to utf8 first if necessary.
char* SvPVutf8(SV* sv, STRLEN len)
=item SvPVutf8x
-Like C<SvPV>, but converts sv to uft8 first if necessary.
-Guarantees to evalute sv only once; use the more efficient C<SvPVutf8>
+Like C<SvPV>, but converts sv to utf8 first if necessary.
+Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
otherwise.
char* SvPVutf8x(SV* sv, STRLEN len)
=item SvPVutf8x_force
-Like C<SvPV_force>, but converts sv to uft8 first if necessary.
-Guarantees to evalute sv only once; use the more efficient C<SvPVutf8_force>
+Like C<SvPV_force>, but converts sv to utf8 first if necessary.
+Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
otherwise.
char* SvPVutf8x_force(SV* sv, STRLEN len)
=item SvPVutf8_force
-Like C<SvPV_force>, but converts sv to uft8 first if necessary.
+Like C<SvPV_force>, but converts sv to utf8 first if necessary.
char* SvPVutf8_force(SV* sv, STRLEN len)
=item SvPVutf8_nolen
-Like C<SvPV_nolen>, but converts sv to uft8 first if necessary.
+Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
- char* SvPVutf8_nolen(SV* sv, STRLEN len)
+ char* SvPVutf8_nolen(SV* sv)
=for hackers
Found in file sv.h
-=item SvPVX
+=item SvPVx
-Returns a pointer to the physical string in the SV. The SV must contain a
-string.
+A version of C<SvPV> which guarantees to evaluate sv only once.
- char* SvPVX(SV* sv)
+ char* SvPVx(SV* sv, STRLEN len)
=for hackers
Found in file sv.h
-=item SvPVx
+=item SvPVX
-A version of C<SvPV> which guarantees to evaluate sv only once.
+Returns a pointer to the physical string in the SV. The SV must contain a
+string.
- char* SvPVx(SV* sv, STRLEN len)
+ char* SvPVX(SV* sv)
=for hackers
Found in file sv.h
=item SvPV_force
-Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
-force if you are going to update the SvPVX directly.
+Like C<SvPV> but will force the SV into containing just a string
+(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
+directly.
char* SvPV_force(SV* sv, STRLEN len)
=item SvPV_force_nomg
-Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
-force if you are going to update the SvPVX directly. Doesn't process magic.
+Like C<SvPV> but will force the SV into containing just a string
+(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
+directly. Doesn't process magic.
char* SvPV_force_nomg(SV* sv, STRLEN len)
=item SvPV_nolen
-Returns a pointer to the string in the SV, or a stringified form of the SV
-if the SV does not contain a string. Handles 'get' magic.
+Returns a pointer to the string in the SV, or a stringified form of
+the SV if the SV does not contain a string. The SV may cache the
+stringified form becoming C<SvPOK>. Handles 'get' magic.
char* SvPV_nolen(SV* sv)
=for hackers
Found in file sv.h
-=item SvROK
-
-Tests if the SV is an RV.
-
- bool SvROK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvROK_off
-
-Unsets the RV status of an SV.
-
- void SvROK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvROK_on
-
-Tells an SV that it is an RV.
-
- void SvROK_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvRV
-
-Dereferences an RV to return the SV.
-
- SV* SvRV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSETMAGIC
-
-Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
-argument more than once.
-
- void SvSETMAGIC(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetMagicSV
+=item SvROK
-Like C<SvSetSV>, but does any set magic required afterwards.
+Tests if the SV is an RV.
- void SvSetMagicSV(SV* dsb, SV* ssv)
+ bool SvROK(SV* sv)
=for hackers
Found in file sv.h
-=item SvSetMagicSV_nosteal
+=item SvROK_off
-Like C<SvSetMagicSV>, but does any set magic required afterwards.
+Unsets the RV status of an SV.
- void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
+ void SvROK_off(SV* sv)
=for hackers
Found in file sv.h
-=item SvSetSV
+=item SvROK_on
-Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
-more than once.
+Tells an SV that it is an RV.
- void SvSetSV(SV* dsb, SV* ssv)
+ void SvROK_on(SV* sv)
=for hackers
Found in file sv.h
-=item SvSetSV_nosteal
+=item SvRV
-Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
-ssv. May evaluate arguments more than once.
+Dereferences an RV to return the SV.
- void SvSetSV_nosteal(SV* dsv, SV* ssv)
+ SV* SvRV(SV* sv)
=for hackers
Found in file sv.h
=for hackers
Found in file sv.h
-=item svtype
-
-An enum of flags for Perl types. These are found in the file B<sv.h>
-in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
-
-=for hackers
-Found in file sv.h
-
=item SvTYPE
Returns the type of the SV. See C<svtype>.
=for hackers
Found in file sv.h
-=item SVt_IV
-
-Integer type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_NV
-
-Double type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PV
-
-Pointer type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVAV
-
-Type flag for arrays. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVCV
-
-Type flag for code refs. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVHV
-
-Type flag for hashes. See C<svtype>.
+=item SvUNLOCK
-=for hackers
-Found in file sv.h
+Releases a mutual exclusion lock on sv if a suitable module
+has been loaded.
-=item SVt_PVMG
-Type flag for blessed scalars. See C<svtype>.
+ void SvUNLOCK(SV* sv)
=for hackers
Found in file sv.h
=item SvUVx
Coerces the given SV to an unsigned integer and returns it. Guarantees to
-evaluate sv only once. Use the more efficent C<SvUV> otherwise.
+evaluate sv only once. Use the more efficient C<SvUV> otherwise.
UV SvUVx(SV* sv)
=item sv_2bool
This function is only called on magical items, and is only used by
-sv_true() or its macro equivalent.
+sv_true() or its macro equivalent.
bool sv_2bool(SV* sv)
=item sv_2mortal
-Marks an existing SV as mortal. The SV will be destroyed when the current
-context ends. See also C<sv_newmortal> and C<sv_mortalcopy>.
+Marks an existing SV as mortal. The SV will be destroyed "soon", either
+by an explicit call to FREETMPS, or by an implicit call at places such as
+statement boundaries. See also C<sv_newmortal> and C<sv_mortalcopy>.
SV* sv_2mortal(SV* sv)
=for hackers
Found in file sv.c
+=item sv_copypv
+
+Copies a stringified representation of the source SV into the
+destination SV. Automatically performs any necessary mg_get and
+coercion of numeric values into strings. Guaranteed to preserve
+UTF-8 flag even from overloaded objects. Similar in nature to
+sv_2pv[_flags] but operates directly on an SV instead of just the
+string. Mostly uses sv_2pv_flags to do its work, except when that
+would lose the UTF-8'ness of the PV.
+
+ void sv_copypv(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.c
+
=item sv_dec
Auto-decrement of the value in the SV, doing string to numeric conversion
Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
then adds a new magic item of type C<how> to the head of the magic list.
-C<name> is assumed to contain an C<SV*> if C<(name && namelen == HEf_SVKEY)>
-
void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
=for hackers
Found in file sv.c
+=item sv_magicext
+
+Adds magic to an SV, upgrading it if necessary. Applies the
+supplied vtable and returns pointer to the magic added.
+
+Note that sv_magicext will allow things that sv_magic will not.
+In particular you can add magic to SvREADONLY SVs and and more than
+one instance of the same 'how'
+
+I C<namelen> is greater then zero then a savepvn() I<copy> of C<name> is stored,
+if C<namelen> is zero then C<name> is stored as-is and - as another special
+case - if C<(name && namelen == HEf_SVKEY)> then C<name> is assumed to contain
+an C<SV*> and has its REFCNT incremented
+
+(This is now used as a subroutine by sv_magic.)
+
+ MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen )
+
+=for hackers
+Found in file sv.c
+
=item sv_mortalcopy
Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
-The new SV is marked as mortal. It will be destroyed when the current
-context ends. See also C<sv_newmortal> and C<sv_2mortal>.
+The new SV is marked as mortal. It will be destroyed "soon", either by an
+explicit call to FREETMPS, or by an implicit call at places such as
+statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
SV* sv_mortalcopy(SV* oldsv)
=item sv_newmortal
Creates a new null SV which is mortal. The reference count of the SV is
-set to 1. It will be destroyed when the current context ends. See
-also C<sv_mortalcopy> and C<sv_2mortal>.
+set to 1. It will be destroyed "soon", either by an explicit call to
+FREETMPS, or by an implicit call at places such as statement boundaries.
+See also C<sv_mortalcopy> and C<sv_2mortal>.
SV* sv_newmortal()
=for hackers
Found in file sv.c
+=item sv_nolocking
+
+Dummy routine which "locks" an SV when there is no locking module present.
+Exists to avoid test for a NULL function pointer and because it could potentially warn under
+some level of strict-ness.
+
+ void sv_nolocking(SV *)
+
+=for hackers
+Found in file util.c
+
+=item sv_nosharing
+
+Dummy routine which "shares" an SV when there is no sharing module present.
+Exists to avoid test for a NULL function pointer and because it could potentially warn under
+some level of strict-ness.
+
+ void sv_nosharing(SV *)
+
+=for hackers
+Found in file util.c
+
+=item sv_nounlocking
+
+Dummy routine which "unlocks" an SV when there is no locking module present.
+Exists to avoid test for a NULL function pointer and because it could potentially warn under
+some level of strict-ness.
+
+ void sv_nounlocking(SV *)
+
+=for hackers
+Found in file util.c
+
=item sv_nv
A private implementation of the C<SvNVx> macro for compilers which can't
=item sv_pv
-A private implementation of the C<SvPV_nolen> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
+Use the C<SvPV_nolen> macro instead
char* sv_pv(SV *sv)
=item sv_pvbyte
-A private implementation of the C<SvPVbyte_nolen> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
-instead.
+Use C<SvPVbyte_nolen> instead.
char* sv_pvbyte(SV *sv)
=item sv_pvutf8
-A private implementation of the C<SvPVutf8_nolen> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
-instead.
+Use the C<SvPVutf8_nolen> macro instead
char* sv_pvutf8(SV *sv)
=for hackers
Found in file sv.c
-=item sv_setpviv
-
-Copies an integer into the given SV, also updating its string value.
-Does not handle 'set' magic. See C<sv_setpviv_mg>.
-
- void sv_setpviv(SV* sv, IV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpviv_mg
-
-Like C<sv_setpviv>, but also handles 'set' magic.
-
- void sv_setpviv_mg(SV *sv, IV iv)
-
-=for hackers
-Found in file sv.c
-
=item sv_setpvn
Copies a string into an SV. The C<len> parameter indicates the number of
C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
C<SvSetMagicSV_nosteal>.
-
void sv_setsv(SV* dsv, SV* ssv)
=for hackers
if this is the case, either returns false or, if C<fail_ok> is not
true, croaks.
+This is not as a general purpose Unicode to byte encoding interface:
+use the Encode extension for that.
+
NOTE: this function is experimental and may change or be
removed without notice.
Always sets the SvUTF8 flag to avoid future validity checks even
if all the bytes have hibit clear.
+This is not as a general purpose byte encoding to Unicode interface:
+use the Encode extension for that.
+
STRLEN sv_utf8_upgrade(SV *sv)
=for hackers
will C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and
C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
+This is not as a general purpose byte encoding to Unicode interface:
+use the Encode extension for that.
+
STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags)
=for hackers
Found in file sv.c
-=item sv_uv
+=item sv_uv
+
+A private implementation of the C<SvUVx> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
+
+ UV sv_uv(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vcatpvfn
+
+Processes its arguments like C<vsprintf> and appends the formatted output
+to an SV. Uses an array of SVs if the C style variable argument list is
+missing (NULL). When running with taint checks enabled, indicates via
+C<maybe_tainted> if results are untrustworthy (often due to the use of
+locales).
+
+Usually used via one of its frontends C<sv_catpvf> and C<sv_catpvf_mg>.
+
+ void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vsetpvfn
+
+Works like C<vcatpvfn> but copies the text into the SV instead of
+appending it.
+
+Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
+
+ void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+
+=for hackers
+Found in file sv.c
+
+
+=back
+
+=head1 Unicode Support
+
+=over 8
+
+=item bytes_from_utf8
+
+Converts a string C<s> of length C<len> from UTF8 into byte encoding.
+Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
+the newly-created string, and updates C<len> to contain the new
+length. Returns the original string if no conversion occurs, C<len>
+is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
+0 if C<s> is converted or contains all 7bit characters.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
+
+=for hackers
+Found in file utf8.c
+
+=item bytes_to_utf8
+
+Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
+Returns a pointer to the newly-created string, and sets C<len> to
+reflect the new length.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ U8* bytes_to_utf8(U8 *s, STRLEN *len)
+
+=for hackers
+Found in file utf8.c
+
+=item ibcmp_utf8
+
+Return true if the strings s1 and s2 differ case-insensitively, false
+if not (if they are equal case-insensitively). If u1 is true, the
+string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true,
+the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2
+are false, the respective string is assumed to be in native 8-bit
+encoding.
+
+If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
+in there (they will point at the beginning of the I<next> character).
+If the pointers behind pe1 or pe2 are non-NULL, they are the end
+pointers beyond which scanning will not continue under any
+circustances. If the byte lengths l1 and l2 are non-zero, s1+l1 and
+s2+l2 will be used as goal end pointers that will also stop the scan,
+and which qualify towards defining a successful match: all the scans
+that define an explicit length must reach their goal pointers for
+a match to succeed).
+
+For case-insensitiveness, the "casefolding" of Unicode is used
+instead of upper/lowercasing both the characters, see
+http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
+
+ I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
+
+=for hackers
+Found in file utf8.c
+
+=item is_utf8_char
+
+Tests if some arbitrary number of bytes begins in a valid UTF-8
+character. Note that an INVARIANT (i.e. ASCII) character is a valid
+UTF-8 character. The actual number of bytes in the UTF-8 character
+will be returned if it is valid, otherwise 0.
+
+ STRLEN is_utf8_char(U8 *p)
+
+=for hackers
+Found in file utf8.c
+
+=item is_utf8_string
+
+Returns true if first C<len> bytes of the given string form a valid UTF8
+string, false otherwise. Note that 'a valid UTF8 string' does not mean
+'a string that contains UTF8' because a valid ASCII string is a valid
+UTF8 string.
+
+ bool is_utf8_string(U8 *s, STRLEN len)
+
+=for hackers
+Found in file utf8.c
+
+=item pv_uni_display
+
+Build to the scalar dsv a displayable version of the string spv,
+length len, the displayable version being at most pvlim bytes long
+(if longer, the rest is truncated and "..." will be appended).
+
+The flags argument can have UNI_DISPLAY_ISPRINT set to display
+isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
+to display the \\[nrfta\\] as the backslashed versions (like '\n')
+(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
+UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
+UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
+
+The pointer to the PV of the dsv is returned.
+
+ char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
+
+=for hackers
+Found in file utf8.c
+
+=item sv_recode_to_utf8
+
+The encoding is assumed to be an Encode object, on entry the PV
+of the sv is assumed to be octets in that encoding, and the sv
+will be converted into Unicode (and UTF-8).
+
+If the sv already is UTF-8 (or if it is not POK), or if the encoding
+is not a reference, nothing is done to the sv. If the encoding is not
+an C<Encode::XS> Encoding object, bad things will happen.
+(See F<lib/encoding.pm> and L<Encode>).
+
+The PV of the sv is returned.
+
+ char* sv_recode_to_utf8(SV* sv, SV *encoding)
+
+=for hackers
+Found in file sv.c
+
+=item sv_uni_display
+
+Build to the scalar dsv a displayable version of the scalar sv,
+the displayable version being at most pvlim bytes long
+(if longer, the rest is truncated and "..." will be appended).
+
+The flags argument is as in pv_uni_display().
+
+The pointer to the PV of the dsv is returned.
+
+ char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
+
+=for hackers
+Found in file utf8.c
+
+=item to_utf8_case
-A private implementation of the C<SvUVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
+The "p" contains the pointer to the UTF-8 string encoding
+the character that is being converted.
- UV sv_uv(SV* sv)
+The "ustrp" is a pointer to the character buffer to put the
+conversion result to. The "lenp" is a pointer to the length
+of the result.
-=for hackers
-Found in file sv.c
+The "swashp" is a pointer to the swash to use.
-=item sv_vcatpvfn
+Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
+and loaded by SWASHGET, using lib/utf8_heavy.pl. The special (usually,
+but not always, a multicharacter mapping), is tried first.
-Processes its arguments like C<vsprintf> and appends the formatted output
-to an SV. Uses an array of SVs if the C style variable argument list is
-missing (NULL). When running with taint checks enabled, indicates via
-C<maybe_tainted> if results are untrustworthy (often due to the use of
-locales).
+The "special" is a string like "utf8::ToSpecLower", which means the
+hash %utf8::ToSpecLower. The access to the hash is through
+Perl_to_utf8_case().
-Usually used via one of its frontends C<sv_catpvf> and C<sv_catpvf_mg>.
+The "normal" is a string like "ToLower" which means the swash
+%utf8::ToLower.
- void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+ UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
=for hackers
-Found in file sv.c
+Found in file utf8.c
-=item sv_vsetpvfn
+=item to_utf8_fold
-Works like C<vcatpvfn> but copies the text into the SV instead of
-appending it.
+Convert the UTF-8 encoded character at p to its foldcase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXLEN_FOLD+1 bytes since the
+foldcase version may be longer than the original character (up to
+three characters).
-Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
+The first character of the foldcased version is returned
+(but note, as explained above, that there may be more.)
- void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+ UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)
=for hackers
-Found in file sv.c
+Found in file utf8.c
-=item THIS
+=item to_utf8_lower
-Variable which is setup by C<xsubpp> to designate the object in a C++
-XSUB. This is always the proper type for the C++ object. See C<CLASS> and
-L<perlxs/"Using XS With C++">.
+Convert the UTF-8 encoded character at p to its lowercase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
+lowercase version may be longer than the original character (up to two
+characters).
- (whatever) THIS
+The first character of the lowercased version is returned
+(but note, as explained above, that there may be more.)
+
+ UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)
=for hackers
-Found in file XSUB.h
+Found in file utf8.c
-=item toLOWER
+=item to_utf8_title
-Converts the specified character to lowercase.
+Convert the UTF-8 encoded character at p to its titlecase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
+titlecase version may be longer than the original character (up to two
+characters).
- char toLOWER(char ch)
+The first character of the titlecased version is returned
+(but note, as explained above, that there may be more.)
+
+ UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)
=for hackers
-Found in file handy.h
+Found in file utf8.c
-=item toUPPER
+=item to_utf8_upper
-Converts the specified character to uppercase.
+Convert the UTF-8 encoded character at p to its uppercase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
+uppercase version may be longer than the original character (up to two
+characters).
- char toUPPER(char ch)
+The first character of the uppercased version is returned
+(but note, as explained above, that there may be more.)
+
+ UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)
=for hackers
-Found in file handy.h
+Found in file utf8.c
=item utf8n_to_uvchr
=for hackers
Found in file utf8.c
-=item uvuni_to_utf8
+=item uvuni_to_utf8_flags
Adds the UTF8 representation of the Unicode codepoint C<uv> to the end
of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
bytes available. The return value is the pointer to the byte after the
end of the new character. In other words,
- d = uvuni_to_utf8(d, uv);
-
-is the recommended Unicode-aware way of saying
-
- *(d++) = uv;
-
- U8* uvuni_to_utf8(U8 *d, UV uv)
-
-=for hackers
-Found in file utf8.c
-
-=item warn
-
-This is the XSUB-writer's interface to Perl's C<warn> function. Use this
-function the same way you use the C C<printf> function. See
-C<croak>.
-
- void warn(const char* pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item XPUSHi
-
-Push an integer onto the stack, extending the stack if necessary. Handles
-'set' magic. See C<PUSHi>.
-
- void XPUSHi(IV iv)
-
-=for hackers
-Found in file pp.h
+ d = uvuni_to_utf8_flags(d, uv, flags);
-=item XPUSHn
+or, in most cases,
-Push a double onto the stack, extending the stack if necessary. Handles
-'set' magic. See C<PUSHn>.
+ d = uvuni_to_utf8(d, uv);
- void XPUSHn(NV nv)
+(which is equivalent to)
-=for hackers
-Found in file pp.h
+ d = uvuni_to_utf8_flags(d, uv, 0);
-=item XPUSHp
+is the recommended Unicode-aware way of saying
-Push a string onto the stack, extending the stack if necessary. The C<len>
-indicates the length of the string. Handles 'set' magic. See
-C<PUSHp>.
+ *(d++) = uv;
- void XPUSHp(char* str, STRLEN len)
+ U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
=for hackers
-Found in file pp.h
-
-=item XPUSHs
-
-Push an SV onto the stack, extending the stack if necessary. Does not
-handle 'set' magic. See C<PUSHs>.
-
- void XPUSHs(SV* sv)
+Found in file utf8.c
-=for hackers
-Found in file pp.h
-=item XPUSHu
+=back
-Push an unsigned integer onto the stack, extending the stack if necessary.
-See C<PUSHu>.
+=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
- void XPUSHu(UV uv)
+=over 8
-=for hackers
-Found in file pp.h
+=item ax
-=item XS
+Variable which is setup by C<xsubpp> to indicate the stack base offset,
+used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
+must be called prior to setup the C<MARK> variable.
-Macro to declare an XSUB and its C parameter list. This is handled by
-C<xsubpp>.
+ I32 ax
=for hackers
Found in file XSUB.h
-=item XSRETURN
+=item CLASS
-Return from XSUB, indicating number of items on the stack. This is usually
-handled by C<xsubpp>.
+Variable which is setup by C<xsubpp> to indicate the
+class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
- void XSRETURN(int nitems)
+ char* CLASS
=for hackers
Found in file XSUB.h
-=item XSRETURN_EMPTY
+=item dAX
-Return an empty list from an XSUB immediately.
+Sets up the C<ax> variable.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
- XSRETURN_EMPTY;
+ dAX;
=for hackers
Found in file XSUB.h
-=item XSRETURN_IV
+=item dITEMS
-Return an integer from an XSUB immediately. Uses C<XST_mIV>.
+Sets up the C<items> variable.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
- void XSRETURN_IV(IV iv)
+ dITEMS;
=for hackers
Found in file XSUB.h
-=item XSRETURN_NO
+=item dXSARGS
-Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
+Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
+Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
+This is usually handled automatically by C<xsubpp>.
- XSRETURN_NO;
+ dXSARGS;
=for hackers
Found in file XSUB.h
-=item XSRETURN_NV
+=item dXSI32
-Return an double from an XSUB immediately. Uses C<XST_mNV>.
+Sets up the C<ix> variable for an XSUB which has aliases. This is usually
+handled automatically by C<xsubpp>.
- void XSRETURN_NV(NV nv)
+ dXSI32;
=for hackers
Found in file XSUB.h
-=item XSRETURN_PV
+=item items
-Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
+Variable which is setup by C<xsubpp> to indicate the number of
+items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
- void XSRETURN_PV(char* str)
+ I32 items
=for hackers
Found in file XSUB.h
-=item XSRETURN_UNDEF
+=item ix
-Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
+Variable which is setup by C<xsubpp> to indicate which of an
+XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
- XSRETURN_UNDEF;
+ I32 ix
=for hackers
Found in file XSUB.h
-=item XSRETURN_YES
-
-Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
+=item newXSproto
- XSRETURN_YES;
+Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
+the subs.
=for hackers
Found in file XSUB.h
-=item XST_mIV
+=item RETVAL
-Place an integer into the specified position C<pos> on the stack. The
-value is stored in a new mortal SV.
+Variable which is setup by C<xsubpp> to hold the return value for an
+XSUB. This is always the proper type for the XSUB. See
+L<perlxs/"The RETVAL Variable">.
- void XST_mIV(int pos, IV iv)
+ (whatever) RETVAL
=for hackers
Found in file XSUB.h
-=item XST_mNO
+=item ST
-Place C<&PL_sv_no> into the specified position C<pos> on the
-stack.
+Used to access elements on the XSUB's stack.
- void XST_mNO(int pos)
+ SV* ST(int ix)
=for hackers
Found in file XSUB.h
-=item XST_mNV
+=item THIS
-Place a double into the specified position C<pos> on the stack. The value
-is stored in a new mortal SV.
+Variable which is setup by C<xsubpp> to designate the object in a C++
+XSUB. This is always the proper type for the C++ object. See C<CLASS> and
+L<perlxs/"Using XS With C++">.
- void XST_mNV(int pos, NV nv)
+ (whatever) THIS
=for hackers
Found in file XSUB.h
-=item XST_mPV
-
-Place a copy of a string into the specified position C<pos> on the stack.
-The value is stored in a new mortal SV.
+=item XS
- void XST_mPV(int pos, char* str)
+Macro to declare an XSUB and its C parameter list. This is handled by
+C<xsubpp>.
=for hackers
Found in file XSUB.h
-=item XST_mUNDEF
-
-Place C<&PL_sv_undef> into the specified position C<pos> on the
-stack.
-
- void XST_mUNDEF(int pos)
-
-=for hackers
-Found in file XSUB.h
+=item XSRETURN_EMPTY
-=item XST_mYES
+Return an empty list from an XSUB immediately.
-Place C<&PL_sv_yes> into the specified position C<pos> on the
-stack.
- void XST_mYES(int pos)
+ XSRETURN_EMPTY;
=for hackers
Found in file XSUB.h
=for hackers
Found in file XSUB.h
-=item Zero
-The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
-destination, C<nitems> is the number of items, and C<type> is the type.
+=back
- void Zero(void* dest, int nitems, type)
+=head1 Warning and Dieing
+
+=over 8
+
+=item croak
+
+This is the XSUB-writer's interface to Perl's C<die> function.
+Normally use this function the same way you use the C C<printf>
+function. See C<warn>.
+
+If you want to throw an exception object, assign the object to
+C<$@> and then pass C<Nullch> to croak():
+
+ errsv = get_sv("@", TRUE);
+ sv_setsv(errsv, exception_object);
+ croak(Nullch);
+
+ void croak(const char* pat, ...)
=for hackers
-Found in file handy.h
+Found in file util.c
+
+=item warn
+
+This is the XSUB-writer's interface to Perl's C<warn> function. Use this
+function the same way you use the C C<printf> function. See
+C<croak>.
+
+ void warn(const char* pat, ...)
+
+=for hackers
+Found in file util.c
+
=back