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

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index d608eef..6471081 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -1,3 +1,9 @@
+-*- buffer-read-only: t -*-
+
+!!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
+This file is built by autodoc.pl extracting documentation from the C source
+files.
+
 =head1 NAME
 
 perlapi - autogenerated documentation for the perl public API
@@ -182,9 +188,15 @@ Found in file av.c
 =item av_fill
 X<av_fill>
 
-Ensure than an array has a given number of elements, equivalent to
+Set the highest index in the array to the given number, equivalent to
 Perl's C<$#array = $fill;>.
 
+The number of elements in the an array will be C<fill + 1> after
+av_fill() returns.  If the array was previously shorter then the
+additional elements appended are set to C<PL_sv_undef>.  If the array
+was longer, then the excess elements are freed.  C<av_fill(av, -1)> is
+the same as C<av_clear(av)>.
+
 	void	av_fill(AV* ar, I32 fill)
 
 =for hackers
@@ -193,8 +205,8 @@ Found in file av.c
 =item av_len
 X<av_len>
 
-Returns the highest index in the array.  Returns -1 if the array is
-empty.
+Returns the highest index in the array.  The number of elements in the
+array is C<av_len(av) + 1>.  Returns -1 if the array is empty.
 
 	I32	av_len(const AV* ar)
 
@@ -753,6 +765,110 @@ Found in file perl.c
 
 =back
 
+=head1 Functions in file dump.c
+
+
+=over 8
+
+=item pv_display
+X<pv_display>
+
+  char *pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len,
+                   STRLEN pvlim, U32 flags)
+
+Similar to
+
+  pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
+
+except that an additional "\0" will be appended to the string when
+len > cur and pv[cur] is "\0".
+
+Note that the final string may be up to 7 chars longer than pvlim.
+
+	char*	pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
+
+=for hackers
+Found in file dump.c
+
+=item pv_escape
+X<pv_escape>
+
+               |const STRLEN count|const STRLEN max
+               |STRLEN const *escaped, const U32 flags
+
+Escapes at most the first "count" chars of pv and puts the results into
+dsv such that the size of the escaped string will not exceed "max" chars
+and will not contain any incomplete escape sequences.
+
+If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string
+will also be escaped.
+
+Normally the SV will be cleared before the escaped string is prepared,
+but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur.
+
+If PERL_PV_ESCAPE_UNI is set then the input string is treated as unicode,
+if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
+using C<is_utf8_string()> to determine if it is unicode.
+
+If PERL_PV_ESCAPE_ALL is set then all input chars will be output
+using C<\x01F1> style escapes, otherwise only chars above 255 will be
+escaped using this style, other non printable chars will use octal or
+common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH
+then all chars below 255 will be treated as printable and 
+will be output as literals.
+
+If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the
+string will be escaped, regardles of max. If the string is utf8 and 
+the chars value is >255 then it will be returned as a plain hex 
+sequence. Thus the output will either be a single char, 
+an octal escape sequence, a special escape like C<\n> or a 3 or 
+more digit hex value. 
+
+Returns a pointer to the escaped text as held by dsv.
+
+NOTE: the perl_ form of this function is deprecated.
+
+	char*	pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
+
+=for hackers
+Found in file dump.c
+
+=item pv_pretty
+X<pv_pretty>
+
+           |const STRLEN count|const STRLEN max\
+           |const char const *start_color| const char const *end_color\
+           |const U32 flags
+
+Converts a string into something presentable, handling escaping via
+pv_escape() and supporting quoting and elipses. 
+
+If the PERL_PV_PRETTY_QUOTE flag is set then the result will be 
+double quoted with any double quotes in the string escaped. Otherwise
+if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
+angle brackets. 
+           
+If the PERL_PV_PRETTY_ELIPSES flag is set and not all characters in
+string were output then an elipses C<...> will be appended to the 
+string. Note that this happens AFTER it has been quoted.
+           
+If start_color is non-null then it will be inserted after the opening
+quote (if there is one) but before the escaped text. If end_color
+is non-null then it will be inserted after the escaped text but before
+any quotes or elipses.
+
+Returns a pointer to the prettified text as held by dsv.
+           
+NOTE: the perl_ form of this function is deprecated.
+
+	char*	pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)
+
+=for hackers
+Found in file dump.c
+
+
+=back
+
 =head1 Functions in file mathoms.c
 
 
