Updated: 2025/Nov/16
Please read Privacy Policy. It's for your privacy.
TOUCH(1) General Commands Manual TOUCH(1)
NAME
touch - change file access and modification times
SYNOPSIS
touch [-acDfhm] [-d posix-datetime|human-datetime]
[--date posix-datetime|human-datetime] [-R ref-file] [-r ref-file]
[--reference ref-file] [-t datetime] file ...
DESCRIPTION
The touch utility changes either or both of the access and modification
times of the files to the time specified by the options, described below,
or to the current time of day, if none of those options is present. If
the file doesn't exist, it is first created with default permissions.
The following options are available:
-a Change the access time of the file. The modification time of
the file is not changed unless the -m flag is also specified.
-c Do not create the file if it does not exist. The touch
utility does not treat this as an error. No error messages
are displayed and the exit value is not affected.
-D Do not attempt to adjust a file's times if they are already
set to the values specified.
-d posix-datetime
-d human-datetime
--date posix-datetime
--date human-datetime
Attempt to parse the arg posix-datetime as a POSIX time
string "CCYY-MM-DDThh:mm:ss[.frac][Z]" where the minus (or
hyphen) (`-') and colon (`:') characters are literals, and:
⊕ CCYY represents a 4 (or more) digit year number,
⊕ MM represents a 2 digit month number (1-12),
⊕ DD represents a 2 digit day of the month (1-31),
⊕ T represents either the character `T' or a single space
character (in which case the space, at least, may need to
be quoted to the shell to avoid the arg being split into
two words),
⊕ hh represents a 2 digit hour of the day (00-23),
⊕ mm represents a 2 digit minute of the hour (00-59),
⊕ ss represents a 2 digit second of the minute (00-60)
where 60 indicates the occurrence of a leap second, which
POSIX systems ignore, resulting in the following second
being generated instead (:00 of the next minute),
⊕ .frac represents optional factional seconds, where the
`.' can be a period (`.') or a comma (`,') and frac gives
one or more digits, interpreted as if in a floating-point
representation of the seconds, so ".3" represents three
tenths of a second, and ",17" represents seventeen
hundredths of a second, etc. Note that if the period or
comma is given, there must be at least one following
digit. If no fraction of a second is to be specified,
also omit the period (or comma). If omitted, the
fractional seconds are set to 0, so specifying ".0" or
",0" is identical to omitting the .frac field entirely,
⊕ Z represents an optional literal `Z' character,
indicating the the time given is to be considered as a
Co-ordinated Universal Time (UTC) value. If omitted, the
time is considered as being in the local timezone, as
specified by the TZ environment variable.
Note that parsing of this string is quite strict. If
successfully parsed, the time to set will be that specified
by this string.
If the attempt to parse the string as a posix-datetime fails,
then touch will attempt to parse it as a human-datetime using
the human datetime parser parsedate(3), and use the result as
the time to set.
-f This flag has no effect; it is accepted for compatibility
reasons.
-h If a file is a symbolic link, the access and/or modification
time of the link is changed. This option implies -c.
-m Change the modification time of the file. The access time of
the file is not changed unless the -a flag is also specified.
-R ref-file
-r ref-file
--reference ref-file
Use the access and modification times, as appropriate for the
operation being performed, from ref-file instead of the
current time of day. If the ref-file is a symbolic link,
then if the -R form of this option was used, the times are
taken from the symbolic link itself, otherwise the times are
taken from the file referenced by it. If ref-file is not a
symbolic link, all three forms are identical.
-t datetime
Change the access and modification times of the file(s) to
the specified datetime. The argument datetime should be in
the form "[[CC]YY]MMDDhhmm[.ss]" where each pair of letters
represents exactly 2 decimal digits, with the following
interpretations:
CC The first two digits of the year (the century).
YY The second two digits of the year. If "YY" is
specified, but "CC" is not, a value for "YY"
between 69 and 99 (inclusive) results in a "CC"
value of 19. Otherwise, a "CC" value of 20 is
used.
MM The month of the year, from 1 to 12.
DD The day of the month, from 1 to 31.
hh The hour of the day, from 0 to 23.
mm The minute of the hour, from 0 to 59.
ss The second of the minute, from 0 to 60
(permitting 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 is one second after
a time where ss is 59. If ss is not given a
value, it is assumed to be zero, and the
preceding period (`.') must be omitted.
If the "CC" and "YY" letter pairs are not specified, the
values default to the current year. If the "ss" letter pair
(and the preceding period) is not specified, the value
defaults to 0. As an extension to the standard, any of the
"MM", "DD", and "hh" fields may also be omitted, defaulting
to the current time of day, but once any one of these letter
pairs is given, all the following ones (except ".ss") are
required. Fields must always be specified as 2 digits, even
when the value is less than 10. Leading zeroes do not cause
the value to be treated as octal, all conversions use decimal
numbers.
The -d, -R, -r, and -t options are (nominally) mutually exclusive. If
more than one of these options is present, each will be evaluated, and
may cause an error, then the result from the last one specified is used.
The options which specify any part of the time (-d, -R, -r, -t) apply to
both the access and modification times (with -r and -R obtaining those
values independently from the ref-file), though which is actually applied
depends upon the -a and -m options.
ENVIRONMENT
TZ The time zone to be used for interpreting the datetime argument of
the -t option, and the default zone for the posix-datetime or
human-datetime argument of the -d option.
EXAMPLES
touch -h -r path path
If path is a symbolic link, this will set the symbolic link's access and
modify timestamps identical to those of the file to which it refers. If
path is not a symbolic link, this will simply update the "inode changed"
time ("ctime") of the path file to the current time of day.
touch -Dh -d human-datetime -t CCYYMMDDhhmm.ss -R file file
Provided file exists, this parses the human-datetime and CCYYMMDDhhmm.ss
arguments, verifying that they would be suitable for use with touch, then
does nothing, as the final time specification (-R) specifies to take the
times from file and apply them to file itself, changing nothing, which
the -D option then prevents from actually occurring. That is, this
merely tests that the human-datetime and datetime arguments to -d and -t
respectively are valid, and could be used to specify a time. Use of both
-h and -R means this works if file is a symbolic link, even one which
does not reference an existing file, as well as if it is some other file
type. Use of -R requires that file exists, though if it does not, and an
error is generated for that reason, the -d and -t arguments would have
already been successfully processed.
touch -m -d '-1 day' somefile
Set the modify time for somefile to one day (24 hours) earlier than the
current time.
EXIT STATUS
The touch utility exits 0 on success, and >0 if an error occurs.
COMPATIBILITY
The obsolescent form of touch, where a time format is specified as the
first argument, is supported. When none of the time setting options is
specified, there are at least two arguments, and the first argument is a
string of digits which is either eight or ten characters in length, the
first argument is interpreted as a time specification of the form
"MMDDhhmm[YY]" and applied to the remaining arguments interpreted as path
names.
The "MM", "DD", "hh" and "mm" letter pairs are treated as their
counterparts specified to the -t option, except that none of these are
optional. If the "YY" letter pair is present, it is interpret the same
as "YY" in the -t option with no "CC" specified, however here it appears
last, rather than first. There are no equivalents to the "CC" or "ss"
fields of -t and the fractional seconds field is always set to zero.
SEE ALSO
utimes(2), parsedate(3)
FUTURE PLANNING
Sometime in the middle of the 21st century, the default "CC" used in
formats where that information is not present, or where those digits are
not given, will be altered to make low year numbers represent the 22nd
century, and high years the 21st century. The boundary between low and
high is also expected to change. To avoid issues, always use formats
which include the "CC" field, and always use it when "YY" is given.
STANDARDS
The touch utility is expected to be a superset of the IEEE Std 1003.2
("POSIX.2") and IEEE Std 1003.1-2008 ("POSIX.1") specifications.
HISTORY
A touch utility appeared in Version 7 AT&T UNIX.
NetBSD 11.99 February 10, 2024 NetBSD 11.99