Integrate with Sarathy.

p4raw-id: //depot/cfgperl@6140

13 files changed, 262 insertions, 33 deletions

diff --git a/pod/perl56delta.pod b/pod/perl56delta.pod
index 27cdc224ff..5a824ac8e5 100644
--- a/pod/perl56delta.pod
+++ b/pod/perl56delta.pod
@@ -10,7 +10,7 @@ This document describes differences between the 5.005 release and this one.
 
 =head2 Interpreter cloning, threads, and concurrency
 
-Perl 5.005_63 introduces the beginnings of support for running multiple
+Perl 5.6.0 introduces the beginnings of support for running multiple
 interpreters concurrently in different threads.  In conjunction with
 the perl_clone() API call, which can be used to selectively duplicate
 the state of any given interpreter, it is possible to compile a
@@ -375,7 +375,7 @@ problems associated with it.
     NOTE: This is currently an experimental feature.  Interfaces and
     implementation are subject to change.
 
-=item Support for CHECK blocks
+=head2 Support for CHECK blocks
 
 In addition to C<BEGIN>, C<INIT>, C<END>, C<DESTROY> and C<AUTOLOAD>,
 subroutines named C<CHECK> are now special.  These are queued up during
@@ -388,7 +388,7 @@ be called directly.
 For example to match alphabetic characters use /[[:alpha:]]/.
 See L<perlre> for details.
 
-=item Better pseudo-random number generator
+=head2 Better pseudo-random number generator
 
 In 5.005_0x and earlier, perl's rand() function used the C library
 rand(3) function.  As of 5.005_52, Configure tests for drand48(),
@@ -409,7 +409,7 @@ Thus:
 
 now correctly prints "3|a", instead of "2|a".
 
-=item Better worst-case behavior of hashes
+=head2 Better worst-case behavior of hashes
 
 Small changes in the hashing algorithm have been implemented in
 order to improve the distribution of lower order bits in the
@@ -632,7 +632,7 @@ Diagnostic output now goes to whichever file the C<STDERR> handle
 is pointing at, instead of always going to the underlying C runtime
 library's C<stderr>.
 
-=item More consistent close-on-exec behavior
+=head2 More consistent close-on-exec behavior
 
 On systems that support a close-on-exec flag on filehandles, the
 flag is now set for any handles created by pipe(), socketpair(),
@@ -693,7 +693,7 @@ The variable modified by shmread(), and messages returned by msgrcv()
 because other untrusted processes can modify messages and shared memory
 segments for their own nefarious purposes.
 
-=item More functional bareword prototype (*)
+=head2 More functional bareword prototype (*)
 
 Bareword prototypes have been rationalized to enable them to be used
 to override builtins that accept barewords and interpret them in
@@ -760,6 +760,38 @@ with another number.
 This behavior must be specifically enabled when running Configure.
 See F<INSTALL> and F<README.Y2K>.
 
+=head2 Arrays now always interpolate into double-quoted strings
+
+In double-quoted strings, arrays now interpolate, no matter what.  The
+behavior in earlier versions of perl 5 was that arrays would interpolate
+into strings if the array had been mentioned before the string was
+compiled, and otherwise Perl would raise a fatal compile-time error.
+In versions 5.000 through 5.003, the error was
+
+        Literal @example now requires backslash
+
+In versions 5.004_01 through 5.6.0, the error was
+
+        In string, @example now must be written as \@example
+
+The idea here was to get people into the habit of writing
+C<"fred\@example.com"> when they wanted a literal C<@> sign, just as
+they have always written C<"Give me back my \$5"> when they wanted a
+literal C<$> sign.
+
+Starting with 5.6.1, when Perl now sees an C<@> sign in a
+double-quoted string, it I<always> attempts to interpolate an array,
+regardless of whether or not the array has been used or declared
+already.  The fatal error has been downgraded to an optional warning:
+
+        Possible unintended interpolation of @example in string
+        
+This warns you that C<"fred@example.com"> is going to turn into
+C<fred.com> if you don't backslash the C<@>.
+
+See L<http://www.plover.com/~mjd/perl/at-error.html> for more details
+about the history here.
+
 =head1 Modules and Pragmata
 
 =head2 Modules
