| blob | e64678ac7d1a9f0e4d248c7ed30316ddab672202 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Portions Copyright (c) 2009, Sun Mricrosystems, Inc. All Rights Reserved
46 .\"
47 .TH TOUCH 1 "Sep 9, 2009"
48 .SH NAME
49 touch, settime \- change file access and modification times
50 .SH SYNOPSIS
51 .LP
52 .nf
53 \fBtouch\fR [\fB-acm\fR] [\fB-r\fR \fIref_file\fR | \fB-t\fR \fItime\fR | \fB-d\fR \fIdate_time\fR] \fIfile\fR...
54 .fi
56 .LP
57 .nf
58 \fBtouch\fR [\fB-acm\fR] [\fItime_spec\fR] \fIfile\fR...
59 .fi
61 .LP
62 .nf
63 \fBsettime\fR [\fB-f\fR \fIref_file\fR] [\fItime_spec\fR] \fIfile\fR...
64 .fi
66 .SH DESCRIPTION
67 .sp
68 .LP
69 The \fBtouch\fR utility sets the access and modification times of each file.
70 The \fIfile\fR operand is created if it does not already exist.
71 .sp
72 .LP
73 The time used can be specified by \fB-t\fR \fItime\fR, by \fB-d\fR
74 \fIdate_time\fR, by the corresponding time fields of the file referenced by
75 \fB-r\fR \fIref_file\fR, or by the \fItime_spec\fR operand. If none of these
76 are specified, \fBtouch\fR uses the current time.
77 .sp
78 .LP
79 If neither the \fB-a\fR nor \fB-m\fR options are specified, \fBtouch\fR updates
80 both the modification and access times.
81 .sp
82 .LP
83 A user with write access to a file, but who is not the owner of the file or a
84 super-user, can change the modification and access times of that file only to
85 the current time. Attempts to set a specific time with \fBtouch\fR results in
86 an error.
87 .sp
88 .LP
89 The \fBsettime\fR utility is equivalent to \fBtouch\fR \fB-c\fR
90 [\fItime_spec\fR] \fIfile\fR.
91 .SH OPTIONS
92 .sp
93 .LP
94 The following options are supported in the \fBtouch\fR and \fBsettime\fR
95 utilities:
96 .SS "touch"
97 .sp
98 .LP
99 The following options are supported for the \fBtouch\fR utility:
100 .sp
101 .ne 2
102 .na
103 \fB\fB-a\fR\fR
104 .ad
105 .sp .6
106 .RS 4n
107 Changes the access time of \fIfile\fR. Does not change the modification time
108 unless \fB-m\fR is also specified.
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fB-c\fR\fR
115 .ad
116 .sp .6
117 .RS 4n
118 Does not create a specified \fIfile\fR if it does not exist. Does not write any
119 diagnostic messages concerning this condition.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fB-d\fR \fIdate_time\fR\fR
126 .ad
127 .sp .6
128 .RS 4n
129 Uses the specified date_time instead of the current time. The option-argument
130 must be a string of the form:
131 .sp
132 .in +2
133 .nf
134 \fIYYYY\fR-\fIMM\fR-\fIDDThh\fR:\fImm\fR:\fISS\fR[.\fIfrac\fR][\fItz\fR]
135 .fi
136 .in -2
137 .sp
139 or
140 .sp
141 .in +2
142 .nf
143 \fIYYYY\fR-\fIMM\fR-\fIDDThh\fR:\fImm\fR:\fISS\fR[,\fIfrac\fR][\fItz\fR]
144 .fi
145 .in -2
146 .sp
148 where
149 .RS +4
150 .TP
151 .ie t \(bu
152 .el o
153 \fIYYYY\fR is at least four decimal digits giving the year
154 .RE
155 .RS +4
156 .TP
157 .ie t \(bu
158 .el o
159 \fIMM\fR, \fIDD\fR, \fIhh\fR, \fImm\fR, and \fISS\fR are as with \fB-t\fR
160 \fItime\fR
161 .RE
162 .RS +4
163 .TP
164 .ie t \(bu
165 .el o
166 \fIT\fR is either the letter \fBT\fR or a single SPACE character
167 .RE
168 .RS +4
169 .TP
170 .ie t \(bu
171 .el o
172 [\fI\&.frac\fR] and [\fI,frac\fR] are either empty, or a period (\fB\&.\fR) or
173 a comma (\fB,\fR) respectively, followed by one or more decimal digits,
174 specifying a fractional second
175 .RE
176 .RS +4
177 .TP
178 .ie t \(bu
179 .el o
180 [\fItz\fR] is either empty, signifying local time, or the letter \fBZ\fR,
181 signifying UTC. If [\fItz\fR] is empty, the resulting time is affected by the
182 value of the \fBTZ\fR environment variable
183 .RE
184 .RE
186 .sp
187 .ne 2
188 .na
189 \fB\fB-m\fR\fR
190 .ad
191 .sp .6
192 .RS 4n
193 Changes the modification time of \fIfile\fR. Does not change the access time
194 unless \fB-a\fR is also specified.
195 .RE
197 .sp
198 .ne 2
199 .na
200 \fB\fB-r\fR \fIref_file\fR\fR
201 .ad
202 .sp .6
203 .RS 4n
204 Uses the corresponding times of the file named by \fIref_file\fR instead of the
205 current time.
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fB\fB-t\fR \fItime\fR\fR
212 .ad
213 .sp .6
214 .RS 4n
215 Uses the specified \fItime\fR instead of the current time. \fItime\fR is a
216 decimal number of the form:
217 .sp
218 .in +2
219 .nf
220 [[\fICC\fR]\fIYY\fR]\fIMMDDhhmm\fR[\fI\&.SS\fR]
221 .fi
222 .in -2
223 .sp
225 where each two digits represent the following:
226 .sp
227 .ne 2
228 .na
229 \fB\fIMM\fR\fR
230 .ad
231 .sp .6
232 .RS 4n
233 The month of the year [01-12].
234 .RE
236 .sp
237 .ne 2
238 .na
239 \fB\fIDD\fR\fR
240 .ad
241 .sp .6
242 .RS 4n
243 The day of the month [01-31].
244 .RE
246 .sp
247 .ne 2
248 .na
249 \fB\fIhh\fR\fR
250 .ad
251 .sp .6
252 .RS 4n
253 The hour of the day [00-23].
254 .RE
256 .sp
257 .ne 2
258 .na
259 \fB\fImm\fR\fR
260 .ad
261 .sp .6
262 .RS 4n
263 The minute of the hour [00-59].
264 .RE
266 .sp
267 .ne 2
268 .na
269 \fB\fICC\fR\fR
270 .ad
271 .sp .6
272 .RS 4n
273 The first two digits of the year.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fIYY\fR\fR
280 .ad
281 .sp .6
282 .RS 4n
283 The second two digits of the year.
284 .RE
286 .sp
287 .ne 2
288 .na
289 \fB\fISS\fR\fR
290 .ad
291 .sp .6
292 .RS 4n
293 The second of the minute [00-61].
294 .RE
296 Both \fICC\fR and \fIYY\fR are optional. If neither is given, the current year
297 is assumed. If \fIYY\fR is specified, but \fICC\fR is not, \fICC\fR is derived
298 as follows:
299 .sp
301 .sp
302 .TS
303 box;
304 c c
305 l l .
306 If YY is: CC becomes:
307 _
308 69-99 19
309 00-38 20
310 39-68 ERROR
311 .TE
313 The resulting time is affected by the value of the \fBTZ\fR environment
314 variable. If the resulting time value precedes the Epoch, \fBtouch\fR exits
315 immediately with an error status. The range of valid times is the Epoch to
316 January 18, 2038.
317 .sp
318 The range for \fISS\fR is [00-61] rather than [00-59] because of leap seconds.
319 If \fISS\fR is 60 or 61, and the resulting time, as affected by the \fBTZ\fR
320 environment variable, does not refer to a leap second, the resulting time is
321 one or two seconds after a time where \fISS\fR is 59. If \fISS\fR is not given,
322 it is assumed to be 0.
323 .RE
325 .SS "settime"
326 .sp
327 .LP
328 The following option is supported for the \fBsettime\fR utility:
329 .sp
330 .ne 2
331 .na
332 \fB\fB-f\fR \fIref_file\fR\fR
333 .ad
334 .sp .6
335 .RS 4n
336 Uses the corresponding times of the file named by \fIref_file\fR instead of the
337 current time.
338 .RE
340 .SH OPERANDS
341 .sp
342 .LP
343 The following operands are supported for the \fBtouch\fR and \fBsettime\fR
344 utilities:
345 .sp
346 .ne 2
347 .na
348 \fB\fIfile\fR\fR
349 .ad
350 .sp .6
351 .RS 4n
352 A path name of a file whose times are to be modified.
353 .RE
355 .sp
356 .ne 2
357 .na
358 \fB\fItime_spec\fR\fR
359 .ad
360 .sp .6
361 .RS 4n
362 Uses the specified \fItime_spec\fR instead of the current time. This operand is
363 a decimal number of the form:
364 .sp
365 .in +2
366 .nf
367 \fIMMDDhhmm\fR[\fIYY\fR]
368 .fi
369 .in -2
370 .sp
372 where each two digits represent the following:
373 .sp
374 .ne 2
375 .na
376 \fB\fIMM\fR\fR
377 .ad
378 .sp .6
379 .RS 4n
380 The month of the year [01-12].
381 .RE
383 .sp
384 .ne 2
385 .na
386 \fB\fIDD\fR\fR
387 .ad
388 .sp .6
389 .RS 4n
390 The day of the month [01-31].
391 .RE
393 .sp
394 .ne 2
395 .na
396 \fB\fIhh\fR\fR
397 .ad
398 .sp .6
399 .RS 4n
400 The hour of the day [00-23].
401 .RE
403 .sp
404 .ne 2
405 .na
406 \fB\fImm\fR\fR
407 .ad
408 .sp .6
409 .RS 4n
410 The minute of the hour [00-59].
411 .RE
413 .sp
414 .ne 2
415 .na
416 \fB\fIYY\fR\fR
417 .ad
418 .sp .6
419 .RS 4n
420 The second two digits of the year.
421 .sp
422 \fIYY\fR is optional. If it is omitted, the current year is assumed. If
423 \fIYY\fR is specified, the year is derived as follows:
424 .RE
426 .sp
428 .sp
429 .TS
430 box;
431 c c
432 l l .
433 YY Corresponding Year
434 69-99 1969-1999
435 00-38 2000-2038
436 39-68 ERROR
437 .TE
439 If no \fB-d\fR, \fB-r\fR, or \fB-t\fRoption is specified, at least two operands
440 are specified, and the first operand is an eight- or ten-digit decimal integer,
441 the first operand is assumed to be a \fItime_spec\fR operand. Otherwise, the
442 first operand is assumed to be a \fIfile\fR operand.
443 .RE
445 .SH USAGE
446 .sp
447 .LP
448 See \fBlargefile\fR(5) for the description of the behavior of \fBtouch\fR when
449 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
450 .SH ENVIRONMENT VARIABLES
451 .sp
452 .LP
453 See \fBenviron\fR(5) for descriptions of the following environment variables
454 that affect the execution of \fBtouch\fR: \fBLANG\fR, \fBLC_ALL\fR, \fBLANG\fR,
455 \fBLC_ALL\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
456 .sp
457 .ne 2
458 .na
459 \fB\fBTZ\fR\fR
460 .ad
461 .sp .6
462 .RS 4n
463 Determine the timezone to be used for interpreting the \fItime\fR or
464 \fIdate_time\fR option-argument or the \fItime_spec\fR operand.
465 .RE
467 .SH EXIT STATUS
468 .sp
469 .LP
470 The following exit values are returned:
471 .sp
472 .ne 2
473 .na
474 \fB\fB0\fR\fR
475 .ad
476 .sp .6
477 .RS 4n
478 The \fBtouch\fR utility executed successfully and all requested changes were
479 made.
480 .RE
482 .sp
483 .ne 2
484 .na
485 \fB\fB>0\fR\fR
486 .ad
487 .sp .6
488 .RS 4n
489 An error occurred. The \fBtouch\fR utility returned the number of files for
490 which the times could not be successfully modified.
491 .RE
493 .SH ATTRIBUTES
494 .sp
495 .LP
496 See \fBattributes\fR(5) for descriptions of the following attributes:
497 .sp
499 .sp
500 .TS
501 box;
502 c | c
503 l | l .
504 ATTRIBUTE TYPE ATTRIBUTE VALUE
505 _
506 CSI Enabled
507 _
508 Interface Stability Committed
509 _
510 Standard See \fBstandards\fR(5).
511 .TE
513 .SH SEE ALSO
514 .sp
515 .LP
516 \fBfutimens\fR(2), \fBstat\fR(2), \fBattributes\fR(5), \fBenviron\fR(5),
517 \fBlargefile\fR(5), \fBstandards\fR(5)
518 .SH NOTES
519 .sp
520 .LP
521 Users familiar with the BSD environment find that for the \fBtouch\fR utility,
522 the \fB-f\fR option is accepted but ignored. The \fB-f\fR option is unnecessary
523 because \fBtouch\fR succeeds for all files owned by the user regardless of the
524 permissions on the files.