X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=9f43de0860619ca2a9a9d42468f8a20930ccba0c;hb=fa11829f4b6d56533794dd127f3d1068d9593670;hp=545350536d2551379e20cf5b2f53b2e9d7f01f03;hpb=6a477168226f5506df9ce7c01de57e2808b61d82;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 5453505..9f43de0 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -120,7 +120,8 @@ Found in file av.c
 =item av_delete
 
 Deletes the element indexed by C<key> from the array.  Returns the
-deleted element. C<flags> is currently ignored.
+deleted element. If C<flags> equals C<G_DISCARD>, the element is freed
+and null is returned.
 
 	SV*	av_delete(AV* ar, I32 key, I32 flags)
 
@@ -283,14 +284,6 @@ Creates a new AV.  The reference count is set to 1.
 =for hackers
 Found in file av.c
 
-=item Nullav
-
-Null AV pointer.
-
-
-=for hackers
-Found in file av.h
-
 =item sortsv
 
 Sort an array. Here is an example:
@@ -514,31 +507,31 @@ Create and return a new interpreter by cloning the current one.
 
 perl_clone takes these flags as parameters:
 
-CLONEf_COPY_STACKS - is used to, well, copy the stacks also, 
-without it we only clone the data and zero the stacks, 
-with it we copy the stacks and the new perl interpreter is 
-ready to run at the exact same point as the previous one. 
-The pseudo-fork code uses COPY_STACKS while the 
+CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
+without it we only clone the data and zero the stacks,
+with it we copy the stacks and the new perl interpreter is
+ready to run at the exact same point as the previous one.
+The pseudo-fork code uses COPY_STACKS while the
 threads->new doesn't.
 
 CLONEf_KEEP_PTR_TABLE
-perl_clone keeps a ptr_table with the pointer of the old 
-variable as a key and the new variable as a value, 
-this allows it to check if something has been cloned and not 
-clone it again but rather just use the value and increase the 
-refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill 
-the ptr_table using the function 
-C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>, 
-reason to keep it around is if you want to dup some of your own 
-variable who are outside the graph perl scans, example of this 
+perl_clone keeps a ptr_table with the pointer of the old
+variable as a key and the new variable as a value,
+this allows it to check if something has been cloned and not
+clone it again but rather just use the value and increase the
+refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
+the ptr_table using the function
+C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>,
+reason to keep it around is if you want to dup some of your own
+variable who are outside the graph perl scans, example of this
 code is in threads.xs create
 
 CLONEf_CLONE_HOST
-This is a win32 thing, it is ignored on unix, it tells perls 
-win32host code (which is c++) to clone itself, this is needed on 
-win32 if you want to run two threads at the same time, 
-if you just want to do some stuff in a separate perl interpreter 
-and then throw it away and return to the original one, 
+This is a win32 thing, it is ignored on unix, it tells perls
+win32host code (which is c++) to clone itself, this is needed on
+win32 if you want to run two threads at the same time,
+if you just want to do some stuff in a separate perl interpreter
+and then throw it away and return to the original one,
 you don't need to do anything.
 
 	PerlInterpreter*	perl_clone(PerlInterpreter* interp, UV flags)
@@ -576,14 +569,6 @@ NOTE: the perl_ form of this function is deprecated.
 =for hackers
 Found in file perl.c
 
-=item Nullcv
-
-Null CV pointer.
-
-
-=for hackers
-Found in file cv.h
-
 
 =back
 
@@ -725,7 +710,9 @@ Found in file pp_pack.c
 
 =item unpackstring
 
-The engine implementing unpack() Perl function.
+The engine implementing unpack() Perl function. C<unpackstring> puts the
+extracted list items on the stack and returns the number of elements.
+Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
 
 	I32	unpackstring(char *pat, char *patend, char *s, char *strend, U32 flags)
 
@@ -922,15 +909,12 @@ Found in file gv.c
 
 =over 8
 
-=item HEf_SVKEY
-
-This flag, used in the length slot of hash entries and magic structures,
-specifies the structure contains an C<SV*> pointer where a C<char*> pointer
-is to be expected. (For information only--not to be used).
+=item Nullav
 
+Null AV pointer.
 
 =for hackers
