434 lines
15 KiB
HTML
434 lines
15 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>touch</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="touch"></a> <a name="tag_04_143"></a><!-- touch -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_143_01"></a>NAME</h4>
|
|
|
|
<blockquote>touch - change file access and modification times</blockquote>
|
|
|
|
<h4><a name="tag_04_143_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>touch</tt> <b>[</b><tt>-acm</tt><b>][</b> <tt>-r</tt> <i>ref_file</i><tt>| -t</tt> <i>time</i><b>]</b>
|
|
<i>file</i><tt>...</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>touch</i> utility shall change the modification times, access times, or both of files. The modification time shall be
|
|
equivalent to the value of the <i>st_mtime</i> member of the <b>stat</b> 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 <i>st_atime</i>.</p>
|
|
|
|
<p>The time used can be specified by the <b>-t</b> <i>time</i> option-argument, the corresponding time fields of the file
|
|
referenced by the <b>-r</b> <i>ref_file</i> option-argument, or the <i>date_time</i> operand, as specified in the following
|
|
sections. If none of these are specified, <i>touch</i> shall use the current time (the value returned by the equivalent of the <a
|
|
href="../functions/time.html"><i>time</i>()</a> function defined in the System Interfaces volume of
|
|
IEEE Std 1003.1-2001).</p>
|
|
|
|
<p>For each <i>file</i> operand, <i>touch</i> shall perform actions equivalent to the following functions defined in the System
|
|
Interfaces volume of IEEE Std 1003.1-2001:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>If <i>file</i> does not exist, a <a href="../functions/creat.html"><i>creat</i>()</a> function call is made with the <i>file</i>
|
|
operand used as the <i>path</i> 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 <i>mode</i> argument.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <a href="../functions/utime.html"><i>utime</i>()</a> function is called with the following arguments:</p>
|
|
|
|
<ol type="a">
|
|
<li>
|
|
<p>The <i>file</i> operand is used as the <i>path</i> argument.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <b>utimbuf</b> structure members <i>actime</i> and <i>modtime</i> are determined as described in the OPTIONS section.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>touch</i> utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap12.html#tag_12_02">Section 12.2, Utility Syntax Guidelines</a>.</p>
|
|
|
|
<p>The following options shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>-a</b></dt>
|
|
|
|
<dd>Change the access time of <i>file</i>. Do not change the modification time unless <b>-m</b> is also specified.</dd>
|
|
|
|
<dt><b>-c</b></dt>
|
|
|
|
<dd>Do not create a specified <i>file</i> if it does not exist. Do not write any diagnostic messages concerning this
|
|
condition.</dd>
|
|
|
|
<dt><b>-m</b></dt>
|
|
|
|
<dd>Change the modification time of <i>file</i>. Do not change the access time unless <b>-a</b> is also specified.</dd>
|
|
|
|
<dt><b>-r </b> <i>ref_file</i></dt>
|
|
|
|
<dd>Use the corresponding time of the file named by the pathname <i>ref_file</i> instead of the current time.</dd>
|
|
|
|
<dt><b>-t </b> <i>time</i></dt>
|
|
|
|
<dd>Use the specified <i>time</i> instead of the current time. The option-argument shall be a decimal number of the form:
|
|
|
|
<pre>
|
|
<b>[[</b><i>CC</i><b>]</b><i>YY</i><b>]</b><i>MMDDhhmm</i><b>[</b><tt>.</tt><i>SS</i><b>]</b>
|
|
</pre>
|
|
|
|
<p>where each two digits represents the following:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>MM</i></dt>
|
|
|
|
<dd>The month of the year [01,12].</dd>
|
|
|
|
<dt><i>DD</i></dt>
|
|
|
|
<dd>The day of the month [01,31].</dd>
|
|
|
|
<dt><i>hh</i></dt>
|
|
|
|
<dd>The hour of the day [00,23].</dd>
|
|
|
|
<dt><i>mm</i></dt>
|
|
|
|
<dd>The minute of the hour [00,59].</dd>
|
|
|
|
<dt><i>CC</i></dt>
|
|
|
|
<dd>The first two digits of the year (the century).</dd>
|
|
|
|
<dt><i>YY</i></dt>
|
|
|
|
<dd>The second two digits of the year.</dd>
|
|
|
|
<dt><i>SS</i></dt>
|
|
|
|
<dd>The second of the minute [00,60].</dd>
|
|
</dl>
|
|
|
|
<p>Both <i>CC</i> and <i>YY</i> shall be optional. If neither is given, the current year shall be assumed. If <i>YY</i> is
|
|
specified, but <i>CC</i> is not, <i>CC</i> shall be derived as follows:</p>
|
|
|
|
<center>
|
|
<table border="1" cellpadding="3" align="center">
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>If <i>YY</i> is:</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b><i>CC</i> becomes:</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="center">
|
|
<p class="tent">[69,99]</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">19</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="center">
|
|
<p class="tent">[00,68]</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">20</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<basefont size="2">
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>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.)</dd>
|
|
</dl>
|
|
|
|
<basefont size="3">
|
|
|
|
<p>The resulting time shall be affected by the value of the <i>TZ</i> environment variable. If the resulting time value precedes
|
|
the Epoch, <i>touch</i> 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 <b>signed int</b>
|
|
as a time holder.</p>
|
|
|
|
<p>The range for <i>SS</i> is [00,60] rather than [00,59] because of leap seconds. If <i>SS</i> is 60, and the resulting time, as
|
|
affected by the <i>TZ</i> environment variable, does not refer to a leap second, the resulting time shall be one second after a
|
|
time where <i>SS</i> is 59. If <i>SS</i> is not given a value, it is assumed to be zero.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>If neither the <b>-a</b> nor <b>-m</b> options were specified, <i>touch</i> shall behave as if both the <b>-a</b> and <b>-m</b>
|
|
options were specified.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operands shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>file</i></dt>
|
|
|
|
<dd>A pathname of a file whose times shall be modified.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>touch</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>LANG</i></dt>
|
|
|
|
<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
|
|
the precedence of internationalization variables used to determine the values of locale categories.)</dd>
|
|
|
|
<dt><i>LC_ALL</i></dt>
|
|
|
|
<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
|
|
|
|
<dt><i>LC_CTYPE</i></dt>
|
|
|
|
<dd>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).</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard
|
|
error.</dd>
|
|
|
|
<dt><i>NLSPATH</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
|
|
<dt><i>TZ</i></dt>
|
|
|
|
<dd>Determine the timezone to be used for interpreting the <i>time</i> option-argument. If <i>TZ</i> is unset or null, an
|
|
unspecified default timezone shall be used.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_11"></a>STDERR</h4>
|
|
|
|
<blockquote>
|
|
<p>The standard error shall be used only for diagnostic messages.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_12"></a>OUTPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_13"></a>EXTENDED DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_14"></a>EXIT STATUS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following exit values shall be returned:</p>
|
|
|
|
<dl compact>
|
|
<dt> 0</dt>
|
|
|
|
<dd>The utility executed successfully and all requested changes were made.</dd>
|
|
|
|
<dt>>0</dt>
|
|
|
|
<dd>An error occurred.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_15"></a>CONSEQUENCES OF ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_04_143_16"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>The interpretation of time is taken to be <i>seconds since the Epoch</i> (see the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap04.html#tag_04_14">Section 4.14, Seconds Since the Epoch</a>). 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 <i>SS</i>=60 is used, the resulting time always refers to 1 plus
|
|
<i>seconds since the Epoch</i> for a time when <i>SS</i>=59.</p>
|
|
|
|
<p>Although the <b>-t</b> <i>time</i> 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 <i>TZ</i> when
|
|
<i>touch</i> is run, there is never more than a few valid hours in 1969 and there need not be any valid times in 1969.</p>
|
|
|
|
<p>One ambiguous situation occurs if <b>-t</b> <i>time</i> is not specified, <b>-r</b> <i>ref_file</i> is not specified, and the
|
|
first operand is an eight or ten-digit decimal number. A portable script can avoid this problem by using:</p>
|
|
|
|
<pre>
|
|
<tt>touch -- file
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>or:</p>
|
|
|
|
<pre>
|
|
<tt>touch ./file
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>in this case.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_17"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_18"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The functionality of <i>touch</i> 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.</p>
|
|
|
|
<p>There are some significant differences between the <i>touch</i> 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:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>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 <i>time</i> value is allowed; files may only be <i>touch</i>ed to the current time. The <b>-t</b> <i>time</i> construct
|
|
solves these problems for future conforming applications (note that the <b>-t</b> option is not historical practice).</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The inclusion of the century digits, <i>CC</i>, is also new. Note that a ten-digit <i>time</i> value is treated as if <i>YY</i>,
|
|
and not <i>CC</i>, 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 <b>signed int</b> as a time holder.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>The <b>-r</b> option was added because several comments requested this capability. This option was named <b>-f</b> in an early
|
|
proposal, but was changed because the <b>-f</b> option is used in the BSD version of <i>touch</i> with a different meaning.</p>
|
|
|
|
<p>At least one historical implementation of <i>touch</i> incremented the exit code if <b>-c</b> was specified and the file did not
|
|
exist. This volume of IEEE Std 1003.1-2001 requires exit status zero if no errors occur.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_19"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>Applications should use the <b>-r</b> or <b>-t</b> options.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_20"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="date.html"><i>date</i></a> , the System Interfaces volume of IEEE Std 1003.1-2001, <a href=
|
|
"../functions/creat.html"><i>creat</i>()</a>, <a href="../functions/time.html"><i>time</i>()</a>, <a href=
|
|
"../functions/utime.html"><i>utime</i>()</a>, the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/sys/stat.h.html"><i><sys/stat.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_21"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 2.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_143_22"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The obsolescent <i>date_time</i> operand is removed.</p>
|
|
|
|
<p>The Open Group Corrigendum U027/1 is applied. This extends the range of valid time past the Epoch to at least the time 0 hours,
|
|
0 minutes, 0 seconds, January 1, 2038, Coordinated Universal Time. This is a new requirement on POSIX implementations.</p>
|
|
|
|
<p>The range for seconds is changed from [00,61] to [00,60] to align with the ISO/IEC 9899:1999 standard, and to allow for
|
|
positive leap seconds.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|