@@ -1409,7 +1441,7 @@ eliminating redundant copying overheads.
 Minor changes in how subroutine calls are handled internally
 provide marginal improvements in performance.
 
-=item delete(), each(), values() and hash iteration are faster
+=head2 delete(), each(), values() and hash iteration are faster
 
 The hash values returned by delete(), each(), values() and hashes in a
 list context are the actual values in the hash, instead of copies.
@@ -2298,6 +2330,20 @@ when you meant
 
 Remember that "my", "our", and "local" bind tighter than comma.
 
+=item Possible unintended interpolation of %s in string
+
+(W ambiguous) It used to be that Perl would try to guess whether you
+wanted an array interpolated or a literal @.  It no longer does this;
+arrays are now I<always> interpolated into strings.  This means that 
+if you try something like:
+
+        print "fred@example.com";
+
+and the array C<@example> doesn't exist, Perl is going to print
+C<fred.com>, which is probably not what you wanted.  To get a literal
+C<@> sign in a string, put a backslash before it, just as you would
+to get a literal C<$> sign.
+
 =item Possible Y2K bug: %s
 
 (W y2k) You are concatenating the number 19 with another number, which
@@ -2522,7 +2568,7 @@ There is a potential incompatibility in the behavior of list slices
 that are comprised entirely of undefined values.
 See L</"Behavior of list slices is more consistent">.
 
-=head2 Format of $English::PERL_VERSION is different
+=item Format of $English::PERL_VERSION is different
 
 The English module now sets $PERL_VERSION to $^V (a string value) rather
 than C<$]> (a numeric value).  This is a potential incompatibility.
@@ -2647,7 +2693,7 @@ a simple scalar or as a reference to a typeglob.
 
 See L</"More functional bareword prototype (*)">.
 
-=head2 Semantics of bit operators may have changed on 64-bit platforms
+=item Semantics of bit operators may have changed on 64-bit platforms
 
 If your platform is either natively 64-bit or if Perl has been
 configured to used 64-bit integers, i.e., $Config{ivsize} is 8, 
@@ -2661,7 +2707,7 @@ the excess bits in the result of unary C<~>, e.g., C<~$x & 0xffffffff>.
 
 See L</"Bit operators support full native integer width">.
 
-=head2 More builtins taint their results
+=item More builtins taint their results
 
 As described in L</"Improved security features">, there may be more
 sources of taint in a Perl program.
@@ -2891,6 +2937,18 @@ appear in %ENV.  This may be a benign occurrence, as some software packages
 might directly modify logical name tables and introduce nonstandard names,
 or it may indicate that a logical name table has been corrupted.
 
+=item In string, @%s now must be written as \@%s
+
+The description of this error used to say:
+
+        (Someday it will simply assume that an unbackslashed @
+         interpolates an array.)
+
+That day has come, and this fatal error has been removed.  It has been
+replaced by a non-fatal warning instead.
+See L</Arrays now always interpolate into double-quoted strings> for
+details.
+
 =item Probable precedence problem on %s
 
 (W) The compiler found a bareword where it expected a conditional,
diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 58e29515c4..cd467ba8ed 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -165,9 +165,16 @@ the type.  May fail on overlapping copies.  See also C<Move>.
 
 =item croak
 
-This is the XSUB-writer's interface to Perl's C<die> function.  Use this
-function the same way you use the C C<printf> function.  See
-C<warn>.
+This is the XSUB-writer's interface to Perl's C<die> function.
+Normally use this function the same way you use the C C<printf>
+function.  See C<warn>.
+
+If you want to throw an exception object, assign the object to
+C<$@> and then pass C<Nullch> to croak():
+
+   errsv = get_sv("@", TRUE);
+   sv_setsv(errsv, exception_object);
+   croak(Nullch);
 
 	void	croak(const char* pat, ...)
 
