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.
If you want portable packed integers you can either use the formats
C<n>, C<N>, C<v>, and C<V>, or you can use the C<E<gt>> and C<E<lt>>
-modifiers. These modifiers are only available as of perl 5.8.5.
+modifiers. These modifiers are only available as of perl 5.9.2.
See also L<perlport>.
=item *
=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
(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
There is no C<systell> function. Use C<sysseek(FH, 0, 1)> for that.
-Do not use tell() on a filehandle that has been opened using
-sysopen(), use sysseek() for that as described above. Why? Because
-sysopen() creates unbuffered, "raw", filehandles, while open() creates
-buffered filehandles. sysseek() make sense only on the first kind,
-tell() only makes sense on the second kind.
+Do not use tell() (or other buffered I/O operations) on a file handle
+that has been manipulated by sysread(), syswrite() or sysseek().
+Those functions ignore the buffering, while tell() does not.
=item telldir DIRHANDLE
and modification times, in that order. Returns the number of files
successfully changed. The inode change time of each file is set
to the current time. For example, this code has the same effect as the
-Unix touch(1) command when the files I<already exist>.
+Unix touch(1) command when the files I<already exist> and belong to
+the user running the program:
#!/usr/bin/perl
$atime = $mtime = time;
the utime(2) function in the C library will be called with a null second
argument. On most systems, this will set the file's access and
modification times to the current time (i.e. equivalent to the example
-above.)
+above) and will even work on other users' files where you have write
+permission:
utime undef, undef, @ARGV;
=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).
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