Improve documentation for sv_catpvf, to note that pattern's UTF-8ness

[p5sagit/p5-mst-13.2.git] / pod / perlguts.pod

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 99c79d0..4d04531 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -926,8 +926,11 @@ SV.
 
 The C<name> and C<namlen> arguments are used to associate a string with
 the magic, typically the name of a variable. C<namlen> is stored in the
-C<mg_len> field and if C<name> is non-null and C<namlen> E<gt>= 0 a malloc'd
-copy of the name is stored in C<mg_ptr> field.
+C<mg_len> field and if C<name> is non-null then either a C<savepvn> copy of
+C<name> or C<name> itself is stored in the C<mg_ptr> field, depending on
+whether C<namlen> is greater than zero or equal to zero respectively.  As a
+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.
 
 The sv_magic function uses C<how> to determine which, if any, predefined
 "Magic Virtual Table" should be assigned to the C<mg_virtual> field.
@@ -944,6 +947,9 @@ count of the C<obj> object is incremented.  If it is the same, or if
 the C<how> argument is C<PERL_MAGIC_arylen>, or if it is a NULL pointer,
 then C<obj> is merely stored, without the reference count being incremented.
 
+See also C<sv_magicext> in L<perlapi> for a more flexible way to add magic
+to an SV.
+
 There is also a function to add magic to an C<HV>:
 
     void hv_magic(HV *hv, GV *gv, int how);
@@ -2277,6 +2283,26 @@ source, like this:
 Please try and supply some documentation if you add functions to the
 Perl core.
 
+=head2 Backwards compatibility
+
+The Perl API changes over time. New functions are added or the interfaces
+of existing functions are changed. The C<Devel::PPPort> module tries to
+provide compatibility code for some of these changes, so XS writers don't
+have to code it themselves when supporting multiple versions of Perl.
+
+C<Devel::PPPort> generates a C header file F<ppport.h> that can also
+be run as a Perl script. To generate F<ppport.h>, run:
+
+    perl -MDevel::PPPort -eDevel::PPPort::WriteFile
+
+Besides checking existing XS code, the script can also be used to retrieve
+compatibility information for various API calls using the C<--api-info>
+command line switch. For example:
+
+  % perl ppport.h --api-info=sv_magicext
+
+For details, see C<perldoc ppport.h>.
+
 =head1 Unicode Support
 
 Perl 5.6.0 introduced Unicode support. It's important for porters and XS