X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=0b915ddba6cc4651d5f6e6ec461ce50437ae0f1d;hb=824215e2e3b067efbb0104afd616d77cb9526d1a;hp=5f0a584e58835705997f5b419f716a786b42786c;hpb=640374d0dfc3428416b596d67c06b3c817f44bd8;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 5f0a584..0b915dd 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -17,6 +17,85 @@ unadorned names, but this support may be disabled in a future release.
 
 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
@@ -182,36 +261,53 @@ must then use C<av_store> to assign values to these new elements.
 =for hackers
 Found in file av.c
 
-=item bytes_from_utf8
+=item get_av
 
-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.
+Returns the AV of the specified Perl array.  If C<create> is set and the
+Perl variable does not exist then it will be created.  If C<create> is not
+set and the variable does not exist then NULL is returned.
 
-NOTE: this function is experimental and may change or be
-removed without notice.
+NOTE: the perl_ form of this function is deprecated.
 
-	U8*	bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
+	AV*	get_av(const char* name, I32 create)
 
 =for hackers
-Found in file utf8.c
+Found in file perl.c
 
-=item bytes_to_utf8
+=item newAV
 
-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.
+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_to_utf8(U8 *s, STRLEN *len)
 
 =for hackers
-Found in file utf8.c
+Found in file av.h
+
+=item sortsv
+
+Sort an array. Here is an example:
+
+    sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
+
+	void	sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp)
+
+=for hackers
+Found in file pp_sort.c
+
+
+=back
+
+=head1 Callback Functions
+
+=over 8
 
 =item call_argv
 
@@ -259,203 +355,181 @@ NOTE: the perl_ form of this function is deprecated.
 =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 dMARK
+=item SAVETMPS
 
-Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
-C<dORIGMARK>.
+Opening bracket for temporaries on a callback.  See C<FREETMPS> and
+L<perlcall>.
 
-		dMARK;
+		SAVETMPS;
 
 =for hackers
-Found in file pp.h
+Found in file scope.h
 
-=item dORIGMARK
 
-Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
+=back
 
-		dORIGMARK;
+=head1 Character classes
 
-=for hackers
-Found in file pp.h
+=over 8
 
-=item dSP
+=item isALNUM
 
-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 alphanumeric
+character (including underscore) or digit.
 
-		dSP;
+	bool	isALNUM(char ch)
 
 =for hackers
-Found in file pp.h
+Found in file handy.h
 
-=item dXSARGS
+=item isALPHA
 
-Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.  This
-is usually handled automatically by C<xsubpp>.  Declares the C<items>
-variable to indicate the number of items on the stack.
+Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
+character.
 
-		dXSARGS;
+	bool	isALPHA(char ch)
 
 =for hackers
-Found in file XSUB.h
+Found in file handy.h
 
-=item dXSI32
+=item isDIGIT
 
-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 an ASCII
+digit.
 
-		dXSI32;
+	bool	isDIGIT(char ch)
 
 =for hackers
-Found in file XSUB.h
+Found in file handy.h
 
-=item ENTER
+=item isLOWER
 
-Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.
+Returns a boolean indicating whether the C C<char> is a lowercase
+character.
 
