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

[Nelson H. F. Beebe]

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: address@hidden  -
- 155 S 1400 E RM 233                       address@hidden  address@hidden -
- Salt Lake City, UT 84112-0090, USA    URL: http://www.math.utah.edu/~beebe/ -
-------------------------------------------------------------------------------