NAME

touch — change file access and modification times

SYNOPSIS

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

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.

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.

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.