@@ -1597,17 +1604,17 @@ false, defined or undefined.  Does not handle 'get' magic.
 
 	bool	SvTRUE(SV* sv)
 
-=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.
-
 =item SvTYPE
 
 Returns the type of the SV.  See C<svtype>.
 
 	svtype	SvTYPE(SV* sv)
 
+=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.
+
 =item SVt_IV
 
 Integer type flag for scalars.  See C<svtype>.
diff --git a/pod/perldebguts.pod b/pod/perldebguts.pod
index 45c33c7ec4..5812a40fcb 100644
--- a/pod/perldebguts.pod
+++ b/pod/perldebguts.pod
@@ -639,7 +639,7 @@ than 32 bytes (all these examples assume 32-bit architectures, the
 result are quite a bit worse on 64-bit architectures).  If a variable
 is accessed in two of three different ways (which require an integer,
 a float, or a string), the memory footprint may increase yet another
-20 bytes.  A sloppy malloc(3) implementation can make inflate these
+20 bytes.  A sloppy malloc(3) implementation can inflate these
 numbers dramatically.
 
 On the opposite end of the scale, a declaration like
@@ -686,7 +686,7 @@ the following example:
   Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
 
 It is possible to ask for such a statistic at arbitrary points in
-your execution using the mstats() function out of the standard
+your execution using the mstat() function out of the standard
 Devel::Peek module.
 
 Here is some explanation of that format:
diff --git a/pod/perldebug.pod b/pod/perldebug.pod
index c8ef60fa45..bccdcf4f51 100644
--- a/pod/perldebug.pod
+++ b/pod/perldebug.pod
@@ -767,6 +767,11 @@ Breakable lines are marked with C<:>.  Lines with breakpoints are
 marked by C<b> and those with actions by C<a>.  The line that's
 about to be executed is marked by C<< ==> >>.
 