-Found in file hv.h
+Found in file av.h
 
 =item Nullch
 
@@ -939,6 +923,20 @@ Null character pointer.
 =for hackers
 Found in file handy.h
 
+=item Nullcv
+
+Null CV pointer.
+
+=for hackers
+Found in file cv.h
+
+=item Nullhv
+
+Null HV pointer.
+
+=for hackers
+Found in file hv.h
+
 =item Nullsv
 
 Null SV pointer.
@@ -966,6 +964,15 @@ NOTE: the perl_ form of this function is deprecated.
 =for hackers
 Found in file perl.c
 
+=item HEf_SVKEY
+
+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).
+
+=for hackers
+Found in file hv.h
+
 =item HeHASH
 
 Returns the computed hash stored in the hash entry.
@@ -1065,6 +1072,15 @@ Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.
 =for hackers
 Found in file hv.h
 
+=item hv_assert
+
+Check that a hash is in an internally consistent state.
+
+	void	hv_assert(HV* tb)
+
+=for hackers
+Found in file hv.c
+
 =item hv_clear
 
 Clears a hash, making it empty.
@@ -1074,6 +1090,21 @@ Clears a hash, making it empty.
 =for hackers
 Found in file hv.c
 
+=item hv_clear_placeholders
+
+Clears any placeholders from a hash.  If a restricted hash has any of its keys
+marked as readonly and the key is subsequently deleted, the key is not actually
+deleted but is marked by assigning it a value of &PL_sv_placeholder.  This tags
+it so it will be ignored by future operations such as iterating over the hash,
+but will still allow the hash to have a value reassigned to the key at some
+future point.  This function clears any such placeholder keys from the hash.
+See Hash::Util::lock_keys() for an example of its use.
+
+	void	hv_clear_placeholders(HV* hb)
+
+=for hackers
+Found in file hv.c
+
 =item hv_delete
 
 Deletes a key/value pair in the hash.  The value SV is removed from the
@@ -1254,6 +1285,15 @@ Adds magic to a hash.  See C<sv_magic>.
 =for hackers
 Found in file hv.c
 
+=item hv_scalar
+
+Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
+
+	SV*	hv_scalar(HV* hv)
+
+=for hackers
+Found in file hv.c
+
 =item hv_store
 
 Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
@@ -1329,14 +1369,6 @@ Creates a new HV.  The reference count is set to 1.
 =for hackers
 Found in file hv.c
 
-=item Nullhv
-
-Null HV pointer.
-
-
-=for hackers
-Found in file hv.h
-
 
 =back
 
@@ -1457,7 +1489,7 @@ Found in file sv.h
 
 =item SvSetMagicSV_nosteal
 
-Like C<SvSetMagicSV>, but does any set magic required afterwards.
+Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
 
 	void	SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
 
@@ -1494,6 +1526,16 @@ has been loaded.
 =for hackers
 Found in file sv.h
 
+=item SvUNLOCK
+
+Releases a mutual exclusion lock on sv if a suitable module
+has been loaded.
+
+	void	SvUNLOCK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 
 =back
 
@@ -1512,6 +1554,16 @@ the type.  May fail on overlapping copies.  See also C<Move>.
 =for hackers
 Found in file handy.h
 
