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

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 7b8a77c..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>
 
@@ -5702,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>
+=item sv_usepvn_flags
+X<sv_usepvn_flags>
 
-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>.
+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.
 
-	void	sv_usepvn(SV* sv, char* ptr, STRLEN len)
-
-=for hackers
-Found in file sv.c
+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>)
 
-=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)
+	void	sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags)
 
 =for hackers
 Found in file sv.c
@@ -6276,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.