+Please be aware that code in debugger listings may not look the same
+as your original source code.  Line directives and external source
+filters can alter the code before Perl sees it, causing code to move
+from its original positions or take on entirely different forms.
+
 =item Frame listing
 
 When the C<frame> option is set, the debugger would print entered (and
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 4e67506e26..f24c1d2ad3 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3426,7 +3426,7 @@ Generalized quotes.  See L<perlop/"Regexp Quote-Like Operators">.
 
 =item quotemeta
 
-Returns the value of EXPR with all non-alphanumeric
+Returns the value of EXPR with all non-"word"
 characters backslashed.  (That is, all characters not matching
 C</[A-Za-z_0-9]/> will be preceded by a backslash in the
 returned string, regardless of any locale settings.)
diff --git a/pod/perlintern.pod b/pod/perlintern.pod
index b0aab33e2b..6d8d67dae0 100644
--- a/pod/perlintern.pod
+++ b/pod/perlintern.pod
@@ -12,6 +12,18 @@ B<they are not for use in extensions>!
 
 =over 8
 
+=item is_gv_magical
+
+Returns C<TRUE> if given the name of a magical GV.
+
+Currently only useful internally when determining if a GV should be
+created even in rvalue contexts.
+
+C<flags> is not used at present but available for future extension to
+allow selecting particular classes of magical variable.
+
+	bool	is_gv_magical(char *name, STRLEN len, U32 flags)
+
 =back
 
 =head1 AUTHORS
diff --git a/pod/perlre.pod b/pod/perlre.pod
index 2db4139c30..a82ab32b73 100644
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -169,7 +169,7 @@ You'll need to write something like C<m/\Quser\E\@\Qhost/>.
 In addition, Perl defines the following:
 
     \w	Match a "word" character (alphanumeric plus "_")
-    \W	Match a non-word character
+    \W	Match a non-"word" character
     \s	Match a whitespace character
     \S	Match a non-whitespace character
     \d	Match a digit character
@@ -180,7 +180,7 @@ In addition, Perl defines the following:
         equivalent to C<(?:\PM\pM*)>
     \C	Match a single C char (octet) even under utf8.
 
-A C<\w> matches a single alphanumeric character, not a whole word.
+A C<\w> matches a single alphanumeric character or C<_>, not a whole word.
 Use C<\w+> to match a string of Perl-identifier characters (which isn't 
 the same as matching an English word).  If C<use locale> is in effect, the
 list of alphabetic characters generated by C<\w> is taken from the
@@ -377,7 +377,7 @@ that looks like \\, \(, \), \<, \>, \{, or \} is always
 interpreted as a literal character, not a metacharacter.  This was
 once used in a common idiom to disable or quote the special meanings
 of regular expression metacharacters in a string that you want to
-use for a pattern. Simply quote all non-alphanumeric characters:
+use for a pattern. Simply quote all non-"word" characters:
 
     $pattern =~ s/(\W)/\\$1/g;
 
diff --git a/pod/perlretut.pod b/pod/perlretut.pod
index 5ff4298012..66f8179ab6 100644
--- a/pod/perlretut.pod
+++ b/pod/perlretut.pod
@@ -344,7 +344,7 @@ become the svelte C<[0-9]> and C<[a-z]>.  Some examples are
     /[0-9bx-z]aa/;  # matches '0aa', ..., '9aa',
                     # 'baa', 'xaa', 'yaa', or 'zaa'
     /[0-9a-fA-F]/;  # matches a hexadecimal digit
-    /[0-9a-zA-Z_]/; # matches an alphanumeric character,
+    /[0-9a-zA-Z_]/; # matches a "word" character,
                     # like those in a perl variable name
 
 If C<'-'> is the first or last character in a character class, it is
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index f1b87923ef..f45f5494f6 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -357,7 +357,7 @@ A compilation error results otherwise.  An inner block may countermand
 this with C<no strict 'vars'>.
 
 A C<my> has both a compile-time and a run-time effect.  At compile
-time, the compiler takes notice of it.  The principle usefulness
+time, the compiler takes notice of it.  The principal usefulness
 of this is to quiet C<use strict 'vars'>, but it is also essential
 for generation of closures as detailed in L<perlref>.  Actual
 initialization is delayed until run time, though, so it gets executed
diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index dfded2ecde..a65b4cd263 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -598,6 +598,11 @@ C</^#\s*line\s+(\d+)\s*(?:\s"([^"]+)")?\s*$/> with C<$1> being the line
 number for the next line, and C<$2> being the optional filename
 (specified within quotes).
 
+There is a fairly obvious gotcha included with the line directive:
+Debuggers and profilers will only show the last source line to appear
+at a particular line number in a given file.  Care should be taken not
+to cause line number collisions in code you'd like to debug later.
+
 Here are some examples that you should be able to type into your command
 shell:
 
diff --git a/pod/perltie.pod b/pod/perltie.pod
index 95de3bb928..49bf98999c 100644
--- a/pod/perltie.pod
+++ b/pod/perltie.pod
@@ -260,6 +260,10 @@ index whose value we're trying to fetch.
       return $self->{ARRAY}[$idx];
     }
 
+If a negative array index is used to read from an array, the index 
+will be translated to a positive one internally by calling FETCHSIZE
+before being passed to FETCH. 
+ 
 As you may have noticed, the name of the FETCH method (et al.) is the same
 for all accesses, even though the constructors differ in names (TIESCALAR
 vs TIEARRAY).  While in theory you could have the same class servicing
@@ -281,6 +285,8 @@ there.  For example:
       }
       return $self->{ARRAY}[$idx] = $value;
     }
+ 
+Negative indexes are treated the same as with FETCH.  
 
 =item DESTROY this
 
diff --git a/pod/perltrap.pod b/pod/perltrap.pod
index c477272abe..3f54edef2b 100644
--- a/pod/perltrap.pod
+++ b/pod/perltrap.pod
@@ -1296,7 +1296,8 @@ within certain expressions, statements, contexts, or whatever.
     print "To: someone@somewhere.com\n";
 
     # perl4 prints: To:someone@somewhere.com
-    # perl5 errors : In string, @somewhere now must be written as \@somewhere
+    # perl < 5.6.1, error : In string, @somewhere now must be written as \@somewhere
+    # perl >= 5.6.1, warning : Possible unintended interpolation of @somewhere in string
 
 =item * Interpolation
 
diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod
index 4756a9edbb..347b46e4f5 100644
--- a/pod/perlxstut.pod
+++ b/pod/perlxstut.pod
@@ -5,8 +5,8 @@ perlXStut - Tutorial for writing XSUBs
 =head1 DESCRIPTION
 
 This tutorial will educate the reader on the steps involved in creating
-a Perl extension.  The reader is assumed to have access to L<perlguts> and
-L<perlxs>.
+a Perl extension.  The reader is assumed to have access to L<perlguts>,
+L<perlapi> and L<perlxs>.
 
 This tutorial starts with very simple examples and becomes more complex,
 with each new example adding new features.  Certain concepts may not be
@@ -187,7 +187,8 @@ been deleted):
 	Manifying ./blib/man3/Mytest.3
 	%
 
-You can safely ignore the line about "prototyping behavior".
+You can safely ignore the line about "prototyping behavior" - it is
+explained in the section "The PROTOTYPES: Keyword" in L<perlxs>.
 
 If you are on a Win32 system, and the build process fails with linker
 errors for functions in the C library, check if your Perl is configured
@@ -1056,9 +1057,143 @@ the stack is I<always> large enough to take one return value.
 
 =back
 
-=head2 EXAMPLE 6 (Coming Soon)
+=head2 EXAMPLE 6
 
