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 -ttime option-argument, the
corresponding time fields of the file referenced by the -rref_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:
If file does not exist, a creat() function
call is made with the file operand used as the path argument
and the value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, S_IRGRP,
S_IWGRP, S_IROTH, and S_IWOTH used as the mode argument.
The utime() function is called with the following
The file operand is used as the path
The utimbuf structure members actime and
modtime are determined as described in the OPTIONS section.
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:
Change the access time of file. Do not change the
modification time unless -m is also specified.
Do not create a specified file if it does not exist.
Do not write any diagnostic messages concerning this condition.
Change the modification time of file. Do not change
the access time unless -a is also specified.
Use the corresponding time of the file named by the
pathname ref_file instead of the current time.
Use the specified time instead of the current time.
The option-argument shall be a decimal number of the form:
where each two digits represents the following:
The month of the year [01,12].
The day of the month [01,31].
The hour of the day [00,23].
The minute of the hour [00,59].
The first two digits of the year (the
The second two digits of the year.
The second of the minute [00,60].
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:
It is expected that in a future version of
IEEE Std 1003.1-2001 the default century inferred from a 2-digit
year will change. (This would apply to all commands accepting a 2-digit year
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 environment variables shall affect the execution of touch:
Provide a default value for the internationalization
variables that are unset or null. (See the Base Definitions volume of
IEEE Std 1003.1-2001, Section 8.2, Internationalization
Variables for the precedence of internationalization variables used to
determine the values of locale categories.)
If set to a non-empty string value, override the values of
all the other internationalization variables.
Determine the locale for the interpretation of sequences of
bytes of text data as characters (for example, single-byte as opposed to
multi-byte characters in arguments).
Determine the locale that should be used to affect the
format and contents of diagnostic messages written to standard error.
Determine the location of message catalogs for the
processing of LC_MESSAGES.
Determine the timezone to be used for interpreting the
time option-argument. If TZ is unset or null, an unspecified
default timezone shall be used.
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
Although the -ttime 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 -ttime is not specified,
-rref_file is not specified, and the first operand is an eight
or ten-digit decimal number. A portable script can avoid this problem by
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
In System V, an ambiguity exists when a pathname that is a
decimal number leads the operands; it is treated as a time value. In BSD,
no time value is allowed; files may only be touched to the
current time. The -ttime construct solves these problems
for future conforming applications (note that the -t option is not
The inclusion of the century digits, CC, is also
new. Note that a ten-digit time value is treated as if YY,
and not CC, were specified. The caveat about the range of dates
following the Epoch was included as recognition that some implementations
are not able to represent dates beyond 18 January 2038 because they use
signed int as a time holder.
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
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group Standard, the original
IEEE and The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.opengroup.org/unix/online.html