+=item CopyD
+
+Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
+optimise.
+
+	void *	CopyD(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
 =item Move
 
 The XSUB-writer's interface to the C C<memmove> function.  The C<src> is the
@@ -1523,6 +1575,16 @@ the type.  Can do overlapping moves.  See also C<Copy>.
 =for hackers
 Found in file handy.h
 
+=item MoveD
+
+Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
+optimise.
+
+	void *	MoveD(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
 =item New
 
 The XSUB-writer's interface to the C C<malloc> function.
@@ -1542,20 +1604,6 @@ cast.
 =for hackers
 Found in file handy.h
 
-=item NEWSV
-
-Creates a new SV.  A non-zero C<len> parameter indicates the number of
-bytes of preallocated string space the SV should have.  An extra byte for a
-tailing NUL is also reserved.  (SvPOK is not set for the SV even if string
-space is allocated.)  The reference count for the new SV is set to 1.
-C<id> is an integer id between 0 and 1299 (used to identify leaks).
-
-
-	SV*	NEWSV(int id, STRLEN len)
-
-=for hackers
-Found in file handy.h
-
 =item Newz
 
 The XSUB-writer's interface to the C C<malloc> function.  The allocated
@@ -1657,6 +1705,16 @@ destination, C<nitems> is the number of items, and C<type> is the type.
 =for hackers
 Found in file handy.h
 
+=item ZeroD
+
+Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
+optimise.
+
+	void *	ZeroD(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
 
 =back
 
@@ -1737,15 +1795,17 @@ an RV.
 
 Function must be called with an already existing SV like
 
-    sv = NEWSV(92,0);
-    s = scan_version(s,sv);
+    sv = newSV(0);
+    s = scan_version(s,SV *sv, bool qv);
 
 Performs some preprocessing to the string to ensure that
 it has the correct characteristics of a version.  Flags the
 object if it contains an underscore (which denotes this
-is a beta version).
+is a alpha version).  The boolean qv denotes that the version
+should be interpreted as if it had multiple decimals, even if
+it doesn't.
 
-	char*	scan_version(char *vstr, SV *sv)
+	char*	scan_version(char *vstr, SV *sv, bool qv)
 
 =for hackers
 Found in file util.c
@@ -1887,6 +1947,21 @@ converted into version objects.
 =for hackers
 Found in file util.c
 
+=item vnormal
+
+Accepts a version object and returns the normalized string
+representation.  Call like:
+
+    sv = vnormal(rv);
+
+NOTE: you can pass either the object directly or the SV
+contained within the RV.
+
+	SV*	vnormal(SV *vs)
+
+=for hackers
+Found in file util.c
+
 =item vnumify
 
 Accepts a version object and returns the normalized floating
@@ -1904,13 +1979,10 @@ Found in file util.c
 
 =item vstringify
 
-Accepts a version object and returns the normalized string
-representation.  Call like:
-
-    sv = vstringify(rv);
-
-NOTE: you can pass either the object directly or the SV
-contained within the RV.
+In order to maintain maximum compatibility with earlier versions
+of Perl, this function will return either the floating point
+notation or the multiple dotted notation, depending on whether
+the original version contained 1 or more dots, respectively
 
 	SV*	vstringify(SV *vs)
 
@@ -1931,8 +2003,10 @@ converts a string representing a binary number to numeric form.
 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
 conversion flags, and I<result> should be NULL or a pointer to an NV.
 The scan stops at the end of the string, or the first invalid character.
-On return I<*len> is set to the length scanned string, and I<*flags> gives
-output flags.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
 
 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
@@ -1940,7 +2014,7 @@ returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
 and writes the value to I<*result> (or the value is discarded if I<result>
 is NULL).
 
-The hex number may optionally be prefixed with "0b" or "b" unless
+The binary 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.
@@ -1956,9 +2030,11 @@ converts a string representing a hex number to numeric form.
 
 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
 conversion flags, and I<result> should be NULL or a pointer to an NV.
-The scan stops at the end of the string, or the first non-hex-digit character.
-On return I<*len> is set to the length scanned string, and I<*flags> gives
-output flags.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
 
 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
@@ -2012,6 +2088,24 @@ Found in file numeric.c
 
 =item grok_oct
 
+converts a string representing an octal number to numeric form.
+
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
+
+If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
+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).
+
+If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
+number may use '_' characters to separate digits.
 
 	UV	grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
 
@@ -2153,6 +2247,94 @@ Stack marker variable for the XSUB.  See C<dMARK>.
 =for hackers
 Found in file pp.h
 
+=item mPUSHi
+
+Push an integer onto the stack.  The stack must have room for this element.
+Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHi>, C<mXPUSHi>
+and C<XPUSHi>.
+
+	void	mPUSHi(IV iv)
+
+=for hackers
+Found in file pp.h
+
+=item mPUSHn
+
+Push a double onto the stack.  The stack must have room for this element.
+Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHn>, C<mXPUSHn>
+and C<XPUSHn>.
+
+	void	mPUSHn(NV nv)
+
+=for hackers
+Found in file pp.h
+
+=item mPUSHp
+
+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.  Does
+not use C<TARG>.  See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
+
+	void	mPUSHp(char* str, STRLEN len)
+
+=for hackers
+Found in file pp.h
+
+=item mPUSHu
+
+Push an unsigned integer onto the stack.  The stack must have room for this
+element.  Handles 'set' magic.  Does not use C<TARG>.  See also C<PUSHu>,
+C<mXPUSHu> and C<XPUSHu>.
+
+	void	mPUSHu(UV uv)
+
+=for hackers
+Found in file pp.h
+
+=item mXPUSHi
+
+Push an integer onto the stack, extending the stack if necessary.  Handles
+'set' magic.  Does not use C<TARG>.  See also C<XPUSHi>, C<mPUSHi> and
+C<PUSHi>.
+
+	void	mXPUSHi(IV iv)
+
+=for hackers
+Found in file pp.h
+
+=item mXPUSHn
+
+Push a double onto the stack, extending the stack if necessary.  Handles
+'set' magic.  Does not use C<TARG>.  See also C<XPUSHn>, C<mPUSHn> and
+C<PUSHn>.
+
+	void	mXPUSHn(NV nv)
+
+=for hackers
+Found in file pp.h
+
+=item mXPUSHp
+
+Push a string onto the stack, extending the stack if necessary.  The C<len>
+indicates the length of the string.  Handles 'set' magic.  Does not use
+C<TARG>.  See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
+
+	void	mXPUSHp(char* str, STRLEN len)
+
+=for hackers
+Found in file pp.h
+
+=item mXPUSHu
+
+Push an unsigned integer onto the stack, extending the stack if necessary.
+Handles 'set' magic.  Does not use C<TARG>.  See also C<XPUSHu>, C<mPUSHu>
+and C<PUSHu>.
+
+	void	mXPUSHu(UV uv)
+
+=for hackers
+Found in file pp.h
+
 =item ORIGMARK
 
 The original stack mark for the XSUB.  See C<dORIGMARK>.
@@ -2229,7 +2411,10 @@ Found in file pp.h
 =item PUSHi
 
 Push an integer onto the stack.  The stack must have room for this element.
-Handles 'set' magic.  See C<XPUSHi>.
+Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
+called to declare it.  Do not call multiple C<TARG>-oriented macros to 
+return lists from XSUB's - see C<mPUSHi> instead.  See also C<XPUSHi> and
+C<mXPUSHi>.
 
 	void	PUSHi(IV iv)
 
@@ -2241,7 +2426,18 @@ Found in file pp.h
 Opening bracket for arguments on a callback.  See C<PUTBACK> and
 L<perlcall>.
 
-		PUSHMARK;
+	void	PUSHMARK(SP)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHmortal
+
+Push a new mortal SV onto the stack.  The stack must have room for this
+element.  Does not handle 'set' magic.  Does not use C<TARG>.  See also
+C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
+
+	void	PUSHmortal()
 
 =for hackers
 Found in file pp.h
@@ -2249,7 +2445,10 @@ 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>.
+Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
+called to declare it.  Do not call multiple C<TARG>-oriented macros to
+return lists from XSUB's - see C<mPUSHn> instead.  See also C<XPUSHn> and
+C<mXPUSHn>.
 
 	void	PUSHn(NV nv)
 
@@ -2259,8 +2458,10 @@ 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>.
+The C<len> indicates the length of the string.  Handles 'set' magic.  Uses
+C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not
+call multiple C<TARG>-oriented macros to return lists from XSUB's - see
+C<mPUSHp> instead.  See also C<XPUSHp> and C<mXPUSHp>.
 
 	void	PUSHp(char* str, STRLEN len)
 
@@ -2270,7 +2471,8 @@ 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>.
+Does not handle 'set' magic.  Does not use C<TARG>.  See also C<PUSHmortal>,
+C<XPUSHs> and C<XPUSHmortal>.
 
 	void	PUSHs(SV* sv)
 
@@ -2280,7 +2482,10 @@ 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>.
+element.  Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
+should be called to declare it.  Do not call multiple C<TARG>-oriented
+macros to return lists from XSUB's - see C<mPUSHu> instead.  See also
+C<XPUSHu> and C<mXPUSHu>.
 
 	void	PUSHu(UV uv)
 
@@ -2317,17 +2522,32 @@ Found in file pp.h
 =item XPUSHi
 
 Push an integer onto the stack, extending the stack if necessary.  Handles
-'set' magic. See C<PUSHi>.
+'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
+declare it.  Do not call multiple C<TARG>-oriented macros to return lists
+from XSUB's - see C<mXPUSHi> instead.  See also C<PUSHi> and C<mPUSHi>.
 
 	void	XPUSHi(IV iv)
 
 =for hackers
 Found in file pp.h
 
+=item XPUSHmortal
+
+Push a new mortal SV onto the stack, extending the stack if necessary.  Does
+not handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHs>,
+C<PUSHmortal> and C<PUSHs>.
+
+	void	XPUSHmortal()
+
+=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>.
+'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
+declare it.  Do not call multiple C<TARG>-oriented macros to return lists
+from XSUB's - see C<mXPUSHn> instead.  See also C<PUSHn> and C<mPUSHn>.
 
 	void	XPUSHn(NV nv)
 
@@ -2337,8 +2557,10 @@ 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>.
+indicates the length of the string.  Handles 'set' magic.  Uses C<TARG>, so
+C<dTARGET> or C<dXSTARG> should be called to declare it.  Do not call
+multiple C<TARG>-oriented macros to return lists from XSUB's - see
+C<mXPUSHp> instead.  See also C<PUSHp> and C<mPUSHp>.
 
 	void	XPUSHp(char* str, STRLEN len)
 
@@ -2348,7 +2570,8 @@ 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>.
+handle 'set' magic.  Does not use C<TARG>.  See also C<XPUSHmortal>,
+C<PUSHs> and C<PUSHmortal>.
 
 	void	XPUSHs(SV* sv)
 
@@ -2358,7 +2581,10 @@ Found in file pp.h
 =item XPUSHu
 
 Push an unsigned integer onto the stack, extending the stack if necessary.
-See C<PUSHu>.
+Handles 'set' magic.  Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
+called to declare it.  Do not call multiple C<TARG>-oriented macros to
+return lists from XSUB's - see C<mXPUSHu> instead.  See also C<PUSHu> and
+C<mPUSHu>.
 
 	void	XPUSHu(UV uv)
 
@@ -2375,6 +2601,15 @@ handled by C<xsubpp>.
 =for hackers
 Found in file XSUB.h
 
+=item XSRETURN_EMPTY
+
+Return an empty list from an XSUB immediately.
+
+		XSRETURN_EMPTY;
+
+=for hackers
+Found in file XSUB.h
+
 =item XSRETURN_IV
 
 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
@@ -2613,6 +2848,19 @@ SV is B<not> incremented.
 =for hackers
 Found in file sv.c
 
+=item NEWSV
+
+Creates a new SV.  A non-zero C<len> parameter indicates the number of
+bytes of preallocated string space the SV should have.  An extra byte for a
+tailing NUL is also reserved.  (SvPOK is not set for the SV even if string
+space is allocated.)  The reference count for the new SV is set to 1.
+C<id> is an integer id between 0 and 1299 (used to identify leaks).
+
+	SV*	NEWSV(int id, STRLEN len)
+
+=for hackers
+Found in file handy.h
+
 =item newSV
 
 Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
@@ -2670,7 +2918,7 @@ Found in file sv.c
 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.
+C<len> bytes long.  If the C<s> argument is NULL the new SV will be undefined.
 
 	SV*	newSVpvn(const char* s, STRLEN len)
 
@@ -2787,7 +3035,7 @@ Found in file sv.h
 
 Returns a boolean indicating whether the SV contains a signed integer.
 
-	void	SvIOK_notUV(SV* sv)
+	bool	SvIOK_notUV(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -2832,7 +3080,7 @@ Found in file sv.h
 
 Returns a boolean indicating whether the SV contains an unsigned integer.
 
-	void	SvIOK_UV(SV* sv)
+	bool	SvIOK_UV(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -2888,6 +3136,15 @@ Only use when you are sure SvIOK is true. See also C<SvIV()>.
 =for hackers
 Found in file sv.h
 
+=item SvIV_nomg
+
+Like C<SvIV> but doesn't process magic.
+
+	IV	SvIV_nomg(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvLEN
 
 Returns the size of the string buffer in the SV, not including any part
@@ -3005,7 +3262,8 @@ Found in file sv.h
 
 =item SvOK
 
-Returns a boolean indicating whether the value is an SV.
+Returns a boolean indicating whether the value is an SV. It also tells
+whether the value is defined or not.
 
 	bool	SvOK(SV* sv)
 
@@ -3244,6 +3502,15 @@ stringified form becoming C<SvPOK>.  Handles 'get' magic.
 =for hackers
 Found in file sv.h
 
+=item SvPV_nomg
+
+Like C<SvPV> but doesn't process magic.
+
+	char*	SvPV_nomg(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
 =item SvREFCNT
 
 Returns the value of the object's reference count.
@@ -3377,17 +3644,6 @@ Returns the type of the SV.  See C<svtype>.
 =for hackers
 Found in file sv.h
 
-=item SvUNLOCK
-
-Releases a mutual exclusion lock on sv if a suitable module
-has been loaded.
-
-
-	void	SvUNLOCK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
 =item SvUOK
 
 Returns a boolean indicating whether the SV contains an unsigned integer.
@@ -3411,7 +3667,7 @@ Found in file sv.h
 
 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
 
-	void	SvUTF8(SV* sv)
+	bool	SvUTF8(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -3465,6 +3721,15 @@ evaluate sv only once. Use the more efficient C<SvUV> otherwise.
 =for hackers
 Found in file sv.h
 
+=item SvUV_nomg
+
+Like C<SvUV> but doesn't process magic.
+
+	UV	SvUV_nomg(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvVOK
 
 Returns a boolean indicating whether the SV contains a v-string.
@@ -3505,12 +3770,13 @@ named after the PV if we're a string.
 =for hackers
 Found in file sv.c
 
-=item sv_2iv
+=item sv_2iv_flags
 
-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.
+Return the integer value of an SV, doing any necessary string
+conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
+Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
 
-	IV	sv_2iv(SV* sv)
+	IV	sv_2iv_flags(SV* sv, I32 flags)
 
 =for hackers
 Found in file sv.c
@@ -3519,7 +3785,9 @@ Found in file sv.c
 
 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>.
+statement boundaries.  SvTEMP() is turned on which means that the SV's
+string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
+and C<sv_mortalcopy>.
 
 	SV*	sv_2mortal(SV* sv)
 
@@ -3608,13 +3876,13 @@ use the macro wrapper C<SvPV_nolen(sv)> instead.
 =for hackers
 Found in file sv.c
 
-=item sv_2uv
+=item sv_2uv_flags
 
 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.
+conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
+Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
 
-	UV	sv_2uv(SV* sv)
+	UV	sv_2uv_flags(SV* sv, I32 flags)
 
 =for hackers
 Found in file sv.c
@@ -3657,9 +3925,8 @@ Processes its arguments like C<sprintf> and appends the formatted
 output to an SV.  If the appended data contains "wide" characters
 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
 and characters >255 formatted with %c), the original SV might get
-upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.
-C<SvSETMAGIC()> must typically be called after calling this function
-to handle 'set' magic.
+upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.  See
+C<sv_catpvf_mg>.
 
 	void	sv_catpvf(SV* sv, const char* pat, ...)
 
@@ -3710,6 +3977,15 @@ Like C<sv_catpvn>, but also handles 'set' magic.
 =for hackers
 Found in file sv.c
 
+=item sv_catpvn_nomg
+
+Like C<sv_catpvn> but doesn't process magic.
+
+	void	sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
 =item sv_catpv_mg
 
 Like C<sv_catpv>, but also handles 'set' magic.
@@ -3751,6 +4027,15 @@ Like C<sv_catsv>, but also handles 'set' magic.
 =for hackers
 Found in file sv.c
 
+=item sv_catsv_nomg
+
+Like C<sv_catsv> but doesn't process magic.
+
+	void	sv_catsv_nomg(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
 =item sv_chop
 
 Efficient removal of characters from the beginning of the string buffer.
@@ -4002,6 +4287,9 @@ Found in file sv.c
 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.
 
+See C<sv_magicext> (which C<sv_magic> now calls) for a description of the
+handling of the C<name> and C<namlen> arguments.
+
 	void	sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
 
 =for hackers
@@ -4010,18 +4298,18 @@ Found in file sv.c
 =item sv_magicext
 
 Adds magic to an SV, upgrading it if necessary. Applies the
-supplied vtable and returns pointer to the magic added.
+supplied vtable and returns a pointer to the magic added.
 
-Note that sv_magicext will allow things that sv_magic will not.
-In particular you can add magic to SvREADONLY SVs and and more than
-one instance of the same 'how'
+Note that C<sv_magicext> will allow things that C<sv_magic> will not.
+In particular, you can add magic to SvREADONLY SVs, and add more than
+one instance of the same 'how'.
 
-I C<namelen> is greater then zero then a savepvn() I<copy> of C<name> is stored,
-if C<namelen> is zero then C<name> is stored as-is and - as another special
-case - if C<(name && namelen == HEf_SVKEY)> then C<name> is assumed to contain
-an C<SV*> and has its REFCNT incremented
+If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is
+stored, if C<namlen> is zero then C<name> is stored as-is and - as another
+special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
+to contain an C<SV*> and is stored as-is with its REFCNT incremented.
 
-(This is now used as a subroutine by sv_magic.)
+(This is now used as a subroutine by C<sv_magic>.)
 
 	MAGIC *	sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen	)
 
@@ -4306,8 +4594,8 @@ Found in file sv.c
 
 =item sv_setpvf
 
-Processes its arguments like C<sprintf> and sets an SV to the formatted
-output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
+Works like C<sv_catpvf> but copies the text into the SV instead of
+appending it.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
 
 	void	sv_setpvf(SV* sv, const char* pat, ...)
 
@@ -4345,7 +4633,8 @@ Found in file sv.c
 =item sv_setpvn
 
 Copies a string into an SV.  The C<len> parameter indicates the number of
-bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
+bytes to be copied.  If the C<ptr> argument is NULL the SV will become
+undefined.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
 
 	void	sv_setpvn(SV* sv, const char* ptr, STRLEN len)
 
@@ -4421,7 +4710,7 @@ Copies a string into a new SV, optionally blessing the SV.  The length of the
 string must be specified with C<n>.  The C<rv> argument will be upgraded to
 an RV.  That RV will be modified to point to the new SV.  The C<classname>
 argument indicates the package for the blessing.  Set C<classname> to
-C<Nullch> to avoid the blessing.  The new SV will have a reference count 
+C<Nullch> to avoid the blessing.  The new SV will have a reference count
 of 1, and the RV will be returned.
 
 Note that C<sv_setref_pv> copies the pointer while this copies the string.
@@ -4469,8 +4758,9 @@ 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.
+C<ssv> if appropriate, else not. If the C<flags> parameter has the
+C<NOSTEAL> bit set then the buffers of temps will not be stolen. <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
@@ -4493,6 +4783,15 @@ Like C<sv_setsv>, but also handles 'set' magic.
 =for hackers
 Found in file sv.c
 
+=item sv_setsv_nomg
+
+Like C<sv_setsv> but doesn't process magic.
+
+	void	sv_setsv_nomg(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
 =item sv_setuv
 
 Copies an unsigned integer into the given SV, upgrading first if necessary.
@@ -4620,9 +4919,11 @@ 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 off SvUTF8 if needed so that we see characters. Used as a building block
-for decode_utf8 in Encode.xs
+If the PV of the SV is an octet sequence in UTF-8
+and contains a multiple-byte character, the C<SvUTF8> flag is turned on
+so that it looks like a character. If the PV contains only single-byte
+characters, the C<SvUTF8> flag stays being off.
+Scans PV for validity and returns false if the PV is invalid UTF-8.
 
 NOTE: this function is experimental and may change or be
 removed without notice.
@@ -4634,9 +4935,9 @@ Found in file sv.c
 
 =item sv_utf8_downgrade
 
-Attempt to convert the PV of an SV from UTF-8-encoded to byte encoding.
-This may not be possible if the PV contains non-byte encoding characters;
-if this is the case, either returns false or, if C<fail_ok> is not
+Attempts to convert the PV of an SV from characters to bytes.
+If the PV contains a character beyond byte, this conversion will fail;
+in this case, either returns false or, if C<fail_ok> is not
 true, croaks.
 
 This is not as a general purpose Unicode to byte encoding interface:
@@ -4652,9 +4953,8 @@ Found in file sv.c
 
 =item sv_utf8_encode
 
-Convert the PV of an SV to UTF-8-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
+Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8>
+flag off so that it looks like octets again.
 
 	void	sv_utf8_encode(SV *sv)
 
@@ -4663,7 +4963,7 @@ Found in file sv.c
 
 =item sv_utf8_upgrade
 
-Convert the PV of an SV to its UTF-8-encoded form.
+Converts the PV of an SV to its UTF-8-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.
@@ -4678,7 +4978,7 @@ Found in file sv.c
 
 =item sv_utf8_upgrade_flags
 
-Convert the PV of an SV to its UTF-8-encoded form.
+Converts the PV of an SV to its UTF-8-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,
@@ -4703,6 +5003,18 @@ cope with complex macro expressions. Always use the macro instead.
 =for hackers
 Found in file sv.c
 
+=item sv_vcatpvf
+
+Processes its arguments like C<vsprintf> and appends the formatted output
+to an SV.  Does not handle 'set' magic.  See C<sv_vcatpvf_mg>.
+
+Usually used via its frontend C<sv_catpvf>.
+
+	void	sv_vcatpvf(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
 =item sv_vcatpvfn
 
 Processes its arguments like C<vsprintf> and appends the formatted output
@@ -4711,25 +5023,59 @@ 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>.
+Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_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_vcatpvf_mg
+
+Like C<sv_vcatpvf>, but also handles 'set' magic.
+
+Usually used via its frontend C<sv_catpvf_mg>.
+
+	void	sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vsetpvf
+
+Works like C<sv_vcatpvf> but copies the text into the SV instead of
+appending it.  Does not handle 'set' magic.  See C<sv_vsetpvf_mg>.
+
+Usually used via its frontend C<sv_setpvf>.
+
+	void	sv_vsetpvf(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
 =item sv_vsetpvfn
 
-Works like C<vcatpvfn> but copies the text into the SV instead of
+Works like C<sv_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>.
+Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_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
 
+=item sv_vsetpvf_mg
+
+Like C<sv_vsetpvf>, but also handles 'set' magic.
+
+Usually used via its frontend C<sv_setpvf_mg>.
+
+	void	sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
 
 =back
 
@@ -4784,7 +5130,7 @@ 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
+circumstances.  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
@@ -5208,6 +5554,16 @@ This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
 =for hackers
 Found in file XSUB.h
 
+=item dUNDERBAR
+
+Sets up the C<padoff_du> variable for an XSUB that wishes to use
+C<UNDERBAR>.
+
+		dUNDERBAR;
+
+=for hackers
+Found in file XSUB.h
+
 =item dXSARGS
 
 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
@@ -5288,20 +5644,18 @@ L<perlxs/"Using XS With C++">.
 =for hackers
 Found in file XSUB.h
 
-=item XS
+=item UNDERBAR
 
-Macro to declare an XSUB and its C parameter list.  This is handled by
-C<xsubpp>.
+The SV* corresponding to the $_ variable. Works even if there
+is a lexical $_ in scope.
 
 =for hackers
 Found in file XSUB.h
 
-=item XSRETURN_EMPTY
-
-Return an empty list from an XSUB immediately.
-
+=item XS
 
-		XSRETURN_EMPTY;
+Macro to declare an XSUB and its C parameter list.  This is handled by
+C<xsubpp>.
 
 =for hackers
 Found in file XSUB.h
@@ -5335,8 +5689,9 @@ Found in file XSUB.h
 =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>.
+Normally call this function the same way you call the C C<printf>
+function.  Calling C<croak> returns control directly to Perl,
+sidestepping the normal C order of execution. See C<warn>.
 
 If you want to throw an exception object, assign the object to
 C<$@> and then pass C<Nullch> to croak():
@@ -5352,9 +5707,8 @@ 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>.
+This is the XSUB-writer's interface to Perl's C<warn> function.  Call this
+function the same way you call the C C<printf> function.  See C<croak>.
 
 	void	warn(const char* pat, ...)