1TOUCH(1P)                  POSIX Programmer's Manual                 TOUCH(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       touch — change file access and modification times
14

SYNOPSIS

16       touch [−acm] [−r ref_file|−t time|−d date_time] file...
17

DESCRIPTION

19       The touch utility shall change the last data  modification  timestamps,
20       the last data access timestamps, or both.
21
22       The time used can be specified by the −t time option-argument, the cor‐
23       responding time fields of  the  file  referenced  by  the  −r  ref_file
24       option-argument,  or  the −d date_time option-argument, as specified in
25       the following sections. If none of these are specified, touch shall use
26       the current time.
27
28       For  each  file  operand, touch shall perform actions equivalent to the
29       following  functions  defined  in  the  System  Interfaces  volume   of
30       POSIX.1‐2008:
31
32        1. If file does not exist:
33
34            a. The creat() function is called with the following arguments:
35
36               --  The file operand is used as the path argument.
37
38               --  The  value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR,
39                   S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH is used as the  mode
40                   argument.
41
42            b. The futimens() function is called with the following arguments:
43
44               --  The file descriptor opened in step 1a.
45
46               --  The access time and the modification time, set as described
47                   in the OPTIONS section, are used as the  first  and  second
48                   elements of the times array argument, respectively.
49
50        2. If file exists, the utimensat() function is called with the follow‐
51           ing arguments:
52
53            a. The AT_FDCWD special value is used as the fd argument.
54
55            b. The file operand is used as the path argument.
56
57            c. The access time and the modification time, set as described  in
58               the  OPTIONS section, are used as the first and second elements
59               of the times array argument, respectively.
60
61            d. The flag argument is set to zero.
62

OPTIONS

64       The touch utility shall conform  to  the  Base  Definitions  volume  of
65       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
66
67       The following options shall be supported:
68
69       −a        Change  the access time of file.  Do not change the modifica‐
70                 tion time unless −m is also specified.
71
72       −c        Do not create a specified file if it does not exist.  Do  not
73                 write any diagnostic messages concerning this condition.
74
75       −d date_time
76                 Use  the specified date_time instead of the current time. The
77                 option-argument shall be a string of the form:
78
79                     YYYYMMDDThh:mm:SS[.frac][tz]
80
81                 or:
82
83                     YYYYMMDDThh:mm:SS[,frac][tz]
84
85                 where:
86
87                  *  YYYY are at least four decimal digits giving the year.
88
89                  *  MM, DD, hh, mm, and SS are as with −t time.
90
91                  *  T is the time designator, and can be replaced by a single
92                     <space>.
93
94                  *  [.frac] and [,frac] are either empty, or a <period> ('.')
95                     or a <comma> (',') respectively, followed by one or  more
96                     decimal digits, specifying a fractional second.
97
98                  *  [tz]  is either empty, signifying local time, or the let‐
99                     ter 'Z', signifying UTC. If [tz] is empty, the  resulting
100                     time shall be affected by the value of the TZ environment
101                     variable.
102
103                 If the resulting time precedes the  Epoch,  the  behavior  is
104                 implementation-defined.  If the time cannot be represented as
105                 the file's timestamp, touch shall exit  immediately  with  an
106                 error status.
107
108       −m        Change  the  modification  time  of  file.  Do not change the
109                 access time unless −a is also specified.
110
111       −r ref_file
112                 Use the corresponding time of the file named by the  pathname
113                 ref_file instead of the current time.
114
115       −t time   Use  the  specified  time  instead  of  the current time. The
116                 option-argument shall be a decimal number of the form:
117
118                     [[CC]YY]MMDDhhmm[.SS]
119
120                 where each two digits represents the following:
121
122                 MM      The month of the year [01,12].
123
124                 DD      The day of the month [01,31].
125
126                 hh      The hour of the day [00,23].
127
128                 mm      The minute of the hour [00,59].
129
130                 CC      The first two digits of the year (the century).
131
132                 YY      The second two digits of the year.
133
134                 SS      The second of the minute [00,60].
135
136                 Both CC and YY shall be optional. If neither  is  given,  the
137                 current  year shall be assumed. If YY is specified, but CC is
138                 not, CC shall be derived as follows:
139
140                                   ┌──────────┬─────────────┐
141If YY is: CC becomes: 
142                                   ├──────────┼─────────────┤
143                                   │ [69,99]  │     19      │
144                                   │ [00,68]  │     20      │
145                                   └──────────┴─────────────┘
146                 Note:     It is expected that in a  future  version  of  this
147                           standard   the  default  century  inferred  from  a
148                           2-digit year will change. (This would apply to  all
149                           commands accepting a 2-digit year as input.)
150
151                 The  resulting  time shall be affected by the value of the TZ
152                 environment variable. If the resulting  time  value  precedes
153                 the  Epoch,  the  behavior  is implementation-defined. If the
154                 time is out of range for the file's  timestamp,  touch  shall
155                 exit  immediately  with  an  error status. The range of valid
156                 times past the Epoch is implementation-defined, but it  shall
157                 extend  to  at  least the time 0 hours, 0 minutes, 0 seconds,
158                 January 1, 2038, Coordinated Universal Time. Some implementa‐
159                 tions  may  not be able to represent dates beyond January 18,
160                 2038, because they use signed int as a time holder.
161
162                 The range for SS is [00,60] rather than  [00,59]  because  of
163                 leap  seconds.  If  SS  is  60,  and  the  resulting time, as
164                 affected by the TZ environment variable, does not refer to  a
165                 leap  second,  the resulting time shall be one second after a
166                 time where SS is 59. If SS  is  not  given  a  value,  it  is
167                 assumed to be zero.
168
169       If  neither the −a nor −m options were specified, touch shall behave as
170       if both the −a and −m options were specified.
171

