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>.
+Returns a boolean indicating whether the C C<char> is an uppercase
+character.
- ENTER;
+ bool isUPPER(char ch)
=for hackers
-Found in file scope.h
-
-=item eval_pv
+Found in file handy.h
-Tells Perl to C<eval> the given string and return an SV* result.
+=item toLOWER
-NOTE: the perl_ form of this function is deprecated.
+Converts the specified character to lowercase.
- SV* eval_pv(const char* p, I32 croak_on_error)
+ char toLOWER(char ch)
=for hackers
-Found in file perl.c
-
-=item eval_sv
+Found in file handy.h
-Tells Perl to C<eval> the string in the SV.
+=item toUPPER
-NOTE: the perl_ form of this function is deprecated.
+Converts the specified character to uppercase.
- I32 eval_sv(SV* sv, I32 flags)
+ char toUPPER(char ch)
=for hackers
-Found in file perl.c
+Found in file handy.h
-=item EXTEND
-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.
+=back
- void EXTEND(SP, int nitems)
+=head1 Cloning an interpreter
-=for hackers
-Found in file pp.h
+=over 8
-=item fbm_compile
+=item perl_clone
-Analyses the string in order to make fast searches on it using fbm_instr()
--- the Boyer-Moore algorithm.
+Create and return a new interpreter by cloning the current one.
- void fbm_compile(SV* sv, U32 flags)
+ PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
=for hackers
-Found in file util.c
+Found in file sv.c
-=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 CV Manipulation Functions
+
+=over 8
+
+=item CvSTASH
+
+Returns the stash of the CV.
+
+ HV* CvSTASH(CV* cv)
=for hackers
-Found in file util.c
+Found in file cv.h
-=item FREETMPS
+=item get_cv
-Closing bracket for temporaries on a callback. See C<SAVETMPS> and
-L<perlcall>.
+Returns the CV of the specified Perl subroutine. If C<create> is set and
+the Perl subroutine does not exist then it will be declared (which has the
+same effect as saying C<sub name;>). If C<create> is not set and the
+subroutine does not exist then NULL is returned.
- FREETMPS;
+NOTE: the perl_ form of this function is deprecated.
+
+ CV* get_cv(const char* name, I32 create)
=for hackers
-Found in file scope.h
+Found in file perl.c
-=item getcwd_sv
+=item Nullcv
-Fill the sv with current working directory
+Null CV pointer.
- int getcwd_sv(SV* sv)
=for hackers
-Found in file util.c
+Found in file cv.h
-=item get_av
-Returns the AV of the specified Perl array. If C<create> is set and the
-Perl variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then NULL is returned.
+=back
-NOTE: the perl_ form of this function is deprecated.
+=head1 Embedding Functions
- AV* get_av(const char* name, I32 create)
+=over 8
-=for hackers
-Found in file perl.c
+=item load_module
-=item get_cv
+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>.
-Returns the CV of the specified Perl subroutine. If C<create> is set and
-the Perl subroutine does not exist then it will be declared (which has the
-same effect as saying C<sub name;>). If C<create> is not set and the
-subroutine does not exist then NULL is returned.
+ void load_module(U32 flags, SV* name, SV* ver, ...)
-NOTE: the perl_ form of this function is deprecated.
+=for hackers
+Found in file op.c
- CV* get_cv(const char* name, I32 create)
+=item nothreadhook
+
+Stub that provides thread hook for perl_destruct when there are
+no threads.
+
+ int nothreadhook()
=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 perl_alloc
-NOTE: the perl_ form of this function is deprecated.
+Allocates a new Perl interpreter. See L<perlembed>.
- HV* get_hv(const char* name, I32 create)
+ PerlInterpreter* perl_alloc()
=for hackers
Found in file perl.c
-=item get_sv
-
-Returns the SV of the specified Perl scalar. If C<create> is set and the
-Perl variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then NULL is returned.
+=item perl_construct
-NOTE: the perl_ form of this function is deprecated.
+Initializes a new Perl interpreter. See L<perlembed>.
- SV* get_sv(const char* name, I32 create)
+ void perl_construct(PerlInterpreter* interp)
=for hackers
Found in file perl.c
-=item GIMME
+=item perl_destruct
-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.
+Shuts down a Perl interpreter. See L<perlembed>.
- U32 GIMME
+ int perl_destruct(PerlInterpreter* interp)
=for hackers
-Found in file op.h
+Found in file perl.c
-=item GIMME_V
+=item perl_free
-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.
+Releases a Perl interpreter. See L<perlembed>.
- U32 GIMME_V
+ void perl_free(PerlInterpreter* interp)
=for hackers
-Found in file op.h
+Found in file perl.c
-=item grok_bin
+=item perl_parse
-converts a string representing a binary number to numeric form.
+Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
-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.
+ int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
-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).
+=for hackers
+Found in file perl.c
-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.
+=item perl_run
- UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
+Tells a Perl interpreter to run. See L<perlembed>.
+
+ int perl_run(PerlInterpreter* interp)
=for hackers
-Found in file numeric.c
+Found in file perl.c
-=item grok_hex
+=item require_pv
-converts a string representing a hex number to numeric form.
+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.
-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.
+NOTE: the perl_ form of this function is deprecated.
-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).
+ void require_pv(const char* pv)
-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.
+=for hackers
+Found in file perl.c
- UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
-=for hackers
-Found in file numeric.c
+=back
-=item grok_number
+=head1 Functions in file pp_pack.c
-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).
-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.
+=over 8
-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.
+=item pack_cat
- int grok_number(const char *pv, STRLEN len, UV *valuep)
+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 numeric.c
+Found in file pp_pack.c
-=item grok_numeric_radix
+=item unpack_str
-Scan and skip for a numeric decimal separator (radix).
+The engine implementing unpack() Perl function.
- bool grok_numeric_radix(const char **sp, const char *send)
+ 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 numeric.c
+Found in file pp_pack.c
-=item grok_oct
+=back
- UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
+=head1 Global Variables
-=for hackers
-Found in file numeric.c
+=over 8
-=item GvSV
+=item PL_modglobal
-Return the SV from the GV.
+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.
- SV* GvSV(GV* gv)
+ HV* PL_modglobal
=for hackers
-Found in file gv.h
+Found in file intrpvar.h
-=item gv_fetchmeth
+=item PL_na
+
+A convenience variable which is typically used with C<SvPV> when one
+doesn't care about the length of the string. It is usually more efficient
+to either declare a local variable and use that instead or to use the
+C<SvPV_nolen> macro.
+
+ STRLEN PL_na
+
+=for hackers
+Found in file thrdvar.h
+
+=item PL_sv_no
+
+This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
+C<&PL_sv_no>.
+
+ SV PL_sv_no
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_undef
+
+This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
+
+ SV PL_sv_undef
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_yes
+
+This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
+C<&PL_sv_yes>.
+
+ SV PL_sv_yes
+
+=for hackers
+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
=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
=for hackers
Found in file gv.c
-=item G_ARRAY
-Used to indicate list context. See C<GIMME_V>, C<GIMME> and
-L<perlcall>.
+=back
-=for hackers
-Found in file cop.h
+=head1 Handy Values
-=item G_DISCARD
+=over 8
-Indicates that arguments returned from a callback should be discarded. See
-L<perlcall>.
+=item HEf_SVKEY
-=for hackers
-Found in file cop.h
+This flag, used in the length slot of hash entries and magic structures,
+specifies the structure contains an C<SV*> pointer where a C<char*> pointer
+is to be expected. (For information only--not to be used).
-=item G_EVAL
-Used to force a Perl C<eval> wrapper around a callback. See
-L<perlcall>.
+=for hackers
+Found in file hv.h
+=item Nullch
+
+Null character pointer.
=for hackers
-Found in file cop.h
+Found in file handy.h
-=item G_NOARGS
+=item Nullsv
-Indicates that no arguments are being sent to a callback. See
-L<perlcall>.
+Null SV pointer.
=for hackers
-Found in file cop.h
+Found in file handy.h
-=item G_SCALAR
-Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
-L<perlcall>.
+=back
-=for hackers
-Found in file cop.h
+=head1 Hash Manipulation Functions
-=item G_VOID
+=over 8
-Used to indicate void context. See C<GIMME_V> and L<perlcall>.
+=item get_hv
-=for hackers
-Found in file cop.h
+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 HEf_SVKEY
+NOTE: the perl_ form of this function is deprecated.
-This flag, used in the length slot of hash entries and magic structures,
-specifies the structure contains an C<SV*> pointer where a C<char*> pointer
-is to be expected. (For information only--not to be used).
+ HV* get_hv(const char* name, I32 create)
=for hackers
-Found in file hv.h
+Found in file perl.c
=item HeHASH
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
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
=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
=for hackers
Found in file hv.c
-=item isALNUM
+=item newHV
-Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
-character (including underscore) or digit.
+Creates a new HV. The reference count is set to 1.
- bool isALNUM(char ch)
+ HV* newHV()
=for hackers
-Found in file handy.h
+Found in file hv.c
-=item isALPHA
+=item Nullhv
-Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
-character.
+Null HV pointer.
- bool isALPHA(char ch)
=for hackers
-Found in file handy.h
+Found in file hv.h
-=item isDIGIT
-Returns a boolean indicating whether the C C<char> is an ASCII
-digit.
+=back
- bool isDIGIT(char ch)
+=head1 Magical Functions
-=for hackers
-Found in file handy.h
+=over 8
-=item isLOWER
+=item mg_clear
-Returns a boolean indicating whether the C C<char> is a lowercase
-character.
+Clear something magical that the SV represents. See C<sv_magic>.
- bool isLOWER(char ch)
+ int mg_clear(SV* sv)
=for hackers
-Found in file handy.h
+Found in file mg.c
-=item isSPACE
+=item mg_copy
-Returns a boolean indicating whether the C C<char> is whitespace.
+Copies the magic from one SV to another. See C<sv_magic>.
- bool isSPACE(char ch)
+ int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
=for hackers
-Found in file handy.h
+Found in file mg.c
-=item isUPPER
+=item mg_find
-Returns a boolean indicating whether the C C<char> is an uppercase
-character.
+Finds the magic pointer for type matching the SV. See C<sv_magic>.
- bool isUPPER(char ch)
+ MAGIC* mg_find(SV* sv, int type)
=for hackers
-Found in file handy.h
+Found in file mg.c
-=item is_utf8_char
+=item mg_free
-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.
+Free any magic storage used by the SV. See C<sv_magic>.
- STRLEN is_utf8_char(U8 *p)
+ int mg_free(SV* sv)
=for hackers
-Found in file utf8.c
+Found in file mg.c
-=item is_utf8_string
+=item mg_get
-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.
+Do magic after a value is retrieved from the SV. See C<sv_magic>.
- bool is_utf8_string(U8 *s, STRLEN len)
+ int mg_get(SV* sv)
=for hackers
-Found in file utf8.c
+Found in file mg.c
-=item items
+=item mg_length
-Variable which is setup by C<xsubpp> to indicate the number of
-items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
+Report on the SV's length. See C<sv_magic>.
- I32 items
+ U32 mg_length(SV* sv)
=for hackers
-Found in file XSUB.h
+Found in file mg.c
-=item ix
+=item mg_magical
-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">.
+Turns on the magical status of an SV. See C<sv_magic>.
- I32 ix
+ void mg_magical(SV* sv)
=for hackers
-Found in file XSUB.h
+Found in file mg.c
-=item LEAVE
+=item mg_set
-Closing bracket on a callback. See C<ENTER> and L<perlcall>.
+Do magic after a value is assigned to the SV. See C<sv_magic>.
- LEAVE;
+ int mg_set(SV* sv)
=for hackers
-Found in file scope.h
+Found in file mg.c
-=item load_module
+=item SvGETMAGIC
-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>.
+Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
+argument more than once.
- void load_module(U32 flags, SV* name, SV* ver, ...)
+ void SvGETMAGIC(SV* sv)
=for hackers
-Found in file op.c
+Found in file sv.h
-=item looks_like_number
+=item SvLOCK
-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.
+Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
+has been loaded.
- I32 looks_like_number(SV* sv)
+ void SvLOCK(SV* sv)
=for hackers
-Found in file sv.c
+Found in file sv.h
-=item MARK
+=item SvSETMAGIC
-Stack marker variable for the XSUB. See C<dMARK>.
+Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
+argument more than once.
-=for hackers
-Found in file pp.h
-
-=item mg_clear
-
-Clear something magical that the SV represents. See C<sv_magic>.
-
- int mg_clear(SV* sv)
+ void SvSETMAGIC(SV* sv)
=for hackers
-Found in file mg.c
+Found in file sv.h
-=item mg_copy
+=item SvSetMagicSV
-Copies the magic from one SV to another. See C<sv_magic>.
+Like C<SvSetSV>, but does any set magic required afterwards.
- int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
+ void SvSetMagicSV(SV* dsb, SV* ssv)
=for hackers
-Found in file mg.c
+Found in file sv.h
-=item mg_find
+=item SvSetMagicSV_nosteal
-Finds the magic pointer for type matching the SV. See C<sv_magic>.
+Like C<SvSetMagicSV>, but does any set magic required afterwards.
- MAGIC* mg_find(SV* sv, int type)
+ void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
=for hackers
-Found in file mg.c
+Found in file sv.h
-=item mg_free
+=item SvSetSV
-Free any magic storage used by the SV. See C<sv_magic>.
+Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
+more than once.
- int mg_free(SV* sv)
+ void SvSetSV(SV* dsb, SV* ssv)
=for hackers
-Found in file mg.c
+Found in file sv.h
-=item mg_get
+=item SvSetSV_nosteal
-Do magic after a value is retrieved from the SV. See C<sv_magic>.
+Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
+ssv. May evaluate arguments more than once.
- int mg_get(SV* sv)
+ void SvSetSV_nosteal(SV* dsv, SV* ssv)
=for hackers
-Found in file mg.c
+Found in file sv.h
-=item mg_length
+=item SvSHARE
-Report on the SV's length. See C<sv_magic>.
+Arranges for sv to be shared between threads if a suitable module
+has been loaded.
- U32 mg_length(SV* sv)
+ void SvSHARE(SV* sv)
=for hackers
-Found in file mg.c
+Found in file sv.h
-=item mg_magical
-Turns on the magical status of an SV. See C<sv_magic>.
+=back
- void mg_magical(SV* sv)
+=head1 Memory Management
-=for hackers
-Found in file mg.c
+=over 8
-=item mg_set
+=item Copy
-Do magic after a value is assigned to the SV. See C<sv_magic>.
+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>.
- int mg_set(SV* sv)
+ void Copy(void* src, void* dest, int nitems, type)
=for hackers
-Found in file mg.c
+Found in file handy.h
=item Move
=for hackers
Found in file handy.h
-=item newAV
-
-Creates a new AV. The reference count is set to 1.
-
- AV* newAV()
-
-=for hackers
-Found in file av.c
-
=item Newc
The XSUB-writer's interface to the C C<malloc> function, with
=for hackers
Found in file handy.h
-=item newCONSTSUB
+=item NEWSV
-Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
-eligible for inlining at compile-time.
+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).
- CV* newCONSTSUB(HV* stash, char* name, SV* sv)
+
+ SV* NEWSV(int id, STRLEN len)
=for hackers
-Found in file op.c
+Found in file handy.h
-=item newHV
+=item Newz
-Creates a new HV. The reference count is set to 1.
+The XSUB-writer's interface to the C C<malloc> function. The allocated
+memory is zeroed with C<memzero>.
- HV* newHV()
+ void Newz(int id, void* ptr, int nitems, type)
=for hackers
-Found in file hv.c
+Found in file handy.h
-=item newRV_inc
+=item Poison
-Creates an RV wrapper for an SV. The reference count for the original SV is
-incremented.
+Fill up memory with a pattern (byte 0xAB over and over again) that
+hopefully catches attempts to access uninitialized memory.
- SV* newRV_inc(SV* sv)
+ void Poison(void* dest, int nitems, type)
=for hackers
-Found in file sv.h
+Found in file handy.h
-=item newRV_noinc
+=item Renew
-Creates an RV wrapper for an SV. The reference count for the original
-SV is B<not> incremented.
+The XSUB-writer's interface to the C C<realloc> function.
- SV* newRV_noinc(SV *sv)
+ void Renew(void* ptr, int nitems, type)
=for hackers
-Found in file sv.c
+Found in file handy.h
-=item newSV
+=item Renewc
-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.
+The XSUB-writer's interface to the C C<realloc> function, with
+cast.
- SV* newSV(STRLEN len)
+ void Renewc(void* ptr, int nitems, type, cast)
=for hackers
-Found in file sv.c
+Found in file handy.h
-=item NEWSV
+=item Safefree
-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).
+The XSUB-writer's interface to the C C<free> function.
- SV* NEWSV(int id, STRLEN len)
+ void Safefree(void* ptr)
=for hackers
Found in file handy.h
-=item newSViv
+=item savepv
-Creates a new SV and copies an integer into it. The reference count for the
-SV is set to 1.
+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.
- SV* newSViv(IV i)
+ char* savepv(const char* pv)
=for hackers
-Found in file sv.c
+Found in file util.c
-=item newSVnv
+=item savepvn
-Creates a new SV and copies a floating point value into it.
-The reference count for the SV is set to 1.
+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.
- SV* newSVnv(NV n)
+ char* savepvn(const char* pv, I32 len)
=for hackers
-Found in file sv.c
+Found in file util.c
-=item newSVpv
+=item savesharedpv
-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.
+A version of C<savepv()> which allocates the duplicate string in memory
+which is shared between threads.
- SV* newSVpv(const char* s, STRLEN len)
+ char* savesharedpv(const char* pv)
=for hackers
-Found in file sv.c
+Found in file util.c
-=item newSVpvf
+=item StructCopy
-Creates a new SV and initializes it with the string formatted like
-C<sprintf>.
+This is an architecture-independent macro to copy one structure to another.
- SV* newSVpvf(const char* pat, ...)
+ void StructCopy(type src, type dest, type)
=for hackers
-Found in file sv.c
+Found in file handy.h
-=item newSVpvn
+=item Zero
-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.
+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.
- SV* newSVpvn(const char* s, STRLEN len)
+ void Zero(void* dest, int nitems, type)
=for hackers
-Found in file sv.c
+Found in file handy.h
-=item newSVpvn_share
-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.
+=back
- SV* newSVpvn_share(const char* s, I32 len, U32 hash)
+=head1 Miscellaneous Functions
+
+=over 8
+
+=item fbm_compile
+
+Analyses the string in order to make fast searches on it using fbm_instr()
+-- the Boyer-Moore algorithm.
+
+ void fbm_compile(SV* sv, U32 flags)
=for hackers
-Found in file sv.c
+Found in file util.c
-=item newSVrv
+=item fbm_instr
-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.
+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.
- SV* newSVrv(SV* rv, const char* classname)
+ char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
=for hackers
-Found in file sv.c
+Found in file util.c
-=item newSVsv
+=item form
-Creates a new SV which is an exact duplicate of the original SV.
-(Uses C<sv_setsv>).
+Takes a sprintf-style format pattern and conventional
+(non-SV) arguments and returns the formatted string.
- SV* newSVsv(SV* old)
+ (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 sv.c
+Found in file util.c
-=item newSVuv
+=item getcwd_sv
-Creates a new SV and copies an unsigned integer into it.
-The reference count for the SV is set to 1.
+Fill the sv with current working directory
- SV* newSVuv(UV u)
+ int getcwd_sv(SV* sv)
=for hackers
-Found in file sv.c
+Found in file util.c
-=item newXS
+=item strEQ
-Used by C<xsubpp> to hook up XSUBs as Perl subs.
+Test two strings to see if they are equal. Returns true or false.
+
+ bool strEQ(char* s1, char* s2)
=for hackers
-Found in file op.c
+Found in file handy.h
-=item newXSproto
+=item strGE
-Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
-the subs.
+Test two strings to see if the first, C<s1>, is greater than or equal to
+the second, C<s2>. Returns true or false.
+
+ bool strGE(char* s1, char* s2)
=for hackers
-Found in file XSUB.h
+Found in file handy.h
-=item Newz
+=item strGT
-The XSUB-writer's interface to the C C<malloc> function. The allocated
-memory is zeroed with C<memzero>.
+Test two strings to see if the first, C<s1>, is greater than the second,
+C<s2>. Returns true or false.
- void Newz(int id, void* ptr, int nitems, type)
+ bool strGT(char* s1, char* s2)
=for hackers
Found in file handy.h
-=item new_vstring
+=item strLE
-Returns a pointer to the next character after the parsed
-vstring, as well as updating the passed in sv.
- *
-Function must be called like
-
- sv = NEWSV(92,5);
- s = new_vstring(s,sv);
+Test two strings to see if the first, C<s1>, is less than or equal to the
+second, C<s2>. Returns true or false.
-The sv must already be large enough to store the vstring
-passed in.
+ bool strLE(char* s1, char* s2)
- char* new_vstring(char *vstr, SV *sv)
+=for hackers
+Found in file handy.h
+
+=item strLT
+
+Test two strings to see if the first, C<s1>, is less than the second,
+C<s2>. Returns true or false.
+
+ bool strLT(char* s1, char* s2)
=for hackers
-Found in file util.c
+Found in file handy.h
-=item Nullav
+=item strNE
-Null AV pointer.
+Test two strings to see if they are different. Returns true or
+false.
+
+ bool strNE(char* s1, char* s2)
=for hackers
-Found in file av.h
+Found in file handy.h
-=item Nullch
+=item strnEQ
-Null character pointer.
+Test two strings to see if they are equal. The C<len> parameter indicates
+the number of bytes to compare. Returns true or false. (A wrapper for
+C<strncmp>).
+
+ bool strnEQ(char* s1, char* s2, STRLEN len)
=for hackers
Found in file handy.h
-=item Nullcv
+=item strnNE
-Null CV pointer.
+Test two strings to see if they are different. The C<len> parameter
+indicates the number of bytes to compare. Returns true or false. (A
+wrapper for C<strncmp>).
+
+ bool strnNE(char* s1, char* s2, STRLEN len)
=for hackers
-Found in file cv.h
+Found in file handy.h
-=item Nullhv
-Null HV pointer.
+=back
+
+=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 hv.h
+Found in file numeric.c
-=item Nullsv
+=item grok_hex
-Null SV pointer.
+converts a string representing a hex 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 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 handy.h
+Found in file numeric.c
-=item ORIGMARK
+=item grok_number
-The original stack mark for the XSUB. See C<dORIGMARK>.
+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).
+
+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 pp.h
+Found in file numeric.c
-=item perl_alloc
+=item grok_numeric_radix
-Allocates a new Perl interpreter. See L<perlembed>.
+Scan and skip for a numeric decimal separator (radix).
- PerlInterpreter* perl_alloc()
+ bool grok_numeric_radix(const char **sp, const char *send)
=for hackers
-Found in file perl.c
+Found in file numeric.c
-=item perl_clone
+=item grok_oct
-Create and return a new interpreter by cloning the current one.
- PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
+ UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
=for hackers
-Found in file sv.c
+Found in file numeric.c
-=item perl_construct
+=item scan_bin
-Initializes a new Perl interpreter. See L<perlembed>.
+For backwards compatibility. Use C<grok_bin> instead.
- void perl_construct(PerlInterpreter* interp)
+ NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
=for hackers
-Found in file perl.c
+Found in file numeric.c
-=item perl_destruct
+=item scan_hex
-Shuts down a Perl interpreter. See L<perlembed>.
+For backwards compatibility. Use C<grok_hex> instead.
- int perl_destruct(PerlInterpreter* interp)
+ NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
=for hackers
-Found in file perl.c
+Found in file numeric.c
-=item perl_free
+=item scan_oct
-Releases a Perl interpreter. See L<perlembed>.
+For backwards compatibility. Use C<grok_oct> instead.
- void perl_free(PerlInterpreter* interp)
+ NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
=for hackers
-Found in file perl.c
+Found in file numeric.c
-=item perl_parse
-Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
+=back
- int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
+=head1 Optree Manipulation Functions
+
+=over 8
+
+=item cv_const_sv
+
+If C<cv> is a constant sub eligible for inlining. returns the constant
+value returned by the sub. Otherwise, returns NULL.
+
+Constant subs can be created with C<newCONSTSUB> or as described in
+L<perlsub/"Constant Functions">.
+
+ SV* cv_const_sv(CV* cv)
=for hackers
-Found in file perl.c
+Found in file op.c
-=item perl_run
+=item newCONSTSUB
-Tells a Perl interpreter to run. See L<perlembed>.
+Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
+eligible for inlining at compile-time.
- int perl_run(PerlInterpreter* interp)
+ CV* newCONSTSUB(HV* stash, char* name, SV* sv)
=for hackers
-Found in file perl.c
+Found in file op.c
-=item PL_modglobal
+=item newXS
-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.
+Used by C<xsubpp> to hook up XSUBs as Perl subs.
- HV* PL_modglobal
+=for hackers
+Found in file op.c
+
+
+=back
+
+=head1 Stack Manipulation Macros
+
+=over 8
+
+=item dMARK
+
+Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
+C<dORIGMARK>.
+
+ dMARK;
=for hackers
-Found in file intrpvar.h
+Found in file pp.h
-=item PL_na
+=item dORIGMARK
-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.
+Saves the original stack mark for the XSUB. See C<ORIGMARK>.
- STRLEN PL_na
+ dORIGMARK;
=for hackers
-Found in file thrdvar.h
+Found in file pp.h
-=item PL_sv_no
+=item dSP
-This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
-C<&PL_sv_no>.
+Declares a local copy of perl's stack pointer for the XSUB, available via
+the C<SP> macro. See C<SP>.
- SV PL_sv_no
+ dSP;
+
+=for hackers
+Found in file pp.h
+
+=item EXTEND
+
+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.
+
+ void EXTEND(SP, int nitems)
=for hackers
-Found in file intrpvar.h
-
-=item PL_sv_undef
+Found in file pp.h
-This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
+=item MARK
- SV PL_sv_undef
+Stack marker variable for the XSUB. See C<dMARK>.
=for hackers
-Found in file intrpvar.h
-
-=item PL_sv_yes
+Found in file pp.h
-This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
-C<&PL_sv_yes>.
+=item ORIGMARK
- SV PL_sv_yes
+The original stack mark for the XSUB. See C<dORIGMARK>.
=for hackers
-Found in file intrpvar.h
+Found in file pp.h
=item POPi
=for hackers
Found in file pp.h
-=item Renew
+=item SP
-The XSUB-writer's interface to the C C<realloc> function.
+Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
+C<SPAGAIN>.
- void Renew(void* ptr, int nitems, type)
+=for hackers
+Found in file pp.h
+
+=item SPAGAIN
+
+Refetch the stack pointer. Used after a callback. See L<perlcall>.
+
+ SPAGAIN;
=for hackers
-Found in file handy.h
+Found in file pp.h
-=item Renewc
+=item XPUSHi
-The XSUB-writer's interface to the C C<realloc> function, with
-cast.
+Push an integer onto the stack, extending the stack if necessary. Handles
+'set' magic. See C<PUSHi>.
- void Renewc(void* ptr, int nitems, type, cast)
+ void XPUSHi(IV iv)
=for hackers
-Found in file handy.h
+Found in file pp.h
-=item require_pv
+=item XPUSHn
-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.
+Push a double onto the stack, extending the stack if necessary. Handles
+'set' magic. See C<PUSHn>.
-NOTE: the perl_ form of this function is deprecated.
+ void XPUSHn(NV nv)
- void require_pv(const char* pv)
+=for hackers
+Found in file pp.h
+
+=item XPUSHp
+
+Push a string onto the stack, extending the stack if necessary. The C<len>
+indicates the length of the string. Handles 'set' magic. See
+C<PUSHp>.
+
+ void XPUSHp(char* str, STRLEN len)
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item RETVAL
+=item XPUSHs
-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">.
+Push an SV onto the stack, extending the stack if necessary. Does not
+handle 'set' magic. See C<PUSHs>.
- (whatever) RETVAL
+ void XPUSHs(SV* sv)
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHu
+
+Push an unsigned integer onto the stack, extending the stack if necessary.
+See C<PUSHu>.
+
+ void XPUSHu(UV uv)
+
+=for hackers
+Found in file pp.h
+
+=item XSRETURN
+
+Return from XSUB, indicating number of items on the stack. This is usually
+handled by C<xsubpp>.
+
+ void XSRETURN(int nitems)
=for hackers
Found in file XSUB.h
-=item Safefree
+=item XSRETURN_IV
-The XSUB-writer's interface to the C C<free> function.
+Return an integer from an XSUB immediately. Uses C<XST_mIV>.
- void Safefree(void* ptr)
+ void XSRETURN_IV(IV iv)
=for hackers
-Found in file handy.h
+Found in file XSUB.h
-=item savepv
+=item XSRETURN_NO
-Copy a string to a safe spot. This does not use an SV.
+Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
- char* savepv(const char* sv)
+ XSRETURN_NO;
=for hackers
-Found in file util.c
+Found in file XSUB.h
-=item savepvn
+=item XSRETURN_NV
-Copy a string to a safe spot. The C<len> indicates number of bytes to
-copy. This does not use an SV.
+Return a double from an XSUB immediately. Uses C<XST_mNV>.
- char* savepvn(const char* sv, I32 len)
+ void XSRETURN_NV(NV nv)
=for hackers
-Found in file util.c
+Found in file XSUB.h
-=item SAVETMPS
+=item XSRETURN_PV
-Opening bracket for temporaries on a callback. See C<FREETMPS> and
-L<perlcall>.
+Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
- SAVETMPS;
+ void XSRETURN_PV(char* str)
=for hackers
-Found in file scope.h
+Found in file XSUB.h
-=item scan_bin
+=item XSRETURN_UNDEF
-For backwards compatibility. Use C<grok_bin> instead.
+Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
- NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
+ XSRETURN_UNDEF;
=for hackers
-Found in file numeric.c
+Found in file XSUB.h
-=item scan_hex
+=item XSRETURN_YES
-For backwards compatibility. Use C<grok_hex> instead.
+Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
- NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
+ XSRETURN_YES;
=for hackers
-Found in file numeric.c
+Found in file XSUB.h
-=item scan_oct
+=item XST_mIV
-For backwards compatibility. Use C<grok_oct> instead.
+Place an integer into the specified position C<pos> on the stack. The
+value is stored in a new mortal SV.
- NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
+ void XST_mIV(int pos, IV iv)
=for hackers
-Found in file numeric.c
+Found in file XSUB.h
+
+=item XST_mNO
+
+Place C<&PL_sv_no> into the specified position C<pos> on the
+stack.
+
+ void XST_mNO(int pos)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mNV
+
+Place a double into the specified position C<pos> on the stack. The value
+is stored in a new mortal SV.
+
+ void XST_mNV(int pos, NV nv)
+
+=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.
+
+ void XST_mPV(int pos, char* str)
+
+=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 XST_mYES
-=item sharedsv_find
+Place C<&PL_sv_yes> into the specified position C<pos> on the
+stack.
+
+ void XST_mYES(int pos)
+
+=for hackers
+Found in file XSUB.h
+
+
+=back
+
+=head1 SV Flags
+
+=over 8
+
+=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 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>.
-Tries to find if a given SV has a shared backend, either by
-looking at magic, or by checking if it is tied again threads::shared.
+=for hackers
+Found in file sv.h
+
+=item SVt_PV
- shared_sv* sharedsv_find(SV* sv)
+Pointer type flag for scalars. See C<svtype>.
=for hackers
-Found in file sharedsv.c
+Found in file sv.h
+
+=item SVt_PVAV
-=item sharedsv_init
+Type flag for arrays. See C<svtype>.
+
+=for hackers
+Found in file sv.h
-Saves a space for keeping SVs wider than an interpreter,
-currently only stores a pointer to the first interpreter.
+=item SVt_PVCV
- void sharedsv_init()
+Type flag for code refs. See C<svtype>.
=for hackers
-Found in file sharedsv.c
+Found in file sv.h
-=item sharedsv_lock
+=item SVt_PVHV
-Recursive locks on a sharedsv.
-Locks are dynamically scoped at the level of the first lock.
- void sharedsv_lock(shared_sv* ssv)
+Type flag for hashes. See C<svtype>.
=for hackers
-Found in file sharedsv.c
+Found in file sv.h
-=item sharedsv_new
+=item SVt_PVMG
-Allocates a new shared sv struct, you must yourself create the SV/AV/HV.
- shared_sv* sharedsv_new()
+Type flag for blessed scalars. See C<svtype>.
=for hackers
-Found in file sharedsv.c
+Found in file sv.h
+
+
+=back
-=item sharedsv_thrcnt_dec
+=head1 SV Manipulation Functions
+
+=over 8
+
+=item get_sv
+
+Returns the SV of the specified Perl scalar. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
-Decrements the threadcount of a shared sv. When a threads frontend is freed
-this function should be called.
+NOTE: the perl_ form of this function is deprecated.
- void sharedsv_thrcnt_dec(shared_sv* ssv)
+ SV* get_sv(const char* name, I32 create)
=for hackers
-Found in file sharedsv.c
+Found in file perl.c
+
+=item looks_like_number
-=item sharedsv_thrcnt_inc
+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.
-Increments the threadcount of a sharedsv.
- void sharedsv_thrcnt_inc(shared_sv* ssv)
+ I32 looks_like_number(SV* sv)
=for hackers
-Found in file sharedsv.c
+Found in file sv.c
-=item sharedsv_unlock
+=item newRV_inc
-Recursively unlocks a shared sv.
+Creates an RV wrapper for an SV. The reference count for the original SV is
+incremented.
- void sharedsv_unlock(shared_sv* ssv)
+ SV* newRV_inc(SV* sv)
=for hackers
-Found in file sharedsv.c
-
-=item sortsv
+Found in file sv.h
-Sort an array. Here is an example:
+=item newRV_noinc
- sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
+Creates an RV wrapper for an SV. The reference count for the original
+SV is B<not> incremented.
- void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t f)
+ SV* newRV_noinc(SV *sv)
=for hackers
-Found in file pp_ctl.c
+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
=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 efficient 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 efficient 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)
=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)
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
-
-Like C<SvSetSV>, but does any set magic required afterwards.
-
- void SvSetMagicSV(SV* dsb, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetMagicSV_nosteal
-
-Like C<SvSetMagicSV>, but does any set magic required afterwards.
-
- void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetSV
-
-Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
-more than once.
-
- void SvSetSV(SV* dsb, SV* ssv)
+ 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
=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>).
=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_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_reftype
Returns a string describing what the SV is a reference to.
=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
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
+=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
+
+The "p" contains the pointer to the UTF-8 string encoding
+the character that is being converted.
+
+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.
+
+The "swashp" is a pointer to the swash to use.
-=item sv_vsetpvfn
+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.
-Works like C<vcatpvfn> but copies the text into the SV instead of
-appending it.
+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_setpvf> and C<sv_setpvf_mg>.
+The "normal" is a string like "ToLower" which means the swash
+%utf8::ToLower.
- void sv_vsetpvfn(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 THIS
+=item to_utf8_fold
-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 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).
- (whatever) THIS
+The first character of the foldcased version is returned
+(but note, as explained above, that there may be more.)
-=for hackers
-Found in file XSUB.h
+ UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)
-=item toLOWER
+=for hackers
+Found in file utf8.c
-Converts the specified character to lowercase.
+=item to_utf8_lower
- char toLOWER(char ch)
+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).
-=for hackers
-Found in file handy.h
+The first character of the lowercased version is returned
+(but note, as explained above, that there may be more.)
-=item toUPPER
+ UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)
-Converts the specified character to uppercase.
+=for hackers
+Found in file utf8.c
- char toUPPER(char ch)
+=item to_utf8_title
-=for hackers
-Found in file handy.h
+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).
-=item to_utf8_case
+The first character of the titlecased version is returned
+(but note, as explained above, that there may be more.)
-The "p" contains the pointer to the UTF-8 string encoding
-the character that is being converted.
+ UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)
-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 utf8.c
-The "swash" is a pointer to the swash to use.
+=item to_utf8_upper
-The "normal" is a string like "ToLower" which means the swash
-$utf8::ToLower, which is stored in lib/unicore/To/Lower.pl,
-and loaded by SWASHGET, using lib/utf8_heavy.pl.
+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).
-The "special" is a string like "utf8::ToSpecLower", which means
-the hash %utf8::ToSpecLower, which is stored in the same file,
-lib/unicore/To/Lower.pl, and also loaded by SWASHGET. The access
-to the hash is by Perl_to_utf8_case().
+The first character of the uppercased version is returned
+(but note, as explained above, that there may be more.)
- UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
+ UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)
=for hackers
Found in file utf8.c
=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 a 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
https://perl5.git.perl.org / perl5.git / blobdiff