2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "TOUCH" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" touch
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
touch \- change file access and modification times
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fBtouch\fP \fB[\fP\fB-acm\fP\fB][\fP \fB-r\fP \fIref_file\fP\fB|
|
|
|
|
-t\fP \fItime\fP\fB]\fP
|
|
|
|
\fIfile\fP\fB...\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fItouch\fP utility shall change the modification times, access
|
|
|
|
times, or both of files. The modification time shall be
|
|
|
|
equivalent to the value of the \fIst_mtime\fP member of the \fBstat\fP
|
|
|
|
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 \fIst_atime\fP.
|
|
|
|
.LP
|
|
|
|
The time used can be specified by the \fB-t\fP \fItime\fP option-argument,
|
|
|
|
the corresponding time fields of the file
|
|
|
|
referenced by the \fB-r\fP \fIref_file\fP option-argument, or the
|
|
|
|
\fIdate_time\fP operand, as specified in the following
|
|
|
|
sections. If none of these are specified, \fItouch\fP shall use the
|
|
|
|
current time (the value returned by the equivalent of the \fItime\fP()
|
|
|
|
function defined in the System Interfaces volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001).
|
|
|
|
.LP
|
|
|
|
For each \fIfile\fP operand, \fItouch\fP shall perform actions equivalent
|
|
|
|
to the following functions defined in the System
|
|
|
|
Interfaces volume of IEEE\ Std\ 1003.1-2001:
|
|
|
|
.IP " 1." 4
|
|
|
|
If \fIfile\fP does not exist, a \fIcreat\fP() function call is made
|
|
|
|
with the \fIfile\fP
|
|
|
|
operand used as the \fIpath\fP 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 \fImode\fP argument.
|
|
|
|
.LP
|
|
|
|
.IP " 2." 4
|
|
|
|
The \fIutime\fP() function is called with the following arguments:
|
|
|
|
.RS
|
|
|
|
.IP " a." 4
|
|
|
|
The \fIfile\fP operand is used as the \fIpath\fP argument.
|
|
|
|
.LP
|
|
|
|
.IP " b." 4
|
|
|
|
The \fButimbuf\fP structure members \fIactime\fP and \fImodtime\fP
|
|
|
|
are determined as described in the OPTIONS section.
|
|
|
|
.LP
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
.SH OPTIONS
|
|
|
|
.LP
|
|
|
|
The \fItouch\fP utility shall conform to the Base Definitions volume
|
|
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
|
|
.LP
|
|
|
|
The following options shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fB-a\fP
|
|
|
|
Change the access time of \fIfile\fP. Do not change the modification
|
|
|
|
time unless \fB-m\fP is also specified.
|
|
|
|
.TP 7
|
|
|
|
\fB-c\fP
|
|
|
|
Do not create a specified \fIfile\fP if it does not exist. Do not
|
|
|
|
write any diagnostic messages concerning this
|
|
|
|
condition.
|
|
|
|
.TP 7
|
|
|
|
\fB-m\fP
|
|
|
|
Change the modification time of \fIfile\fP. Do not change the access
|
|
|
|
time unless \fB-a\fP is also specified.
|
|
|
|
.TP 7
|
|
|
|
\fB-r\ \fP \fIref_file\fP
|
|
|
|
Use the corresponding time of the file named by the pathname \fIref_file\fP
|
|
|
|
instead of the current time.
|
|
|
|
.TP 7
|
|
|
|
\fB-t\ \fP \fItime\fP
|
|
|
|
Use the specified \fItime\fP instead of the current time. The option-argument
|
|
|
|
shall be a decimal number of the form:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB[[\fP\fICC\fP\fB]\fP\fIYY\fP\fB]\fP\fIMMDDhhmm\fP\fB[\fP\fB.\fP\fISS\fP\fB]\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
where each two digits represents the following:
|
|
|
|
.TP 7
|
|
|
|
\fIMM\fP
|
|
|
|
.RS
|
|
|
|
The month of the year [01,12].
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fIDD\fP
|
|
|
|
.RS
|
|
|
|
The day of the month [01,31].
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fIhh\fP
|
|
|
|
.RS
|
|
|
|
The hour of the day [00,23].
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fImm\fP
|
|
|
|
.RS
|
|
|
|
The minute of the hour [00,59].
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fICC\fP
|
|
|
|
.RS
|
|
|
|
The first two digits of the year (the century).
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fIYY\fP
|
|
|
|
.RS
|
|
|
|
The second two digits of the year.
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fISS\fP
|
|
|
|
.RS
|
|
|
|
The second of the minute [00,60].
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
Both \fICC\fP and \fIYY\fP shall be optional. If neither is given,
|
|
|
|
the current year shall be assumed. If \fIYY\fP is
|
|
|
|
specified, but \fICC\fP is not, \fICC\fP shall be derived as follows:
|
|
|
|
.TS C
|
|
|
|
center; l l.
|
|
|
|
\fBIf \fIYY\fP is:\fP \fB\fICC\fP becomes:\fP
|
|
|
|
[69,99] 19
|
|
|
|
[00,68] 20
|
|
|
|
.TE
|
|
|
|
.TP 7
|
|
|
|
\fBNote:\fP
|
|
|
|
.RS
|
|
|
|
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.)
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
The resulting time shall be affected by the value of the \fITZ\fP
|
|
|
|
environment variable. If the resulting time value precedes
|
|
|
|
the Epoch, \fItouch\fP 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 \fBsigned int\fP
|
|
|
|
as a time holder.
|
|
|
|
.LP
|
|
|
|
The range for \fISS\fP is [00,60] rather than [00,59] because of leap
|
|
|
|
seconds. If \fISS\fP is 60, and the resulting time, as
|
|
|
|
affected by the \fITZ\fP environment variable, does not refer to a
|
|
|
|
leap second, the resulting time shall be one second after a
|
|
|
|
time where \fISS\fP is 59. If \fISS\fP is not given a value, it is
|
|
|
|
assumed to be zero.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
If neither the \fB-a\fP nor \fB-m\fP options were specified, \fItouch\fP
|
|
|
|
shall behave as if both the \fB-a\fP and \fB-m\fP
|
|
|
|
options were specified.
|
|
|
|
.SH OPERANDS
|
|
|
|
.LP
|
|
|
|
The following operands shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fIfile\fP
|
|
|
|
A pathname of a file whose times shall be modified.
|
|
|
|
.sp
|
|
|
|
.SH STDIN
|
|
|
|
.LP
|
|
|
|
Not used.
|
|
|
|
.SH INPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH ENVIRONMENT VARIABLES
|
|
|
|
.LP
|
|
|
|
The following environment variables shall affect the execution of
|
|
|
|
\fItouch\fP:
|
|
|
|
.TP 7
|
|
|
|
\fILANG\fP
|
|
|
|
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.)
|
|
|
|
.TP 7
|
|
|
|
\fILC_ALL\fP
|
|
|
|
If set to a non-empty string value, override the values of all the
|
|
|
|
other internationalization variables.
|
|
|
|
.TP 7
|
|
|
|
\fILC_CTYPE\fP
|
|
|
|
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).
|
|
|
|
.TP 7
|
|
|
|
\fILC_MESSAGES\fP
|
|
|
|
Determine the locale that should be used to affect the format and
|
|
|
|
contents of diagnostic messages written to standard
|
|
|
|
error.
|
|
|
|
.TP 7
|
|
|
|
\fINLSPATH\fP
|
|
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
|
|
\&.\fP
|
|
|
|
.TP 7
|
|
|
|
\fITZ\fP
|
|
|
|
Determine the timezone to be used for interpreting the \fItime\fP
|
|
|
|
option-argument. If \fITZ\fP is unset or null, an
|
|
|
|
unspecified default timezone shall be used.
|
|
|
|
.sp
|
|
|
|
.SH ASYNCHRONOUS EVENTS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.SH STDOUT
|
|
|
|
.LP
|
|
|
|
Not used.
|
|
|
|
.SH STDERR
|
|
|
|
.LP
|
|
|
|
The standard error shall be used only for diagnostic messages.
|
|
|
|
.SH OUTPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXTENDED DESCRIPTION
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXIT STATUS
|
|
|
|
.LP
|
|
|
|
The following exit values shall be returned:
|
|
|
|
.TP 7
|
|
|
|
\ 0
|
|
|
|
The utility executed successfully and all requested changes were made.
|
|
|
|
.TP 7
|
|
|
|
>0
|
|
|
|
An error occurred.
|
|
|
|
.sp
|
|
|
|
.SH CONSEQUENCES OF ERRORS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
The interpretation of time is taken to be \fIseconds since the Epoch\fP
|
|
|
|
(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
|
|
|
|
\fISS\fP=60 is used, the resulting time always refers to 1 plus
|
|
|
|
\fIseconds since the Epoch\fP for a time when \fISS\fP=59.
|
|
|
|
.LP
|
|
|
|
Although the \fB-t\fP \fItime\fP 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 \fITZ\fP when
|
|
|
|
\fItouch\fP is run, there is never more than a few valid hours in
|
|
|
|
1969 and there need not be any valid times in 1969.
|
|
|
|
.LP
|
|
|
|
One ambiguous situation occurs if \fB-t\fP \fItime\fP is not specified,
|
|
|
|
\fB-r\fP \fIref_file\fP is not specified, and the
|
|
|
|
first operand is an eight or ten-digit decimal number. A portable
|
|
|
|
script can avoid this problem by using:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBtouch -- file
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
or:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBtouch ./file
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
in this case.
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
The functionality of \fItouch\fP 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.
|
|
|
|
.LP
|
|
|
|
There are some significant differences between the \fItouch\fP 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:
|
|
|
|
.IP " 1." 4
|
|
|
|
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 \fItime\fP value is allowed; files may only be \fItouch\fPed
|
|
|
|
to the current time. The \fB-t\fP \fItime\fP construct
|
|
|
|
solves these problems for future conforming applications (note that
|
|
|
|
the \fB-t\fP option is not historical practice).
|
|
|
|
.LP
|
|
|
|
.IP " 2." 4
|
|
|
|
The inclusion of the century digits, \fICC\fP, is also new. Note that
|
|
|
|
a ten-digit \fItime\fP value is treated as if \fIYY\fP,
|
|
|
|
and not \fICC\fP, 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 \fBsigned int\fP as a time holder.
|
|
|
|
.LP
|
|
|
|
.LP
|
|
|
|
The \fB-r\fP option was added because several comments requested this
|
|
|
|
capability. This option was named \fB-f\fP in an early
|
|
|
|
proposal, but was changed because the \fB-f\fP option is used in the
|
|
|
|
BSD version of \fItouch\fP with a different meaning.
|
|
|
|
.LP
|
|
|
|
At least one historical implementation of \fItouch\fP incremented
|
|
|
|
the exit code if \fB-c\fP was specified and the file did not
|
|
|
|
exist. This volume of IEEE\ Std\ 1003.1-2001 requires exit status
|
|
|
|
zero if no errors occur.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
Applications should use the \fB-r\fP or \fB-t\fP options.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 06:36:16 +00:00
|
|
|
\fIdate\fP, the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
|
2004-11-03 13:51:07 +00:00
|
|
|
\fIcreat\fP(), \fItime\fP(), \fIutime\fP(), the Base Definitions volume
|
|
|
|
of IEEE\ Std\ 1003.1-2001, \fI<sys/stat.h>\fP
|
|
|
|
.SH COPYRIGHT
|
|
|
|
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 .
|