OPERANDS

173       The following operands shall be supported:
174
175       file      A pathname of a file whose times shall be modified.
176

STDIN

178       Not used.
179

INPUT FILES

181       None.
182

ENVIRONMENT VARIABLES

184       The following environment  variables  shall  affect  the  execution  of
185       touch:
186
187       LANG      Provide  a  default  value for the internationalization vari‐
188                 ables that are unset or null. (See the Base Definitions  vol‐
189                 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
190                 ables for the precedence  of  internationalization  variables
191                 used to determine the values of locale categories.)
192
193       LC_ALL    If  set  to  a non-empty string value, override the values of
194                 all the other internationalization variables.
195
196       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
197                 bytes of text data as characters (for example, single-byte as
198                 opposed to multi-byte characters in arguments).
199
200       LC_MESSAGES
201                 Determine the locale that should be used to affect the format
202                 and  contents  of  diagnostic  messages  written  to standard
203                 error.
204
205       NLSPATH   Determine the location of message catalogs for the processing
206                 of LC_MESSAGES.
207
208       TZ        Determine  the  timezone to be used for interpreting the time
209                 option-argument. If TZ  is  unset  or  null,  an  unspecified
210                 default timezone shall be used.
211

ASYNCHRONOUS EVENTS

213       Default.
214

STDOUT

216       Not used.
217

STDERR

219       The standard error shall be used only for diagnostic messages.
220

OUTPUT FILES

222       None.
223

EXTENDED DESCRIPTION

225       None.
226

EXIT STATUS

228       The following exit values shall be returned:
229
230        0    The  utility executed successfully and all requested changes were
231             made.
232
233       >0    An error occurred.
234

CONSEQUENCES OF ERRORS

236       Default.
237
238       The following sections are informative.
239

APPLICATION USAGE

241       The interpretation of time is taken to be seconds since the Epoch  (see
242       the  Base  Definitions  volume  of  POSIX.1‐2008, Section 4.15, Seconds
243       Since the Epoch).  It should be noted that  implementations  conforming
244       to  the  System Interfaces volume of POSIX.1‐2008 do not take leap sec‐
245       onds into account when computing seconds since the Epoch. When SS=60 is
246       used,  the  resulting  time  always  refers to 1 plus seconds since the
247       Epoch for a time when SS=59.
248
249       Although the −t time option-argument  specifies  values  in  1969,  the
250       access  time  and modification time fields are defined in terms of sec‐
251       onds since the Epoch (00:00:00  on  1  January  1970  UTC).  Therefore,
252       depending  on  the  value  of TZ when touch is run, there is never more
253       than a few valid hours in 1969 and there need not be any valid times in
254       1969.
255
256       One ambiguous situation occurs if −t time is not specified, −r ref_file
257       is not specified, and the first operand is an eight or ten-digit  deci‐
258       mal number. A portable script can avoid this problem by using:
259
260           touch −− file
261
262       or:
263
264           touch ./file
265
266       in this case.
267
268       If  the T time designator is replaced by a <space> for the −d date_time
269       option-argument, the <space> must be quoted to prevent the  shell  from
270       splitting the argument.
271

EXAMPLES