@@ -1249,6 +1365,16 @@ package does not exist then NULL is returned.
 =for hackers
 Found in file gv.c
 
+=item gv_stashpvs
+X<gv_stashpvs>
+
+Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
+
+	HV*	gv_stashpvs(const char* name, I32 create)
+
+=for hackers
+Found in file handy.h
+
 =item gv_stashsv
 X<gv_stashsv>
 
@@ -1548,6 +1674,16 @@ information on how to use this function on tied hashes.
 =for hackers
 Found in file hv.c
 
+=item hv_fetchs
+X<hv_fetchs>
+
+Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
+
+	SV**	hv_fetchs(HV* tb, const char* key, I32 lval)
+
+=for hackers
+Found in file handy.h
+
 =item hv_fetch_ent
 X<hv_fetch_ent>
 
@@ -1715,6 +1851,17 @@ information on how to use this function on tied hashes.
 =for hackers
 Found in file hv.c
 
+=item hv_stores
+X<hv_stores>
+
+Like C<hv_store>, but takes a literal string instead of a string/length pair
+and omits the hash parameter.
+
+	SV**	hv_stores(HV* tb, const char* key, NULLOK SV* val)
+
+=for hackers
+Found in file handy.h
+
 =item hv_store_ent
 X<hv_store_ent>
 
@@ -1766,6 +1913,20 @@ Creates a new HV.  The reference count is set to 1.
 =for hackers
 Found in file hv.c
 
+=item refcounted_he_chain_2hv
+X<refcounted_he_chain_2hv>
+
+Generates an returns a C<HV *> by walking up the tree starting at the passed
+in C<struct refcounted_he *>.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+	HV *	refcounted_he_chain_2hv(const struct refcounted_he *c)
+
+=for hackers
+Found in file hv.c
+
 
 =back
 
@@ -2051,6 +2212,16 @@ PoisonWith(0xEF) for catching access to freed memory.
 =for hackers
 Found in file handy.h
 
