touch command (changes a file's last access date and time or modification date and time)
- Organization of this page
Format
touch[-a][-c][-f][-m][-r path-name][-t date-and-time]path-name ... touch[-a][-c][-f][-m]date-and-time path-name ...
Description
This command changes the most recent access date and time or the most recent modification date and time for specified files. In Windows, the command can change only the most recent modification date and time.
Arguments
Type of date and time to be changed
The -a and -m options specify the type of date and time to be changed. If both these options are omitted or both are specified, the command changes both the most recent access date and time and the most recent modification date and time. In Windows, the file's most recent access date and time is not changed.
- -a
-
Changes the file's most recent access date and time.
When the -m option is omitted and the -a option is specified, the command changes only the file's most recent access date and time and does not change the file's most recent modification date and time.
In Windows, if the -a option is specified, the command does not change the file's most recent access date and time, but checks the format of the date and time specified in the argument and reads the file specified in the -r option.
- -m
-
Changes the file's most recent modification date and time.
When the -a option is omitted and the -m option is specified, the command changes only the file's most recent modification date and time and does not change the file's most recent access date and time.
Specifying the time to be set
The -r or -t option or date-and-time in MMDDhhmm[YY] format specifies the date and time to be set. If none of these options is specified, the command sets the date and time this command executes.
The range of time values permitted in the -t option and in MMDDhhmm[YY] format is from 1970-01-01 at 00:00:00 to 2038-01-19 at 03:14:07 in UTC (Coordinated Universal Time). The specified date and time is interpreted according to the time zone in effect when the command is executed.
If the time zone is Japan Standard Time (UTC + 9), the permitted range of time values is 1970-01-01 at 09:00:00 to 2038-01-19 at 12:14:07. Note that in AIX and Windows, the maximum time value permitted in Japan Standard Time (UTC + 9) is 2038-01-19 at 03:14:07.
For the time zone, the command uses the value of the TZ environment variable. In Windows, if the TZ environment variable is not set, the command uses the time zone set in the Date and Time control panel. In Windows, the time zone set in the TZ environment variable must match the time zone set in Date and Time.
- -r path-name
-
Specifies that the file's most recent access and modification dates and times to be set in the files are to be obtained from the file path specified here. An obtained date and time is set as a file's most recent access date and time when the -a option is specified and as a file's most recent modification date and time when the -m option is specified.
When a directory name is specified, the command obtains the most recent access and modification dates and times from the specified directory.
If this option is specified more than once, the last option specified takes effect. If the -r and -t options are both specified, the last option specified takes effect.
- -t date-and-time
-
Specifies a date and time to be set as the most recent access or modification date and time in the files. The specified date and time is set as the most recent access date and time when the -a option is specified and as the most recent modification date and time when the -m option is specified.
If this option is specified more than once, the last option specified takes effect.
If the -r and -t options are both specified, the last option specified takes effect.
Specify the date and time in the following format:
[[CC]YY]MMDDhhmm[.SS]
- CC
-
First two digits of the year.
- YY
-
Last two digits of the year
If CC is omitted, the following value is set as CC:
If YY is from 69 to 99: 19 is set as CC.
If YY is from 00 to 68, 20 is set as CC.
If CC and YY are both omitted, the year in which this command executes is set.
- MM
-
Month, as a numeric value from 01 to 12. To specify a single-digit number, add a leading zero.
- DD
-
Date, as a numeric value from 01 to 31. To specify a single-digit number, add a leading zero.
- hh
-
Hour, as a numeric value from 00 to 23. To specify a single-digit number, add a leading zero.
- mm
-
Minute, as a numeric value from 00 to 59. To specify a single-digit number, add a leading zero.
- SS
-
Second, as a numeric value from 00 to 61. To specify a single-digit number, add a leading zero. If this specification is omitted, 00 is set.
Note that if 60 or 61 is specified and the system does not support leap seconds, the date and time displayed by the ls command is advanced by one second for 60 and two seconds for 61.
- date-and-time
-
Specifies the date and time to be set as the file's most recent access or modification date and time. The specified date and time is set as the most recent access date and time when the -a option is specified and as the most recent modification date and time when the -m option is specified.
If the -r or -t option is specified, the specified value is treated as a file name.
If the specified date and time does not consist of eight or 10 digits, it is treated as a file name. If there is no such file, a file with the specified name is created.
Specify the date and time in the following format:
MMDDhhmm[YY]
- MM
-
Month, as a numeric value from 01 to 12. To specify a single-digit number, add a leading zero.
- DD
-
Date, as a numeric value from 01 to 31. To specify a single-digit number, add a leading zero.
- hh
-
Hour, as a numeric value from 00 to 23. To specify a single-digit number, add a leading zero.
- mm
-
Minute, as a numeric value from 00 to 59. To specify a single-digit number, add a leading zero.
- YY
-
Last two digits of the year. If the specification is omitted, the year in which this command executes is set.
For the first two digits of the year, the following value is set:
If YY is from 69 to 99: 19
If YY is from 00 to 68: 20
Other options
- path-name
-
Specifies the path name of a file whose most recent access or modification date and time is to be changed. You can specify multiple path names.
If the specified path does not exist, the command creates a new file with a size of zero bytes.
- In Windows:
-
A directory's most recent modification date and time cannot be changed. If a directory name is specified, an error results. Read and write permissions are required to change the most recent modification date and time of an existing file.
- In UNIX:
-
Permissions for a newly created file are set according to umask. If a directory name is specified, the directory's most recent access and modification dates and times are changed.
For a non-superuser to change the most recent access or modification date and time of an existing file, the following permissions are required:
-
When the -t option or a date-and-time value in MMDDhhmm[YY] format is specified
File owner permissions are required.
-
When neither the -t option nor a date-and-time value in MMDDhhmm[YY] format is specified
Write permission for the file is required.
-
- -c
-
Specifies that no file is to be created when there is no file whose most recent modification date and time is to be changed. No error message is output (because this event is not handled as an error).
- -f
-
This option is provided for compatibility with the touch OS command. This option is ignored, if specified.
Most recent access and modification dates and times that can be set in files
How the file's most recent access and modification dates and times are set depends on the -r or -t option or the date-and-time value in MMDDhhmm[YY] format that specifies a date and time and the -a or -m option that specifies the type of date and time to be changed, as described in the following.
- When the -r option is specified
-
How the most recent access and modification dates and times obtained from the file specified in the -r option are set depends on whether the file specified in path-name exists, as described in the following table.
Table 8‒11: Most recent access and modification dates and times that are set when the -r option is specified Specification of the -a and -m options
Whether the file specified in path-name exists
Most recent access date and time that is set
Most recent modification date and time that is set
Windows
UNIX
Only -a is specified
Yes
--
T
--
No
C
T
C
Only -m is specified
Yes
--
T
No
C
T
-a and -m are both specified or neither -a nor -m is specified
Yes
--
T
T
No
C
T
T
- Legend:
-
T: The corresponding date and time in the file specified in the -r option is set.
C: This command's execution date and time is set.
--: The most recent access or modification date and time set in the file before this command executed is set.
- When the -t option or a date-and-time value in MMDDhhmm[YY] format is specified
-
How the date and time specified in the -t option or the date-and-time value specified in MMDDhhmm[YY] format is set depends on whether the file specified in path-name exists, as described in the following table.
Table 8‒12: Most recent access and modification dates and times that are set when a date-and-time value is specified in the argument Specification of the -a and -m options
Whether the file specified in path-name exists
File's most recent access date and time that is set
File's most recent modification date and time that is set
Windows
UNIX
Only -a is specified
Yes
--
T
--
No
C
T
C
Only -m is specified
Yes
--
T
No
C
T
-a and -m are both specified or neither -a nor -m is specified
Yes
--
T
T
No
C
T
T
- Legend:
-
T: The date and time specified in the -t option or the date-and-time value specified in MMDDhhmm[YY] format is set.
C: This command's execution date and time is set.
--: The most recent access or modification date and time set in the file before this command executed is set.
- When the -r option, the -t option, and a date-and-time value in MMDDhhmm[YY] format are all omitted
-
When the -r option, the -t option, and a date-and-time value in MMDDhhmm[YY] format are all omitted, how the date and time is set depends on whether the file specified in path-name exists, as described in the following table.
Table 8‒13: File's most recent access and modification dates and times that are set when a date-and-time value is not obtained or specified Specification of the -a and -m options
Whether the file specified in path-name exists
File's most recent access date and time that is set
File's most recent modification date and time that is set
Windows
UNIX
Only the -a option is specified
Yes
--
C
--
No
C
C
Only the -m option is specified
Yes
--
C
No
C
C
-a and -m are both specified or neither -a nor -m is specified
Yes
--
C
C
No
C
C
- Legend:
-
C: This command's execution date and time is set.
--: The most recent access or modification date and time set in the file before this command executed is set.
Return code
|
Return code |
Meaning |
|---|---|
|
0 |
Normal termination |
|
1 |
Error termination
|
|
2 |
Error termination
If multiple files are specified in the argument, the command processes the next file. |
Notes
-
In UNIX, if symbolic links are specified for the path name in the -r option or for a path name whose most recent access or modification date and time is to be changed, the specified symbolic links are subject to command processing.
In Windows, symbolic links are not supported.
-
If the date and time in the file specified in the -r option is outside the range from 1970-01-01 at 00:00 to 2038-01-19 at 03:14 in UTC (Coordinated Universal Time), the most recent access or modification date and time that is set in the file by the command is not guaranteed to be correct.
-
In Windows, the precision of the most recent modification date and time that is actually set in the file depends on specifications for the file system being used. For example, the most recent access and modification dates and times are set in files in a FAT file system as follows:
-
The range of times that can be specified is from 1980-01-01 at 00:00:00 to 2038-01-19 at 03:14:07, regardless of the time zone in effect when the command executes.
-
The hour, minute, and second (hhmm.ss) values of a file's most recent access date and time are not set.
-
The number of seconds specified in the most recent modification date and time is rounded up to the next multiple of two seconds.
-
Usage examples
-
Create a file:
$ touch file001
The most recent access and modification dates and times of the created file are the date and time this command executes. The file is created with a size of zero.
-
Change the most recent access and modification dates and times of an existing file to the date and time specified in the -t option (2012-05-12 at 03:49:05):
$ touch -t 1205120349.05 file001
This command changes the most recent access and modification dates and times of the file to the date and time specified in the -t option.
-
Change only the most recent access date and time of an existing file to the date and time specified in the -t option (2013-11-01 at 15:08:00):
$ touch -a -t 201311011508 file001
This command changes the most recent access date and time of the file to the date and time specified in the -t option. The file's most recent modification date and time remains the same as before the command executed.
-
Change only the most recent modification date and time of an existing file to the date-and-time value specified in MMDDhhmm[YY] format (2013-09-29 at 23:00:00):
$ touch -m 0929230013 file001
This command changes the most recent modification date and time of the file to the date-and-time value specified in MMDDhhmm[YY] format. The file's most recent access date and time remains the same as before the command executed.
-
Change the most recent access and modification dates and times of multiple files to the date and time specified in the -t option. Specify the -c option so that any file that does not already exist will not be created. In the following example, file002 does not already exist:
$ touch -c -t 201311011508 file001 file002 file003 $ ls -lT * -rw-r--r-- 1 usr1 grp1 5 Nov 1 15:08:00 2013 file001 -rw-r--r-- 1 usr1 rrp1 9 Nov 1 15:08:00 2013 file003