X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=d608eef3c3c4003d765c503c95a60edf5a1de671;hb=77004dee2553ce034a8a58b2b2849e3656df46c3;hp=a9dbc5c571fdcd48ed0c2402004ca8d9749837cf;hpb=d2a0f284b32a9deb0ebffbb06cf667a0ea1ea610;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index a9dbc5c..d608eef 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -768,6 +768,17 @@ See L<gv_fetchmethod_autoload>.
 =for hackers
 Found in file mathoms.c
 
+=item pack_cat
+X<pack_cat>
+
+The engine implementing pack() Perl function. Note: parameters next_in_list and
+flags are not used. This call should not be used; use packlist instead.
+
+	void	pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
+
+=for hackers
+Found in file mathoms.c
+
 =item sv_2pvbyte_nolen
 X<sv_2pvbyte_nolen>
 
@@ -973,6 +984,28 @@ being zero.  See C<SvROK_off>.
 =for hackers
 Found in file mathoms.c
 
+=item sv_usepvn
+X<sv_usepvn>
+
+Tells an SV to use C<ptr> to find its string value. Implemented by
+calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
+magic. See C<sv_usepvn_flags>.
+
+	void	sv_usepvn(SV* sv, char* ptr, STRLEN len)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_usepvn_mg
+X<sv_usepvn_mg>
+
+Like C<sv_usepvn>, but also handles 'set' magic.
+
+	void	sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
+
+=for hackers
+Found in file mathoms.c
+
 =item sv_uv
 X<sv_uv>
 
@@ -984,6 +1017,17 @@ cope with complex macro expressions. Always use the macro instead.
 =for hackers
 Found in file mathoms.c
 
+=item unpack_str
+X<unpack_str>
+
+The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
+and ocnt are not used. This call should not be used, use unpackstring instead.
+
+	I32	unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
+
+=for hackers
+Found in file mathoms.c
+
 
 =back
 
@@ -1002,17 +1046,6 @@ The engine implementing pack() Perl function.
 =for hackers
 Found in file pp_pack.c
 
-=item pack_cat
-X<pack_cat>
-
-The engine implementing pack() Perl function. Note: parameters next_in_list and
-flags are not used. This call should not be used; use packlist instead.
-
-	void	pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
-
-=for hackers
-Found in file pp_pack.c
-
 =item unpackstring
 X<unpackstring>
 
@@ -1025,17 +1058,6 @@ Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
 =for hackers
 Found in file pp_pack.c
 
-=item unpack_str
-X<unpack_str>
-
-The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
-and ocnt are not used. This call should not be used, use unpackstring instead.
-
-	I32	unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
-
-=for hackers
-Found in file pp_pack.c
-
 
 =back
 
@@ -2022,14 +2044,34 @@ Found in file handy.h
 =item Poison
 X<Poison>
 
-Fill up memory with a pattern (byte 0xAB over and over again) that
-hopefully catches attempts to access uninitialized memory.
+PoisonWith(0xEF) for catching access to freed memory.
 
 	void	Poison(void* dest, int nitems, type)
 
 =for hackers
 Found in file handy.h
 
