touch [-acm][ -r ref_file| -t time] file...
The touch utility shall change the modification times, access times, or both of files. The modification time shall be equivalent to the value of the st_mtime member of the stat structure for a file, as described in the System Interfaces volume of IEEE Std 1003.1-2001; the access time shall be equivalent to the value of st_atime.
The time used can be specified by the -t time option-argument, the corresponding time fields of the file referenced by the -r ref_file option-argument, or the date_time operand, as specified in the following sections. If none of these are specified, touch shall use the current time (the value returned by the equivalent of the time() function defined in the System Interfaces volume of IEEE Std 1003.1-2001).
For each file operand, touch shall perform actions equivalent to the following functions defined in the System Interfaces volume of IEEE Std 1003.1-2001:
The touch utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported:
[[CC]YY]MMDDhhmm[.SS]
where each two digits represents the following:
Both CC and YY shall be optional. If neither is given, the current year shall be assumed. If YY is specified, but CC is not, CC shall be derived as follows:
| If YY is: | CC becomes: | |||
| [69,99] | 19 | |||
| [00,68] | 20 |
The resulting time shall be affected by the value of the TZ environment variable. If the resulting time value precedes the Epoch, touch shall exit immediately with an error status. The range of valid times past the Epoch is implementation-defined, but it shall extend to at least the time 0 hours, 0 minutes, 0 seconds, January 1, 2038, Coordinated Universal Time. Some implementations may not be able to represent dates beyond January 18, 2038, because they use signed int as a time holder.
The range for SS is [00,60] rather than [00,59] because of leap seconds. If SS is 60, and the resulting time, as affected by the TZ environment variable, does not refer to a leap second, the resulting time shall be one second after a time where SS is 59. If SS is not given a value, it is assumed to be zero.
If neither the -a nor -m options were specified, touch shall behave as if both the -a and -m options were specified.
The following operands shall be supported:
The following environment variables shall affect the execution of touch:
The standard error shall be used only for diagnostic messages.
The following exit values shall be returned:
Default.
The following sections are informative.
The interpretation of time is taken to be seconds since the Epoch (see the Base Definitions volume of IEEE Std 1003.1-2001, Section 4.14, Seconds Since the Epoch). It should be noted that implementations conforming to the System Interfaces volume of IEEE Std 1003.1-2001 do not take leap seconds into account when computing seconds since the Epoch. When SS=60 is used, the resulting time always refers to 1 plus seconds since the Epoch for a time when SS=59.
Although the -t time option-argument specifies values in 1969, the access time and modification time fields are defined in terms of seconds since the Epoch (00:00:00 on 1 January 1970 UTC). Therefore, depending on the value of TZ when touch is run, there is never more than a few valid hours in 1969 and there need not be any valid times in 1969.
One ambiguous situation occurs if -t time is not specified, -r ref_file is not specified, and the first operand is an eight or ten-digit decimal number. A portable script can avoid this problem by using:
touch -- file
or:
touch ./file
The functionality of touch is described almost entirely through references to functions in the System Interfaces volume of IEEE Std 1003.1-2001. In this way, there is no duplication of effort required for describing such side effects as the relationship of user IDs to the user database, permissions, and so on.
There are some significant differences between the touch utility in this volume of IEEE Std 1003.1-2001 and those in System V and BSD systems. They are upwards-compatible for historical applications from both implementations:
The -r option was added because several comments requested this capability. This option was named -f in an early proposal, but was changed because the -f option is used in the BSD version of touch with a different meaning.
At least one historical implementation of touch incremented the exit code if -c was specified and the file did not exist. This volume of IEEE Std 1003.1-2001 requires exit status zero if no errors occur.
Applications should use the -r or -t options.
date , the System Interfaces volume of IEEE Std 1003.1-2001, creat(), time(), utime(), the Base Definitions volume of IEEE Std 1003.1-2001, <sys/stat.h>