Improve documentation of XS autoloading

4 files changed, 27 insertions, 6 deletions

diff --git a/cv.h b/cv.h
index ebc876a540..baf769296a 100644
--- a/cv.h
+++ b/cv.h
@@ -34,6 +34,9 @@ Returns the stash of the CV. A stash is the symbol table hash, containing
 the package-scoped variables in the package where the subroutine was defined.
 For more information, see L<perlguts>.
 
+This also has a special use with XS AUTOLOAD subs.
+See L<perlguts/Autoloading with XSUBs>.
+
 =cut
 */
 
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 38ed3e1926..97b97589e1 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -1498,6 +1498,26 @@ C<m(X)PUSH[iunp]> macros instead; see L</Putting a C value on Perl stack>.
 
 For more information, consult L<perlxs> and L<perlxstut>.
 
+=head2 Autoloading with XSUBs
+
+If an AUTOLOAD routine is an XSUB, as with Perl subroutines, Perl puts the
+fully-qualified name of the autoloaded subroutine in the $AUTOLOAD variable
+of the XSUB's package.
+
+But it also puts the same information in certain fields of the XSUB itself:
+
+    HV *stash           = CvSTASH(cv);
+    const char *subname = SvPVX(cv);
+    STRLEN name_length  = SvCUR(cv); /* in bytes */
+    U32 is_utf8         = SvUTF8(cv);
+    
+C<SvPVX(cv)> contains just the sub name itself, not including the package.
+
+B<Note>: Setting $AUTOLOAD stopped working in 5.6.1, which did not support
+XS AUTOLOAD subs at all.  Perl 5.8.0 introduced the use of fields in the
+XSUB itself.  Perl 5.16.0 restored the setting of $AUTOLOAD.  If you need
+to support 5.8-5.14, use the XSUB's fields.
+
 =head2 Calling Perl Routines from within C Programs
 
 There are four routines that can be used to call a Perl subroutine from
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 6d034f171f..9aae8ac479 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -1432,8 +1432,8 @@ variable of the same package as the C<AUTOLOAD> routine.  The name
 is not passed as an ordinary argument because, er, well, just
 because, that's why.  (As an exception, a method call to a nonexistent
 C<import> or C<unimport> method is just skipped instead.  Also, if
-the AUTOLOAD subroutine is an XSUB, C<$AUTOLOAD> is not populated;
-see L<perlapi/SvPVX> for details.)
+the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the
+subroutine name.  See L<perlguts/Autoloading with XSUBs> for details.)
 
 
 Many C<AUTOLOAD> routines load in a definition for the requested
diff --git a/sv.h b/sv.h
index 46e53acc29..72cd887026 100644
--- a/sv.h
+++ b/sv.h
@@ -685,10 +685,8 @@ Only use when you are sure SvNOK is true. See also C<SvNV()>.
 Returns a pointer to the physical string in the SV.  The SV must contain a
 string.
 
-During autoloading, if the AUTOLOAD routine is an XSUB, C<SvPVX(cv)>
-returns the name of the subroutine for which AUTOLOAD was invoked.
-Likewise, C<SvCUR(cv)> returns the length, and C<SvUTF8(cv)> returns true
-if the name is in UTF8.
+This is also used to store the name of an autoloaded subroutine in an XS
+AUTOLOAD routine.  See L<perlguts/Autoloading with XSUBs>.
 
 =for apidoc Am|STRLEN|SvCUR|SV* sv
 Returns the length of the string which is in the SV.  See C<SvLEN>.