diff options
Diffstat (limited to 'man1p/touch.1p')
| -rw-r--r-- | man1p/touch.1p | 344 |
1 files changed, 344 insertions, 0 deletions
diff --git a/man1p/touch.1p b/man1p/touch.1p new file mode 100644 index 000000000..5c1c65a30 --- /dev/null +++ b/man1p/touch.1p @@ -0,0 +1,344 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TOUCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" touch +.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 +\fIdate\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001, +\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 . |