touch, settime - change file access and modification times
/usr/bin/touch [-acmR] [-r ref_file | -t time | -d date_time] file...
/usr/bin/touch [-acmR] [time_spec] file...
/usr/xpg7/bin/touch [-acmR] [-r ref_file | -t time | -d date_time] file...
/usr/bin/settime [-f ref_file] [time_spec] file...
The touch and settime utilities set the access and modification times of each file. The touch utility creates the file operand if it does not already exist. The settime utility does not create new files.
The time used by the touch utility can be specified by -t time, by -d date_time, or by the corresponding time fields of the file referenced by -r ref_file. The /usr/bin/touch utility also accepts a time_spec operand, though this is deprecated in favor of the previously named options. The time used by the settime utility can be specified by the corresponding time fields of the file referenced by -f ref_file, or by the time_spec operand. If none of these are specified, these utilities use the current time.
If neither the -a nor -m options are specified, touch updates both the modification and access times.
A user with write access to a file, but who is not the owner of the file and does not have the PRIV_FILE_OWNER privilege, can change the modification and access times of that file only to the current time. Attempts to set a specific time results in an error.
The settime utility is equivalent to touch -c with a different syntax.
The following options are supported for the touch utility:
Changes the access time of file. Does not change the modification time unless -m is also specified.
Does not create a specified file if it does not exist. Does not write any diagnostic messages concerning this condition.
Uses the specified date_time instead of the current time. The option-argument must be a string of the form:
YYYY-MM-DDThh:mm:SS[.frac][tz]
or
YYYY-MM-DDThh:mm:SS[,frac][tz]
where
YYYY is at least four decimal digits giving the year
MM, DD, hh, mm, and SS are as described with -t time
T is either the letter T or a single SPACE character
[.frac] and [,frac] are either empty, or a period (.) or a comma (,) respectively, followed by one or more decimal digits, specifying a fractional second
[tz] is either empty, signifying local time, or the letter Z, signifying UTC. If [tz] is empty, the resulting time is affected by the value of the TZ environment variable
Changes the modification time of file. Does not change the access time unless -a is also specified.
Uses the corresponding times of the file named by ref_file instead of the current time.
Uses the specified time instead of the current time. time is a decimal number of the form:
[[CC]YY] MMDDhhmm[.SS]
where each two digits represent 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 second two digits of the year.
The second of the minute [00-61].
Both CC and YY are optional. If neither is given, the current year is assumed. If YY is specified, but CC is not, CC is derived as follows:
|
The resulting time is affected by the value of the TZ environment variable. Times before the Epoch (January 1, 1970) are considered invalid.
The range for SS is [00-61] rather than [00-59] because of leap seconds. If SS is 60 or 61, and the resulting time, as affected by the TZ environment variable, does not refer to a leap second, the resulting time is one or two seconds after a time where SS is 59. If SS is not given, it is assumed to be 0.
Changes the retention time of file.
The following option is supported for the settime utility:
Uses the corresponding times of the file named by ref_file instead of the current time.
The following operand is supported for all of the touch and settime utilities:
A path name of a file whose times are to be modified.
The following operand is supported for the /usr/bin/touch and settime utilities, but not /usr/xpg7/bin/touch:
Uses the specified time_spec instead of the current time. This operand is a decimal number of the form:
MMDDhhmm[YY]
where each two digits represent 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 second two digits of the year.
YY is optional. If it is omitted, the current year is assumed. If YY is specified, the year is derived as follows:
|
If no -d, -r, or -t option is specified, at least two operands are specified, and the first operand is an eight- or ten-digit decimal integer, the first operand is assumed to be a time_spec operand. Otherwise, the first operand is assumed to be a file operand.
See environ(7) for descriptions of the following environment variables that affect the execution of touch: LANG, LC_ALL, LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.
Determine the time zone to be used for interpreting the time or date_time option-argument or the time_spec operand.
The following exit values are returned:
The touch utility executed successfully and all requested changes were made.
An error occurred. The touch utility returned the number of files for which the times could not be successfully modified.
See attributes(7) for descriptions of the following attributes:
|
|
The /usr/bin/touch command conforms to the requirements of the XPG2 through XPG5 standards. The /usr/xpg7/bin/touch command conforms to the requirements of the XPG6 through XPG7 standards, which do not allow the time_spec operand and require all operands to be treated as file names instead.
The settime utility is not specified by any standard.
For more details on these standards, see the standards(7) manual page.
stat(1), futimens(2), stat(2), attributes(7), environ(7), privileges(7), standards(7)
The range of valid times depends on the file system on which the file resides. For instance, the ufs(4FS) filesystem does not support times after 03:14:07 UTC, January 19, 2038, but the tmpfs(4FS) and zfs(4FS) file systems do. The range for the pcfs(4FS) filesystem depends on whether or not it is mounted with the clamptime option, as described in the mount_pcfs(8) manual page. If the filesystem supports such timestamps, 32-bit programs will receive EOVERFLOW errors from the stat(2) system call for files with any timestamp past 03:14:07 UTC, January 19, 2038. New software should be compiled 64-bit to avoid this.
Users familiar with the BSD environment find that for the touch utility, the -f option is accepted but ignored. The -f option is unnecessary because touch succeeds for all files owned by the user regardless of the permissions on the files.
Support for dates past the 32-bit time_t limit of 03:14:07 UTC, January 19, 2038 was added in Oracle Solaris 11.4.0 when these commands were converted to 64-bit programs.
The /usr/xpg7/bin/touch command was added in Oracle Solaris 11.4.0.
The -d option was added to the touch command in Solaris 10 9/10 (Update 9).
The -r and -t options were added to the touch command in Solaris 2.5 to support the XPG4 standard.
The settime command was added in Solaris 2.0.
The touch command, with support for the -a, -m, and -c options, has been present in all Sun and Oracle releases of Solaris.