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