-		ENTER;
+	bool	isLOWER(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 isSPACE
 
-NOTE: the perl_ form of this function is deprecated.
+Returns a boolean indicating whether the C C<char> is whitespace.
 
-	SV*	eval_pv(const char* p, I32 croak_on_error)
+	bool	isSPACE(char ch)
 
 =for hackers
-Found in file perl.c
+Found in file handy.h
 
-=item eval_sv
+=item isUPPER
 
-Tells Perl to C<eval> the string in the SV.
+Returns a boolean indicating whether the C C<char> is an uppercase
+character.
 
-NOTE: the perl_ form of this function is deprecated.
-
-	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
+Found in file sv.c
 
-=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 CV Manipulation Functions
 
-	AV*	get_av(const char* name, I32 create)
+=over 8
+
+=item CvSTASH
+
+Returns the stash of the CV.
+
+	HV*	CvSTASH(CV* cv)
 
 =for hackers
-Found in file perl.c
+Found in file cv.h
 
 =item get_cv
 
@@ -471,53 +545,171 @@ NOTE: the perl_ form of this function is deprecated.
 =for hackers
 Found in file perl.c
 
-=item get_hv
+=item Nullcv
 
-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.
+Null CV pointer.
 
-NOTE: the perl_ form of this function is deprecated.
 
-	HV*	get_hv(const char* name, I32 create)
+=for hackers
+Found in file cv.h
+
+
+=back
+
+=head1 Embedding Functions
+
+=over 8
+
+=item load_module
+
+Loads the module whose name is pointed to by the string part of name.
+Note that the actual module name, not its filename, should be given.
+Eg, "Foo::Bar" instead of "Foo/Bar.pm".  flags can be any of
+PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
+(or 0 for no flags). ver, if specified, provides version semantics
+similar to 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>.
+
+	void	load_module(U32 flags, SV* name, SV* ver, ...)
+
+=for hackers
+Found in file op.c
+
+=item perl_alloc
+
+Allocates a new Perl interpreter.  See L<perlembed>.
+
+	PerlInterpreter*	perl_alloc()
 
 =for hackers
 Found in file perl.c
 
-=item get_sv
+=item perl_construct
 
-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.
+Initializes a new Perl interpreter.  See L<perlembed>.
+
+	void	perl_construct(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item perl_destruct
+
+Shuts down a Perl interpreter.  See L<perlembed>.
+
+	int	perl_destruct(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item perl_free
+
+Releases a Perl interpreter.  See L<perlembed>.
+
+	void	perl_free(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item perl_parse
+
+Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
+
+	int	perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
+
+=for hackers
+Found in file perl.c
+
+=item perl_run
+
+Tells a Perl interpreter to run.  See L<perlembed>.
+
+	int	perl_run(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item require_pv
+
+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.
 
-	SV*	get_sv(const char* name, I32 create)
+	void	require_pv(const char* pv)
 
 =for hackers
 Found in file perl.c
 
-=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.
+=back
 
-	U32	GIMME
+=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 op.h
+Found in file intrpvar.h
 
-=item GIMME_V
+=item PL_na
 
-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.
+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.
 
-	U32	GIMME_V
+	STRLEN	PL_na
 
 =for hackers
-Found in file op.h
+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
 
@@ -610,61 +802,55 @@ valid UTF-8 string.  See C<gv_stashpv>.
 =for hackers
 Found in file gv.c
 
-=item G_ARRAY
-
-Used to indicate list context.  See C<GIMME_V>, C<GIMME> and
-L<perlcall>.
 
-=for hackers
-Found in file cop.h
+=back
 
-=item G_DISCARD
+=head1 Handy Values
 
-Indicates that arguments returned from a callback should be discarded.  See
-L<perlcall>.
+=over 8
 
-=for hackers
-Found in file cop.h
+=item HEf_SVKEY
 
-=item G_EVAL
+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).
 
-Used to force a Perl C<eval> wrapper around a callback.  See
-L<perlcall>.
 
 =for hackers
-Found in file cop.h
-
-=item G_NOARGS
+Found in file hv.h
 
-Indicates that no arguments are being sent to a callback.  See
-L<perlcall>.
+=item Nullch 
 
+Null character pointer.
 =for hackers
-Found in file cop.h
+Found in file handy.h
 
-=item G_SCALAR
+=item Nullsv
 
-Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and
-L<perlcall>.
+Null SV pointer.
 
 =for hackers
-Found in file cop.h
+Found in file handy.h
 
-=item G_VOID
 
-Used to indicate void context.  See C<GIMME_V> and L<perlcall>.
+=back
 
-=for hackers
-Found in file cop.h
+=head1 Hash Manipulation Functions
 
-=item HEf_SVKEY
+=over 8
 
-This flag, used in the length slot of hash entries and magic structures,
-specifies the structure contains a C<SV*> pointer where a C<char*> pointer
-is to be expected. (For information only--not to be used).
+=item 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 hv.h
+Found in file perl.c
 
 =item HeHASH
 
@@ -824,7 +1010,7 @@ Found in file hv.c
 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*>.
+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.
@@ -974,151 +1160,29 @@ Undefines the hash.
 =for hackers
 Found in file hv.c
 
-=item isALNUM
-
-Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
-character (including underscore) or digit.
-
-	bool	isALNUM(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isALPHA
-
-Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
-character.
-
-	bool	isALPHA(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isDIGIT
-
-Returns a boolean indicating whether the C C<char> is an ASCII
-digit.
-
-	bool	isDIGIT(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isLOWER
-
-Returns a boolean indicating whether the C C<char> is a lowercase
-character.
-
-	bool	isLOWER(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isSPACE
-
-Returns a boolean indicating whether the C C<char> is whitespace.
-
-	bool	isSPACE(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isUPPER
-
-Returns a boolean indicating whether the C C<char> is an uppercase
-character.
-
-	bool	isUPPER(char ch)
-
-=for hackers
-Found in file handy.h
-
-=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 items
-
-Variable which is setup by C<xsubpp> to indicate the number of 
-items on the stack.  See L<perlxs/"Variable-length Parameter Lists">.
-
-	I32	items
-
-=for hackers
-Found in file XSUB.h
-
-=item ix
-
-Variable which is setup by C<xsubpp> to indicate which of an 
-XSUB's aliases was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
-
-	I32	ix
-
-=for hackers
-Found in file XSUB.h
-
-=item LEAVE
+=item newHV
 
-Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
+Creates a new HV.  The reference count is set to 1.
 
-		LEAVE;
+	HV*	newHV()
 
 =for hackers
-Found in file scope.h
+Found in file hv.c
 
-=item load_module
+=item Nullhv
 
-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>.
+Null HV pointer.
 
-	void	load_module(U32 flags, SV* name, SV* ver, ...)
 
 =for hackers
-Found in file op.c
-
-=item looks_like_number
-
-Test if an 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.
-
-	I32	looks_like_number(SV* sv)
+Found in file hv.h
 
-=for hackers
-Found in file sv.c
 
-=item MARK
+=back
 
-Stack marker variable for the XSUB.  See C<dMARK>.
+=head1 Magical Functions
 
-=for hackers
-Found in file pp.h
+=over 8
 
 =item mg_clear
 
@@ -1192,83 +1256,102 @@ Do magic after a value is assigned to the SV.  See C<sv_magic>.
 =for hackers
 Found in file mg.c
 
-=item Move
+=item SvGETMAGIC
 
-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>.
+Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates its
+argument more than once.
 
-	void	Move(void* src, void* dest, int nitems, type)
+	void	SvGETMAGIC(SV* sv)
 
 =for hackers
-Found in file handy.h
+Found in file sv.h
 
-=item New
+=item SvSETMAGIC
 
-The XSUB-writer's interface to the C C<malloc> function.
+Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates its
+argument more than once.
 
-	void	New(int id, void* ptr, int nitems, type)
+	void	SvSETMAGIC(SV* sv)
 
 =for hackers
-Found in file handy.h
+Found in file sv.h
 
-=item newAV
+=item SvSetMagicSV
 
-Creates a new AV.  The reference count is set to 1.
+Like C<SvSetSV>, but does any set magic required afterwards.
 
-	AV*	newAV()
+	void	SvSetMagicSV(SV* dsb, SV* ssv)
 
 =for hackers
-Found in file av.c
+Found in file sv.h
 
-=item Newc
+=item SvSetSV
 
-The XSUB-writer's interface to the C C<malloc> function, with
-cast.
+Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
+more than once.
 
-	void	Newc(int id, void* ptr, int nitems, type, cast)
+	void	SvSetSV(SV* dsb, SV* ssv)
 
 =for hackers
-Found in file handy.h
+Found in file sv.h
 
-=item newCONSTSUB
+=item SvSetSV_nosteal
 
-Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
-eligible for inlining at compile-time.
+Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
+ssv. May evaluate arguments more than once.
 
-	CV*	newCONSTSUB(HV* stash, char* name, SV* sv)
+	void	SvSetSV_nosteal(SV* dsv, SV* ssv)
 
 =for hackers
-Found in file op.c
+Found in file sv.h
 
-=item newHV
 
-Creates a new HV.  The reference count is set to 1.
+=back
 
-	HV*	newHV()
+=head1 Memory Management
+
+=over 8
+
+=item Copy
+
+The XSUB-writer's interface to the C C<memcpy> function.  The C<src> is the
+source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
+the type.  May fail on overlapping copies.  See also C<Move>.
+
+	void	Copy(void* src, void* dest, int nitems, type)
 
 =for hackers
-Found in file hv.c
+Found in file handy.h
 
-=item newRV_inc
+=item Move
 
-Creates an RV wrapper for an SV.  The reference count for the original SV is
-incremented.
+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>.
 
-	SV*	newRV_inc(SV* sv)
+	void	Move(void* src, void* dest, int nitems, type)
 
 =for hackers
-Found in file sv.h
+Found in file handy.h
 
-=item newRV_noinc
+=item New
 
-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<malloc> function.
 
-	SV*	newRV_noinc(SV *sv)
+	void	New(int id, void* ptr, int nitems, type)
 
 =for hackers
-Found in file sv.c
+Found in file handy.h
+
+=item Newc
+
+The XSUB-writer's interface to the C C<malloc> function, with
+cast.
+
+	void	Newc(int id, void* ptr, int nitems, type, cast)
+
+=for hackers
+Found in file handy.h
 
 =item NEWSV
 
@@ -1278,343 +1361,584 @@ tailing NUL is also reserved.  (SvPOK is not set for the SV even if string
 space is allocated.)  The reference count for the new SV is set to 1.
 C<id> is an integer id between 0 and 1299 (used to identify leaks).
 
+
 	SV*	NEWSV(int id, STRLEN len)
 
 =for hackers
 Found in file handy.h
 
-=item newSViv
+=item Newz
 
-Creates a new SV and copies an integer into it.  The reference count for the
-SV is set to 1.
+The XSUB-writer's interface to the C C<malloc> function.  The allocated
+memory is zeroed with C<memzero>.
 
-	SV*	newSViv(IV i)
+	void	Newz(int id, void* ptr, int nitems, type)
 
 =for hackers
-Found in file sv.c
+Found in file handy.h
 
-=item newSVnv
+=item Renew
 
-Creates a new SV and copies a floating point value into it.
-The reference count for the SV is set to 1.
+The XSUB-writer's interface to the C C<realloc> function.
 
-	SV*	newSVnv(NV n)
+	void	Renew(void* ptr, int nitems, type)
 
 =for hackers
-Found in file sv.c
+Found in file handy.h
 
-=item newSVpv
+=item Renewc
 
-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.
+The XSUB-writer's interface to the C C<realloc> function, with
+cast.
 
-	SV*	newSVpv(const char* s, STRLEN len)
+	void	Renewc(void* ptr, int nitems, type, cast)
 
 =for hackers
-Found in file sv.c
+Found in file handy.h
 
-=item newSVpvf
+=item Safefree
 
-Creates a new SV an initialize it with the string formatted like
-C<sprintf>.
+The XSUB-writer's interface to the C C<free> function.
 
-	SV*	newSVpvf(const char* pat, ...)
+	void	Safefree(void* ptr)
 
 =for hackers
-Found in file sv.c
+Found in file handy.h
 
-=item newSVpvn
+=item savepv
 
-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.
+Copy a string to a safe spot.  This does not use an SV.
 
-	SV*	newSVpvn(const char* s, STRLEN len)
+	char*	savepv(const char* sv)
 
 =for hackers
-Found in file sv.c
+Found in file util.c
 
-=item newSVpvn_share
+=item savepvn
 
-Creates a new SV and populates it with a string from
-the string table. Turns on READONLY and FAKE.
-The idea here is that as string table is used for shared hash
-keys these strings will have SvPVX == HeKEY and hash lookup
-will avoid string compare.
+Copy a string to a safe spot.  The C<len> indicates number of bytes to
+copy.  This does not use an SV.
 
-	SV*	newSVpvn_share(const char* s, I32 len, U32 hash)
+	char*	savepvn(const char* sv, I32 len)
 
 =for hackers
-Found in file sv.c
+Found in file util.c
 
-=item newSVrv
+=item StructCopy
 
-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.
+This is an architecture-independent macro to copy one structure to another.
 
-	SV*	newSVrv(SV* rv, const char* classname)
+	void	StructCopy(type src, type dest, type)
 
 =for hackers
-Found in file sv.c
+Found in file handy.h
 
-=item newSVsv
+=item Zero
 
-Creates a new SV which is an exact duplicate of the original SV.
+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*	newSVsv(SV* old)
+	void	Zero(void* dest, int nitems, type)
 
 =for hackers
-Found in file sv.c
-
-=item newSVuv
-
-Creates a new SV and copies an unsigned integer into it.
-The reference count for the SV is set to 1.
+Found in file handy.h
 
-	SV*	newSVuv(UV u)
 
-=for hackers
-Found in file sv.c
+=back
 
-=item newXS
+=head1 Miscellaneous Functions
 
-Used by C<xsubpp> to hook up XSUBs as Perl subs.
+=over 8
 
-=for hackers
-Found in file op.c
+=item fbm_compile
 
-=item newXSproto
+Analyses the string in order to make fast searches on it using fbm_instr()
+-- the Boyer-Moore algorithm.
 
-Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
-the subs.
+	void	fbm_compile(SV* sv, U32 flags)
 
 =for hackers
-Found in file XSUB.h
+Found in file util.c
 
-=item Newz
+=item fbm_instr
 
-The XSUB-writer's interface to the C C<malloc> function.  The allocated
-memory is zeroed with C<memzero>.
+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.
 
-	void	Newz(int id, void* ptr, int nitems, type)
+	char*	fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
 
 =for hackers
-Found in file handy.h
-
-=item Nullav
+Found in file util.c
 
-Null AV pointer.
+=item form
 
-=for hackers
-Found in file av.h
+Takes a sprintf-style format pattern and conventional
+(non-SV) arguments and returns the formatted string.
 
-=item Nullch
+    (char *) Perl_form(pTHX_ const char* pat, ...)
 
-Null character pointer.
+can be used any place a string (char *) is required:
 
-=for hackers
-Found in file handy.h
+    char * s = Perl_form("%d.%d",major,minor);
 
-=item Nullcv
+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).
 
-Null CV pointer.
+	char*	form(const char* pat, ...)
 
 =for hackers
-Found in file cv.h
+Found in file util.c
 
-=item Nullhv
+=item getcwd_sv
 
-Null HV pointer.
+Fill the sv with current working directory
+
+	int	getcwd_sv(SV* sv)
 
 =for hackers
-Found in file hv.h
+Found in file util.c
 
-=item Nullsv
+=item strEQ
 
-Null SV pointer.
+Test two strings to see if they are equal.  Returns true or false.
+
+	bool	strEQ(char* s1, char* s2)
 
 =for hackers
 Found in file handy.h
 
-=item ORIGMARK
+=item strGE
 
-The original stack mark for the XSUB.  See C<dORIGMARK>.
+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 pp.h
+Found in file handy.h
 
-=item perl_alloc
+=item strGT
 
-Allocates a new Perl interpreter.  See L<perlembed>.
+Test two strings to see if the first, C<s1>, is greater than the second,
+C<s2>.  Returns true or false.
 
-	PerlInterpreter*	perl_alloc()
+	bool	strGT(char* s1, char* s2)
 
 =for hackers
-Found in file perl.c
+Found in file handy.h
 
-=item perl_construct
+=item strLE
 
-Initializes a new Perl interpreter.  See L<perlembed>.
+Test two strings to see if the first, C<s1>, is less than or equal to the
+second, C<s2>.  Returns true or false.
 
-	void	perl_construct(PerlInterpreter* interp)
+	bool	strLE(char* s1, char* s2)
 
 =for hackers
-Found in file perl.c
+Found in file handy.h
 
-=item perl_destruct
+=item strLT
 
-Shuts down a Perl interpreter.  See L<perlembed>.
+Test two strings to see if the first, C<s1>, is less than the second,
+C<s2>.  Returns true or false.
 
-	void	perl_destruct(PerlInterpreter* interp)
+	bool	strLT(char* s1, char* s2)
 
 =for hackers
-Found in file perl.c
+Found in file handy.h
 
-=item perl_free
+=item strNE
 
-Releases a Perl interpreter.  See L<perlembed>.
+Test two strings to see if they are different.  Returns true or
+false.
 
-	void	perl_free(PerlInterpreter* interp)
+	bool	strNE(char* s1, char* s2)
 
 =for hackers
-Found in file perl.c
+Found in file handy.h
 
-=item perl_parse
+=item strnEQ
 
-Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
+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	perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
+	bool	strnEQ(char* s1, char* s2, STRLEN len)
 
 =for hackers
-Found in file perl.c
+Found in file handy.h
 
-=item perl_run
+=item strnNE
 
-Tells a Perl interpreter to run.  See L<perlembed>.
+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>).
 
-	int	perl_run(PerlInterpreter* interp)
+	bool	strnNE(char* s1, char* s2, STRLEN len)
 
 =for hackers
-Found in file perl.c
-
-=item PL_modglobal
+Found in file handy.h
 
-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
+=back
 
-=for hackers
-Found in file intrpvar.h
+=head1 Numeric functions
 
-=item PL_na
+=over 8
 
-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.
+=item grok_bin
 
-	STRLEN	PL_na
+converts a string representing a binary number to numeric form.
 
-=for hackers
-Found in file thrdvar.h
+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.
 
-=item PL_sv_no
+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).
 
-This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as
-C<&PL_sv_no>.
+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.
 
-	SV	PL_sv_no
+	UV	grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
 
 =for hackers
-Found in file intrpvar.h
-
-=item PL_sv_undef
+Found in file numeric.c
 
-This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
+=item grok_hex
 
-	SV	PL_sv_undef
+converts a string representing a hex number to numeric form.
 
-=for hackers
-Found in file intrpvar.h
+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.
 
-=item PL_sv_yes
+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).
 
-This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as
-C<&PL_sv_yes>.
+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.
 
-	SV	PL_sv_yes
+	UV	grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
 
 =for hackers
-Found in file intrpvar.h
+Found in file numeric.c
 
-=item POPi
+=item grok_number
 
-Pops an integer off the stack.
+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).
 
-	IV	POPi
+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 POPl
+=item grok_numeric_radix
 
-Pops a long off the stack.
+Scan and skip for a numeric decimal separator (radix).
 
-	long	POPl
+	bool	grok_numeric_radix(const char **sp, const char *send)
 
 =for hackers
-Found in file pp.h
+Found in file numeric.c
 
-=item POPn
+=item grok_oct
 
-Pops a double off the stack.
 
-	NV	POPn
+	UV	grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
 
 =for hackers
-Found in file pp.h
+Found in file numeric.c
 
-=item POPp
+=item scan_bin
 
-Pops a string off the stack. Deprecated. New code should provide
-a STRLEN n_a and use POPpx.
+For backwards compatibility. Use C<grok_bin> instead.
 
-	char*	POPp
+	NV	scan_bin(char* start, STRLEN len, STRLEN* retlen)
 
 =for hackers
-Found in file pp.h
+Found in file numeric.c
 
-=item POPpbytex
+=item scan_hex
 
-Pops a string off the stack which must consist of bytes i.e. characters < 256.
-Requires a variable STRLEN n_a in scope.
+For backwards compatibility. Use C<grok_hex> instead.
 
-	char*	POPpbytex
+	NV	scan_hex(char* start, STRLEN len, STRLEN* retlen)
 
 =for hackers
-Found in file pp.h
+Found in file numeric.c
 
-=item POPpx
+=item scan_oct
 
-Pops a string off the stack.
-Requires a variable STRLEN n_a in scope.
+For backwards compatibility. Use C<grok_oct> instead.
 
-	char*	POPpx
+	NV	scan_oct(char* start, STRLEN len, STRLEN* retlen)
 
 =for hackers
-Found in file pp.h
+Found in file numeric.c
 
-=item POPs
 
-Pops an SV off the stack.
+=back
+
+=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 op.c
+
+=item newCONSTSUB
+
+Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
+eligible for inlining at compile-time.
+
+	CV*	newCONSTSUB(HV* stash, char* name, SV* sv)
+
+=for hackers
+Found in file op.c
+
+=item newXS
+
+Used by C<xsubpp> to hook up XSUBs as Perl subs.
+
+=for hackers
+Found in file op.c
+
+
+=back
+
+=head1 Shared SV Functions
+
+=over 8
+
+=item sharedsv_find
+
+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.
+
+	shared_sv*	sharedsv_find(SV* sv)
+
+=for hackers
+Found in file sharedsv.c
+
+=item sharedsv_init
+
+Saves a space for keeping SVs wider than an interpreter,
+currently only stores a pointer to the first interpreter.
+
+	void	sharedsv_init()
+
+=for hackers
+Found in file sharedsv.c
+
+=item sharedsv_lock
+
+Recursive locks on a sharedsv.
+Locks are dynamically scoped at the level of the first lock.
+	void	sharedsv_lock(shared_sv* ssv)
+
+=for hackers
+Found in file sharedsv.c
+
+=item sharedsv_new
+
+Allocates a new shared sv struct, you must yourself create the SV/AV/HV.
+	shared_sv*	sharedsv_new()
+
+=for hackers
+Found in file sharedsv.c
+
+=item sharedsv_thrcnt_dec
+
+Decrements the threadcount of a shared sv. When a threads frontend is freed
+this function should be called.
+
+	void	sharedsv_thrcnt_dec(shared_sv* ssv)
+
+=for hackers
+Found in file sharedsv.c
+
+=item sharedsv_thrcnt_inc
+
+Increments the threadcount of a sharedsv.
+	void	sharedsv_thrcnt_inc(shared_sv* ssv)
+
+=for hackers
+Found in file sharedsv.c
+
+=item sharedsv_unlock
+
+Recursively unlocks a shared sv.
+
+	void	sharedsv_unlock(shared_sv* ssv)
+
+=for hackers
+Found in file sharedsv.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 pp.h
+
+=item dORIGMARK
+
+Saves the original stack mark for the XSUB.  See C<ORIGMARK>.
+
+		dORIGMARK;
+
+=for hackers
+Found in file pp.h
+
+=item dSP
+
+Declares a local copy of perl's stack pointer for the XSUB, available via
+the C<SP> macro.  See C<SP>.
+
+		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 pp.h
+
+=item MARK
+
+Stack marker variable for the XSUB.  See C<dMARK>.
+
+=for hackers
+Found in file pp.h
+
+=item ORIGMARK
+
+The original stack mark for the XSUB.  See C<dORIGMARK>.
+
+=for hackers
+Found in file pp.h
+
+=item POPi
+
+Pops an integer off the stack.
+
+	IV	POPi
+
+=for hackers
+Found in file pp.h
+
+=item POPl
+
+Pops a long off the stack.
+
+	long	POPl
+
+=for hackers
+Found in file pp.h
+
+=item POPn
+
+Pops a double off the stack.
+
+	NV	POPn
+
+=for hackers
+Found in file pp.h
+
+=item POPp
+
+Pops a string off the stack. Deprecated. New code should provide
+a STRLEN n_a and use POPpx.
+
+	char*	POPp
+
+=for hackers
+Found in file pp.h
+
+=item POPpbytex
+
+Pops a string off the stack which must consist of bytes i.e. characters < 256.
+Requires a variable STRLEN n_a in scope.
+
+	char*	POPpbytex
+
+=for hackers
+Found in file pp.h
+
+=item POPpx
+
+Pops a string off the stack.
+Requires a variable STRLEN n_a in scope.
+
+	char*	POPpx
+
+=for hackers
+Found in file pp.h
+
+=item POPs
+
+Pops an SV off the stack.
 
 	SV*	POPs
 
@@ -1629,265 +1953,504 @@ Handles 'set' magic.  See C<XPUSHi>.
 	void	PUSHi(IV iv)
 
 =for hackers
-Found in file pp.h
+Found in file pp.h
+
+=item PUSHMARK
+
+Opening bracket for arguments on a callback.  See C<PUTBACK> and
+L<perlcall>.
+
+		PUSHMARK;
+
+=for hackers
+Found in file pp.h
+
+=item PUSHn
+
+Push a double onto the stack.  The stack must have room for this element.
+Handles 'set' magic.  See C<XPUSHn>.
+
+	void	PUSHn(NV nv)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHp
+
+Push a string onto the stack.  The stack must have room for this element.
+The C<len> indicates the length of the string.  Handles 'set' magic.  See
+C<XPUSHp>.
+
+	void	PUSHp(char* str, STRLEN len)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHs
+
+Push an SV onto the stack.  The stack must have room for this element.
+Does not handle 'set' magic.  See C<XPUSHs>.
+
+	void	PUSHs(SV* sv)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHu
+
+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 PUTBACK
+
+Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
+See C<PUSHMARK> and L<perlcall> for other uses.
+
+		PUTBACK;
+
+=for hackers
+Found in file pp.h
+
+=item SP
+
+Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
+C<SPAGAIN>.
+
+=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 pp.h
+
+=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
+
+=item XPUSHn
+
+Push a double onto the stack, extending the stack if necessary.  Handles
+'set' magic.  See C<PUSHn>.
+
+	void	XPUSHn(NV nv)
+
+=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 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)
+
+=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 XSRETURN_IV
+
+Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
+
+	void	XSRETURN_IV(IV iv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_NO
+
+Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
+
+		XSRETURN_NO;
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_NV
+
+Return a double from an XSUB immediately.  Uses C<XST_mNV>.
+
+	void	XSRETURN_NV(NV nv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_PV
+
+Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
+
+	void	XSRETURN_PV(char* str)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_UNDEF
+
+Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
+
+		XSRETURN_UNDEF;
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_YES
+
+Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
+
+		XSRETURN_YES;
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mIV
+
+Place an integer into the specified position C<pos> on the stack.  The
+value is stored in a new mortal SV.
+
+	void	XST_mIV(int pos, IV iv)
+
+=for hackers
+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 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 Safefree
+=item get_sv
 
-The XSUB-writer's interface to the C C<free> function.
+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.
 
-	void	Safefree(void* ptr)
+NOTE: the perl_ form of this function is deprecated.
+
+	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
 
@@ -1912,17 +2475,7 @@ Found in file sv.h
 Returns a pointer to the last character in the string which is in the SV.
 See C<SvCUR>.  Access the character as *(SvEND(sv)).
 
-	char*	SvEND(SV* sv)
-
-=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)
+	char*	SvEND(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -1931,7 +2484,7 @@ Found in file sv.h
 
 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)
@@ -1960,7 +2513,7 @@ Found in file sv.h
 
 =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)
 
@@ -2014,17 +2567,28 @@ Found in file sv.h
 
 =item SvIV
 
-Coerces the given SV to an integer and returns it.
+Coerces the given SV to an integer and returns it. See  C<SvIVx> for a
+version which guarantees to evaluate sv only once.
 
 	IV	SvIV(SV* sv)
 
 =for hackers
 Found in file sv.h
 
+=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.
+
+	IV	SvIVx(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvIVX
 
-Returns the integer which is stored in the SV, assuming SvIOK is
-true.
+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)
 
@@ -2118,7 +2682,8 @@ Found in file sv.h
 
 =item SvNV
 
-Coerce the given SV to a double and return it.
+Coerce the given SV to a double and return it. See  C<SvNVx> for a version
+which guarantees to evaluate sv only once.
 
 	NV	SvNV(SV* sv)
 
@@ -2127,14 +2692,24 @@ Found in file sv.h
 
 =item SvNVX
 
-Returns the double which is stored in the SV, assuming SvNOK is
-true.
+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)
 
 =for hackers
 Found in file sv.h
 
+=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.
+
+	NV	SvNVx(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvOK
 
 Returns a boolean indicating whether the value is an SV.
@@ -2217,16 +2792,116 @@ 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.
+if the SV does not contain a string.  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 SvPVbyte
+
+Like C<SvPV>, but converts sv to byte representation first if necessary.
+
+	char*	SvPVbyte(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVbytex
+
+Like C<SvPV>, but converts sv to byte representation first if necessary.
+Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
+otherwise.
+
+
+	char*	SvPVbytex(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVbytex_force
+
+Like C<SvPV_force>, but converts sv to byte representation first if necessary.
+Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
+otherwise.
+
+	char*	SvPVbytex_force(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVbyte_force
+
+Like C<SvPV_force>, but converts sv to byte representation first if necessary.
+
+	char*	SvPVbyte_force(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVbyte_nolen
+
+Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
+
+	char*	SvPVbyte_nolen(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVutf8
+
+Like C<SvPV>, but converts sv to utf8 first if necessary.
+
+	char*	SvPVutf8(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVutf8x
+
+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)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVutf8x_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)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVutf8_force
+
+Like C<SvPV_force>, but converts sv to utf8 first if necessary.
+
+	char*	SvPVutf8_force(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVutf8_nolen
+
+Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
+
+	char*	SvPVutf8_nolen(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvPVX
 
-Returns a pointer to the string in the SV.  The SV must contain a
+Returns a pointer to the physical string in the SV.  The SV must contain a
 string.
 
 	char*	SvPVX(SV* sv)
@@ -2234,6 +2909,15 @@ string.
 =for hackers
 Found in file sv.h
 
+=item SvPVx
+
+A version of C<SvPV> which guarantees to evaluate sv only once.
+
+	char*	SvPVx(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
 =item SvPV_force
 
 Like <SvPV> but will force the SV into becoming a string (SvPOK).  You want
@@ -2244,6 +2928,16 @@ force if you are going to update the SvPVX directly.
 =for hackers
 Found in file sv.h
 
+=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.
+
+	char*	SvPV_force_nomg(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
 =item SvPV_nolen
 
 Returns a pointer to the string in the SV, or a stringified form of the SV
@@ -2317,32 +3011,12 @@ Dereferences an RV to return the 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 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)
-
-=for hackers
-Found in file sv.h
+=item SvSetMagicSV_nosteal
 
-=item SvSetSV_nosteal
+Like C<SvSetMagicSV>, but does any set magic required afterwards.
 
-Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
-ssv. May evaluate arguments more than once.
 
-	void	SvSetSV_nosteal(SV* dsv, SV* ssv)
+	void	SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
 
 =for hackers
 Found in file sv.h
@@ -2408,144 +3082,243 @@ false, defined or undefined.  Does not handle 'get' magic.
 =for hackers
 Found in file sv.h
 
-=item svtype
+=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.
+Returns the type of the SV.  See C<svtype>.
+
+	svtype	SvTYPE(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SvTYPE
+=item SvUOK
 
-Returns the type of the SV.  See C<svtype>.
+Returns a boolean indicating whether the SV contains an unsigned integer.
 
-	svtype	SvTYPE(SV* sv)
+	void	SvUOK(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SVt_IV
+=item SvUPGRADE
 
-Integer type flag for scalars.  See C<svtype>.
+Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
+perform the upgrade if necessary.  See C<svtype>.
+
+	void	SvUPGRADE(SV* sv, svtype type)
 
 =for hackers
 Found in file sv.h
 
-=item SVt_NV
+=item SvUTF8
 
-Double type flag for scalars.  See C<svtype>.
+Returns a boolean indicating whether the SV contains UTF-8 encoded data.
+
+	void	SvUTF8(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SVt_PV
+=item SvUTF8_off
 
-Pointer type flag for scalars.  See C<svtype>.
+Unsets the UTF8 status of an SV.
+
+	void	SvUTF8_off(SV *sv)
 
 =for hackers
 Found in file sv.h
 
-=item SVt_PVAV
+=item SvUTF8_on
 
-Type flag for arrays.  See C<svtype>.
+Turn on the UTF8 status of an SV (the data is not changed, just the flag).
+Do not use frivolously.
+
+	void	SvUTF8_on(SV *sv)
 
 =for hackers
 Found in file sv.h
 
-=item SVt_PVCV
+=item SvUV
 
-Type flag for code refs.  See C<svtype>.
+Coerces the given SV to an unsigned integer and returns it.  See C<SvUVx>
+for a version which guarantees to evaluate sv only once.
+
+	UV	SvUV(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SVt_PVHV
+=item SvUVx
 
-Type flag for hashes.  See C<svtype>.
+Coerces the given SV to an unsigned integer and returns it. Guarantees to
+evaluate sv only once. Use the more efficient C<SvUV> otherwise.
+
+	UV	SvUVx(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SVt_PVMG
+=item SvUVX
 
-Type flag for blessed scalars.  See C<svtype>.
+Returns the raw value in the SV's UV slot, without checks or conversions.
+Only use when you are sure SvIOK is true. See also C<SvUV()>.
+
+	UV	SvUVX(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SvUOK
+=item sv_2bool
 
-Returns a boolean indicating whether the SV contains an unsigned integer.
+This function is only called on magical items, and is only used by
+sv_true() or its macro equivalent.
 
-	void	SvUOK(SV* sv)
+	bool	sv_2bool(SV* sv)
 
 =for hackers
-Found in file sv.h
+Found in file sv.c
 
-=item SvUPGRADE
+=item sv_2cv
 
-Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
-perform the upgrade if necessary.  See C<svtype>.
+Using various gambits, try to get a CV from an SV; in addition, try if
+possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
 
-	void	SvUPGRADE(SV* sv, svtype type)
+	CV*	sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
 
 =for hackers
-Found in file sv.h
+Found in file sv.c
 
-=item SvUTF8
+=item sv_2io
 
-Returns a boolean indicating whether the SV contains UTF-8 encoded data.
+Using various gambits, try to get an IO from an SV: the IO slot if its a
+GV; or the recursive result if we're an RV; or the IO slot of the symbol
+named after the PV if we're a string.
 
-	void	SvUTF8(SV* sv)
+	IO*	sv_2io(SV* sv)
 
 =for hackers
-Found in file sv.h
+Found in file sv.c
 
-=item SvUTF8_off
+=item sv_2iv
 
-Unsets the UTF8 status of an SV.
+Return the integer value of an SV, doing any necessary string conversion,
+magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
 
-	void	SvUTF8_off(SV *sv)
+	IV	sv_2iv(SV* sv)
 
 =for hackers
-Found in file sv.h
+Found in file sv.c
 
-=item SvUTF8_on
+=item sv_2mortal
 
-Turn on the UTF8 status of an SV (the data is not changed, just the flag).
-Do not use frivolously.
+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>.
 
-	void	SvUTF8_on(SV *sv)
+	SV*	sv_2mortal(SV* sv)
 
 =for hackers
-Found in file sv.h
+Found in file sv.c
 
-=item SvUV
+=item sv_2nv
 
-Coerces the given SV to an unsigned integer and returns it.
+Return the num value of an SV, doing any necessary string or integer
+conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
+macros.
 
-	UV	SvUV(SV* sv)
+	NV	sv_2nv(SV* sv)
 
 =for hackers
-Found in file sv.h
+Found in file sv.c
 
-=item SvUVX
+=item sv_2pvbyte
 
-Returns the unsigned integer which is stored in the SV, assuming SvIOK is
-true.
+Return a pointer to the byte-encoded representation of the SV, and set *lp
+to its length.  May cause the SV to be downgraded from UTF8 as a
+side-effect.
 
-	UV	SvUVX(SV* sv)
+Usually accessed via the C<SvPVbyte> macro.
+
+	char*	sv_2pvbyte(SV* sv, STRLEN* lp)
 
 =for hackers
-Found in file sv.h
+Found in file sv.c
 
-=item sv_2mortal
+=item sv_2pvbyte_nolen
 
-Marks an SV as mortal.  The SV will be destroyed when the current context
-ends.
+Return a pointer to the byte-encoded representation of the SV.
+May cause the SV to be downgraded from UTF8 as a side-effect.
 
-	SV*	sv_2mortal(SV* sv)
+Usually accessed via the C<SvPVbyte_nolen> macro.
+
+	char*	sv_2pvbyte_nolen(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2pvutf8
+
+Return a pointer to the UTF8-encoded representation of the SV, and set *lp
+to its length.  May cause the SV to be upgraded to UTF8 as a side-effect.
+
+Usually accessed via the C<SvPVutf8> macro.
+
+	char*	sv_2pvutf8(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2pvutf8_nolen
+
+Return a pointer to the UTF8-encoded representation of the SV.
+May cause the SV to be upgraded to UTF8 as a side-effect.
+
+Usually accessed via the C<SvPVutf8_nolen> macro.
+
+	char*	sv_2pvutf8_nolen(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2pv_flags
+
+Returns a pointer to the string value of an SV, and sets *lp to its length.
+If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
+if necessary.
+Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
+usually end up here too.
+
+	char*	sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2pv_nolen
+
+Like C<sv_2pv()>, but doesn't return the length too. You should usually
+use the macro wrapper C<SvPV_nolen(sv)> instead.
+	char*	sv_2pv_nolen(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2uv
+
+Return the unsigned integer value of an SV, doing any necessary string
+conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
+macros.
+
+	UV	sv_2uv(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_backoff
+
+Remove any string offset. You should normally use the C<SvOOK_off> macro
+wrapper instead.
+
+	int	sv_backoff(SV* sv)
 
 =for hackers
 Found in file sv.c
@@ -2677,7 +3450,7 @@ Found in file sv.c
 Efficient removal of characters from the beginning of the string buffer.
 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
 the string buffer.  The C<ptr> becomes the first character of the adjusted
-string.
+string. Uses the "OOK hack".
 
 	void	sv_chop(SV* sv, char* ptr)
 
@@ -2686,8 +3459,13 @@ Found in file sv.c
 
 =item sv_clear
 
-Clear an SV, making it empty. Does not free the memory used by the SV
-itself.
+Clear an SV: call any destructors, free up any memory used by the body,
+and free the body itself. The SV's head is I<not> freed, although
+its type is set to all 1's so that it won't inadvertently be assumed
+to be live during global destruction etc.
+This function should only be called when REFCNT is zero. Most of the time
+you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
+instead.
 
 	void	sv_clear(SV* sv)
 
@@ -2698,7 +3476,8 @@ Found in file sv.c
 
 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
 string in C<sv1> is less than, equal to, or greater than the string in
-C<sv2>.
+C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
+coerce its args to strings if necessary.  See also C<sv_cmp_locale>.
 
 	I32	sv_cmp(SV* sv1, SV* sv2)
 
@@ -2707,17 +3486,33 @@ Found in file sv.c
 
 =item sv_cmp_locale
 
-Compares the strings in two SVs in a locale-aware manner. See
-L</sv_cmp_locale>
+Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
+'use bytes' aware, handles get magic, and will coerce its args to strings
+if necessary.  See also C<sv_cmp_locale>.  See also C<sv_cmp>.
 
 	I32	sv_cmp_locale(SV* sv1, SV* sv2)
 
 =for hackers
 Found in file sv.c
 
+=item sv_collxfrm
+
+Add Collate Transform magic to an SV if it doesn't already have it.
+
+Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
+scalar data of the variable, but transformed to such a format that a normal
+memory comparison can be used to compare the data according to the locale
+settings.
+
+	char*	sv_collxfrm(SV* sv, STRLEN* nxp)
+
+=for hackers
+Found in file sv.c
+
 =item sv_dec
 
-Auto-decrement of the value in the SV.
+Auto-decrement of the value in the SV, doing string to numeric conversion
+if necessary. Handles 'get' magic.
 
 	void	sv_dec(SV* sv)
 
@@ -2738,30 +3533,48 @@ Found in file universal.c
 =item sv_eq
 
 Returns a boolean indicating whether the strings in the two SVs are
-identical.
+identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
+coerce its args to strings if necessary.
 
 	I32	sv_eq(SV* sv1, SV* sv2)
 
 =for hackers
 Found in file sv.c
 
-=item sv_free
+=item sv_force_normal
 
-Free the memory used by an SV.
+Undo various types of fakery on an SV: if the PV is a shared string, make
+a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
+an xpvmg. See also C<sv_force_normal_flags>.
 
-	void	sv_free(SV* sv)
+	void	sv_force_normal(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_force_normal_flags
+
+Undo various types of fakery on an SV: if the PV is a shared string, make
+a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
+an xpvmg. The C<flags> parameter gets passed to  C<sv_unref_flags()>
+when unrefing. C<sv_force_normal> calls this function with flags set to 0.
+
+	void	sv_force_normal_flags(SV *sv, U32 flags)
 
 =for hackers
 Found in file sv.c
 
-=item sv_getcwd
+=item sv_free
 
-Fill the sv with current working directory
+Decrement an SV's reference count, and if it drops to zero, call
+C<sv_clear> to invoke destructors and free up any memory used by
+the body; finally, deallocate the SV's head itself.
+Normally called via a wrapper macro C<SvREFCNT_dec>.
 
-	int	sv_getcwd(SV* sv)
+	void	sv_free(SV* sv)
 
 =for hackers
-Found in file util.c
+Found in file sv.c
 
 =item sv_gets
 
@@ -2775,9 +3588,9 @@ Found in file sv.c
 
 =item sv_grow
 
-Expands the character buffer in the SV.  This will use C<sv_unref> and will
-upgrade the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
-Use C<SvGROW>.
+Expands the character buffer in the SV.  If necessary, uses C<sv_unref> and
+upgrades the SV to C<SVt_PV>.  Returns a pointer to the character buffer.
+Use the C<SvGROW> wrapper instead.
 
 	char*	sv_grow(SV* sv, STRLEN newlen)
 
@@ -2786,7 +3599,8 @@ Found in file sv.c
 
 =item sv_inc
 
-Auto-increment of the value in the SV.
+Auto-increment of the value in the SV, doing string to numeric conversion
+if necessary. Handles 'get' magic.
 
 	void	sv_inc(SV* sv)
 
@@ -2825,9 +3639,20 @@ will return false.
 =for hackers
 Found in file sv.c
 
+=item sv_iv
+
+A private implementation of the C<SvIVx> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
+
+	IV	sv_iv(SV* sv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_len
 
-Returns the length of the string in the SV.  See also C<SvCUR>.
+Returns the length of the string in the SV. Handles magic and type
+coercion.  See also C<SvCUR>, which gives raw access to the xpv_cur slot.
 
 	STRLEN	sv_len(SV* sv)
 
@@ -2837,7 +3662,7 @@ Found in file sv.c
 =item sv_len_utf8
 
 Returns the number of characters in the string in an SV, counting wide
-UTF8 bytes as a single character.
+UTF8 bytes as a single character. Handles magic and type coercion.
 
 	STRLEN	sv_len_utf8(SV* sv)
 
@@ -2846,7 +3671,10 @@ Found in file sv.c
 
 =item sv_magic
 
-Adds magic to an SV.
+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)
 
@@ -2855,8 +3683,10 @@ Found in file sv.c
 
 =item sv_mortalcopy
 
-Creates a new SV which is a copy of the original SV.  The new SV is marked
-as mortal.
+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 "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)
 
@@ -2865,16 +3695,118 @@ Found in file sv.c
 
 =item sv_newmortal
 
-Creates a new SV which is mortal.  The reference count of the SV is set to 1.
+Creates a new null SV which is mortal.  The reference count of the SV is
+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_newref
+
+Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
+instead.
+
+	SV*	sv_newref(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_nv
+
+A private implementation of the C<SvNVx> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
+
+	NV	sv_nv(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pos_b2u
+
+Converts the value pointed to by offsetp from a count of bytes from the
+start of the string, to a count of the equivalent number of UTF8 chars.
+Handles magic and type coercion.
+
+	void	sv_pos_b2u(SV* sv, I32* offsetp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pos_u2b
+
+Converts the value pointed to by offsetp from a count of UTF8 chars from
+the start of the string, to a count of the equivalent number of bytes; if
+lenp is non-zero, it does the same to lenp, but this time starting from
+the offset, rather than from the start of the string. Handles magic and
+type coercion.
+
+	void	sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
+
+=for hackers
+Found in file sv.c
+
+=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.
+
+	char*	sv_pv(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=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.
+
+	char*	sv_pvbyte(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pvbyten
+
+A private implementation of the C<SvPVbyte> macro for compilers
+which can't cope with complex macro expressions. Always use the macro
+instead.
+
+	char*	sv_pvbyten(SV *sv, STRLEN *len)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pvbyten_force
+
+A private implementation of the C<SvPVbytex_force> macro for compilers
+which can't cope with complex macro expressions. Always use the macro
+instead.
+
+	char*	sv_pvbyten_force(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pvn
+
+A private implementation of the C<SvPV> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
+
+	char*	sv_pvn(SV *sv, STRLEN *len)
+
+=for hackers
+Found in file sv.c
+
 =item sv_pvn_force
 
 Get a sensible string out of the SV somehow.
+A private implementation of the C<SvPV_force> macro for compilers which
+can't cope with complex macro expressions. Always use the macro instead.
 
 	char*	sv_pvn_force(SV* sv, STRLEN* lp)
 
@@ -2887,30 +3819,46 @@ Get a sensible string out of the SV somehow.
 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
 appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
 implemented in terms of this function.
+You normally want to use the various wrapper macros instead: see
+C<SvPV_force> and C<SvPV_force_nomg>
 
 	char*	sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
 
 =for hackers
 Found in file sv.c
 
-=item sv_pvutf8n_force
+=item sv_pvutf8
 
-Get a sensible UTF8-encoded string out of the SV somehow. See
-L</sv_pvn_force>.
+A private implementation of the C<SvPVutf8_nolen> macro for compilers
+which can't cope with complex macro expressions. Always use the macro
+instead.
 
-	char*	sv_pvutf8n_force(SV* sv, STRLEN* lp)
+	char*	sv_pvutf8(SV *sv)
 
 =for hackers
 Found in file sv.c
 
-=item sv_realpath
+=item sv_pvutf8n
 
-Wrap or emulate realpath(3).
+A private implementation of the C<SvPVutf8> macro for compilers
+which can't cope with complex macro expressions. Always use the macro
+instead.
 
-	int	sv_realpath(SV* sv, char *path, STRLEN len)
+	char*	sv_pvutf8n(SV *sv, STRLEN *len)
 
 =for hackers
-Found in file util.c
+Found in file sv.c
+
+=item sv_pvutf8n_force
+
+A private implementation of the C<SvPVutf8_force> macro for compilers
+which can't cope with complex macro expressions. Always use the macro
+instead.
+
+	char*	sv_pvutf8n_force(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
 
 =item sv_reftype
 
@@ -2924,15 +3872,42 @@ Found in file sv.c
 =item sv_replace
 
 Make the first argument a copy of the second, then delete the original.
+The target SV physically takes over ownership of the body of the source SV
+and inherits its flags; however, the target keeps any magic it owns,
+and any magic in the source is discarded.
+Note that this is a rather specialist SV copying operation; most of the
+time you'll want to use C<sv_setsv> or one of its many macro front-ends.
 
 	void	sv_replace(SV* sv, SV* nsv)
 
 =for hackers
 Found in file sv.c
 
+=item sv_report_used
+
+Dump the contents of all SVs not yet freed. (Debugging aid).
+
+	void	sv_report_used()
+
+=for hackers
+Found in file sv.c
+
+=item sv_reset
+
+Underlying implementation for the C<reset> Perl function.
+Note that the perl-level function is vaguely deprecated.
+
+	void	sv_reset(char* s, HV* stash)
+
+=for hackers
+Found in file sv.c
+
 =item sv_rvweaken
 
-Weaken a reference.
+Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
+referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
+push a back-reference to this RV onto the array of backreferences
+associated with that magic.
 
 	SV*	sv_rvweaken(SV *sv)
 
@@ -2941,8 +3916,8 @@ Found in file sv.c
 
 =item sv_setiv
 
-Copies an integer into the given SV.  Does not handle 'set' magic.  See
-C<sv_setiv_mg>.
+Copies an integer into the given SV, upgrading first if necessary.
+Does not handle 'set' magic.  See also C<sv_setiv_mg>.
 
 	void	sv_setiv(SV* sv, IV num)
 
@@ -2960,8 +3935,8 @@ Found in file sv.c
 
 =item sv_setnv
 
-Copies a double into the given SV.  Does not handle 'set' magic.  See
-C<sv_setnv_mg>.
+Copies a double into the given SV, upgrading first if necessary.
+Does not handle 'set' magic.  See also C<sv_setnv_mg>.
 
 	void	sv_setnv(SV* sv, NV num)
 
@@ -3129,10 +4104,16 @@ Found in file sv.c
 
 =item sv_setsv
 
-Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
-The source SV may be destroyed if it is mortal.  Does not handle 'set'
-magic.  See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
-C<sv_setsv_mg>.
+Copies the contents of the source SV C<ssv> into the destination SV
+C<dsv>.  The source SV may be destroyed if it is mortal, so don't use this
+function if the source SV needs to be reused. Does not handle 'set' magic.
+Loosely speaking, it performs a copy-by-value, obliterating any previous
+content of the destination.
+
+You probably want to use one of the assortment of wrappers, such as
+C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
+C<SvSetMagicSV_nosteal>.
+
 
 	void	sv_setsv(SV* dsv, SV* ssv)
 
@@ -3141,11 +4122,21 @@ Found in file sv.c
 
 =item sv_setsv_flags
 
-Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
-The source SV may be destroyed if it is mortal.  Does not handle 'set'
-magic.  If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<ssv> if
-appropriate, else not. C<sv_setsv> and C<sv_setsv_nomg> are implemented
-in terms of this function.
+Copies the contents of the source SV C<ssv> into the destination SV
+C<dsv>.  The source SV may be destroyed if it is mortal, so don't use this
+function if the source SV needs to be reused. Does not handle 'set' magic.
+Loosely speaking, it performs a copy-by-value, obliterating any previous
+content of the destination.
+If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
+C<ssv> if appropriate, else not. C<sv_setsv> and C<sv_setsv_nomg> are
+implemented in terms of this function.
+
+You probably want to use one of the assortment of wrappers, such as
+C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
+C<SvSetMagicSV_nosteal>.
+
+This is the primary function for copying scalars, and most other
+copy-ish functions and macros use this underneath.
 
 	void	sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
 
@@ -3163,8 +4154,8 @@ Found in file sv.c
 
 =item sv_setuv
 
-Copies an unsigned integer into the given SV.  Does not handle 'set' magic.
-See C<sv_setuv_mg>.
+Copies an unsigned integer into the given SV, upgrading first if necessary.
+Does not handle 'set' magic.  See also C<sv_setuv_mg>.
 
 	void	sv_setuv(SV* sv, UV num)
 
@@ -3180,9 +4171,27 @@ Like C<sv_setuv>, but also handles 'set' magic.
 =for hackers
 Found in file sv.c
 
+=item sv_taint
+
+Taint an SV. Use C<SvTAINTED_on> instead.
+	void	sv_taint(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_tainted
+
+Test an SV for taintedness. Use C<SvTAINTED> instead.
+	bool	sv_tainted(SV* sv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_true
 
 Returns true if the SV has a true value by Perl's rules.
+Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
+instead use an in-line version.
 
 	I32	sv_true(SV *sv)
 
@@ -3191,7 +4200,7 @@ Found in file sv.c
 
 =item sv_unmagic
 
-Removes magic from an SV.
+Removes all magic of type C<type> from an SV.
 
 	int	sv_unmagic(SV* sv, int type)
 
@@ -3225,10 +4234,19 @@ See C<SvROK_off>.
 =for hackers
 Found in file sv.c
 
+=item sv_untaint
+
+Untaint an SV. Use C<SvTAINTED_off> instead.
+	void	sv_untaint(SV* sv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_upgrade
 
-Upgrade an SV to a more complex form.  Use C<SvUPGRADE>.  See
-C<svtype>.
+Upgrade an SV to a more complex form.  Generally adds a new body type to the
+SV, then copies across as much information as possible from the old body.
+You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
 
 	bool	sv_upgrade(SV* sv, U32 mt)
 
@@ -3262,7 +4280,7 @@ Found in file sv.c
 =item sv_utf8_decode
 
 Convert the octets in the PV from UTF-8 to chars. Scan for validity and then
-turn of SvUTF8 if needed so that we see characters. Used as a building block
+turn off SvUTF8 if needed so that we see characters. Used as a building block
 for decode_utf8 in Encode.xs
 
 NOTE: this function is experimental and may change or be
@@ -3285,97 +4303,305 @@ removed without notice.
 
 	bool	sv_utf8_downgrade(SV *sv, bool fail_ok)
 
-=for hackers
-Found in file sv.c
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_encode
+
+Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
+flag so that it looks like octets again. Used as a building block
+for encode_utf8 in Encode.xs
+
+	void	sv_utf8_encode(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_upgrade
+
+Convert the PV of an SV to its UTF8-encoded form.
+Forces the SV to string form if it is not already.
+Always sets the SvUTF8 flag to avoid future validity checks even
+if all the bytes have hibit clear.
+
+	STRLEN	sv_utf8_upgrade(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_upgrade_flags
+
+Convert the PV of an SV to its UTF8-encoded form.
+Forces the SV to string form if it is not already.
+Always sets the SvUTF8 flag to avoid future validity checks even
+if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
+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.
+
+	STRLEN	sv_utf8_upgrade_flags(SV *sv, I32 flags)
+
+=for hackers
+Found in file sv.c
+
+=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 is currently unused but available for future extensions.
+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).
 
-=item sv_utf8_encode
+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>).
 
-Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
-flag so that it looks like octets again. Used as a building block
-for encode_utf8 in Encode.xs
+The PV of the sv is returned.
 
-	void	sv_utf8_encode(SV *sv)
+	char*	sv_recode_to_utf8(SV* sv, SV *encoding)
 
 =for hackers
 Found in file sv.c
 
-=item sv_utf8_upgrade
+=item sv_uni_display
 
-Convert the PV of an SV to its UTF8-encoded form.
-Forces the SV to string form it it is not already.
-Always sets the SvUTF8 flag to avoid future validity checks even
-if all the bytes have hibit clear.
+Build to the scalar dsv a displayable version of the scalar sv,
+he displayable version being at most pvlim bytes long
+(if longer, the rest is truncated and "..." will be appended).
+The flags argument is currently unused but available for future extensions.
+The pointer to the PV of the dsv is returned.
 
-	STRLEN	sv_utf8_upgrade(SV *sv)
+	char*	sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
 
 =for hackers
-Found in file sv.c
+Found in file utf8.c
 
-=item sv_utf8_upgrade_flags
+=item to_utf8_case
 
-Convert the PV of an SV to its UTF8-encoded form.
-Forces the SV to string form it it is not already.
-Always sets the SvUTF8 flag to avoid future validity checks even
-if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
-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.
+The "p" contains the pointer to the UTF-8 string encoding
+the character that is being converted.
 
-	STRLEN	sv_utf8_upgrade_flags(SV *sv, I32 flags)
+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 "swash" is a pointer to the swash to use.
 
-=item sv_vcatpvfn
+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.
 
-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, 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().
 
-	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).
 
-	void	sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+The first character of the foldcased version is returned
+(but note, as explained above, that there may be more.)
+
+	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
 
@@ -3517,223 +4743,174 @@ is the recommended wide native character-aware way of saying
 =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
@@ -3757,15 +4934,42 @@ C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
 =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