GNU bug report logs - #7999
[coreutils-8.x] documentation of touch command needs clarification

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 7999 in the body.
You can then email your comments to 7999 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Nelson H. F. Beebe" <beebe <at> math.utah.edu>
To: bug-coreutils <at> gnu.org
Cc: beebe <at> math.utah.edu
Subject: [coreutils-8.x] documentation of touch command needs clarification
Date: Mon, 7 Feb 2011 16:36:46 -0700 (MST)

Examination of the info documention for the coreutils-8.x
implementation of the touch command, and the POSIX (IEEE Std
1003.1-2001), does not make clear exactly what time is used when the
argument files exist, and no time specifier (-r or -t option) is
supplied.

For example,

	touch first second .... umpteenth

If the files do not exist, then POSIX says

35294               1. If file does not exist, a creat( ) function call is made with the file operand used as the path
35295                    argument and the value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, S_IRGRP,
35296                    S_IWGRP, S_IROTH, and S_IWOTH used as the mode argument.

That implies that each newly-created file gets the time of its
creation, so the timestamps should be expected to differ if the clock
resolution is not too coarse.

However, if the files already exist, what happens?  Should the files
all get the same timestamp, or the timestamp in effect when the touch
of that file actually occurred?

If I want to guarantee identical timestamps, am I forced to use a
temporary reference file, perhaps like this?

	touch /tmp/TIMESTAMP.$$
	touch -r /tmp/TIMESTAMP.$$ first second ... umpteenth
	rm -f /tmp/TIMESTAMP.$$

Perhaps the coreutils manual page and info documentation could be
updated to document what that implementation does, and discuss whether
it agrees or differs from other implementations (and POSIX).

Because file timestamps are used heavily by commands like "make" and
"rsync", it can be important to know how the touch command does its
job.

An experiment on SGI IRIX (a system with microsecond-resolution
timestamps) with coreutils-7.5 shows that the touch command from that
release has a new time for each file:

	% /usr/local/bin/touch /tmp/fee.{`seq -s , 1000 2000`}
	% /usr/local/bin/touch /tmp/fee.{`seq -s , 1000 2000`}
	% stat /tmp/fee.?000
	  File: `/tmp/fee.1000'
	...
	Access: 2011-02-07 16:27:07.332753000 -0700
	...
	  File: `/tmp/fee.2000'
	...
	Access: 2011-02-07 16:27:09.934987800 -0700


Similar behavior is found with coreutils-8.9 on NetBSD IA-32 and Sun
Solaris SPARC.

-------------------------------------------------------------------------------
- Nelson H. F. Beebe                    Tel: +1 801 581 5254                  -
- University of Utah                    FAX: +1 801 581 4148                  -
- Department of Mathematics, 110 LCB    Internet e-mail: beebe <at> math.utah.edu  -
- 155 S 1400 E RM 233                       beebe <at> acm.org  beebe <at> computer.org -
- Salt Lake City, UT 84112-0090, USA    URL: http://www.math.utah.edu/~beebe/ -
-------------------------------------------------------------------------------

Message #8 received at 7999 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: "Nelson H. F. Beebe" <beebe <at> math.utah.edu>
Cc: 7999 <at> debbugs.gnu.org
Subject: Re: bug#7999: [coreutils-8.x] documentation of touch command needs
	clarification
Date: Mon, 07 Feb 2011 21:37:15 -0800

On 02/07/2011 03:36 PM, Nelson H. F. Beebe wrote:
> Perhaps the coreutils manual page and info documentation could be
> updated to document what that implementation does, and discuss whether
> it agrees or differs from other implementations (and POSIX).