273       Create  or  update  a  file called dwc; the resulting file has both the
274       last data modification and last data access timestamps set to  November
275       12, 2007 at 10:15:30 local time:
276
277           touch −d 2007-11-12T10:15:30 dwc
278
279       Create  or  update  a file called nick; the resulting file has both the
280       last data modification and last data access timestamps set to  November
281       12, 2007 at 10:15:30 UTC:
282
283           touch −d 2007-11-12T10:15:30Z nick
284
285       Create  or  update  a  file called gwc; the resulting file has both the
286       last data modification and last data access timestamps set to  November
287       12,  2007  at 10:15:30 local time with a fractional second timestamp of
288       .002 seconds:
289
290           touch −d 2007-11-12T10:15:30,002 gwc
291
292       Create or update a file called ajosey; the resulting file has both  the
293       last  data modification and last data access timestamps set to November
294       12, 2007 at 10:15:30 UTC with a fractional  second  timestamp  of  .002
295       seconds:
296
297           touch −d "2007-11-12 10:15:30.002Z" ajosey
298
299       Create  or  update a file called cathy; the resulting file has both the
300       last data modification and last data access timestamps set to  November
301       12, 2007 at 10:15:00 local time:
302
303           touch −t 200711121015 cathy
304
305       Create or update a file called drepper; the resulting file has both the
306       last data modification and last data access timestamps set to  November
307       12, 2007 at 10:15:30 local time:
308
309           touch −t 200711121015.30 drepper
310
311       Create  or  update  a file called ebb9; the resulting file has both the
312       last data modification and last data access timestamps set to  November
313       12, 2007 at 10:15:30 local time:
314
315           touch −t 0711121015.30 ebb9
316
317       Create  or update a file called eggert; the resulting file has the last
318       data access timestamp set to the corresponding time of the  file  named
319       mark  instead  of  the  current time. If the file exists, the last data
320       modification time is not changed:
321
322           touch −a −r mark eggert
323

RATIONALE

325       The functionality of touch is described almost entirely through  refer‐
326       ences  to functions in the System Interfaces volume of POSIX.1‐2008. In
327       this way, there is no duplication of  effort  required  for  describing
328       such side-effects as the relationship of user IDs to the user database,
329       permissions, and so on.
330
331       There are some significant differences between  the  touch  utility  in
332       this volume of POSIX.1‐2008 and those in System V and BSD systems. They
333       are upwards-compatible for historical applications from both  implemen‐
334       tations:
335
336        1. In  System V, an ambiguity exists when a pathname that is a decimal
337           number leads the operands; it is treated as a time value.  In  BSD,
338           no  time value is allowed; files may only be touched to the current
339           time. The −t time construct solves these problems for  future  con‐
340           forming  applications  (note  that  the −t option is not historical
341           practice).
342
343        2. The inclusion of the century digits, CC, is also new. Note  that  a
344           ten-digit  time  value is treated as if YY, and not CC, were speci‐
345           fied. The caveat about the range of dates following the  Epoch  was
346           included  as  recognition that some implementations are not able to
347           represent dates beyond 18 January 2038 because they use signed  int
348           as a time holder.
349
350       The  −r  option was added because several comments requested this capa‐
351       bility.  This option was named −f in an early proposal, but was changed
352       because  the  −f option is used in the BSD version of touch with a dif‐
353       ferent meaning.
354
355       At least one historical implementation of touch  incremented  the  exit
356       code  if  −c  was  specified and the file did not exist. This volume of
357       POSIX.1‐2008 requires exit status zero if no errors occur.
358
359       In previous version of the standard, if at least two operands are spec‐
360       ified,  and the first operand is an eight or ten-digit decimal integer,
361       the first operand was assumed to be a date_time operand. This usage was
362       removed  in this version of the standard since it had been marked obso‐
363       lescent previously.
364
365       The −d date_time format is an ISO 8601:2004 standard complete represen‐
366       tation  of date and time extended format with an optional decimal point
367       or <comma> followed by a string of digits following the seconds portion
368       to  specify  fractions  of  a  second. It is not necessary to recognize
369       "[+/-]hh:mm" and "[+/-]hh" to specify timezones other than  local  time
370       and  UTC.  The T time designator in the ISO 8601:2004 standard extended
371       format may be replaced by <space>.
372

FUTURE DIRECTIONS

374       None.
375

SEE ALSO

377       date
378
379       The Base Definitions volume  of  POSIX.1‐2008,  Section  4.15,  Seconds
380       Since  the Epoch, Chapter 8, Environment Variables, Section 12.2, Util‐
381       ity Syntax Guidelines, <sys_stat.h>
382
383       The System Interfaces  volume  of  POSIX.1‐2008,  creat(),  futimens(),
384       time(), utime()
385
387       Portions  of  this text are reprinted and reproduced in electronic form
388       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
389       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
390       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
391       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
392       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
393       event of any discrepancy between this version and the original IEEE and
394       The Open Group Standard, the original IEEE and The Open Group  Standard
395       is  the  referee document. The original Standard can be obtained online
396       at http://www.unix.org/online.html .
397
398       Any typographical or formatting errors that appear  in  this  page  are
399       most likely to have been introduced during the conversion of the source
400       files to man page format. To report such errors,  see  https://www.ker
401       nel.org/doc/man-pages/reporting_bugs.html .
402
403
404
405IEEE/The Open Group                  2013                            TOUCH(1P)
Impressum