+=item PoisonFree
+X<PoisonFree>
+
+PoisonWith(0xEF) for catching access to freed memory.
+
+	void	PoisonFree(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
 =item PoisonNew
 X<PoisonNew>
 
@@ -2129,6 +2300,16 @@ the new string can be freed with the C<Safefree()> function.
 =for hackers
 Found in file util.c
 
+=item savepvs
+X<savepvs>
+
+Like C<savepvn>, but takes a literal string instead of a string/length pair.
+
+	char*	savepvs(const char* s)
+
+=for hackers
+Found in file handy.h
+
 =item savesharedpv
 X<savesharedpv>
 
@@ -2245,6 +2426,21 @@ Fill the sv with current working directory
 =for hackers
 Found in file util.c
 
+=item my_snprintf
+X<my_snprintf>
+
+The C library C<snprintf> functionality, if available and
+standards-compliant (uses C<vsnprintf>, actually).  However, if the
+C<vsnprintf> is not available, will unfortunately use the unsafe
+C<vsprintf> which can overrun the buffer (there is an overrun check,
+but that may be too late).  Consider using C<sv_vcatpvf> instead, or
+getting C<vsnprintf>.
+
+	int	my_snprintf(char *buffer, const Size_t len, const char *format, ...)
+
+=for hackers
+Found in file util.c
+
 =item my_sprintf
 X<my_sprintf>
 
@@ -2257,6 +2453,20 @@ need the wrapper function - usually this is a direct call to C<sprintf>.
 =for hackers
 Found in file util.c
 
+=item my_vsnprintf
+X<my_vsnprintf>
+
+The C library C<vsnprintf> if available and standards-compliant.
+However, if if the C<vsnprintf> is not available, will unfortunately
+use the unsafe C<vsprintf> which can overrun the buffer (there is an
+overrun check, but that may be too late).  Consider using
+C<sv_vcatpvf> instead, or getting C<vsnprintf>.
+
+	int	my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
+
+=for hackers
+Found in file util.c
+
 =item new_version
 X<new_version>
 
@@ -4181,6 +4391,9 @@ X<SvREFCNT_inc>
 
 Increments the reference count of the given SV.
 
+All of the following SvREFCNT_inc* macros are optimized versions of
+SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
+
 	SV*	SvREFCNT_inc(SV* sv)
 
 =for hackers
@@ -4228,7 +4441,20 @@ 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)
+	void	SvREFCNT_inc_simple_void(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple_void_NN
+X<SvREFCNT_inc_simple_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.
+
+	void	SvREFCNT_inc_simple_void_NN(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -4239,7 +4465,7 @@ 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)
+	void	SvREFCNT_inc_void(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -4252,7 +4478,7 @@ 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)
+	void	SvREFCNT_inc_void_NN(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -4322,7 +4548,7 @@ X<SvSTASH_set>
 
 Set the value of the STASH pointer in sv to val.  See C<SvIV_set>.
 
-	void	SvSTASH_set(SV* sv, STASH* val)
+	void	SvSTASH_set(SV* sv, HV* val)
 
 =for hackers
 Found in file sv.h
@@ -4532,15 +4758,26 @@ Found in file sv.h
 =item sv_derived_from
 X<sv_derived_from>
 
-Returns a boolean indicating whether the SV is derived from the specified
-class.  This is the function that implements C<UNIVERSAL::isa>.  It works
-for class names as well as for objects.
+Returns a boolean indicating whether the SV is derived from the specified class
+I<at the C level>.  To check derivation at the Perl level, call C<isa()> as a
+normal Perl method.
 
 	bool	sv_derived_from(SV* sv, const char* name)
 
 =for hackers
 Found in file universal.c
 
+=item sv_does
+X<sv_does>
+
+Returns a boolean indicating whether the SV performs a specific, named role.
+The SV can be a Perl object or the name of a Perl class.
+
+	bool	sv_does(SV* sv, const char* name)
+
+=for hackers
+Found in file universal.c
+
 =item sv_report_used
 X<sv_report_used>
 
@@ -4696,6 +4933,27 @@ hash lookup will avoid string compare.
 =for hackers
 Found in file sv.c
 
+=item newSVpvs
+X<newSVpvs>
+
+Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
+
+	SV*	newSVpvs(const char* s)
+
+=for hackers
+Found in file handy.h
+
+=item newSVpvs_share
+X<newSVpvs_share>
+
+Like C<newSVpvn_share>, but takes a literal string instead of a string/length
+pair and omits the hash parameter.
+
+	SV*	newSVpvs_share(const char* s)
+
+=for hackers
+Found in file handy.h
+
 =item newSVrv
 X<newSVrv>
 
@@ -4946,6 +5204,16 @@ in terms of this function.
 =for hackers
 Found in file sv.c
 
+=item sv_catpvs
+X<sv_catpvs>
+
+Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
+
+	void	sv_catpvs(SV* sv, const char* s)
+
+=for hackers
+Found in file handy.h
+
 =item sv_catpv_mg
 X<sv_catpv_mg>
 
@@ -5367,7 +5635,7 @@ X<sv_reftype>
 
 Returns a string describing what the SV is a reference to.
 
-	char*	sv_reftype(const SV* sv, int ob)
+	const char*	sv_reftype(const SV* sv, int ob)
 
 =for hackers
 Found in file sv.c
@@ -5404,7 +5672,8 @@ X<sv_rvweaken>
 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.
+associated with that magic. If the RV is magical, set magic will be
+called after the RV is cleared.
 
 	SV*	sv_rvweaken(SV *sv)
 
@@ -5528,6 +5797,16 @@ Like C<sv_setpvn>, but also handles 'set' magic.
 =for hackers
 Found in file sv.c
 
+=item sv_setpvs
+X<sv_setpvs>
+
+Like C<sv_setpvn>, but takes a literal string instead of a string/length pair.
+
+	void	sv_setpvs(SV* sv, const char* s)
+
+=for hackers
+Found in file handy.h
+
 =item sv_setpv_mg
 X<sv_setpv_mg>
 
@@ -5754,7 +6033,7 @@ 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>.
 
-	void	sv_upgrade(SV* sv, U32 mt)
+	void	sv_upgrade(SV* sv, svtype new_type)
 
 =for hackers
 Found in file sv.c
@@ -6678,3 +6957,6 @@ Updated to be autogenerated from comments in the source by Benjamin Stuhl.
 
 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
 
+=cut
+
+ ex: set ro: