Re: [perl #31924] %INC caching failure-case problem

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

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 211bdc8..dec40d7 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -614,7 +614,7 @@ false otherwise. See the example under C<die>.
 
 Changes the permissions of a list of files.  The first element of the
 list must be the numerical mode, which should probably be an octal
-number, and which definitely should I<not> a string of octal digits:
+number, and which definitely should I<not> be a string of octal digits:
 C<0644> is okay, C<'0644'> is not.  Returns the number of files
 successfully changed.  See also L</oct>, if all you have is a string.
 
@@ -3828,9 +3828,14 @@ array in subroutines, just like C<shift>.
 =item pos
 
 Returns the offset of where the last C<m//g> search left off for the variable
-in question (C<$_> is used when the variable is not specified).  May be
-modified to change that offset.  Such modification will also influence
-the C<\G> zero-width assertion in regular expressions.  See L<perlre> and
+in question (C<$_> is used when the variable is not specified).  Note that
+0 is a valid match offset, while C<undef> indicates that the search position
+is reset (usually due to match failure, but can also be because no match has
+yet been performed on the scalar). C<pos> directly accesses the location used
+by the regexp engine to store the offset, so assigning to C<pos> will change
+that offset, and so will also influence the C<\G> zero-width assertion in
+regular expressions. Because a failed C<m//gc> match doesn't reset the offset,
+the return from C<pos> won't change either in this case.  See L<perlre> and
 L<perlop>.
 
 =item print FILEHANDLE LIST
@@ -5464,9 +5469,9 @@ meanings of the fields:
 
 (The epoch was at 00:00 January 1, 1970 GMT.)
 
-(*) The ctime field is non-portable.  In particular, you cannot expect
-it to be a "creation time", see L<perlport/"Files and Filesystems">
-for details.
+(*) Not all fields are supported on all filesystem types. Notably, the
+ctime field is non-portable.  In particular, you cannot expect it to be a
+"creation time", see L<perlport/"Files and Filesystems"> for details.
 
 If C<stat> is passed the special filehandle consisting of an underline, no
 stat is done, but the current contents of the stat structure from the
@@ -6726,7 +6731,7 @@ and for other examples.
 =item wantarray
 
 Returns true if the context of the currently executing subroutine or
-eval() block is looking for a list value.  Returns false if the context is
+C<eval> is looking for a list value.  Returns false if the context is
 looking for a scalar.  Returns the undefined value if the context is
 looking for no value (void context).
 
@@ -6734,6 +6739,10 @@ looking for no value (void context).
     my @a = complex_calculation();
     return wantarray ? @a : "@a";
 
+C<wantarray()>'s result is unspecified in the top level of a file,
+in a C<BEGIN>, C<CHECK>, C<INIT> or C<END> block, or in a C<DESTROY>
+method.
+
 This function should have been named wantlist() instead.
 
 =item warn LIST