Integrate:

[ 21523]
Subject: [PATCH] utime documentation
Message-Id: <lrekx4jfq0.fsf@caliper.activestate.com>
p4raw-link: @21523 on //depot/perl: 2c21a326619911d05e8626e425f90895ef6d740e

p4raw-id: //depot/maint-5.8/perl@21525
p4raw-integrated: from //depot/perl@21524 'merge in' pod/perlfunc.pod
	(@21417..)

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 04eb899..36b7f96 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -6258,12 +6258,8 @@ 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;
-
-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.
+    $atime = $mtime = time;
+    utime $atime, $mtime, @ARGV;
 
 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
@@ -6273,6 +6269,17 @@ above.)
 
     utime undef, undef, @ARGV;
 
+Under NFS this will use 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.  The Unix
+touch(1) command will in fact normally use this form instead of the
+one shown in the first example.
+
+Note that only passing one of the first two elements as C<undef> will
+be equivalent of passing it as 0 and will not have the same effect as
+described when they are both C<undef>.  This case will also trigger an
+uninitialized warning.
+
 =item values HASH
 
 Returns a list consisting of all the values of the named hash.