If A and B both exist, then "touch A B" might set A's time stamp
to be earlier than B's, or later than B's, or they might
be set to exactly the same time.  POSIX doesn't say, and I suspect that
for efficiency reasons coreutils's documentation shouldn't say
either (except perhaps to say that it doesn't say :-).

The same thing is true, in general, for other coreutils
applications.  For example, "cat A B" might set A's
last-access time to be less than B's, or greater than B's,
or equal to B's.

Message #11 received at 7999 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: "Nelson H. F. Beebe" <beebe <at> math.utah.edu>
Cc: 7999 <at> debbugs.gnu.org
Subject: Re: bug#7999: [coreutils-8.x] documentation of touch command needs
	clarification
Date: Tue, 08 Feb 2011 08:22:31 -0700

[Message part 1 (text/plain, inline)]

On 02/07/2011 04:36 PM, Nelson H. F. Beebe wrote:
> If I want to guarantee identical timestamps, am I forced to use a
> temporary reference file, perhaps like this?
> 
> 	touch /tmp/TIMESTAMP.$$
> 	touch -r /tmp/TIMESTAMP.$$ first second ... umpteenth
> 	rm -f /tmp/TIMESTAMP.$$

Yes, if you want guaranteed equivalence in timestamps, you must use a
reference file.

On 02/07/2011 10:37 PM, Paul Eggert wrote:
> On 02/07/2011 03:36 PM, Nelson H. F. Beebe wrote:
>> Perhaps the coreutils manual page and info documentation could be
>> updated to document what that implementation does, and discuss whether
>> it agrees or differs from other implementations (and POSIX).
>
> If A and B both exist, then "touch A B" might set A's time stamp
> to be earlier than B's, or later than B's, or they might
> be set to exactly the same time.  POSIX doesn't say, and I suspect that
> for efficiency reasons coreutils's documentation shouldn't say
> either (except perhaps to say that it doesn't say :-).

Well, POSIX generally states that arguments are process left-to-right,
so A should be processed before B.  However, depending on whether time
was cached when touch first started, or updated for each file touched,
affects whether A < B or A == B.  Then there's the matter of multiple
mount points, where different precision between mount points (or even
differing NFS clocks) can indeed lead to B > A, without any loss of
generality (since POSIX is silent on the matter of intra-file relations
within a single touch invocation).

-- 
Eric Blake   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Message #16 received at 7999-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: "Nelson H. F. Beebe" <beebe <at> math.utah.edu>
Cc: 7999-done <at> debbugs.gnu.org
Subject: Re: bug#7999: [coreutils-8.x] documentation of touch command needs
	clarification
Date: Mon, 12 Dec 2011 16:59:39 -0800

I installed the following patch to try to document this issue better
and am taking the liberty of marking this as done.  Further comments
are welcome (and we can reopen the bug as needed).

doc: document 'touch' and timestamps better
* doc/coreutils.texi (touch invocation): Explain file timestamps
better.  Problem reported by Nelson H.F. Beebe (Bug#7999).
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 369fad2..c26a53d 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -7199,6 +7199,7 @@ a date like @samp{Mar 30@ @ 2002} for non-recent timestamps, and a
 date-without-year and time like @samp{Mar 30 23:45} for recent timestamps.
 This format can change depending on the current locale as detailed below.

+@cindex clock skew
 A timestamp is considered to be @dfn{recent} if it is less than six
 months old, and is not dated in the future.  If a timestamp dated
 today is not listed in recent form, the timestamp is in the future,
@@ -10261,11 +10262,39 @@ A @var{file} argument string of @samp{-} is handled specially and
 causes @command{touch} to change the times of the file associated with
 standard output.

+@cindex clock skew
+By default, @command{touch} sets file timestamps to the current time.
+Because @command{touch} acts on its operands left to right, the
+resulting timestamps of earlier and later operands may disagree.
+Also, the determination of what time is ``current'' depends on the
+platform.  Platforms with network file systems often use different
+clocks for the operating system and for file systems; because
+@command{touch} typically uses file systems' clocks by default, clock
+skew can cause the resulting file timestamps to appear to be in a
+program's ``future'' or ``past''.
+
+@cindex file timestamp resolution
+The @command{touch} command sets the file's timestamp to the greatest
+representable value that is not greater than the requested time.  This
+can differ from the requested time for several reasons.  First, the
+requested time may have a higher resolution than supported.  Second, a
+file system may use different resolutions for different types of
+times.  Third, file timestamps may use a different resolution than
+operating system timestamps.  Fourth, the operating system primitives
+used to update timestamps may employ yet a different resolution.  For
+example, in theory a file system might use 10-microsecond resolution
+for access time and 100-nanosecond resolution for modification time,
+and the operating system might use nanosecond resolution for the
+current time and microsecond resolution for the primitive that
+@command{touch} uses to set a file's timestamp to an arbitrary value.
+
 @cindex permissions, for changing file timestamps
-If changing both the access and modification times to the current
-time, @command{touch} can change the timestamps for files that the user
-running it does not own but has write permission for.  Otherwise, the
-user must own the files.
+When setting file timestamps to the current time, @command{touch} can
+change the timestamps for files that the user does not own but has
+write permission for.  Otherwise, the user must own the files.  Some
+older systems have a further restriction: the user must own the files
+unless both the access and modification times are being set to the
+current time.

 Although @command{touch} provides options for changing two of the times---the
 times of last access and modification---of a file, there is actually

Message #19 received at 7999 <at> debbugs.gnu.org (full text, mbox):

From: Jim Meyering <jim <at> meyering.net>
To: 7999 <at> debbugs.gnu.org
Cc: eggert <at> cs.ucla.edu
Subject: Re: bug#7999: [coreutils-8.x] documentation of touch command needs
	clarification
Date: Tue, 13 Dec 2011 08:09:40 +0100

Paul Eggert wrote:
> I installed the following patch to try to document this issue better
> and am taking the liberty of marking this as done.  Further comments
> are welcome (and we can reopen the bug as needed).

Nice.  Thanks!

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.