Document sv_magic() changes brought about by sv_magicext()

Change 14335 made sv_magic() a wrapper to a new sv_magicext(),
but didn't update the documentation for sv_magic() to reflect
the changed handling of the name/namlen arguments.

Also correct a couple of typos, and mention sv_magicext() in
perlguts.

p4raw-id: //depot/perl@23432

1 files changed, 8 insertions, 2 deletions

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 99c79d0a43..5eb46d2d0e 100644
--- 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);