perlartistic and perlgpl reformatting from Sean Burke.

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

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index d3eb002..b538701 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -246,11 +246,11 @@ L<perlport> and other available platform-specific documentation.
 
 =over 8
 
-=item I<-X> FILEHANDLE
+=item -X FILEHANDLE
 
-=item I<-X> EXPR
+=item -X EXPR
 
-=item I<-X>
+=item -X
 
 A file test, where X is one of the letters listed below.  This unary
 operator takes one argument, either a filename or a filehandle, and
@@ -429,6 +429,8 @@ modulo the caveats given in L<perlipc/"Signals">.
        # didn't
     }
 
+For more information see L<perlipc>.
+
 =item atan2 Y,X
 
 Returns the arctangent of Y/X in the range -PI to PI.
@@ -790,9 +792,6 @@ filehandle, usually the real filehandle name.
 Closes a directory opened by C<opendir> and returns the success of that
 system call.
 
-DIRHANDLE may be an expression whose value can be used as an indirect
-dirhandle, usually the real dirhandle name.
-
 =item connect SOCKET,NAME
 
 Attempts to connect to a remote socket, just as the connect system call
@@ -2757,11 +2756,11 @@ FILEHANDLE.
 (The following is a comprehensive reference to open(): for a gentler
 introduction you may consider L<perlopentut>.)
 
-If FILEHANDLE is an undefined lexical (C<my>) variable the variable is
-assigned a reference to a new anonymous filehandle, otherwise if
-FILEHANDLE is an expression, its value is used as the name of the real
-filehandle wanted.  (This is considered a symbolic reference, so C<use
-strict 'refs'> should I<not> be in effect.)
+If FILEHANDLE is an undefined scalar variable (or array or hash element)
+the variable is assigned a reference to a new anonymous filehandle,
+otherwise if FILEHANDLE is an expression, its value is used as the name of
+the real filehandle wanted.  (This is considered a symbolic reference, so
+C<use strict 'refs'> should I<not> be in effect.)
 
 If EXPR is omitted, the scalar variable of the same name as the
 FILEHANDLE contains the filename.  (Note that lexical variables--those
@@ -3089,6 +3088,10 @@ See L</seek> for some details about mixing reading and writing.
 
 Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
 C<seekdir>, C<rewinddir>, and C<closedir>.  Returns true if successful.
+DIRHANDLE may be an expression whose value can be used as an indirect
+dirhandle, usually the real dirhandle name.  If DIRHANDLE is an undefined
+scalar variable (or array or hash element), the variable is assigned a
+reference to a new anonymous dirhandle.
 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
 =item ord EXPR
@@ -3833,6 +3836,21 @@ operator is discussed in more detail in L<perlop/"I/O Operators">.
     $line = <STDIN>;
     $line = readline(*STDIN);          # same thing
 
+If readline encounters an operating system error, C<$!> will be set with the
+corresponding error message.  It can be helpful to check C<$!> when you are
+reading from filehandles you don't trust, such as a tty or a socket.  The
+following example uses the operator form of C<readline>, and takes the necessary
+steps to ensure that C<readline> was successful.
+
+    for (;;) {
+        undef $!;
+        unless (defined( $line = <> )) {
+            die $! if $!;
+            last; # reached EOF
+        }
+        # ...
+    }
+
 =item readlink EXPR
 
 =item readlink
@@ -4721,13 +4739,13 @@ If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
 past the end of the array, perl issues a warning, and splices at the
 end of the array.
 
-The following equivalences hold (assuming C<$[ == 0>):
+The following equivalences hold (assuming C<< $[ == 0 and $#a >= $i >> )
 
     push(@a,$x,$y)     splice(@a,@a,0,$x,$y)
     pop(@a)            splice(@a,-1)
     shift(@a)          splice(@a,0,1)
     unshift(@a,$x,$y)  splice(@a,0,0,$x,$y)
-    $a[$x] = $y                splice(@a,$x,1,$y)
+    $a[$i] = $y                splice(@a,$i,1,$y)
 
 Example, assuming array lengths are passed before arrays:
 
@@ -6132,17 +6150,22 @@ Changes the access and modification times on each file of a list of
 files.  The first two elements of the list must be the NUMERICAL access
 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.  This code has the same effect as the C<touch>
-command if the files already exist:
+to the current time.  For example, this code has the same effect as the
+Unix touch(1) command when the files I<already exist>.
 
     #!/usr/bin/perl
     $now = time;
     utime $now, $now, @ARGV;
 
-If the first two elements of the list are C<undef>, then 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.)
+B<Note:>  Under NFS, touch(1) uses the time of the NFS server, not
+the time of the local machine.  If there is a time synchronization
+problem, the NFS server and local machine will have different times.
+
+Since perl 5.7.2, if the first two elements of the list are C<undef>, then
+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.)
 
     utime undef, undef, @ARGV;