logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

touch.1p (15362B)


  1. '\" et
  2. .TH TOUCH "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. touch
  12. \(em change file access and modification times
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. touch \fB[\fR-acm\fB] [\fR-r \fIref_file\fR|-t \fItime\fR|-d \fIdate_time\fB] \fIfile\fR...
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR touch
  21. utility shall change the last data modification timestamps, the
  22. last data access timestamps, or both.
  23. .P
  24. The time used can be specified by the
  25. .BR \-t
  26. .IR time
  27. option-argument, the corresponding
  28. .IR time
  29. fields of the file referenced by the
  30. .BR \-r
  31. .IR ref_file
  32. option-argument, or the
  33. .BR \-d
  34. .IR date_time
  35. option-argument, as specified in the following sections. If none of
  36. these are specified,
  37. .IR touch
  38. shall use the current time.
  39. .P
  40. For each
  41. .IR file
  42. operand,
  43. .IR touch
  44. shall perform actions equivalent to the following functions defined in
  45. the System Interfaces volume of POSIX.1\(hy2017:
  46. .IP " 1." 4
  47. If
  48. .IR file
  49. does not exist:
  50. .RS 4
  51. .IP " a." 4
  52. The
  53. \fIcreat\fR()
  54. function is called with the following arguments:
  55. .RS 4
  56. .IP -- 4
  57. The
  58. .IR file
  59. operand is used as the
  60. .IR path
  61. argument.
  62. .IP -- 4
  63. The value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR,
  64. S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH is used as the
  65. .IR mode
  66. argument.
  67. .RE
  68. .IP " b." 4
  69. The
  70. \fIfutimens\fR()
  71. function is called with the following arguments:
  72. .RS 4
  73. .IP -- 4
  74. The file descriptor opened in step 1a.
  75. .IP -- 4
  76. The access time and the modification time, set as described in the
  77. OPTIONS section, are used as the first and second elements of the
  78. .IR times
  79. array argument, respectively.
  80. .RE
  81. .RE
  82. .IP " 2." 4
  83. If
  84. .IR file
  85. exists, the
  86. \fIutimensat\fR()
  87. function is called with the following arguments:
  88. .RS 4
  89. .IP " a." 4
  90. The AT_FDCWD special value is used as the
  91. .IR fd
  92. argument.
  93. .IP " b." 4
  94. The
  95. .IR file
  96. operand is used as the
  97. .IR path
  98. argument.
  99. .IP " c." 4
  100. The access time and the modification time, set as described in the
  101. OPTIONS section, are used as the first and second elements of the
  102. .IR times
  103. array argument, respectively.
  104. .IP " d." 4
  105. The
  106. .IR flag
  107. argument is set to zero.
  108. .RE
  109. .SH OPTIONS
  110. The
  111. .IR touch
  112. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  113. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  114. .P
  115. The following options shall be supported:
  116. .IP "\fB\-a\fP" 10
  117. Change the access time of
  118. .IR file .
  119. Do not change the modification time unless
  120. .BR \-m
  121. is also specified.
  122. .IP "\fB\-c\fP" 10
  123. Do not create a specified
  124. .IR file
  125. if it does not exist. Do not write any diagnostic messages concerning
  126. this condition.
  127. .IP "\fB\-d\ \fIdate_time\fR" 10
  128. Use the specified
  129. .IR date_time
  130. instead of the current time. The option-argument shall be a string of
  131. the form:
  132. .RS 10
  133. .sp
  134. .RS 4
  135. .nf
  136. \fIYYYY\fR-\fIMM\fR-\fIDD\fRT\fIhh\fR:\fImm\fR:\fISS\fB[\fR.\fIfrac\fB][\fItz\fB]\fR
  137. .fi
  138. .P
  139. .RE
  140. .P
  141. or:
  142. .sp
  143. .RS 4
  144. .nf
  145. \fIYYYY\fR-\fIMM\fR-\fIDD\fRT\fIhh\fR:\fImm\fR:\fISS\fB[\fR,\fIfrac\fB][\fItz\fB]\fR
  146. .fi
  147. .P
  148. .RE
  149. .P
  150. where:
  151. .IP " *" 4
  152. .IR YYYY
  153. are at least four decimal digits giving the year.
  154. .IP " *" 4
  155. .IR MM ,
  156. .IR DD ,
  157. .IR hh ,
  158. .IR mm ,
  159. and
  160. .IR SS
  161. are as with
  162. .BR \-t
  163. .IR time .
  164. .IP " *" 4
  165. \fRT\fR is the time designator, and can be replaced by a single
  166. <space>.
  167. .IP " *" 4
  168. \fR[.\fIfrac\fR]\fR and \fR[,\fIfrac\fR]\fR are either empty, or a
  169. <period>
  170. (\c
  171. .BR '.' )
  172. or a
  173. <comma>
  174. (\c
  175. .BR ',' )
  176. respectively, followed by one or more decimal digits, specifying
  177. a fractional second.
  178. .IP " *" 4
  179. \fR[\fItz\fR]\fR is either empty, signifying local time, or the letter
  180. .BR 'Z' ,
  181. signifying UTC. If \fR[\fItz\fR]\fR is empty, the resulting time shall
  182. be affected by the value of the
  183. .IR TZ
  184. environment variable.
  185. .P
  186. If the resulting time precedes the Epoch, the behavior is
  187. implementation-defined. If the time cannot be represented as the file's
  188. timestamp,
  189. .IR touch
  190. shall exit immediately with an error status.
  191. .RE
  192. .IP "\fB\-m\fP" 10
  193. Change the modification time of
  194. .IR file .
  195. Do not change the access time unless
  196. .BR \-a
  197. is also specified.
  198. .IP "\fB\-r\ \fIref_file\fR" 10
  199. Use the corresponding time of the file named by the pathname
  200. .IR ref_file
  201. instead of the current time.
  202. .IP "\fB\-t\ \fItime\fR" 10
  203. Use the specified
  204. .IR time
  205. instead of the current time. The option-argument shall be a decimal
  206. number of the form:
  207. .RS 10
  208. .sp
  209. .RS 4
  210. .nf
  211. \fB[[\fICC\fB]\fIYY\fB]\fIMMDDhhmm\fB[\fR.\fISS\fB]\fR
  212. .fi
  213. .P
  214. .RE
  215. .P
  216. where each two digits represents the following:
  217. .IP "\fIMM\fR" 8
  218. The month of the year [01,12].
  219. .IP "\fIDD\fR" 8
  220. The day of the month [01,31].
  221. .IP "\fIhh\fR" 8
  222. The hour of the day [00,23].
  223. .IP "\fImm\fR" 8
  224. The minute of the hour [00,59].
  225. .IP "\fICC\fR" 8
  226. The first two digits of the year (the century).
  227. .IP "\fIYY\fR" 8
  228. The second two digits of the year.
  229. .IP "\fISS\fR" 8
  230. The second of the minute [00,60].
  231. .P
  232. Both
  233. .IR CC
  234. and
  235. .IR YY
  236. shall be optional. If neither is given, the current year shall be
  237. assumed. If
  238. .IR YY
  239. is specified, but
  240. .IR CC
  241. is not,
  242. .IR CC
  243. shall be derived as follows:
  244. .TS
  245. center tab(@) box;
  246. cB | cB
  247. c | n.
  248. If \fIYY\fP is:@\fICC\fP becomes:
  249. _
  250. [69,99]@19
  251. [00,68]@20
  252. .TE
  253. .TP 10
  254. .BR Note:
  255. It is expected that in a future version of this standard the default
  256. century inferred from a 2-digit year will change. (This would apply
  257. to all commands accepting a 2-digit year as input.)
  258. .P
  259. .P
  260. The resulting time shall be affected by the value of the
  261. .IR TZ
  262. environment variable. If the resulting time value precedes the Epoch,
  263. the behavior is implementation-defined. If the time is out of range for
  264. the file's timestamp,
  265. .IR touch
  266. shall exit immediately with an error status. The range of valid times
  267. past the Epoch is implementation-defined, but it shall extend to at
  268. least the time 0 hours, 0 minutes, 0 seconds, January 1, 2038,
  269. Coordinated Universal Time. Some implementations may not be able to
  270. represent dates beyond January 18, 2038, because they use
  271. .BR "signed int"
  272. as a time holder.
  273. .P
  274. The range for
  275. .IR SS
  276. is [00,60] rather than [00,59] because of leap seconds. If
  277. .IR SS
  278. is 60, and the resulting time, as affected by the
  279. .IR TZ
  280. environment variable, does not refer to a leap second, the resulting
  281. time shall be one second after a time where
  282. .IR SS
  283. is 59. If
  284. .IR SS
  285. is not given a value, it is assumed to be zero.
  286. .RE
  287. .P
  288. If neither the
  289. .BR \-a
  290. nor
  291. .BR \-m
  292. options were specified,
  293. .IR touch
  294. shall behave as if both the
  295. .BR \-a
  296. and
  297. .BR \-m
  298. options were specified.
  299. .SH OPERANDS
  300. The following operands shall be supported:
  301. .IP "\fIfile\fR" 10
  302. A pathname of a file whose times shall be modified.
  303. .SH STDIN
  304. Not used.
  305. .SH "INPUT FILES"
  306. None.
  307. .SH "ENVIRONMENT VARIABLES"
  308. The following environment variables shall affect the execution of
  309. .IR touch :
  310. .IP "\fILANG\fP" 10
  311. Provide a default value for the internationalization variables that are
  312. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  313. .IR "Section 8.2" ", " "Internationalization Variables"
  314. for the precedence of internationalization variables used to determine
  315. the values of locale categories.)
  316. .IP "\fILC_ALL\fP" 10
  317. If set to a non-empty string value, override the values of all the
  318. other internationalization variables.
  319. .IP "\fILC_CTYPE\fP" 10
  320. Determine the locale for the interpretation of sequences of bytes of
  321. text data as characters (for example, single-byte as opposed to
  322. multi-byte characters in arguments).
  323. .IP "\fILC_MESSAGES\fP" 10
  324. .br
  325. Determine the locale that should be used to affect the format and
  326. contents of diagnostic messages written to standard error.
  327. .IP "\fINLSPATH\fP" 10
  328. Determine the location of message catalogs for the processing of
  329. .IR LC_MESSAGES .
  330. .IP "\fITZ\fP" 10
  331. Determine the timezone to be used for interpreting the
  332. .IR time
  333. option-argument. If
  334. .IR TZ
  335. is unset or null, an unspecified default timezone shall be used.
  336. .SH "ASYNCHRONOUS EVENTS"
  337. Default.
  338. .SH STDOUT
  339. Not used.
  340. .SH STDERR
  341. The standard error shall be used only for diagnostic messages.
  342. .SH "OUTPUT FILES"
  343. None.
  344. .SH "EXTENDED DESCRIPTION"
  345. None.
  346. .SH "EXIT STATUS"
  347. The following exit values shall be returned:
  348. .IP "\00" 6
  349. The utility executed successfully and all requested changes were made.
  350. .IP >0 6
  351. An error occurred.
  352. .SH "CONSEQUENCES OF ERRORS"
  353. Default.
  354. .LP
  355. .IR "The following sections are informative."
  356. .SH "APPLICATION USAGE"
  357. The interpretation of time is taken to be
  358. .IR "seconds since the Epoch"
  359. (see the Base Definitions volume of POSIX.1\(hy2017,
  360. .IR "Section 4.16" ", " "Seconds Since the Epoch").
  361. It should be noted that implementations conforming to the System Interfaces volume of POSIX.1\(hy2017 do
  362. not take leap seconds into account when computing seconds since the
  363. Epoch. When
  364. .IR SS =60
  365. is used, the resulting time always refers to 1 plus
  366. .IR "seconds since the Epoch"
  367. for a time when
  368. .IR SS =59.
  369. .P
  370. Although the
  371. .BR \-t
  372. .IR time
  373. option-argument specifies values in 1969, the access time and
  374. modification time fields are defined in terms of seconds since the
  375. Epoch (00:00:00 on 1 January 1970 UTC). Therefore, depending on the
  376. value of
  377. .IR TZ
  378. when
  379. .IR touch
  380. is run, there is never more than a few valid hours in 1969 and there
  381. need not be any valid times in 1969.
  382. .P
  383. If the
  384. .IR T
  385. time designator is replaced by a
  386. <space>
  387. for the
  388. .BR \-d
  389. .IR date_time
  390. option-argument, the
  391. <space>
  392. must be quoted to prevent the shell from splitting the argument.
  393. .SH EXAMPLES
  394. Create or update a file called
  395. .BR dwc ;
  396. the resulting file has both the last data modification and last data
  397. access timestamps set to November 12, 2007 at 10:15:30 local time:
  398. .sp
  399. .RS 4
  400. .nf
  401. touch -d 2007-11-12T10:15:30 dwc
  402. .fi
  403. .P
  404. .RE
  405. .P
  406. Create or update a file called
  407. .BR nick ;
  408. the resulting file has both the last data modification and last data
  409. access timestamps set to November 12, 2007 at 10:15:30 UTC:
  410. .sp
  411. .RS 4
  412. .nf
  413. touch -d 2007-11-12T10:15:30Z nick
  414. .fi
  415. .P
  416. .RE
  417. .P
  418. Create or update a file called
  419. .BR gwc ;
  420. the resulting file has both the last data modification and last data
  421. access timestamps set to November 12, 2007 at 10:15:30 local time with
  422. a fractional second timestamp of .002 seconds:
  423. .sp
  424. .RS 4
  425. .nf
  426. touch -d 2007-11-12T10:15:30,002 gwc
  427. .fi
  428. .P
  429. .RE
  430. .P
  431. Create or update a file called
  432. .BR ajosey ;
  433. the resulting file has both the last data modification and last data
  434. access timestamps set to November 12, 2007 at 10:15:30 UTC with a
  435. fractional second timestamp of .002 seconds:
  436. .sp
  437. .RS 4
  438. .nf
  439. touch -d "2007-11-12 10:15:30.002Z" ajosey
  440. .fi
  441. .P
  442. .RE
  443. .P
  444. Create or update a file called
  445. .BR cathy ;
  446. the resulting file has both the last data modification and last data
  447. access timestamps set to November 12, 2007 at 10:15:00 local time:
  448. .sp
  449. .RS 4
  450. .nf
  451. touch -t 200711121015 cathy
  452. .fi
  453. .P
  454. .RE
  455. .P
  456. Create or update a file called
  457. .BR drepper ;
  458. the resulting file has both the last data modification and last data
  459. access timestamps set to November 12, 2007 at 10:15:30 local time:
  460. .sp
  461. .RS 4
  462. .nf
  463. touch -t 200711121015.30 drepper
  464. .fi
  465. .P
  466. .RE
  467. .P
  468. Create or update a file called
  469. .BR ebb9 ;
  470. the resulting file has both the last data modification and last data
  471. access timestamps set to November 12, 2007 at 10:15:30 local time:
  472. .sp
  473. .RS 4
  474. .nf
  475. touch -t 0711121015.30 ebb9
  476. .fi
  477. .P
  478. .RE
  479. .P
  480. Create or update a file called
  481. .BR eggert ;
  482. the resulting file has the last data access timestamp set to the
  483. corresponding time of the file named
  484. .BR mark
  485. instead of the current time. If the file exists, the last data
  486. modification time is not changed:
  487. .sp
  488. .RS 4
  489. .nf
  490. touch -a -r mark eggert
  491. .fi
  492. .P
  493. .RE
  494. .SH RATIONALE
  495. The functionality of
  496. .IR touch
  497. is described almost entirely through references to functions in
  498. the System Interfaces volume of POSIX.1\(hy2017. In this way, there is no duplication of effort required for
  499. describing such side-effects as the relationship of user IDs to the
  500. user database, permissions, and so on.
  501. .P
  502. There are some significant differences between the
  503. .IR touch
  504. utility in this volume of POSIX.1\(hy2017 and those in System V and BSD systems. They are
  505. upwards-compatible for historical applications from both
  506. implementations:
  507. .IP " 1." 4
  508. In System V, an ambiguity exists when a pathname that is a decimal
  509. number leads the operands; it is treated as a time value. In BSD, no
  510. .IR time
  511. value is allowed; files may only be
  512. .IR touch ed
  513. to the current time. The
  514. .BR \-t
  515. .IR time
  516. construct solves these problems for future conforming applications (note
  517. that the
  518. .BR \-t
  519. option is not historical practice).
  520. .IP " 2." 4
  521. The inclusion of the century digits,
  522. .IR CC ,
  523. is also new. Note that a ten-digit
  524. .IR time
  525. value is treated as if
  526. .IR YY ,
  527. and not
  528. .IR CC ,
  529. were specified. The caveat about the range of dates following the
  530. Epoch was included as recognition that some implementations are not
  531. able to represent dates beyond 18 January 2038 because they use
  532. .BR "signed int"
  533. as a time holder.
  534. .P
  535. The
  536. .BR \-r
  537. option was added because several comments requested this capability.
  538. This option was named
  539. .BR \-f
  540. in an early proposal, but was changed because the
  541. .BR \-f
  542. option is used in the BSD version of
  543. .IR touch
  544. with a different meaning.
  545. .P
  546. At least one historical implementation of
  547. .IR touch
  548. incremented the exit code if
  549. .BR \-c
  550. was specified and the file did not exist. This volume of POSIX.1\(hy2017 requires exit status
  551. zero if no errors occur.
  552. .P
  553. In previous version of the standard, if at least two operands are
  554. specified, and the first operand is an eight or ten-digit decimal
  555. integer, the first operand was assumed to be a
  556. .IR date_time
  557. operand. This usage was removed in this version of the standard since
  558. it had been marked obsolescent previously.
  559. .P
  560. The
  561. .BR \-d
  562. .IR date_time
  563. format is an ISO\ 8601:\|2004 standard complete representation of date and time extended
  564. format with an optional decimal point or
  565. <comma>
  566. followed by a string of digits following the seconds portion to specify
  567. fractions of a second. It is not necessary to recognize
  568. .BR \(dq[+/-]hh:mm\(dq
  569. and
  570. .BR \(dq[+/-]hh\(dq
  571. to specify timezones other than local time and UTC. The
  572. .IR T
  573. time designator in the ISO\ 8601:\|2004 standard extended format may be replaced by
  574. <space>.
  575. .SH "FUTURE DIRECTIONS"
  576. None.
  577. .SH "SEE ALSO"
  578. .IR "\fIdate\fR\^"
  579. .P
  580. The Base Definitions volume of POSIX.1\(hy2017,
  581. .IR "Section 4.16" ", " "Seconds Since the Epoch",
  582. .IR "Chapter 8" ", " "Environment Variables",
  583. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  584. .IR "\fB<sys_stat.h>\fP"
  585. .P
  586. The System Interfaces volume of POSIX.1\(hy2017,
  587. .IR "\fIcreat\fR\^(\|)",
  588. .IR "\fIfutimens\fR\^(\|)",
  589. .IR "\fItime\fR\^(\|)",
  590. .IR "\fIutime\fR\^(\|)"
  591. .\"
  592. .SH COPYRIGHT
  593. Portions of this text are reprinted and reproduced in electronic form
  594. from IEEE Std 1003.1-2017, Standard for Information Technology
  595. -- Portable Operating System Interface (POSIX), The Open Group Base
  596. Specifications Issue 7, 2018 Edition,
  597. Copyright (C) 2018 by the Institute of
  598. Electrical and Electronics Engineers, Inc and The Open Group.
  599. In the event of any discrepancy between this version and the original IEEE and
  600. The Open Group Standard, the original IEEE and The Open Group Standard
  601. is the referee document. The original Standard can be obtained online at
  602. http://www.opengroup.org/unix/online.html .
  603. .PP
  604. Any typographical or formatting errors that appear
  605. in this page are most likely
  606. to have been introduced during the conversion of the source files to
  607. man page format. To report such errors, see
  608. https://www.kernel.org/doc/man-pages/reporting_bugs.html .