touch invocation (GNU Coreutils 9.0)
Previous: chmod invocation, Up: Changing file attributes [Contents][Index]
13.4 touch: Change file timestamps
touch
changes the access and/or modification timestamps of the specified files. Synopsis:
touch [option]… file…
Any file
argument that does not exist is created empty, unless option --no-create
(-c
) or --no-dereference
(-h
) was in effect.
A file
argument string of ‘-
’ is handled specially and causes touch
to change the times of the file associated with standard output.
By default, touch
sets file timestamps to the current time. Because touch
acts on its operands left to right, the resulting timestamps of earlier and later operands may disagree.
When setting file timestamps to the current time, 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 timestamps are being set to the current time.
The touch
command cannot set a file’s status change timestamp to a user-specified value, and cannot change the file’s birth time (if supported) at all. Also, touch
has issues similar to those affecting all programs that update file timestamps. For example, touch
may set a file’s timestamp to a value that differs slightly from the requested time. See File timestamps.
Timestamps assume the time zone rules specified by the TZ
environment variable, or by the system default rules if TZ
is not set. See Specifying the Time Zone with TZ in The GNU C Library Reference Manual. You can avoid ambiguities during daylight saving transitions by using UTC timestamps.
The program accepts the following options. Also see Common options.
- ‘
-a
’
‘--time=atime
’
‘--time=access
’
‘--time=use
’ Change the access timestamp only. See File timestamps.
- ‘
-c
’
‘--no-create
’ Do not warn about or create files that do not exist.
- ‘
-d time
’
‘--date=time
’ Use
time
instead of the current time. It can contain month names, time zones, ‘am
’ and ‘pm
’, ‘yesterday
’, etc. For example,--date="2020-07-21 14:19:13.489392193 +0530"
specifies the instant of time that is 489,392,193 nanoseconds after July 21, 2020 at 2:19:13 PM in a time zone that is 5 hours and 30 minutes east of UTC. See Date input formats. File systems that do not support high-resolution timestamps silently ignore any excess precision here.- ‘
-f
’ Ignored; for compatibility with BSD versions of
touch
.- ‘
-h
’
‘--no-dereference
’ Attempt to change the timestamps of a symbolic link, rather than what the link refers to. When using this option, empty files are not created, but option
-c
must also be used to avoid warning about files that do not exist. Not all systems support changing the timestamps of symlinks, since underlying system support for this action was not required until POSIX 2008. Also, on some systems, the mere act of examining a symbolic link changes the access timestamp, such that only changes to the modification timestamp will persist long enough to be observable. When coupled with option-r
, a reference timestamp is taken from a symbolic link rather than the file it refers to.- ‘
-m
’
‘--time=mtime
’
‘--time=modify
’ Change the modification timestamp only.
- ‘
-r file
’
‘--reference=file
’ Use the times of the reference
file
instead of the current time. If this option is combined with the--date=time
(-d time
) option, the referencefile
’s time is the origin for any relativetime
s given, but is otherwise ignored. For example, ‘-r foo -d '-5 seconds'
’ specifies a timestamp equal to five seconds before the corresponding timestamp forfoo
. Iffile
is a symbolic link, the reference timestamp is taken from the target of the symlink, unless-h
was also in effect.- ‘
-t [[cc]yy]mmddhhmm[.ss]
’ Use the argument (optional four-digit or two-digit years, months, days, hours, minutes, optional seconds) instead of the current time. If the year is specified with only two digits, then
cc
is 20 for years in the range 0 … 68, and 19 for years in 69 … 99. If no digits of the year are specified, the argument is interpreted as a date in the current year. On the atypical systems that support leap seconds,ss
may be ‘60
’.
On systems predating POSIX 1003.1-2001, touch
supports an obsolete syntax, as follows. If no timestamp is given with any of the -d
, -r
, or -t
options, and if there are two or more file
s and the first file
is of the form ‘mmddhhmm[yy]
’ and this would be a valid argument to the -t
option (if the yy
, if any, were moved to the front), and if the represented year is in the range 1969–1999, that argument is interpreted as the time for the other files instead of as a file name. Although this obsolete behavior can be controlled with the _POSIX2_VERSION
environment variable (see Standards conformance), portable scripts should avoid commands whose behavior depends on this variable. For example, use ‘touch ./12312359 main.c
’ or ‘touch -t 12312359 main.c
’ rather than the ambiguous ‘touch 12312359 main.c
’.
An exit status of zero indicates success, and a nonzero value indicates failure.
Previous: chmod invocation, Up: Changing file attributes [Contents][Index]