-Passing in and returning references to arrays and/or hashes
+In this example, we will accept a reference to an array as an input
+parameter, and return a reference to an array of hashes.  This will
+demonstrate manipulation of complex Perl data types from an XSUB.
+
+This extension is somewhat contrived.  It is based on the code in
+the previous example.  It calls the statfs function multiple times,
+accepting a reference to an array of filenames as input, and returning
+a reference to an array of hashes containing the data for each of the
+filesystems.
+
+Return to the Mytest directory and add the following code to the end of
+Mytest.xs:
+
+	SV *
+	multi_statfs(paths)
+		SV * paths
+	    INIT:
+        	AV * results;
+        	I32 numpaths = 0;
+        	int i, n;
+        	struct statfs buf;
+
+        	if ((!SvROK(paths))
+		    || (SvTYPE(SvRV(paths)) != SVt_PVAV)
+		    || ((numpaths = av_len((AV *)SvRV(paths))) < 0))
+		{
+		    XSRETURN_UNDEF;
+        	}
+        	results = (AV *)sv_2mortal((SV *)newAV());
+	    CODE:
+        	for (n = 0; n <= numpaths; n++) {
+		    HV * rh;
+            	    STRLEN l;
+            	    char * fn = SvPV(*av_fetch((AV *)SvRV(paths), n, 0), l);
+	
+            	    i = statfs(fn, &buf);
+            	    if (i != 0) {
+		        av_push(results, newSVnv(errno));
+		        continue;
+            	    }
+	
+            	    rh = (HV *)sv_2mortal((SV *)newHV());
+	
+            	    hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0);
+            	    hv_store(rh, "f_bfree",  7, newSVnv(buf.f_bfree),  0);
+            	    hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0);
+            	    hv_store(rh, "f_bsize",  7, newSVnv(buf.f_bsize),  0);
+            	    hv_store(rh, "f_ffree",  7, newSVnv(buf.f_ffree),  0);
+            	    hv_store(rh, "f_files",  7, newSVnv(buf.f_files),  0);
+            	    hv_store(rh, "f_type",   6, newSVnv(buf.f_type),   0);
+	
+            	    av_push(results, newRV((SV *)rh));
+        	}
+        	RETVAL = newRV((SV *)results);
+	    OUTPUT:
+        	RETVAL
+
+And add the following code to test.pl, while incrementing the "1..11" 
+string in the BEGIN block to "1..13":
+
+	$results = Mytest::multi_statfs([ '/', '/blech' ]);
+	print ((ref $results->[0]) ? "ok 12\n" : "not ok 12\n");
+	print ((! ref $results->[1]) ? "ok 13\n" : "not ok 13\n");
+
+=head2 New Things in this Example
+
+There are a number of new concepts introduced here, described below:
+
+=over 4
+
+=item *
+
+This function does not use a typemap.  Instead, we declare it as accepting
+one SV* (scalar) parameter, and returning an SV* value, and we take care of
+populating these scalars within the code.  Because we are only returning
+one value, we don't need a C<PPCODE:> directive - instead, we use C<CODE:>
+and C<OUTPUT:> directives.
+
+=item *
+
+When dealing with references, it is important to handle them with caution.
+The C<INIT:> block first checks that
+C<SvROK> returns true, which indicates that paths is a valid reference.  It
+then verifies that the object referenced by paths is an array, using C<SvRV>
+to dereference paths, and C<SvTYPE> to discover its type.  As an added test,
+it checks that the array referenced by paths is non-empty, using the C<av_len>
+function (which returns -1 if the array is empty).  The XSRETURN_UNDEF macro
+is used to abort the XSUB and return the undefined value whenever all three of
+these conditions are not met.
+
+=item *
+
+We manipulate several arrays in this XSUB.  Note that an array is represented
+internally by an AV* pointer.  The functions and macros for manipulating
+arrays are similar to the functions in Perl: C<av_len> returns the highest
+index in an AV*, much like $#array; C<av_fetch> fetches a single scalar value
+from an array, given its index; C<av_push> pushes a scalar value onto the
+end of the array, automatically extending the array as necessary.
+
+Specifically, we read pathnames one at a time from the input array, and
+store the results in an output array (results) in the same order.  If
+statfs fails, the element pushed onto the return array is the value of
+errno after the failure.  If statfs succeeds, though, the value pushed
+onto the return array is a reference to a hash containing some of the
+information in the statfs structure.
+
+As with the return stack, it would be possible (and a small performance win)
+to pre-extend the return array before pushing data into it, since we know
+how many elements we will return:
+
+	av_extend(results, numpaths);
+
+=item *
+
+We are performing only one hash operation in this function, which is storing
+a new scalar under a key using C<hv_store>.  A hash is represented by an HV*
+pointer.  Like arrays, the functions for manipulating hashes from an XSUB
+mirror the functionality available from Perl.  See L<perlguts> and L<perlapi>
+for details.
+
+=item *
+
+To create a reference, we use the C<newRV> function.  Note that you can
+cast an AV* or an HV* to type SV* in this case (and many others).  This
+allows you to take references to arrays, hashes and scalars with the same
+function.  Conversely, the C<SvRV> function always returns an SV*, which may
+need to be be cast to the appropriate type if it is something other than a
+scalar (check with C<SvTYPE>).
+
+=item *
+
+At this point, xsubpp is doing very little work - the differences between
+Mytest.xs and Mytest.c are minimal.
+
+=back
 
 =head2 EXAMPLE 7 (Coming Soon)
 
@@ -1112,7 +1247,7 @@ Some systems may have installed Perl version 5 as "perl5".
 
 =head1 See also
 
-For more information, consult L<perlguts>, L<perlxs>, L<perlmod>,
+For more information, consult L<perlguts>, L<perlapi>, L<perlxs>, L<perlmod>,
 and L<perlpod>.
 
 =head1 Author