Originální popis anglicky:
touch - change file access and modification times
Návod, kniha: POSIX Programmer's Manual
touch [-acm][ -r ref_file|
-t time] file...
The
touch utility shall change the modification times, access times, or
both of files. The modification time shall be equivalent to the value of the
st_mtime member of the
stat structure for a file, as described
in the System Interfaces volume of IEEE Std 1003.1-2001; the
access time shall be equivalent to the value of
st_atime.
The time used can be specified by the
-t time option-argument, the
corresponding time fields of the file referenced by the
-r
ref_file option-argument, or the
date_time operand, as specified
in the following sections. If none of these are specified,
touch shall
use the current time (the value returned by the equivalent of the
time() function defined in the System Interfaces volume of
IEEE Std 1003.1-2001).
For each
file operand,
touch shall perform actions equivalent to
the following functions defined in the System Interfaces volume of
IEEE Std 1003.1-2001:
- 1.
- If file does not exist, a creat() function
call is made with the file operand used as the path argument
and the value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, S_IRGRP,
S_IWGRP, S_IROTH, and S_IWOTH used as the mode argument.
- 2.
- The utime() function is called with the following
arguments:
- a.
- The file operand is used as the path
argument.
- b.
- The utimbuf structure members actime and
modtime are determined as described in the OPTIONS section.
The
touch utility shall conform to the Base Definitions volume of
IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported:
- -a
- Change the access time of file. Do not change the
modification time unless -m is also specified.
- -c
- Do not create a specified file if it does not exist.
Do not write any diagnostic messages concerning this condition.
- -m
- Change the modification time of file. Do not change
the access time unless -a is also specified.
- -r ref_file
- Use the corresponding time of the file named by the
pathname ref_file instead of the current time.
- -t time
- Use the specified time instead of the current time.
The option-argument shall be a decimal number of the form:
where each two digits represents the following:
- MM
The month of the year [01,12].
- DD
The day of the month [01,31].
- hh
The hour of the day [00,23].
- mm
The minute of the hour [00,59].
- CC
The first two digits of the year (the
century).
- YY
The second two digits of the year.
- SS
The second of the minute [00,60].
Both
CC and
YY shall be optional. If neither is given, the current
year shall be assumed. If
YY is specified, but
CC is not,
CC shall be derived as follows:
| If YY is: |
CC becomes: |
| [69,99] |
19 |
| [00,68] |
20 |
- Note:
It is expected that in a future version of
IEEE Std 1003.1-2001 the default century inferred from a 2-digit
year will change. (This would apply to all commands accepting a 2-digit year
as input.)
The resulting time shall be affected by the value of the
TZ environment
variable. If the resulting time value precedes the Epoch,
touch shall
exit immediately with an error status. The range of valid times past the Epoch
is implementation-defined, but it shall extend to at least the time 0 hours, 0
minutes, 0 seconds, January 1, 2038, Coordinated Universal Time. Some
implementations may not be able to represent dates beyond January 18, 2038,
because they use
signed int as a time holder.
The range for
SS is [00,60] rather than [00,59] because of 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
shall be one second after a time where
SS is 59. If
SS is not
given a value, it is assumed to be zero.
If neither the
-a nor
-m options were specified,
touch
shall behave as if both the
-a and
-m options were specified.
The following operands shall be supported:
- file
- A pathname of a file whose times shall be modified.
Not used.
None.
The following environment variables shall affect the execution of
touch:
- LANG
- Provide a default value for the internationalization
variables that are unset or null. (See the Base Definitions volume of
IEEE Std 1003.1-2001, Section 8.2, Internationalization
Variables for the precedence of internationalization variables used to
determine the values of locale categories.)
- LC_ALL
- If set to a non-empty string value, override the values of
all the other internationalization variables.
- LC_CTYPE
- Determine the locale for the interpretation of sequences of
bytes of text data as characters (for example, single-byte as opposed to
multi-byte characters in arguments).
- LC_MESSAGES
- Determine the locale that should be used to affect the
format and contents of diagnostic messages written to standard error.
- NLSPATH
- Determine the location of message catalogs for the
processing of LC_MESSAGES .
- TZ
- Determine the timezone to be used for interpreting the
time option-argument. If TZ is unset or null, an unspecified
default timezone shall be used.
Default.
Not used.
The standard error shall be used only for diagnostic messages.
None.
None.
The following exit values shall be returned:
- 0
- The utility executed successfully and all requested changes
were made.
- >0
- An error occurred.
Default.
The following sections are informative.
The interpretation of time is taken to be
seconds since the Epoch (see
the Base Definitions volume of IEEE Std 1003.1-2001, Section
4.14, Seconds Since the Epoch). It should be noted that implementations
conforming to the System Interfaces volume of
IEEE Std 1003.1-2001 do not take leap seconds into account when
computing seconds since the Epoch. When
SS=60 is used, the resulting
time always refers to 1 plus
seconds since the Epoch for a time when
SS=59.
Although the
-t time option-argument specifies values in 1969, the
access time and modification time fields are defined in terms of seconds since
the Epoch (00:00:00 on 1 January 1970 UTC). Therefore, depending on the value
of
TZ when
touch is run, there is never more than a few valid
hours in 1969 and there need not be any valid times in 1969.
One ambiguous situation occurs if
-t time is not specified,
-r ref_file is not specified, and the first operand is an eight
or ten-digit decimal number. A portable script can avoid this problem by
using:
or:
in this case.
None.
The functionality of
touch is described almost entirely through
references to functions in the System Interfaces volume of
IEEE Std 1003.1-2001. In this way, there is no duplication of
effort required for describing such side effects as the relationship of user
IDs to the user database, permissions, and so on.
There are some significant differences between the
touch utility in this
volume of IEEE Std 1003.1-2001 and those in System V and BSD
systems. They are upwards-compatible for historical applications from both
implementations:
- 1.
- In System V, an ambiguity exists when a pathname that is a
decimal number leads the operands; it is treated as a time value. In BSD,
no time value is allowed; files may only be touched to the
current time. The -t time construct solves these problems
for future conforming applications (note that the -t option is not
historical practice).
- 2.
- The inclusion of the century digits, CC, is also
new. Note that a ten-digit time value is treated as if YY,
and not CC, were specified. The caveat about the range of dates
following the Epoch was included as recognition that some implementations
are not able to represent dates beyond 18 January 2038 because they use
signed int as a time holder.
The
-r option was added because several comments requested this
capability. This option was named
-f in an early proposal, but was
changed because the
-f option is used in the BSD version of
touch with a different meaning.
At least one historical implementation of
touch incremented the exit code
if
-c was specified and the file did not exist. This volume of
IEEE Std 1003.1-2001 requires exit status zero if no errors
occur.
Applications should use the
-r or
-t options.
date , the System Interfaces volume of
IEEE Std 1003.1-2001,
creat(),
time(),
utime(), the Base Definitions volume of
IEEE Std 1003.1-2001,
<sys/stat.h>
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group Standard, the original
IEEE and The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.opengroup.org/unix/online.html
.