+=item PoisonNew
+X<PoisonNew>
+
+PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
+
+	void	PoisonNew(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item PoisonWith
+X<PoisonWith>
+
+Fill up memory with a byte pattern (a byte repeated over and over
+again) that hopefully catches attempts to access uninitialized memory.
+
+	void	PoisonWith(void* dest, int nitems, type, U8 byte)
+
+=for hackers
+Found in file handy.h
+
 =item Renew
 X<Renew>
 
@@ -2079,8 +2121,8 @@ X<savepvn>
 
 Perl's version of what C<strndup()> would be if it existed. Returns a
 pointer to a newly allocated string which is a duplicate of the first
-C<len> bytes from C<pv>. The memory allocated for the new string can be
-freed with the C<Safefree()> function.
+C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
+the new string can be freed with the C<Safefree()> function.
 
 	char*	savepvn(const char* pv, I32 len)
 
@@ -2683,7 +2725,8 @@ Found in file op.c
 =item newXS
 X<newXS>
 
-Used by C<xsubpp> to hook up XSUBs as Perl subs.
+Used by C<xsubpp> to hook up XSUBs as Perl subs.  I<filename> needs to be
+static storage, as it is used directly as CvFILE(), without a copy being made.
 
 =for hackers
 Found in file op.c
@@ -3483,6 +3526,20 @@ See C<SvCUR>.  Access the character as *(SvEND(sv)).
 =for hackers
 Found in file sv.h
 
+=item SvGAMAGIC
+X<SvGAMAGIC>
+
+Returns true if the SV has get magic or overloading. If either is true then
+the scalar is active data, and has the potential to return a new value every
+time it is accessed. Hence you must be careful to only read it once per user
+logical operation and work with that returned value. If neither is true then
+the scalar's value cannot change unless written to.
+
+	char*	SvGAMAGIC(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvGROW
 X<SvGROW>
 
@@ -4129,6 +4186,77 @@ Increments the reference count of the given SV.
 =for hackers
 Found in file sv.h
 
+=item SvREFCNT_inc_NN
+X<SvREFCNT_inc_NN>
+
+Same as SvREFCNT_inc, but can only be used if you know I<sv>
+is not NULL.  Since we don't have to check the NULLness, it's faster
+and smaller.
+
+	SV*	SvREFCNT_inc_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple
+X<SvREFCNT_inc_simple>
+
+Same as SvREFCNT_inc, but can only be used with simple variables, not
+expressions or pointer dereferences.  Since we don't have to store a
+temporary value, it's faster.
+
+	SV*	SvREFCNT_inc_simple(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple_NN
+X<SvREFCNT_inc_simple_NN>
+
+Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
+is not NULL.  Since we don't have to check the NULLness, it's faster
+and smaller.
+
+	SV*	SvREFCNT_inc_simple_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple_void
+X<SvREFCNT_inc_simple_void>
+
+Same as SvREFCNT_inc_simple, but can only be used if you don't need the
+return value.  The macro doesn't need to return a meaningful value.
+
+	SV*	SvREFCNT_inc_simple_void(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_void
+X<SvREFCNT_inc_void>
+
+Same as SvREFCNT_inc, but can only be used if you don't need the
+return value.  The macro doesn't need to return a meaningful value.
+
+	SV*	SvREFCNT_inc_void(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_void_NN
+X<SvREFCNT_inc_void_NN>
+
+Same as SvREFCNT_inc, but can only be used if you don't need the return
+value, and you know that I<sv> is not NULL.  The macro doesn't need
+to return a meaningful value, or check for NULLness, so it's smaller
+and faster.
+
+	SV*	SvREFCNT_inc_void_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvROK
 X<SvROK>
 
@@ -4458,7 +4586,7 @@ X<newRV_noinc>
 Creates an RV wrapper for an SV.  The reference count for the original
 SV is B<not> incremented.
 
-	SV*	newRV_noinc(SV *sv)
+	SV*	newRV_noinc(SV* sv)
 
 =for hackers
 Found in file sv.c
@@ -5631,28 +5759,24 @@ You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
 =for hackers
 Found in file sv.c
 
-=item sv_usepvn
-X<sv_usepvn>
-
-Tells an SV to use C<ptr> to find its string value.  Normally the string is
-stored inside the SV but sv_usepvn allows the SV to use an outside string.
-The C<ptr> should point to memory that was allocated by C<malloc>.  The
-string length, C<len>, must be supplied.  This function will realloc the
-memory pointed to by C<ptr>, so that pointer should not be freed or used by
-the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
-See C<sv_usepvn_mg>.
-
-	void	sv_usepvn(SV* sv, char* ptr, STRLEN len)
-
-=for hackers
-Found in file sv.c
+=item sv_usepvn_flags
+X<sv_usepvn_flags>
 
-=item sv_usepvn_mg
-X<sv_usepvn_mg>
+Tells an SV to use C<ptr> to find its string value.  Normally the
+string is stored inside the SV but sv_usepvn allows the SV to use an
+outside string.  The C<ptr> should point to memory that was allocated
+by C<malloc>.  The string length, C<len>, must be supplied.  By default
+this function will realloc (i.e. move) the memory pointed to by C<ptr>,
+so that pointer should not be freed or used by the programmer after
+giving it to sv_usepvn, and neither should any pointers from "behind"
+that pointer (e.g. ptr + 1) be used.
 
-Like C<sv_usepvn>, but also handles 'set' magic.
+If C<flags> & SV_SMAGIC is true, will call SvSETMAGIC. If C<flags> &
+SV_HAS_TRAILING_NUL is true, then C<ptr[len]> must be NUL, and the realloc
+will be skipped. (i.e. the buffer is actually at least 1 byte longer than
+C<len>, and already meets the requirements for storing in C<SvPVX>)
 
-	void	sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
+	void	sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags)
 
 =for hackers
 Found in file sv.c
@@ -6205,6 +6329,8 @@ Unlike C<bytes_to_utf8>, this over-writes the original string, and
 updates len to contain the new length.
 Returns zero on failure, setting C<len> to -1.
 
+If you need a copy of the string, see C<bytes_from_utf8>.
+
 NOTE: this function is experimental and may change or be
 removed without notice.