X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=5fbc20162c78a304dc9c2621538bf62b5524acdf;hb=ec38d36ccc38aad33e07cbbbf1e8816341de661d;hp=aaa9e90abdc40e07658488fa07a364b52492b9d3;hpb=4d4e713df03e36e02b94d8347b24e61304531f93;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index aaa9e90..5fbc201 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -1086,6 +1086,22 @@ Closing bracket on a callback.  See C<ENTER> and L<perlcall>.
 =for hackers
 Found in file scope.h
 
+=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 looks_like_number
 
 Test if an the content of an SV looks like a number (or is a
@@ -1697,7 +1713,9 @@ Found in file handy.h
 
 =item require_pv
 
-Tells Perl to C<require> a module.
+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.
 
@@ -1916,7 +1934,7 @@ indicated number of bytes (remember to reserve space for an extra trailing
 NUL character).  Calls C<sv_grow> to perform the expansion if necessary. 
 Returns a pointer to the character buffer.
 
-	void	SvGROW(SV* sv, STRLEN len)
+	char *	SvGROW(SV* sv, STRLEN len)
 
 =for hackers
 Found in file sv.h
@@ -2179,6 +2197,7 @@ Found in file sv.h
 =item SvPOK_only
 
 Tells an SV that it is a string and disables all other OK bits.
+Will also turn off the UTF8 status.
 
 	void	SvPOK_only(SV* sv)
 
@@ -2187,8 +2206,8 @@ Found in file sv.h
 
 =item SvPOK_only_UTF8
 
-Tells an SV that it is a UTF8 string (do not use frivolously)
-and disables all other OK bits.
+Tells an SV that it is a string and disables all other OK bits,
+and leaves the UTF8 status as it was.
   
 	void	SvPOK_only_UTF8(SV* sv)
 
@@ -2389,19 +2408,19 @@ 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
-
-Returns the type of the SV.  See C<svtype>.
+=item svtype
 
-	svtype	SvTYPE(SV* sv)
+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 sv.h
@@ -2494,7 +2513,8 @@ Found in file sv.h
 
 =item SvUTF8_on
 
-Tells an SV that it is a string and encoded in UTF8.  Do not use frivolously.
+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)
 
@@ -2544,7 +2564,8 @@ Found in file sv.c
 =item sv_catpv
 
 Concatenates the string onto the end of the string which is in the SV.
-Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
+If the SV has the UTF8 status set, then the bytes appended should be
+valid UTF8.  Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
 
 	void	sv_catpv(SV* sv, const char* ptr)
 
@@ -2553,9 +2574,13 @@ Found in file sv.c
 
 =item sv_catpvf
 
-Processes its arguments like C<sprintf> and appends the formatted output
-to an SV.  Handles 'get' magic, but not 'set' magic.  C<SvSETMAGIC()> must
-typically be called after calling this function to handle 'set' magic.
+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.
 
 	void	sv_catpvf(SV* sv, const char* pat, ...)
 
@@ -2574,8 +2599,9 @@ Found in file sv.c
 =item sv_catpvn
 
 Concatenates the string onto the end of the string which is in the SV.  The
-C<len> indicates number of bytes to copy.  Handles 'get' magic, but not
-'set' magic.  See C<sv_catpvn_mg>.
+C<len> indicates number of bytes to copy.  If the SV has the UTF8
+status set, then the bytes appended should be valid UTF8.
+Handles 'get' magic, but not 'set' magic.  See C<sv_catpvn_mg>.
 
 	void	sv_catpvn(SV* sv, const char* ptr, STRLEN len)